brainaccess.core.eeg_manager#

Classes#

EEGManager

Manages all communication with a BrainAccess device.

Module Contents#

class brainaccess.core.eeg_manager.EEGManager[source]#

Manages all communication with a BrainAccess device.

The EEGManager is the primary interface for connecting to, configuring, and streaming data from a BrainAccess device. It handles the low-level details of Bluetooth communication and provides a high-level API for controlling the device.

Initializes a new EEGManager instance.

Warning

The BrainAccess Core library must be initialized with init() before creating an EEGManager.

annotate(annotation)[source]#

Adds a timestamped annotation to the data stream.

Warning

Annotations are cleared when the device is disconnected.

Parameters:

annotation (str) – The text of the annotation.

Raises:

BrainAccessException – If the annotation is None or empty.

Return type:

None

clear_annotations()[source]#

Clears all existing annotations.

Return type:

None

connect(bt_device_name)[source]#

Connects to a BrainAccess device.

Parameters:

bt_device_name (str) – The name of the device to connect to (e.g., “HALO 001”, “MINI 001”).

Returns:

  • 0: Connection successful.

  • 2: Connection successful, but the data stream is incompatible.

    A firmware update is recommended.

Return type:

int

Raises:

BrainAccessException – If the connection could not be established.

destroy()[source]#

Releases all resources associated with the EEG manager.

This method should be called when the manager is no longer needed to ensure a clean shutdown.

Warning

This method must be called exactly once.

Return type:

None

disconnect()[source]#

Disconnects from the device, if a connection is active.

Return type:

None

get_annotations()[source]#

Retrieves all accumulated annotations.

Warning

Annotations are cleared when the device is disconnected.

Returns:

A dictionary with two keys: - “annotations”: A list of annotation strings. - “timestamps”: A list of corresponding timestamps.

Return type:

dict

get_battery_info()[source]#

Retrieves the current battery status from the device.

Returns:

An object containing battery level and charging status.

Return type:

BatteryInfo

get_channel_index(channel)[source]#

Gets the index of a specific channel within the data chunk.

This allows you to locate the data for a particular channel within the array provided by the chunk callback.

Parameters:

channel (int) – The ID of the channel.

Returns:

The index of the channel’s data in the chunk array.

Return type:

int

Raises:

BrainAccessException – If the channel does not exist or is not currently being streamed.

get_device_features()[source]#

Retrieves the features and capabilities of the connected device.

Returns:

An object with methods to query for features like gyroscope, accelerometer, bipolar electrodes, and electrode count.

Return type:

DeviceFeatures

get_device_info()[source]#

Retrieves static information about the connected device.

Warning

This method should only be called after a successful connection has been established.

Returns:

An object containing the device model, hardware/firmware versions, and other static information.

Return type:

DeviceInfo

get_sample_frequency()[source]#

Gets the sampling frequency of the device.

Returns:

The sampling frequency.

Return type:

int

is_connected()[source]#

Checks if a connection to a device is currently active.

Returns:

True if connected, False otherwise.

Return type:

bool

is_streaming()[source]#

Checks if the device is currently streaming data.

Returns:

True if the stream is active, False otherwise.

Return type:

bool

load_config(callback=None)[source]#

Applies the current channel and other settings to the device.

Parameters:

callback (callable, optional) – A function to be called when the configuration has been successfully loaded onto the device.

Return type:

None

set_callback_battery(callback=None)[source]#

Sets a callback function to be executed when the battery status is updated.

Warning

The callback may be executed in a different thread. Ensure that any shared data is properly synchronized and that the callback executes quickly to avoid blocking communication with the device.

Parameters:

callback (callable, optional) – The function to be called. It should accept a BatteryInfo object as an argument. Set to None to disable.

Raises:

BrainAccessException – If the callback is None.

Return type:

None

set_callback_chunk(f)[source]#

Sets a callback function to be executed when a new data chunk is available.

Warning

The callback may be executed in a different thread. Ensure that any shared data is properly synchronized and that the callback executes quickly to avoid blocking communication with the device.

Parameters:

f (callable) – The function to be called. It should accept a list of NumPy arrays (one for each channel) and the chunk size as arguments. Set to None to disable the callback.

Return type:

None

set_callback_disconnect(callback=None)[source]#

Sets a callback function to be executed when the device disconnects.

Warning

The callback may be executed in a different thread. Ensure that any shared data is properly synchronized and that the callback executes quickly.

Parameters:

callback (callable, optional) – The function to be called on disconnect. Set to None to disable.

Return type:

None

set_channel_bias(channel, bias)[source]#

DEPRECATED: Use the version with Polarity instead.

Configures an electrode channel for bias feedback. The signals from bias channels are inverted and fed back into the bias electrode to reduce common-mode noise (e.g., from power lines).

Warning

This setting takes effect on stream start and is reset on stream stop. Only select channels with good skin contact for bias feedback.

Parameters:

  • channel (int) – The ID of the channel to use for bias feedback.

  • bias (bool) – True to enable bias feedback for this channel, False to disable.

Raises:

BrainAccessException – If the device is currently streaming.

Return type:

None

set_channel_enabled(channel, state)[source]#

Enables or disables a specific data channel.

Warning

Channel settings are reset when the stream is stopped. This method must be called before each stream start to configure the desired channels.

Parameters:

  • channel (int) – The ID of the channel to enable or disable (see brainaccess.core.eeg_channel).

  • state (bool) – True to enable the channel, False to disable it.

Raises:

BrainAccessException – If the device is currently streaming.

Return type:

None

set_channel_gain(channel, gain)[source]#

Sets the gain mode for a specific channel.

Lower gain values increase the measurable voltage range at the cost of reduced amplitude resolution. A gain of X12 is optimal for most use cases.

Warning

This setting takes effect on stream start and is reset on stream stop. It only affects channels that support gain control, such as electrode measurement channels.

Parameters:

  • channel (int) – The ID of the channel to configure.

  • gain (GainMode) – The desired gain mode.

Raises:

BrainAccessException – If the device is streaming or the channel number is invalid.

Return type:

None

set_impedance_mode(mode)[source]#

Configures the device for impedance measurement.

This mode injects a small, known current through the bias electrodes and measures the resulting voltage at each electrode. The impedance can then be calculated using Ohm’s law (Impedance = Voltage / Current).

Warning

This setting takes effect on stream start and is reset on stream stop.

Parameters:

mode (ImpedanceMeasurementMode) – The impedance measurement mode to set.

Raises:

BrainAccessException – If the device is currently streaming.

set_sample_rate(sample_rate)[source]#

Sets the data stream sample rate for the device.

The available sample rates may depend on the device model and firmware version. Refer to the brainaccess.core.stream_rate.StreamRate enum for available options.

Warning

This setting takes effect on stream start and is reset on stream stop.

Parameters:

sample_rate (int) – The desired data stream sample rate.

Raises:

BrainAccessException – If the device is currently streaming. If the device sample rate is not possible

Return type:

bool

start_stream(callback=None)[source]#

Starts streaming data from the device.

Parameters:

callback (callable, optional) – A function to be called when the stream has successfully started.

Returns:

True if the stream was started successfully.

Return type:

bool

Raises:

BrainAccessException – If the stream is already running or could not be started.

start_update(callback=None)[source]#

Starts a firmware update for the device.

Parameters:

callback (callable, optional) – A function to be called with the progress of the update. It should accept two arguments: the number of bytes sent and the total number of bytes.

Raises:

BrainAccessException – If the update cannot be started.

Return type:

None

stop_stream(callback=None)[source]#

Stops the data stream from the device.

Parameters:

callback (callable, optional) – A function to be called when the stream has successfully stopped.

Returns:

True if the stream was stopped successfully.

Return type:

bool

Raises:

BrainAccessException – If the stream is not currently running or could not be stopped.

conenction_success: int = 0[source]#