BrainAccess Core C API Reference

This is the reference for classes and functions of BrainAccess Core Library used to communicate with BrainAccess devices and stream EEG and other data through Bluetooth connection.

EEG device manager.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Typedefs

typedef void ba_eeg_manager

EEG manager typedef. Note that the EEG manager is not thread-safe.

Functions

BA_CORE_DLL_EXPORT ba_eeg_manager * ba_eeg_manager_new () NOEXCEPT

Creates a new EEG manager instance.

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

Returns:

EEG manager instance handle

BA_CORE_DLL_EXPORT void ba_eeg_manager_free (ba_eeg_manager *instance) NOEXCEPT

Destroys an EEG manager instance.

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

Parameters:

instance – Handle of the EEG manager instance to destroy

BA_CORE_DLL_EXPORT void ba_eeg_manager_connect (ba_eeg_manager *instance, const char *port, ba_callback_future_bool callback, void *data) NOEXCEPT

Connects to a device via COM port and attempts to initialize it.

This function runs asynchronously. This means that this function does not block, and in order to get the result, you must use the callback. 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.

You must wait for the callback to complete before doing anything else with the EEG manager. The boolean parameter of the callback is true if the connection is successful, false otherwise.

Parameters:
  • instance – Handle of the EEG manager instance to connect to the port

  • portCOMx on Windows, /dev/rfcommX on Linux

  • callback – Function to be called after the connection succeeds

  • data – Data to be passed to the callback

BA_CORE_DLL_EXPORT void ba_eeg_manager_disconnect (ba_eeg_manager *instance) NOEXCEPT

Disconnects the EEG manager from the device, if connected.

Parameters:

instance – Handle of the EEG manager to disconnect

BA_CORE_DLL_EXPORT bool ba_eeg_manager_is_connected (ba_eeg_manager *instance) NOEXCEPT

Checks if an EEG manager is connected to any device.

Parameters:

instance – Handle of the EEG manager to check the connection status of

Returns:

true if EEG manager is connected

BA_CORE_DLL_EXPORT ba_error ba_eeg_manager_start_stream (ba_eeg_manager *instance, ba_callback_future_void callback, void *data) NOEXCEPT

Starts streaming data from the device.

This function runs asynchronously. This means that this function does not block, and in order to get the result, you must use the callback. 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.

You must not call this function twice without stopping the stream in between.

Parameters:
  • instance – Handle of the EEG manager to stream from

  • callback – Function to be called after the stream starts

  • data – Data to be passed to the callback

Returns:

Error code

BA_CORE_DLL_EXPORT ba_error ba_eeg_manager_stop_stream (ba_eeg_manager *instance, ba_callback_future_void callback, void *data) NOEXCEPT

Stops streaming data from the device.

This function runs asynchronously. This means that this function does not block, and in order to get the result, you must use the callback. 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.

You must not call this function twice without starting the stream in between. You must not call this function while the stream is not running.

Calling this function resets all stream settings. If you want to stream again afterwards, you must re-enable all the channels, biases, gains, and impedance measurement mode that you set previously.

Parameters:
  • instance – Handle of the EEG manager to stop streaming from

  • callback – Function to be called after the stream stops

  • data – Data to be passed to the callback

Returns:

Error code

BA_CORE_DLL_EXPORT bool ba_eeg_manager_is_streaming (const ba_eeg_manager *instance) NOEXCEPT

Checks if the device is streaming.

Parameters:

instance – Handle of the EEG manager to check the streaming status of

Returns:

true if the device is currently streaming

BA_CORE_DLL_EXPORT ba_error ba_eeg_manager_set_io (ba_eeg_manager *instance, uint8_t pin, bool state, ba_callback_future_void callback, void *data) NOEXCEPT

This function runs asynchronously. This means that this function does not block, and in order to get the result, you must use the callback. 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.

The digital input pin, which by default is pulled high but can be pulled low by an external sensor, can also be pulled low by the device itself. By default, upon powering up or connecting/disconnecting the device, the digital input pin is pulled high.

This can be useful, for example, in case you want to synchronize devices: connect device A and B’s digital inputs, start both streams, then set A’s digital input to pull low, which also pulls B’s input with it. The falling edge can be recorded from both streams, and the data can then be aligned accordingly.

This can also be used for low-speed communication with external devices, controlling LEDs via a mosfet, etc.

Parameters:
  • instance – Handle of the EEG manager to set the IO state of

  • pin – Number of digital input pin of the EEG device to set the IO state of (starting from 0)

  • statetrue to pull high, false to pull to ground

  • callback – Function to be called after the stream stops

  • data – Data to be passed to the callback

Returns:

Error code

BA_CORE_DLL_EXPORT const ba_battery_info ba_eeg_manager_get_battery_info (ba_eeg_manager *instance) NOEXCEPT

Gets the standard battery info from an EEG device.

The device periodically sends its battery info after an update. That info is stored in a cache and can be retrieved with this function.

Parameters:

instance – Handle of the EEG manager to get the battery info of

Returns:

Cached battery info

BA_CORE_DLL_EXPORT ba_error ba_eeg_manager_get_full_battery_info (ba_eeg_manager *instance, ba_callback_future_full_battery_info callback, void *data) NOEXCEPT

Gets the extended battery info from an EEG device.

This function runs asynchronously. This means that this function does not block, and in order to get the result, you must use the callback. 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.

Sends a request to the device for the full battery info. No caching is performed on this data.

Parameters:
  • instance – Handle of the EEG manager to get the battery info of

  • callback – Function to be called after the info is received

  • data – Data to be passed to the callback

Returns:

Error code

BA_CORE_DLL_EXPORT ba_error ba_eeg_manager_get_latency (ba_eeg_manager *instance, ba_callback_future_float callback, void *data) NOEXCEPT

Measure approximate communication latency with the device.

This function runs asynchronously. This means that this function does not block, and in order to get the result, you must use the callback. 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.

Performs a single ping request and measures the time in seconds. The float parameter of the callback is set to the latency.

Parameters:
  • instance – Handle of the EEG manager to measure the latency of

  • callback – Function to be called after the latency is measured

  • data – Data to be passed to the callback

Returns:

Error code

BA_CORE_DLL_EXPORT void ba_eeg_manager_set_channel_enabled (ba_eeg_manager *instance, ba_eeg_channel ch, bool state) NOEXCEPT

Enables the channel on the device and adds the data to the stream chunks.

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:
  • instance – Handle of the EEG Manager instance for which to enable/disable the channel

  • ch – Channel ID of the channel to enable/disable

  • state – True for enable, false for disable

BA_CORE_DLL_EXPORT void ba_eeg_manager_set_channel_gain (ba_eeg_manager *instance, ba_eeg_channel ch, ba_gain_mode g) NOEXCEPT

Changes gain mode for a channel on the device.

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.

Note that the affected channel data is already multiplied by the gain you set here.

Parameters:
  • instance – Handle of the EEG Manager instance for which to modify channel gains

  • ch – Channel ID of the channel to modify the gain of

  • g – Gain mode

BA_CORE_DLL_EXPORT void ba_eeg_manager_set_channel_bias (ba_eeg_manager *instance, ba_eeg_channel ch, ba_polarity p) NOEXCEPT

Set an electrode channel as a bias electrode.

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.

Sets channel that is used for bias feedback. The set channel signal is used to drive the bias electrode and cable shields to actively cancel common mode noise such as noise from the mains. Please select channel that is believed to have a relatively good signal.

Parameters:
  • instance – Handle of the EEG Manager instance for which to set bias

  • ch – Channel ID of the electrode to set as bias

  • p – Which side of the electrode to use (if device is not bipolar, use BOTH)

BA_CORE_DLL_EXPORT void ba_eeg_manager_set_impedance_mode (ba_eeg_manager *instance, ba_impedance_measurement_mode mode) NOEXCEPT

Sets impedance measurement mode.

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 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

Parameters:
  • instance – Handle of the EEG Manager instance for which to set impedance mode

  • mode – Impedance mode to set

BA_CORE_DLL_EXPORT const ba_device_info * ba_eeg_manager_get_device_info (const ba_eeg_manager *instance) NOEXCEPT

Get EEG device info.

Must not be called unless device connection is successful.

Parameters:

instance – Handle of the EEG Manager instance to get the device info of

Returns:

Info of the currently connected device

BA_CORE_DLL_EXPORT size_t ba_eeg_manager_get_channel_index (const ba_eeg_manager *instance, ba_eeg_channel ch) NOEXCEPT

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

Must only be used during stream (after stream start, before stream stop).

A chunk is an array of channel data (channel data being an array of values). To get the index for the channel you’re looking for, use this function.

If channel was not enabled, returns (size_t)-1

Parameters:
  • instance – Handle of the EEG Manager

  • ch – Channel to get the index of

Returns:

Index into chunk representing a channel

BA_CORE_DLL_EXPORT uint16_t ba_eeg_manager_get_sample_frequency (const ba_eeg_manager *instance) NOEXCEPT

Gets device sample rate.

Parameters:

instance – Handle of the EEG Manager to get the sample frequency of

Returns:

Sample frequency (Hz)

BA_CORE_DLL_EXPORT void ba_eeg_manager_set_callback_chunk (ba_eeg_manager *instance, ba_callback_chunk callback, void *data) NOEXCEPT

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

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.

Set to null to disable.

Parameters:
  • instance – Handle of the EEG Manager to set the callback of

  • callback – Function to be called every time a chunk is available

  • data – Data to be passed to the callback

BA_CORE_DLL_EXPORT void ba_eeg_manager_set_callback_battery (ba_eeg_manager *instance, ba_callback_battery callback, void *data) NOEXCEPT

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

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.

Set to null to disable.

Parameters:
  • instance – Handle of the EEG Manager to set the callback of

  • callback – Function to be called every time a battery update is available

  • data – Data to be passed to the callback

BA_CORE_DLL_EXPORT void ba_eeg_manager_set_callback_disconnect (ba_eeg_manager *instance, ba_callback_disconnect callback, void *data) NOEXCEPT

Sets a callback to be called every time the device disconnects.

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.

Set to null to disable.

Parameters:
  • instance – Handle of the EEG Manager to set the callback of

  • callback – Function to be called every time the device disconnects

  • data – Data to be passed to the callback

BA_CORE_DLL_EXPORT void ba_eeg_manager_annotate (ba_eeg_manager *instance, const char *annotation) NOEXCEPT

Add an annotation with the current timestamp and given string.

Should not be used before stream start.

Note that annotations are cleared on disconnect.

Parameters:
  • instance – Handle of the EEG Manager to add an annotation to

  • annotation – Annotation string to add

BA_CORE_DLL_EXPORT void ba_eeg_manager_get_annotations (const ba_eeg_manager *instance, ba_annotation **annotations, size_t *annotations_size) NOEXCEPT

Retrieve all the annotations accumulated so far.

Note that annotations are cleared on disconnect

Parameters:
  • instance – Handle of the EEG Manager to get the annotations from

  • annotations – (Output parameter) Annotation array

  • annotations_size – (Output parameter) Annotation array size

BA_CORE_DLL_EXPORT void ba_eeg_manager_clear_annotations (ba_eeg_manager *instance) NOEXCEPT

Clears all accumulated annotations.

Note that annotations are cleared on disconnect

Parameters:

instance – Handle of the EEG Manager to clear the annotations for

Version numbers.

Functions

BA_CORE_DLL_EXPORT bool ba_is_version_compatible (const ba_version *expected, const ba_version *actual) NOEXCEPT

Check if versions are compatible.

Uses semantic versioning

Parameters:
  • expected

  • actual

Returns:

true if compatible

struct ba_version
#include <version.h>

Struct describing version numbers.

Uses semantic versioning

Public Members

uint8_t major

API-breaking changes.

uint8_t minor

Feature updates.

uint8_t patch

Bugfixes.

Battery info.

struct ba_battery_info
#include <battery_info.h>

Struct containing standard battery information received from the device.

Public Members

uint8_t level

Battery charge percentage, 0-100.

bool is_charger_connected

True if charger is connected to the device.

bool is_charging

True if battery is charging.

Full battery info.

struct ba_full_battery_info
#include <full_battery_info.h>

Struct containing extended battery information received from the device.

Public Members

bool is_charging

True if battery is charging.

bool is_charger_connected

True if charger is connected to the device.

uint8_t level

Battery charge percentage, 0-100.

float health

Battery health percentage, 0-100.

float voltage

Battery voltage in volts.

float current

Current flow in amps (negative means discharge)

Defines

BA_IMPEDANCE_MEASUREMENT_MODE_OFF

No active impedance measurement.

BA_IMPEDANCE_MEASUREMENT_MODE_HZ_7_8

7.8 Hz wave

BA_IMPEDANCE_MEASUREMENT_MODE_HZ_31_2

31.2 Hz wave

BA_IMPEDANCE_MEASUREMENT_MODE_DR_DIV4

Wave frequency of sample_rate/4.

Typedefs

typedef uint8_t ba_impedance_measurement_mode

Annotation.

struct ba_annotation

Public Members

size_t timestamp

Sample number corresponding to the time the annotation was recorded.

char *annotation

Annotation text.

Defines

BA_GAIN_MODE_X1

1x gain

BA_GAIN_MODE_X2

2x gain

BA_GAIN_MODE_X4

4x gain

BA_GAIN_MODE_X6

6x gain

BA_GAIN_MODE_X8

8x gain

BA_GAIN_MODE_X12

12x gain

BA_GAIN_MODE_X24

24x gain

BA_GAIN_MODE_UNKNOWN

Unknown gain.

Typedefs

typedef uint8_t ba_gain_mode

Gain mode type.

Functions

BA_CORE_DLL_EXPORT int ba_gain_mode_to_multiplier (ba_gain_mode g) NOEXCEPT

Converts gain mode to integer multiplier representing the gain mode (ex: X12 returns 12)

Parameters:

g – Gain mode to convert to multiplier

Returns:

Integer multiplier representing the gain mode (ex: X12 returns 12)

BA_CORE_DLL_EXPORT ba_gain_mode ba_multiplier_to_gain_mode (int g) NOEXCEPT

Attempts to convert multiplier to gain mode (ex: 12 returns X12)

Parameters:

g – Multiplier to convert to gain mode

Returns:

Gain mode

Defines

BA_POLARITY_NONE
BA_POLARITY_BOTH
BA_POLARITY_POSITIVE
BA_POLARITY_NEGATIVE

Typedefs

typedef uint8_t ba_polarity

Device feature query functionality.

Typedefs

typedef void ba_device_features

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

Functions

BA_CORE_DLL_EXPORT bool ba_core_device_features_has_gyro (const ba_device_features *f) NOEXCEPT

Whether or not the device can capture gyroscope data.

Parameters:

f – Device features handle

Returns:

true if device has a gyroscope, false otherwise

BA_CORE_DLL_EXPORT bool ba_core_device_features_is_bipolar (const ba_device_features *f) NOEXCEPT

Whether or not the device’s electrodes are bipolar.

Bipolar electrodes have separate P (positive) and N (negative) contacts

Parameters:

f – Device features handle

Returns:

true if electrodes are bipolar, false otherwise

BA_CORE_DLL_EXPORT uint8_t ba_core_device_features_electrode_count (const ba_device_features *f) NOEXCEPT

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

Parameters:

f – Device features handle

Returns:

Number of electrodes

BA_CORE_DLL_EXPORT const ba_device_features * ba_core_device_features_get (const ba_device_info *info) NOEXCEPT

Gets pointer to ba_device_features instance.

The pointer is guaranteed to be statically allocated, so no need to delete or do any kind of memory management.

Parameters:

i – Device for which to get features. Serial number is ignored.

Returns:

Pointer to corresponding ba_device_features instance, or NULL if the device is not supported

struct ba_device_info
#include <device_info.h>

Struct containing device information.

Public Members

ba_device_model id

Device model number.

ba_version hardware_version

Hardware version.

ba_version firmware_version

Firmware version.

size_t serial_number

Device serial number.

BrainAccess device model numbers.

Defines

BA_DEVICE_MODEL_MINI_V2

BrainAccess MINI V2.

BA_DEVICE_MODEL_MIDI

BrainAccess MIDI (16 Channels)

BA_DEVICE_MODEL_MAXI

BrainAccess MAXI (32 Channels)

BA_DEVICE_MODEL_EMG

BrainAccess EMG.

BA_DEVICE_MODEL_HALO

BrainAccess Halo.

BA_DEVICE_MODEL_UNKNOWN

Unknown device.

Typedefs

typedef uint8_t ba_device_model

Device model type.

Core library info and lifecycle API.

Defines

BA_INIT_ERROR_UNKNOWN

Unknown error while calling ba_core_init()

BA_INIT_ERROR_OK

Initialized successfully.

BA_INIT_ERROR_CONFIG_TYPE

Configuration file contains a value of the wrong type.

BA_INIT_ERROR_CONFIG_PARSE

Configuration file could not be parsed, invalid JSON or missing value.

BA_INIT_ERROR_INCOMPATIBLE_VERSION

The version requested and the version.

Typedefs

typedef uint8_t ba_init_error

Error codes for init.

Functions

BA_CORE_DLL_EXPORT ba_init_error ba_core_init (const ba_version *version) NOEXCEPT

Initializes the library. Must be called before any other BrainAccess Core library function. Only call once.

This function reads the config file, starts logging, etc. It first checks if the version of the library that the application expects and the version of the library installed are compatible.

Parameters:

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

Returns:

Error code

BA_CORE_DLL_EXPORT const ba_version * ba_core_get_version () NOEXCEPT

Returns the installed library’s actual version.

Uses semantic versioning

Returns:

Installed library’s actual version

BA_CORE_DLL_EXPORT void ba_core_close () NOEXCEPT

Closes the library and cleans up afterwards. Must be called after all BrainAccess Core libary functions used by the application. Only call once.

If ba_core_init() failed, do not call this function.

Callback function typedefs.

Typedefs

typedef void (*ba_callback_chunk)(const void*const*, size_t, void*)
typedef void (*ba_callback_battery)(const ba_battery_info*, void*)
typedef void (*ba_callback_disconnect)(void*)
typedef void (*ba_callback_future_void)(void*)
typedef void (*ba_callback_future_bool)(bool, void*)
typedef void (*ba_callback_future_float)(float, void*)
typedef void (*ba_callback_future_full_battery_info)(const ba_full_battery_info*, void*)

Macros used to export/import library functions.

Defines

BA_CORE_DLL_EXPORT
NOT_BA_CORE_DLL_EXPORT
NOEXCEPT

EEG data stream channel ID constants.

Defines

BA_EEG_CHANNEL_ID_SAMPLE_NUMBER

The number of the sample starting from 0 at stream start.

Data type: size_t

BA_EEG_CHANNEL_ID_ELECTRODE_MEASUREMENT

EEG electrode measurement value (uV)

Data type: double

BA_EEG_CHANNEL_ID_ELECTRODE_CONTACT

Whether or not the electrode is making contact with the skin.

Data type: bool

If the device has separate P and N electrodes, the value will be true only if both electrodes are making contact.

BA_EEG_CHANNEL_ID_ELECTRODE_CONTACT_P

Whether or not the positive (P) electrode is making contact with the skin.

Data type: bool

BA_EEG_CHANNEL_ID_ELECTRODE_CONTACT_N

Whether or not the negative (N) electrode is making contact with the skin.

Data type: bool

BA_EEG_CHANNEL_ID_DIGITAL_INPUT

Digital IO pin state.

Data type: bool

BA_EEG_CHANNEL_ID_ACCELEROMETER

Accelerometer value.

Data type: float

BA_EEG_CHANNEL_ID_GYROSCOPE

Gyroscope value.

Data type: float

Typedefs

typedef uint16_t ba_eeg_channel

Error codes.

Defines

BA_ERROR_OK
BA_ERROR_CONNECTION
BA_ERROR_UNSUPPORTED_DEVICE
BA_ERROR_UNKNOWN

Typedefs

typedef uint8_t ba_error