brainaccess.core package

Submodules

brainaccess.core.annotation module

class brainaccess.core.annotation.Annotation[source]

Bases: Structure

Object containing annotation information

timestamp: Sample number corresponding to the time the annotation was recorded

annotation: Annotation text

property annotation

timestamp: Structure/Union member

brainaccess.core.battery_info module

class brainaccess.core.battery_info.BatteryInfo[source]

Bases: Structure

Object containing standard battery information

level: Battery charge percentage, 0-100

is_charger_connected: True if charger is connected to the device

is_charging: True if battery is charging

is_charger_connected: Structure/Union member

is_charging: Structure/Union member

level: Structure/Union member

brainaccess.core.device_features module

class brainaccess.core.device_features.DeviceFeatures(device_info)[source]

Bases: object

The DeviceFeatures class allowing the user to check what features a particular device supports.

Gets an instance of DeviceFeatures for the corresponding DeviceInfo class.

Parameters:: device_info (DeviceInfo) – Device for which to get features. Serial number is ignored.

electrode_count() → int[source]

Gets the number of EEG/EMG electrodes supported by the device.

Returns:: Number of electrodes
Return type:: int

has_accel() → bool[source]

Whether or not the device can capture accelerometer data.

Returns:: True if device has an accelerometer, False otherwise
Return type:: bool

has_gyro() → bool[source]

Whether or not the device can capture gyroscope data.

Returns:: True if device has a gyroscope, False otherwise
Return type:: bool

is_bipolar() → bool[source]

Whether or not the device’s electrodes are bipolar. Bipolar electrodes have separate P (positive) and N (negative) contacts.

Returns:: True if electrodes are bipolar, False otherwise
Return type:: bool

brainaccess.core.device_info module

class brainaccess.core.device_info.DeviceInfo[source]

Bases: Structure

Object containing device information

id: Device model number

hardware_version: Hardware version

firmware_version: Firmware version

serial_number: Device serial number

property device_model

firmware_version: Structure/Union member

hardware_version: Structure/Union member

serial_number: Structure/Union member

brainaccess.core.device_model module

class brainaccess.core.device_model.DeviceModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Device model information

MINI_V2: BrainAccess MINI V2

MIDI: BrainAccess MIDI (16 Channels)

MAXI: BrainAccess MAXI (32 Channels)

EMG: BrainAccess EMG

HALO1: BrainAccess Halo v1

HALO: BrainAccess Halo

UNKNOWN: Unknown device

EMG = 3

HALO = 5

HALO1 = 4

MAXI = 2

MIDI = 1

MINI = 0

UNKNOWN = 255

brainaccess.core.eeg_channel module

Starting addresses of channels in the chunk

brainaccess.core.eeg_channel.SAMPLE_NUMBER: The number of the sample starting from 0 at stream start

brainaccess.core.eeg_channel.ELECTRODE_MEASUREMENT: EEG electrode measurement value (uV)

brainaccess.core.eeg_channel.ELECTRODE_CONTACT: Whether or not the electrode is making contact with the skin

brainaccess.core.eeg_channel.DIGITAL_INPUT: Digital IO pin

brainaccess.core.eeg_channel.ACCELEROMETER: Accelerometer values

brainaccess.core.eeg_channel.GYROSCOPE: Gyroscope values

brainaccess.core.eeg_channel.STREAMING: Whether or not the device is streaming

brainaccess.core.eeg_channel.ELECTRODE_CONTACT_P: Whether or not the positive (P) electrode is making contact with the skin

brainaccess.core.eeg_channel.ELECTRODE_CONTACT_N: Whether or not the negative (N) electrode is making contact with the skin

Examples

To get ACCELEROMETER x y and z index in the chunk

x: get_channel_index(ACCELEROMETER + 0)
y: get_channel_index(ACCELEROMETER + 1)
z: get_channel_index(ACCELEROMETER + 2)

brainaccess.core.eeg_manager module

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

Bases: object

The EEG manager is the primary tool for communicating with the BrainAccess device.

Creates an EEG Manager.

Warning

Make sure the core library has been initialized first!

annotate(annotation: str) → None[source]

Adds an annotation at the current time

Warning

Annotations are cleared on disconnect

Parameters:: annotation (str) – annotation text
Raises:: BrainAccessException if annotation is None or empty –

clear_annotations() → None[source]: Clears annotations

connect(bt_device_index: int = 0) → int[source]

Connects the EEGManager to an EEG device

Parameters:: bt_device_index (int) – index of the device to connect in the scan list
Returns:: value: 0 if the connection was successful, 1 if connection failed, 2 if connection is established but data stream is not compatible
Return type:: int

destroy() → None[source]: Destroys an EEG manager instance.

Warning

Must be called exactly once, after the manager is no longer needed

disconnect() → None[source]: Disconnects the EEGManager from the EEG device, if connected

get_annotations() → dict[source]

Retrieve all the accumulated annotations

Warning

Annotations are cleared on disconnect

Returns:: annotations: List[str] timestamps: List[float]
Return type:: dict

get_battery_info() → BatteryInfo[source]

Returns a structure containing standard battery information from the device

Returns:: Battery information from the EEG device
Return type:: BatteryInfo

get_channel_index(channel: int) → int[source]

Gets the index of a channel’s data into the chunk

Get the index into the array provided by the chunk callback that contains the data of the channel number specified

Parameters:: channel (int) – The number of the channel whose index to get
Returns:: Index into chunk representing a channel
Return type:: int

get_device_features() → DeviceFeatures[source]

Get device features and capabilities

Returns:: object with methods to check the status of gyro, accelerometer, bipolarity, electrode count
Return type:: DeviceFeatures

get_device_info() → DeviceInfo[source]

Get device information

Warning

Must not be called unless device connection is successful

Returns:: device model, version, firmware version and buffer size
Return type:: DeviceInfo

get_sample_frequency() → int[source]

Get device sampling frequency

Returns:: Sample frequency (Hz)
Return type:: int

is_connected() → bool[source]

Checks if the EEGManager is currently connected to an EEG device

Returns:: True if connected, False otherwise
Return type:: bool

is_streaming() → bool[source]

Checks if the device is streaming

Returns:: True if the stream is active, False otherwise
Return type:: bool

load_config(callback: Callable | None = None) → None[source]: Loads the configuration of channel and other settings to the device

set_callback_battery(callback: Callable | None = None) → None[source]

Sets a callback to be called every time the battery status is updated

Warning

The callback may or may not run in the reader thread, and as such, synchronization must be used to avoid race conditions, and the callback itself must be as short as possible to avoid blocking communication with the device.

Parameters:: callback (Union[Callable, None]) – pass callback Function to be called every time a battery update is available Set to null to disable.
Raises:: BrainAccessException if callback is None –

set_callback_chunk(f: Callable) → None[source]

Sets a callback to be called every time a chunk is available

Warning

The callback may or may not run in the reader thread, and as such, synchronization must be used to avoid race conditions, and the callback itself must be as short as possible to avoid blocking communication with the device.

Parameters:: f – callback Function to be called every time a chunk is available Set to null to disable.

set_callback_disconnect(callback: Callable | None = None) → None[source]

Sets a callback to be called every time the device disconnects

Warning

The callback may or may not run in the reader thread, and as such, synchronization must be used to avoid race conditions, and the callback itself must be as short as possible to avoid blocking communication with the device.

Parameters:: callback (Union[Callable, None]) – callback Function to be called every time the device disconnects. Set to null to disable.

set_channel_bias(self, channel: int, bias: bool) → None[source]

DEPRECATED: use the version with Polarity instead.

Set an electrode channel as a bias electrode Essentially the signals of these channels are inverted and injected into the bias channel/electrode. This helps in reducing common mode noise such as noise coming from the mains. Only select channels for bias feedback that have good contact with a skin. Typically one channel is sufficient for bias feedback to work effectively.

This function takes effect on stream start, and its effects are reset by stream stop. Therefore, it must be called with the appropriate arguments before every stream start.

channel: int
Channel ID (brainaccess.core.eeg_channel) to set/unset as bias channel

bias: bool
True to enable channel, False to disable.

BrainAccessException if device is streaming

set_channel_bias(self, channel: int, p: brainaccess.core.polarity.Polarity) -> None

Set an electrode channel as a bias electrode

Essentially the signals of these channels are inverted and injected into the bias channel/electrode. This helps in reducing common mode noise such as noise coming from the mains. Only select channels for bias feedback that have good contact with a skin. Typically one channel is sufficient for bias feedback to work effectively.

This function takes effect on stream start, and its effects are reset by stream stop. Therefore, it must be called with the appropriate arguments before every stream start.

channel: int: Channel ID (brainaccess.core.eeg_channel) to set/unset as bias channel
p: Polarity: Which side of the electrode to use (if device is not bipolar, use BOTH)

BrainAccessException if device is streaming

set_channel_enabled(channel: int, state: bool) → None[source]

Enables or disables the channel on the device

Warning

Enabled channels are reset by stream stop. Must be called with the appropriate arguments before every stream start

Parameters:

channel (int) – Channel ID (brainaccess.core.eeg_channel) to enable/disable.
state (bool) – True to enable channel, False to disable.

Raises:

BrainAccessException if device is streaming –

set_channel_gain(channel: int, gain: GainMode) → None[source]

Changes gain mode for a channel on the device. Setting gain values to lower will increase the measured voltage range, but would decrease the amplitude resolution, 12 is the optimum in most cases.

Warning

This function takes effect on stream start, and its effects are reset by stream stop. Therefore, it must be called with the appropriate arguments before every stream start. This only affects channels that support it. For example, it affects the electrode measurement channels but not sample number or digital input.

Parameters:

channel (int) – Channel ID (brainaccess.core.eeg_channel) whose gain to modify.
gain (GainMode) – Gain mode. Default X12

Raises:

BrainAccessException if device is streaming or if the channel number is invalid –

set_impedance_mode(mode: ImpedanceMeasurementMode)[source]

Sets impedance measurement mode This function setups device for electrode impedance measurement. It injects a 7nA certain frequency current through the bias electrodes to measurement electrodes. Voltage recordings from each channel can then be used to calculate the impedance for each electrode: Impedance = Vpp/7nA

Warning

This function takes effect on stream start, and its effects are reset by stream stop. Therefore, it must be called with the appropriate arguments before every stream start.

Parameters:: mode (ImpedanceMeasurementMode) – Impedance mode to set
Raises:: BrainAccessException if device is streaming –

start_stream(callback: Callable | None = None) → bool[source]

Starts streaming data from the device

Returns:

value: True if the stream was started successfully

Return type:

bool

Raises:

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

start_update(callback: Callable | None = None) → None[source]

Starts a firmware update

Parameters:: callback (Union[Callable, None]) – callback to be called every time the update progress changes
Raises:: BrainAccessException if unable to start update –

stop_stream(callback: Callable | None = None) → bool[source]

Stops streaming data from the device

Returns:

value: True if the stream was stopped successfully

Return type:

bool

Raises:

BrainAccessException if the stream is not running –
or if the stream could not be stopped –

brainaccess.core.full_battery_info module

class brainaccess.core.full_battery_info.EBaChargeLevel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

e_ba_charge_level_critical = 3

e_ba_charge_level_good = 1

e_ba_charge_level_last = 4

e_ba_charge_level_low = 2

e_ba_charge_level_unknown = 0

class brainaccess.core.full_battery_info.EBaChargeStates(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

e_ba_charge_states_charging = 1

e_ba_charge_states_discharging_active = 2

e_ba_charge_states_discharging_inactive = 3

e_ba_charge_states_last = 4

e_ba_charge_states_unknown = 0

class brainaccess.core.full_battery_info.FullBatteryInfo[source]

Bases: Structure

Object containing extended battery information .. attribute:: is_charger_connected

True if charger is connected to the device

level: Battery charge percentage, 0-100

health: Battery health percentage, 0-100

voltage: Battery voltage in volts

current: Current flow in amps (negative means discharge)

charge_state

charge_level: Structure/Union member

charge_state: Structure/Union member

property charging_state

current: Structure/Union member

health: Structure/Union member

is_charger_connected: Structure/Union member

level: Structure/Union member

voltage: Structure/Union member

brainaccess.core.gain_mode module

class brainaccess.core.gain_mode.GainMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Gain mode multipliers

X4: 4x gain

X6: 6x gain

X8: 8x gain

X12: 12x gain

UNKNOWN: OxFF gain

UNKNOWN = 255

X12 = 5

X4 = 2

X6 = 3

X8 = 4

brainaccess.core.gain_mode.gain_mode_to_multiplier(gain_mode: GainMode) → int[source]

Converts gain mode to integer multiplier representing the gain mode

Parameters:: gain_mode (GainMode)
Returns:: integer multiplier representing the gain mode (ex: X12 returns 12)
Return type:: int

brainaccess.core.gain_mode.multiplier_to_gain_mode(multiplier: int) → GainMode[source]

Converts multiplier to the gain mode

Parameters:: multiplier (int)
Return type:: GainMode

brainaccess.core.impedance_measurement_mode module

Modes to be used for impedance measurement

class brainaccess.core.impedance_measurement_mode.ImpedanceMeasurementMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

OFF: No active impedance measurement

HZ_7_8: 7.9 Hz wave

HZ_31_2: 31.2 Hz wave

DR_DIV4: Wave frequency of sample_rate/4

DR_DIV4 = 3

HZ_31_2 = 2

HZ_7_8 = 1

OFF = 0

brainaccess.core.polarity module

class brainaccess.core.polarity.Polarity(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

BOTH = 1

NEGATIVE = 3

NONE = 0

POSITIVE = 2

brainaccess.core.version module

class brainaccess.core.version.Version(major, minor, patch)[source]

Bases: Structure

Object describing version numbers

major: API-breaking changes

minor: Feature updates

patch: Bugfixes

major: Structure/Union member

minor: Structure/Union member

patch: Structure/Union member

brainaccess.core.version.is_version_compatible(expected: str, actual: str) → bool[source]

Check if versions are compatible

Parameters:

expected (str)
actual (str)

Returns:

True if compatible

Return type:

bool

Module contents

brainaccess.core.close() → None[source]: Closes the library and cleans up afterwards.

Warning

Must be called after all BrainAccess Core library functions used by the application. Only call once. If initialization failed, do not call this function.

brainaccess.core.config_enable_logging(enable: bool) → bool[source]

Enables or disables logging

Parameters:: enable (bool) – True to enable logging, False to disable
Returns:: True if successful otherwise raises a BrainAccessException
Return type:: bool
Raises:: BrainAccessException if logging cannot be enabled –

brainaccess.core.config_set_chunk_size(chunk_size: int) → bool[source]

Sets the chunk size

Parameters:: chunk_size (int) – The chunk size to set
Returns:: True if successful otherwise raises a BrainAccessException
Return type:: bool
Raises:: BrainAccessException if chunk size is invalid –

brainaccess.core.config_set_log_level(log_level: LogLevel) → bool[source]

Sets the log level

Parameters:: log_level (LogLevel) – The log level to set
Returns:: True if successful otherwise raises a BrainAccessException
Return type:: bool
Raises:: BrainAccessException if log level is invalid –

brainaccess.core.get_device_address(device_index: int) → str[source]: Returns the address of the device at the given index

brainaccess.core.get_device_count() → int[source]: Returns the number of devices connected to the computer

brainaccess.core.get_device_name(device_index: int) → str[source]: Returns the name of the device at the given index

brainaccess.core.get_version() → Version[source]: Returns the installed library’s actual version

brainaccess.core.init() → bool[source]

Initializes the library

This function reads the config file, starts logging, etc.

bool
True if successful otherwise raises a RuntimeError

BrainAccessException if initialization fails

Must bet called before any other BrainAccess Core library function. Only call once.

init(expected_version: brainaccess.core.version.Version) -> bool

Initializes the library DEPRECATED: Use init() instead, version is not needed anymore during initialization

This function reads the config file, starts logging, etc.

version: The version of the library that the application expects.

bool: True if successful otherwise raises a RuntimeError

BrainAccessException if initialization fails

Must bet called before any other BrainAccess Core library function. Only call once.

brainaccess.core.scan(adapter_index: int = 0) → bool[source]

Scans for devices for the given amount of time

Parameters:: adapter_index (int (default: 0)) – The index of the Bluetooth adapter to use
Returns:: True if successful otherwise raises a BrainAccessException
Return type:: bool
Raises:: BrainAccessException if scanning fails –

brainaccess.core.set_config_autoflush(enable: bool = True) → bool[source]

Enables or disables autoflush in the log file

Parameters:: enable – True to enable autoflush, False to disable
Returns:: True if successful otherwise raises a BrainAccessException
Return type:: bool
Raises:: BrainAccessException if autoflush cannot be set –

brainaccess.core.set_config_path(file_path: str, append: bool = True, buffer_size: int = 512) → bool[source]

Sets the path for the core log file

Parameters:

file_path – The path to the log file
append – If True, the log file will be appended
buffer_size – The size of the buffer

Returns:

True if successful otherwise raises a BrainAccessException

Return type:

bool

Raises:

BrainAccessException if log file path cannot be set –

brainaccess.core.set_config_thread_id(enable: bool = True) → bool[source]

Enables or disables thread id in the log file

Parameters:: enable – True to enable thread id, False to disable
Returns:: True if successful otherwise raises a BrainAccessException
Return type:: bool
Raises:: BrainAccessException if thread id cannot be set –

brainaccess.core.set_config_timestamp(enable: bool = True) → bool[source]

Enables or disables timestamps in the log file

Parameters:: enable – True to enable timestamps, False to disable
Returns:: True if successful otherwise raises a BrainAccessException
Return type:: bool
Raises:: BrainAccessException if timestamp cannot be set –

brainaccess.core.set_config_update_path(file_path: str) → bool[source]

Sets the path for the update file

Parameters:: file_path – The path to the update file
Returns:: True if successful otherwise raises a BrainAccessException
Return type:: bool