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.

namespace brainaccess
namespace core

Functions

static eeg_manager *eeg_manager_new() noexcept

Creates a new EEG manager instance.

Returns:

EEG manager instance handle

namespace abi_0
class eeg_manager
#include <eeg_manager.hpp>

The EEG manager is the primary tool for communicating with the BrainAccess device. Note that the EEG manager is not thread-safe.

Public Functions

virtual ~eeg_manager() noexcept = default

Destroys an EEG manager instance.

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

virtual void connect(const char *port, ba_callback_future_bool callback, void *data) noexcept = 0

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:
  • portCOMx on Windows, /dev/rfcommX on Linux

  • callback – Function to be called after the connection succeeds

  • data – Data to be passed to the callback

virtual void disconnect() noexcept = 0

Disconnects the EEG manager from the device, if connected.

virtual bool is_connected() noexcept = 0

Checks if an EEG manager is connected to any device.

Returns:

true if EEG manager is connected

virtual error start_stream(ba_callback_future_void callback, void *data) noexcept = 0

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:
  • callback – Function to be called after the stream starts

  • data – Data to be passed to the callback

Returns:

Error code

virtual error stop_stream(ba_callback_future_void callback, void *data) noexcept = 0

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:
  • callback – Function to be called after the stream stops

  • data – Data to be passed to the callback

Returns:

Error code

virtual bool is_streaming() const noexcept = 0

Checks if the device is streaming.

Returns:

true if the device is currently streaming

virtual error set_io(uint8_t pin, bool state, ba_callback_future_void callback, void *data) noexcept = 0

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

virtual battery_info get_battery_info() noexcept = 0

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.

Returns:

Cached battery info

virtual error get_full_battery_info(ba_callback_future_full_battery_info callback, void *data) noexcept = 0

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:
  • callback – Function to be called after the info is received

  • data – Data to be passed to the callback

Returns:

Error code

virtual error get_latency(ba_callback_future_float callback, void *data) noexcept = 0

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:
  • callback – Function to be called after the latency is measured

  • data – Data to be passed to the callback

Returns:

Error code

virtual void set_channel_enabled(eeg_channel ch, bool state) noexcept = 0

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:
  • ch – Channel ID of the channel to enable/disable

  • state – True for enable, false for disable

virtual void set_channel_gain(eeg_channel ch, gain_mode g) noexcept = 0

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:
  • ch – Channel ID of the channel to modify the gain of

  • g – Gain mode

virtual void set_channel_bias(eeg_channel ch, polarity p) noexcept = 0

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:
  • 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)

virtual void set_impedance_mode(impedance_measurement_mode mode) noexcept = 0

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:

mode – Impedance mode to set

virtual const device_info &get_device_info() const noexcept = 0

Get EEG device info.

Must not be called unless device connection is successful.

Returns:

Info of the currently connected device

virtual size_t get_channel_index(eeg_channel ch) const noexcept = 0

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:

ch – Channel to get the index of

Returns:

Index into chunk representing a channel

virtual uint16_t get_sample_frequency() const noexcept = 0

Gets device sample rate.

Returns:

Sample frequency (Hz)

virtual void set_callback_chunk(ba_callback_chunk callback, void *data) noexcept = 0

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:
  • callback – Function to be called every time a chunk is available

  • data – Data to be passed to the callback

virtual void set_callback_battery(ba_callback_battery callback, void *data) noexcept = 0

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:
  • callback – Function to be called every time a battery update is available

  • data – Data to be passed to the callback

virtual void set_callback_disconnect(ba_callback_disconnect callback, void *data) noexcept = 0

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:
  • callback – Function to be called every time the device disconnects

  • data – Data to be passed to the callback

virtual void annotate(const char *annotation) noexcept = 0

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:

annotation – Annotation string to add

virtual void get_annotations(annotation **annotations, size_t *annotations_size) const noexcept = 0

Retrieve all the annotations accumulated so far.

Note that annotations are cleared on disconnect

Parameters:
  • annotations – (Output parameter) Annotation array

  • annotations_size – (Output parameter) Annotation array size

virtual void clear_annotations() noexcept = 0

Clears all accumulated annotations.

Note that annotations are cleared on disconnect

Version numbers.

namespace brainaccess
namespace core

Typedefs

typedef ba_version version

Struct describing version numbers.

Uses semantic versioning

Functions

static bool is_version_compatible(const version &expected, const version &actual) noexcept

Check if versions are compatible.

Uses semantic versioning

Parameters:
  • expected

  • actual

Returns:

true if compatible

Battery info.

namespace brainaccess
namespace core

Typedefs

typedef ba_battery_info battery_info

Full battery info.

namespace brainaccess
namespace core

Typedefs

typedef ba_full_battery_info full_battery_info

Impedance measurement mode constants.

namespace brainaccess
namespace core

Enums

enum class impedance_measurement_mode : ba_impedance_measurement_mode

Values:

enumerator OFF

No active impedance measurement.

enumerator HZ_7_8

7.8 Hz wave

enumerator HZ_31_2

31.2 Hz wave

enumerator DR_DIV4

Wave frequency of sample_rate/4.

Annotation.

namespace brainaccess
namespace core

Typedefs

typedef ba_annotation annotation

Gain mode.

namespace brainaccess
namespace core

Enums

enum class gain_mode : ba_gain_mode

Gain mode enum.

Values:

enumerator X1

1x gain

enumerator X2

2x gain

enumerator X4

4x gain

enumerator X6

6x gain

enumerator X8

8x gain

enumerator X12

12x gain

enumerator X24

24x gain

enumerator UNKNOWN

Unknown gain.

Functions

static int gain_mode_to_multiplier(const 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)

static gain_mode multiplier_to_gain_mode(const 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

namespace brainaccess
namespace core

Enums

enum class polarity : ba_polarity

Values:

enumerator NONE
enumerator BOTH
enumerator POSITIVE
enumerator NEGATIVE

Device feature query functionality.

namespace brainaccess
namespace core

Functions

static const device_features *device_features_get(const device_info &i) noexcept

Gets pointer to 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 device_features instance, or nullptr if the device is not supported

namespace abi_0
class device_features
#include <device_features.hpp>

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

Public Functions

virtual ~device_features() noexcept = default
virtual bool has_gyro() const noexcept = 0

Whether or not the device can capture gyroscope data.

Returns:

true if device has a gyroscope, false otherwise

virtual bool is_bipolar() const noexcept = 0

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

virtual uint8_t electrode_count() const noexcept = 0

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

Returns:

Number of electrodes

BrainAccess device info.

namespace brainaccess
namespace core

Typedefs

typedef ba_device_info device_info

BrainAccess device model numbers.

namespace brainaccess
namespace core

Enums

enum class device_model : ba_device_model

Values:

enumerator MINI_V2

BrainAccess MINI V2.

enumerator MIDI

BrainAccess MIDI (16 Channels)

enumerator MAXI

BrainAccess MAXI (32 Channels)

enumerator EMG

BrainAccess EMG.

enumerator HALO

BrainAccess Halo.

enumerator UNKNOWN

Unknown device.

Core library info and lifecycle API.

namespace brainaccess
namespace core

Enums

enum class init_error : ba_init_error

Error codes for init.

Values:

enumerator UNKNOWN

Unknown error while calling core::init()

enumerator OK

Initialized successfully.

enumerator CONFIG_TYPE

Configuration file contains a value of the wrong type.

enumerator CONFIG_PARSE

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

enumerator INCOMPATIBLE_VERSION

The version requested and the version.

Functions

static init_error init(const 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

static const version &get_version() noexcept

Returns the installed library’s actual version.

Uses semantic versioning

Returns:

Installed library’s actual version

static void 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 core::init() failed, do not call this function.

Callback function typedefs.

namespace brainaccess
namespace core

Warning

doxygenfile: Cannot find file “dllexport.hpp

EEG data stream channel ID constants.

namespace brainaccess
namespace core

Typedefs

typedef ba_eeg_channel eeg_channel
namespace eeg_channel_id

Variables

static constexpr eeg_channel SAMPLE_NUMBER = BA_EEG_CHANNEL_ID_SAMPLE_NUMBER

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

Data type: size_t

static constexpr eeg_channel ELECTRODE_MEASUREMENT = BA_EEG_CHANNEL_ID_ELECTRODE_MEASUREMENT

EEG electrode measurement value (uV)

Data type: double

static constexpr eeg_channel ELECTRODE_CONTACT = 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.

static constexpr eeg_channel ELECTRODE_CONTACT_P = BA_EEG_CHANNEL_ID_ELECTRODE_CONTACT_P

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

Data type: bool

static constexpr eeg_channel ELECTRODE_CONTACT_N = BA_EEG_CHANNEL_ID_ELECTRODE_CONTACT_N

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

Data type: bool

static constexpr eeg_channel DIGITAL_INPUT = BA_EEG_CHANNEL_ID_DIGITAL_INPUT

Digital IO pin state.

Data type: bool

static constexpr eeg_channel ACCELEROMETER = BA_EEG_CHANNEL_ID_ACCELEROMETER

Accelerometer value.

Data type: float

static constexpr eeg_channel GYROSCOPE = BA_EEG_CHANNEL_ID_GYROSCOPE

Gyroscope value.

Data type: float

Error codes.

namespace brainaccess
namespace core

Enums

enum class error : ba_error

Error codes.

Values:

enumerator OK

Successful.

enumerator CONNECTION

Connection error.

enumerator UNSUPPORTED_DEVICE

Unsupported device.

enumerator UNKNOWN

Unknown error.