BrainAccess Core C++ API Reference
This is the reference for classes and functions of BrainAccess
EEG device manager (C++)
Gain mode (C)
-
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:
port –
COMx
on Windows,/dev/rfcommX
on Linuxcallback – 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)
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
-
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
-
virtual ~eeg_manager() noexcept = default
-
class eeg_manager
-
static eeg_manager *eeg_manager_new() noexcept
-
namespace core
Version numbers (C++)
-
namespace brainaccess
-
namespace core
Typedefs
-
typedef ba_version version
Struct describing version numbers.
Uses semantic versioning
-
typedef ba_version version
-
namespace core
-
namespace brainaccess
-
namespace core
Typedefs
-
typedef ba_battery_info battery_info
-
typedef ba_battery_info battery_info
-
namespace core
-
namespace brainaccess
-
namespace core
Typedefs
-
typedef ba_full_battery_info full_battery_info
-
typedef ba_full_battery_info full_battery_info
-
namespace core
Impedance measurement mode constants (C++)
-
namespace brainaccess
-
namespace core
-
namespace core
-
namespace brainaccess
-
namespace core
Typedefs
-
typedef ba_annotation annotation
-
typedef ba_annotation annotation
-
namespace core
Gain mode (C++)
-
namespace brainaccess
-
namespace core
Enums
-
namespace core
-
namespace brainaccess
-
namespace core
-
namespace core
-
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
-
virtual ~device_features() noexcept = default
-
class device_features
-
static const device_features *device_features_get(const device_info &i) noexcept
-
namespace core
-
namespace brainaccess
-
namespace core
Typedefs
-
typedef ba_device_info device_info
-
typedef ba_device_info device_info
-
namespace core
-
namespace brainaccess
-
namespace core
-
namespace core
Core library info and lifecycle API (C++)
-
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.
-
enumerator UNKNOWN
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.
-
enum class init_error : ba_init_error
-
namespace core
-
namespace brainaccess
-
namespace core
-
namespace core
Warning
doxygenfile: Cannot find file “dllexport.hpp
EEG data stream channel ID constants (C++)
-
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
-
static constexpr eeg_channel SAMPLE_NUMBER = BA_EEG_CHANNEL_ID_SAMPLE_NUMBER
-
typedef ba_eeg_channel eeg_channel
-
namespace core
Error codes (C++)
-
namespace brainaccess
-
namespace core
-
namespace core