Unicorn Hybrid Black

class gpype.backend.sources.hybrid_black.HybridBlack[source]

Bases: AmplifierSource

Unicorn Hybrid Black amplifier for wireless EEG acquisition.

Interface to g.tec Unicorn Hybrid Black wireless EEG amplifier using Bluetooth. Supports 8-channel EEG acquisition at 250 Hz, plus optional accelerometer, gyroscope, battery, counter, and validation channels.

On macOS the main thread must run an event loop while the node acquires, as MainApp.run() does: the driver receives every Bluetooth callback there, and the node reads on its own thread. A script whose main thread only sleeps gets read errors naming that cause.

DEFAULT_INCLUDE_ACCEL = False

The optional data streams, all off unless asked for.

DEFAULT_INCLUDE_GYRO = False
DEFAULT_INCLUDE_AUX = False
DEFAULT_TEST_SIGNAL = False
SAMPLING_RATE = 250

Fixed sampling rate for Unicorn Hybrid Black amplifier in Hz

NUM_EEG_CHANNELS = 8

Number of EEG channels

NUM_ACCEL_CHANNELS = 3

Number of accelerometer channels (X, Y, Z)

NUM_GYRO_CHANNELS = 3

Number of gyroscope channels (X, Y, Z)

NUM_AUX_CHANNELS = 3

Number of auxiliary channels (battery, counter, validation)

NUM_TIMELINE_CHANNELS = 1

Channels appended to carry the first-sight stamp. One instant per block, declared on the output port rather than in the configuration – see setup().

TOTAL_ACQUIRED_CHANNELS = 17

Total number of acquired channels (EEG + Accel + Gyro + Battery + Counter + Validation)

DEVICE_DELAY_MS = 40
BEHIND_BACKLOG_S = 1.0
NUM_ACQUISITION_ERRORS_ALLOWED = 3

Consecutive failed reads tolerated before acquisition is given up. One failure is a Bluetooth hiccup the next read recovers from, so failing on the first would end a run over nothing; three in a row is a device that has stopped answering, and carrying on then means a pipeline that emits nothing while reporting Healthy.

class Configuration[source]

Bases: Configuration

Configuration class for Unicorn Hybrid Black specific parameters.

class Keys[source]

Bases: Keys

Configuration keys for Unicorn Hybrid Black settings.

EEG_CHANNEL_COUNT = 'eeg_channel_count'

Number of EEG channels, as requested. Recorded on its own because the port’s channel_count is the total including the optional accelerometer, gyroscope and auxiliary channels: deriving the EEG count back out of that total would add them a second time on every round trip.

INCLUDE_ACCEL = 'include_accel'
INCLUDE_GYRO = 'include_gyro'
INCLUDE_AUX = 'include_aux'
TEST_SIGNAL = 'test_signal'
class OptionalKeys[source]

Bases: OptionalKeys

Optional configuration keys.

SERIAL = 'serial'

Serial number of the target device. Recorded because it selects which amplifier is opened; absent means the first one discovered.

__init__(serial=None, channel_count=None, frame_size=None, include_accel=None, include_gyro=None, include_aux=None, test_signal=None, enable_oscar=False, edge_id=None, **kwargs)[source]

Initialize Unicorn Hybrid Black amplifier source.

Nothing reaches the device or its driver here: the device is opened when the pipeline starts, so the node constructs in every residency and under load_from.

Parameters:
  • serial (Optional[str]) – Serial number of target device. Uses first discovered if None.

  • channel_count (Optional[int]) – Number of EEG channels (1-8). Defaults to 8.

  • frame_size (Optional[int]) – Samples per processing frame.

  • include_accel (Optional[bool]) – Include accelerometer channels (3 channels).

  • include_gyro (Optional[bool]) – Include gyroscope channels (3 channels).

  • include_aux (Optional[bool]) – Include auxiliary channels (battery, counter, validation).

  • test_signal (Optional[bool]) – Enable test signal mode instead of live data.

  • enable_oscar (bool) – Run OSCAR artifact removal on this stream.

  • edge_id (Optional[str]) – Which edge runs this node, matched against the edge process’s –edge-id. None, the default, is every edge; ignored when the pipeline is not distributed.

  • **kwargs – Additional arguments for parent AmplifierSource.

attach_timeline(timeline)[source]

Bind to the pipeline’s timeline, and forget a previous failure.

The pipeline calls this as each start() begins, so an open that failed in the previous start is tried again in this one.

Parameters:

timeline – Timeline manager owned by the pipeline.

Return type:

None

open_for_attestation()[source]

Open the device before the entitlement gate. See the base class.

Safe to call twice: the handle opened here is the one start() uses. Never raises. A failure – the device off, no licence – is logged once and raised again by start(), without a second open.

Return type:

None

start()[source]

Start Unicorn Hybrid Black amplifier and begin data acquisition.

Opens the device unless the entitlement gate already did, starts acquisition, and starts the thread that reads blocks and drives the pipeline via cycle().

Raises:
  • RuntimeError – If gtec_unicorn cannot be loaded.

  • ConnectionError – If no Unicorn is available.

  • gtec_unicorn.LicenseError – If no licence for the product it names is active on this machine.

  • gtec_unicorn.DeviceError – If the device cannot be opened or started.

Return type:

None

channel_units()[source]

One ‘uV’ per EEG channel, each enabled block’s own unit, and None for the arrival stamp.

Accelerometer is ‘g’, gyroscope ‘deg/s’, and the auxiliary triple is battery ‘%’, then counter and the validation flag – gtec_unicorn’s own device configuration reports both of those as ‘-’ (gtec-unicorn-py’s DEFAULT_CHANNELS, matching Amplifier.get_configuration()’s per-channel unit), which this passes on rather than inventing g.Pype’s own ‘count’ for a channel the driver itself declines to give a physical unit.

Return type:

Optional[list]

setup(data, port_context_in)[source]

Describe the channel layout, and stamp after it.

The arrival stamp is appended after every acquired block and counted apart from them: the blocks below are the channels the device delivers, which the stamp is no part of.

The stamp is declared on the output port and nowhere else, so config[CHANNEL_COUNT] still equals the width the device was asked for. Core-8 raises the configuration instead, and survives it only because it keeps eeg_channel_count beside it; here the total is also the width the device is configured to and checked against at open, so widening the configuration would ask the device for a channel it does not have.

Parameters:
  • data (dict[str, ndarray]) – Input data arrays (empty for source nodes).

  • port_context_in (dict[str, dict]) – Input port contexts (empty for source nodes).

Return type:

dict[str, dict]

Returns:

Dictionary of output port contexts with 250 Hz sampling rate.

stop()[source]

Stop Unicorn Hybrid Black amplifier and clean up resources.

Stops the acquisition thread, then stops and closes the device.

step(data)[source]

Retrieve processed data frames from the amplifier.

Returns data frames when decimation step is active.

Parameters:

data (dict[str, ndarray]) – Input data dictionary (unused for source nodes).

Return type:

dict[str, ndarray]

Returns:

Dictionary containing EEG data, or None if not a decimation step.

behind_reads()[source]

Consecutive backlogged reads that mean a backlog, not a burst.

Return type:

int

static get_available_devices()[source]

Get list of available Unicorn Hybrid Black devices.

Returns:

the paired devices on Windows, the discoverable ones elsewhere. Empty where gtec_unicorn cannot be loaded, or discovery fails.

Return type:

list[str]