BrainAccess Core C API Reference
This is the reference for classes and functions of BrainAccess
EEG device manager (C)
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
port –
COMx
on Windows,/dev/rfcommX
on Linuxcallback – 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)
state –
true
to pull high,false
to pull to groundcallback – 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 (C)
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
Battery info (C)
-
struct ba_battery_info
- #include <battery_info.h>
Struct containing standard battery information received from the device.
Full battery info (C)
-
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)
-
bool is_charging
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 (C)
-
struct ba_annotation
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
Typedefs
-
typedef uint8_t ba_polarity
Device feature query functionality (C)
Device feature query functionality (C++)
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.
-
ba_device_model id
BrainAccess device model numbers (C)
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_UNKNOWN
Unknown device.
Typedefs
-
typedef uint8_t ba_device_model
Device model type.
Core library info and lifecycle API (C)
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 (C/C++)
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 (C/C++)
EEG data stream channel ID constants (C)
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 (C)
Typedefs
-
typedef uint8_t ba_error