Class HannesHand
Hannes robotic prosthesis control block — sends 4-DOF joint references over a BLE-to-serial dongle.
JSON configuration
Use these block entries inside a pipeline configuration. Input names must match other blocks in that pipeline; device addresses and file paths must match your setup.
JSON configuration:
{
"MyHannes": {
"Type": "HannesHand",
"DesiredRate": 50,
"Inputs": [ "ControlAlgorithm" ],
"Path": "C:/Data/session1"
}
}
Params: None. Port name and device selection are configured via the UI at runtime.
How Type, Inputs and Params work · Block catalogue and parameter reference
Implements
Inherited Members
Namespace: MOSAIC.Models.Devices
Assembly: MOSAIC.dll
Syntax
public sealed class HannesHand : BaseBlock, INotifyPropertyChanged, INotifyPropertyChanging, ISubscriber, IPublisher, IBaseBlockProps, IJsonExportable, IDisposable, IAsyncDisposable
Remarks
Overview: Receives a 4-element MathNet.Numerics.LinearAlgebra.Vector<T> of double (each 0–1) representing normalised joint references, converts them to the Hannes EMGEM protocol format, and transmits them over a BLE dongle serial link. Also supports a manual slider mode for direct UI control.
Input vector layout:
| Index | Joint |
|---|---|
| 0 | Hand open/close (0 = open, 1 = closed) |
| 1 | Wrist flexion/extension (0 = extension, 1 = flexion) |
| 2 | Wrist pronation/supination (0 = supination, 0.5 = neutral, 1 = pronation) |
| 3 | Thumb rotation (0 = one extreme, 0.5 = neutral, 1 = other extreme) |
Input types: The block accepts three input shapes:
- MathNet.Numerics.LinearAlgebra.Vector<T> of double — used directly.
Dictionary<DegreesOfActuation, double>— converted via ConvertFromDoaDict(Dictionary<DegreesOfActuation, double>).ValueTuple<string, object>— tagged wrapper; inner value is unwrapped and handled as above.
Connection lifecycle:
- ConnectDongleAsync(CancellationToken) — opens the COM port and enters dongle command mode.
- ScanForDevicesAsync(CancellationToken) — sends a BLE scan command and parses discovered devices.
- ConnectHannesAsync(CancellationToken) — connects to the selected device, pings for ACK, and configures reference control mode.
- DisconnectHannes() — switches to command mode, disconnects BLE, and closes the link.
EMGEM protocol: Packets are framed as 0x25 (%) | payload | 0x26 (&) | CR | LF.
The SendSimultaneousRefs(Vector<double>) method builds an 11-byte payload containing joint references
scaled and sign-converted per the Hannes firmware specification.
CSV logging: When a Path is specified in the JSON configuration, the base class
Dumper automatically logs every published vector as
timestamp, hand, wristFE, wristPS, thumb.
Constructors
HannesHand(string, double)
Initializes a new HannesHand block.
Declaration
public HannesHand(string name = "HannesHand", double desiredRate = 0)
Parameters
| Type | Name | Description |
|---|---|---|
| string | name | Display name of the block. |
| double | desiredRate | Desired processing rate in Hz. Typical values: 20–50 Hz for prosthesis control. |
Fields
_addrs
BLE MAC addresses from the last BLE scan (used for deduplication).
Declaration
private readonly List<string> _addrs
Field Value
| Type | Description |
|---|---|
| List<string> |
_connected
Whether BLE is connected to the prosthesis.
Declaration
private bool _connected
Field Value
| Type | Description |
|---|---|
| bool |
_cons
Connection indices from the last BLE scan (used by con {id} command).
Declaration
private readonly List<int> _cons
Field Value
| Type | Description |
|---|---|
| List<int> |
_dongle
Serial dongle client for Hannes EMGEM communication.
Declaration
private readonly RehabDongleClient _dongle
Field Value
| Type | Description |
|---|---|
| RehabDongleClient |
_mode
Current dongle streaming mode (command vs. stream).
Declaration
private HannesProtocol.StreamMode _mode
Field Value
| Type | Description |
|---|---|
| HannesProtocol.StreamMode |
_names
Device display names from the last BLE scan.
Declaration
private readonly List<string> _names
Field Value
| Type | Description |
|---|---|
| List<string> |
_rssis
RSSI values from the last BLE scan.
Declaration
private readonly List<int> _rssis
Field Value
| Type | Description |
|---|---|
| List<int> |
_status
Current device connection state.
Declaration
private DeviceStatus _status
Field Value
| Type | Description |
|---|---|
| DeviceStatus |
_streaming
Whether streaming/reference-control mode is active.
Declaration
private bool _streaming
Field Value
| Type | Description |
|---|---|
| bool |
Properties
DumpFilePrefix
Recordings from this block are named <block>_out.csv.
Declaration
protected override string DumpFilePrefix { get; }
Property Value
| Type | Description |
|---|---|
| string |
Overrides
HandOpenClose
Enables/disables hand open/close DOF in reference control.
Declaration
public bool HandOpenClose { get; set; }
Property Value
| Type | Description |
|---|---|
| bool |
IsManualMode
When true, ignores pipeline input and uses manual slider values via SendManualRefs(Vector<double>).
Declaration
public bool IsManualMode { get; set; }
Property Value
| Type | Description |
|---|---|
| bool |
JsonTypeName
Block type identifier for JSON serialization. Override for a custom name.
Declaration
protected override string JsonTypeName { get; }
Property Value
| Type | Description |
|---|---|
| string |
Overrides
PortName
Serial port name for the BLE dongle (e.g. "COM3"). Set by the ViewModel.
Declaration
public string? PortName { get; set; }
Property Value
| Type | Description |
|---|---|
| string |
Scope
Scope for visualising the 4-channel joint reference output in the UI.
Declaration
public ScopeMonitor Scope { get; }
Property Value
| Type | Description |
|---|---|
| ScopeMonitor |
SelectedDevice
Display name of the BLE device selected from ScanForDevicesAsync(CancellationToken) results. Set by the ViewModel.
Declaration
public string? SelectedDevice { get; set; }
Property Value
| Type | Description |
|---|---|
| string |
Thumb
Enables/disables thumb rotation DOF in reference control.
Declaration
public bool Thumb { get; set; }
Property Value
| Type | Description |
|---|---|
| bool |
WristExFlex
Enables/disables wrist flexion/extension DOF in reference control.
Declaration
public bool WristExFlex { get; set; }
Property Value
| Type | Description |
|---|---|
| bool |
WristSupPro
Enables/disables wrist pronation/supination DOF in reference control.
Declaration
public bool WristSupPro { get; set; }
Property Value
| Type | Description |
|---|---|
| bool |
Methods
BitArrayToByte(BitArray)
Declaration
private static byte BitArrayToByte(BitArray bits)
Parameters
| Type | Name | Description |
|---|---|---|
| BitArray | bits | Bit array to convert. |
Returns
| Type | Description |
|---|---|
| byte | The byte representation of the first 8 bits. |
ConfigureForRefControlAsync(CancellationToken)
Configures the Hannes firmware for reference control: sets the active joint mask and control mode, then switches to stream mode.
Declaration
private Task ConfigureForRefControlAsync(CancellationToken ct)
Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | ct | Cancellation token. |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
The joint mask is built from the Thumb, WristExFlex, WristSupPro, and HandOpenClose toggle properties. Control mode is set to UNITY_CONTROL.
ConfigureInput(IServiceProvider, JsonModel)
Creates and configures a HannesHand from a JSON model definition.
Declaration
public static HannesHand ConfigureInput(IServiceProvider sp, JsonModel m)
Parameters
| Type | Name | Description |
|---|---|---|
| IServiceProvider | sp | Service provider for dependency injection. |
| JsonModel | m | The JSON model. See the class-level example for details. |
Returns
| Type | Description |
|---|---|
| HannesHand | A fully configured HannesHand instance. |
ConnectDongleAsync(CancellationToken)
Opens the serial port and enters dongle command mode.
Declaration
public Task<bool> ConnectDongleAsync(CancellationToken ct = default)
Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | ct | Optional cancellation token. |
Returns
| Type | Description |
|---|---|
| Task<bool> |
Remarks
If PortName is a bare number (e.g. "3"), it is auto-corrected
to "COM3" on Windows.
ConnectHannesAsync(CancellationToken)
Connects to the selected Hannes device over BLE, pings for ACK, and configures reference control mode.
Declaration
public Task<bool> ConnectHannesAsync(CancellationToken ct = default)
Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | ct | Optional cancellation token. |
Returns
| Type | Description |
|---|---|
| Task<bool> | true if the prosthesis is ready for streaming; false otherwise. |
Remarks
Sequence: con {id} → ping (EnterCMDMode) → check ACK →
configure joint mask and control mode → switch to stream mode.
The ACK reply is expected as 0x25 0x02 0x26 0x0D (Start + ACK + End + CR).
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Thrown if the serial port is not open. |
ConvertFromDoaDict(Dictionary<DegreesOfActuation, double>)
Converts a Dictionary<DegreesOfActuation, double> (0–100 scale) to the
Hannes 4-element reference vector (0–1 scale).
Declaration
private static Vector<double> ConvertFromDoaDict(Dictionary<DegreesOfActuation, double> dict)
Parameters
| Type | Name | Description |
|---|---|---|
| Dictionary<DegreesOfActuation, double> | dict | DOA dictionary with values in the range 0–100. |
Returns
| Type | Description |
|---|---|
| Vector<double> | Dense vector: [Hand (0–1), WristFE (0–1), WristPS (0–1), Thumb (0–1)]. |
Remarks
Hand: Computed as the average of available finger flexions (Index, Middle, Ring, Little), or 0.5 if none are present.
Wrist F/E: Direct mapping — 0 = full extension, 100 = full flexion.
Wrist P/S: 0 = full supination, 50 = neutral, 100 = full pronation.
Thumb: Uses ThumbFlexion DOA directly.
DisconnectHannes()
Disconnects from the Hannes prosthesis: switches to command mode, sends dct,
and resets connection state.
Declaration
public void DisconnectHannes()
Dispose()
Releases all resources: scope, serial dongle, and base class resources (including the CSV dumper if configured).
Declaration
public override void Dispose()
Overrides
EnsureOpen()
Throws if the serial port is not open.
Declaration
private void EnsureOpen()
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Thrown when the dongle port is closed. |
OnReceive(object, object)
Processes incoming data: extracts a 4-element reference vector and sends it to the prosthesis.
Declaration
protected override void OnReceive(object sender, object data)
Parameters
| Type | Name | Description |
|---|---|---|
| object | sender | The upstream block. |
| object | data | One of: MathNet.Numerics.LinearAlgebra.Vector<T> of double,
|
Overrides
Remarks
Ignored when IsManualMode is true — use SendManualRefs(Vector<double>) instead.
ParseScan(IEnumerable<string>)
Declaration
private void ParseScan(IEnumerable<string> lines)
Parameters
| Type | Name | Description |
|---|---|---|
| IEnumerable<string> | lines | Raw text lines from the dongle's scan response. |
Remarks
Expected format: # {con} {rssi} {addr} {name} (with or without a leading # token).
Duplicate addresses are skipped.
ScanForDevicesAsync(CancellationToken)
Sends a BLE scan command and returns the list of discovered device names.
Declaration
public Task<IReadOnlyList<string>> ScanForDevicesAsync(CancellationToken ct = default)
Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | ct | Optional cancellation token. |
Returns
| Type | Description |
|---|---|
| Task<IReadOnlyList<string>> | A read-only list of discovered device names. |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Thrown if the serial port is not open (call ConnectDongleAsync(CancellationToken) first). |
SendManualRefs(Vector<double>)
Sends manual reference values from UI sliders. Only effective when IsManualMode is true.
Declaration
public void SendManualRefs(Vector<double> refs)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | refs | Vector [Hand, WristFE, WristPS, Thumb], each 0–1. |
SendRefs(Vector<double>)
Internal method that sends references to the device, publishes downstream, and updates the scope.
Declaration
private void SendRefs(Vector<double> refs)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | refs | 4-element normalised reference vector. |
Remarks
The vector is sent to the prosthesis (if connected and streaming), then published downstream. Publish(object) handles automatic CSV logging.
SendSimultaneousRefs(Vector<double>)
Sends a simultaneous 4-DOF reference command to the Hannes prosthesis.
Declaration
private void SendSimultaneousRefs(Vector<double> v)
Parameters
| Type | Name | Description |
|---|---|---|
| Vector<double> | v | 4-element reference vector: [Hand (0–1), WristFE (0–1), WristPS (0–1), Thumb (0–1)]. Values are clamped to [0, 1]. |
Remarks
Protocol mapping:
- Hand: 0–1 → 0–100 (unsigned byte)
- Wrist F/E: 0–1 → 0–100 (unsigned byte)
- Wrist P/S: 0–1 → −100 to +100 (signed byte, negated: −(v−50)×2)
- Thumb: 0–1 → −100 to +100 (signed byte, negated: −(v−50)×2)
SwitchMode()
Toggles between command mode and stream mode by sending the appropriate EMGEM command.
Declaration
private void SwitchMode()
WriteEmgemPacket(params byte[])
Builds and writes an EMGEM-framed packet: 0x25 | payload | 0x26 | CR | LF.
Declaration
private void WriteEmgemPacket(params byte[] payload)
Parameters
| Type | Name | Description |
|---|---|---|
| byte[] | payload | One or more payload bytes to frame. |