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

Inheritance
HannesHand
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:

IndexJoint
0Hand open/close (0 = open, 1 = closed)
1Wrist flexion/extension (0 = extension, 1 = flexion)
2Wrist pronation/supination (0 = supination, 0.5 = neutral, 1 = pronation)
3Thumb rotation (0 = one extreme, 0.5 = neutral, 1 = other extreme)

Input types: The block accepts three input shapes:

Connection lifecycle:

  1. ConnectDongleAsync(CancellationToken) — opens the COM port and enters dongle command mode.
  2. ScanForDevicesAsync(CancellationToken) — sends a BLE scan command and parses discovered devices.
  3. ConnectHannesAsync(CancellationToken) — connects to the selected device, pings for ACK, and configures reference control mode.
  4. 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
BaseBlock.DumpFilePrefix

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
BaseBlock.JsonTypeName

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)

Converts a BitArray to a single byte (first 8 bits).

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>

true if the dongle is ready; false on failure.

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
BaseBlock.Dispose()

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, Dictionary<DegreesOfActuation, double>, or a tagged ValueTuple<string, object> wrapping either of the above.

Overrides
BaseBlock.OnReceive(object, object)
Remarks

Ignored when IsManualMode is true — use SendManualRefs(Vector<double>) instead.

ParseScan(IEnumerable<string>)

Parses BLE scan output lines into the _names, _cons, _rssis, and _addrs lists.

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.

Implements

INotifyPropertyChanged
INotifyPropertyChanging
ISubscriber
IPublisher
IBaseBlockProps
IJsonExportable
IDisposable
IAsyncDisposable

Search documentation

Start typing to search the documentation.