Core

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)

Copyright

Copyright (c) 2022 Neurotechnology

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 instance of an EEG manager.

Returns:

A pointer to a new instance of the EEG manager. Returns nullptr if the allocation fails.

BA_CORE_DLL_EXPORT void ba_eeg_manager_free (ba_eeg_manager *instance) NOEXCEPT

Frees the memory associated with the specified EEG manager instance.

This function deallocates the resources used by the provided EEG manager. Ensure that the instance is no longer in use before calling this function.

Parameters:

instance – A pointer to the EEG manager instance to be freed. The pointer must point to an instance created earlier, and it should not be accessed after this function is called.

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

Connects to a device and attempts to initialize it.

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

• device_name – Brainaccess device name

• callback – Function to be called after the connection succeeds

• data – Data to be passed to the callback

Returns:

status if device compatible

BA_CORE_DLL_EXPORT void ba_eeg_manager_disconnect (ba_eeg_manager *instance) NOEXCEPT

Disconnects the EEG manager instance, terminating any active connection.

Parameters:

instance – A pointer to the EEG manager instance to disconnect.

BA_CORE_DLL_EXPORT bool ba_eeg_manager_is_connected (ba_eeg_manager *instance) NOEXCEPT

Checks if the EEG manager instance is currently connected.

Parameters:

instance – A pointer to the EEG manager instance to check. Must not be null.

Returns:

True if the EEG manager is connected, false otherwise.

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 EEG data using the given EEG manager instance.

Initiates data streaming using the current in-memory configuration (enabled channels, gains, bias, impedance mode, and data stream rate). If not explicitly configured since the last stop or disconnect, defaults are used where applicable (e.g., impedance measurement off; default data stream rate is 250 Hz).

Requirements:

• The manager must be connected.

• Do not call if a stream is already running.

• Wait for the callback to complete before issuing further streaming calls.

Possible return values:

Parameters:

• instance – A pointer to the EEG manager instance.

• callback – The callback function invoked after the stream start completes.

• data – User-defined data passed to the callback.

Return values:

• BA_ERROR_OK – Streaming started successfully.

• BA_ERROR_CONNECTION – The device is not connected, or a connection error occurred while starting the stream.

• BA_ERROR_WRONG_VALUE – The current configuration is invalid for streaming.

• BA_ERROR_CORE_NOT_INITIALIZED – Core isn’t initialized.

• BA_ERROR_BLUETOOTH_DISABLED – Bluetooth is disabled on the host.

• BA_ERROR_BLUETOOTH_ADAPTER_NOT_FOUND – No Bluetooth adapter found.

• BA_ERROR_ADAPTER_OUT_OF_INDEX – Selected adapter index is invalid.

• BA_ERROR_UNKNOWN – An unspecified error occurred.

Returns:

A ba_error indicating the outcome of the operation.

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 EEG data using the given EEG manager instance.

Requests the device to stop data streaming. After a successful stop, volatile per-stream configuration is cleared. To start streaming again, re-apply channel enables, gains, bias selection, impedance mode, and data stream rate as needed.

Requirements:

• The manager must be connected.

• A stream must be currently running.

• Do not call repeatedly without a new start in between.

• Wait for the callback to complete before issuing further streaming calls.

Possible return values:

Parameters:

• instance – A pointer to the EEG manager instance.

• callback – The callback function invoked after the stream stop completes.

• data – User-defined data passed to the callback.

Return values:

• BA_ERROR_OK – Streaming stopped successfully.

• BA_ERROR_CONNECTION – The device is not connected, or a connection error occurred while stopping the stream.

• BA_ERROR_WRONG_VALUE – The operation is invalid in the current state (e.g., stream not running).

• BA_ERROR_CORE_NOT_INITIALIZED – Core isn’t initialized.

• BA_ERROR_BLUETOOTH_DISABLED – Bluetooth is disabled on the host.

• BA_ERROR_BLUETOOTH_ADAPTER_NOT_FOUND – No Bluetooth adapter found.

• BA_ERROR_ADAPTER_OUT_OF_INDEX – Selected adapter index is invalid.

• BA_ERROR_UNKNOWN – An unspecified error occurred.

Returns:

A ba_error indicating the outcome of the operation.

BA_CORE_DLL_EXPORT bool ba_eeg_manager_is_streaming (const ba_eeg_manager *instance) NOEXCEPT

Checks whether EEG data streaming is currently active.

Provides a non-blocking snapshot of the streaming state. During start/stop transitions, the state may not reflect the final result until the corresponding callback has completed.

Usage notes:

• Safe to call after the manager is created.

• For definitive state after a start/stop request, wait for the associated callback and then query this function if needed.

Parameters:

instance – A pointer to the EEG manager instance.

Returns:

true if the device is currently streaming, false otherwise.

BA_CORE_DLL_EXPORT ba_battery_info ba_eeg_manager_get_battery_info (ba_eeg_manager *instance) NOEXCEPT

ba_eeg_manager_get_battery_info — Retrieves the latest battery status reported by the device.

Returns the most recently cached battery information. The device periodically reports its battery status, which the manager stores internally. This call is synchronous and does not request an update from the device; it only returns the last known values.

Defaults and freshness:

• If no battery report has been received yet for this session, the returned structure may contain default-initialized values (e.g., zeros or unspecified fields depending on the platform).

• To receive updates as they arrive, register a battery update callback with ba_eeg_manager_set_callback_battery (pass NULL to unregister), and call this function after the callback has been triggered.

See also

ba_eeg_manager_set_callback_battery

Parameters:

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

Returns:

A ba_battery_info structure with the cached battery information.

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

Loads the current in-memory configuration to the EEG device.

Sends the manager’s current configuration to the device, including enabled channels, channel gains, bias selection, impedance measurement mode, and data stream rate. The operation is asynchronous; wait for the provided callback to complete before issuing additional configuration or streaming requests.

How to set values:

• Enable or disable channels with ba_eeg_manager_set_channel_enabled(instance, ch, state).

• Set channel gains with ba_eeg_manager_set_channel_gain(instance, ch,

  gain).

• Select the bias electrode with ba_eeg_manager_set_channel_bias(instance, ch, polarity).

• Configure impedance measurement with ba_eeg_manager_set_impedance_mode(instance, mode).

• Set the data stream rate with ba_eeg_manager_set_data_stream_rate(instance, rate).

• Then call ba_eeg_manager_load_config(instance, callback, data) and wait for the callback.

Defaults:

• If a setting has not been explicitly configured since the last stop or disconnect, device defaults are applied:

  • Impedance measurement: off by default.

  • Data stream rate: 250 Hz by default.

  • Channels: all enabled.

  • Bias: all disabled.

  • Gains: all set to 8.

Requirements:

• The manager must be connected.

• Recommended to call when streaming is stopped. If called while a stream is running, the device may defer or reject the request; rely on the callback result.

Possible return values:

Parameters:

• instance – A pointer to the EEG manager instance.

• callback – The callback invoked once the configuration load completes.

• data – User-defined data passed to the callback.

Return values:

• BA_ERROR_OK – Configuration applied successfully.

• BA_ERROR_CONNECTION – The device is not connected, or a connection error occurred while applying the configuration.

• BA_ERROR_WRONG_VALUE – The configuration is invalid for the current state (e.g., not supported while streaming).

• BA_ERROR_CORE_NOT_INITIALIZED – Core isn’t initialized.

• BA_ERROR_BLUETOOTH_DISABLED – Bluetooth is disabled on the host.

• BA_ERROR_BLUETOOTH_ADAPTER_NOT_FOUND – No Bluetooth adapter found.

• BA_ERROR_ADAPTER_OUT_OF_INDEX – Selected adapter index is invalid.

• BA_ERROR_UNKNOWN – An unspecified error occurred.

Returns:

A ba_error indicating the outcome of the operation.

BA_CORE_DLL_EXPORT ba_charging_settings ba_eeg_manager_get_charging_settings (ba_eeg_manager *instance) NOEXCEPT

Retrieves the charging settings of the EEG device.

Returns the current charging behavior of the device, including whether the device is allowed to be enabled while charging and the sleep timeout (in minutes) while charging.

Defaults and persistence:

• After the device powers off, charging settings revert to defaults:

  • enabled = false

  • timeout = 20 minutes

• If a timeout value of 0 is provided, it is automatically treated as 1 minute.

How to set values:

• Prepare a ba_charging_settings structure:

  • settings.enabled = true or false

  • settings.timeout_minutes = desired timeout in minutes (0 becomes 1)

• Apply it with ba_eeg_manager_set_charging_settings(instance, settings).

See also

ba_eeg_manager_set_charging_settings

Parameters:

instance – Handle of the EEG Manager instance to retrieve the charging settings from.

Returns:

A ba_charging_settings structure containing the current charging settings on the device.

BA_CORE_DLL_EXPORT bool ba_eeg_manager_set_charging_settings (ba_eeg_manager *instance, ba_charging_settings settings) NOEXCEPT

Updates the charging settings of the EEG device.

Applies new charging behavior to the device:

• Whether the device is allowed to remain enabled while charging (settings.enabled).

• The sleep timeout in minutes while charging (settings.timeout_minutes).

Defaults and constraints:

• After the device powers off, settings revert to defaults:

  • enabled = false

  • timeout = 20 minutes

• If settings.timeout_minutes is set to 0, it is automatically treated as 1 minute.

How to set values:

• Construct a ba_charging_settings value:

  • ba_charging_settings s; s.enabled = true; s.timeout_minutes = 15;

• Call ba_eeg_manager_set_charging_settings(instance, s).

• Optionally call ba_eeg_manager_get_charging_settings afterward to confirm what the device accepted.

Requirements:

• The manager must be connected.

See also

ba_eeg_manager_get_charging_settings

Parameters:

• instance – Handle of the EEG Manager instance to configure.

• settings – A ba_charging_settings structure with desired values.

Returns:

true if the settings were successfully applied, false otherwise.

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

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

Sets the gain mode for a specific channel.

Configures the amplification applied to the selected channel. This setting is applied on the next stream start and is reset when the stream stops.

Notes:

• the configured gain already scales The returned channel data during streaming.

• If not explicitly configured before the stream starts, the device uses its default gain for that channel. The default value is 8.

How to set values:

• Choose the target channel (BA_EEG_CHANNEL_ID_ELECTRODE_MEASUREMENT + ch) and a supported gain mode (g).

• Call ba_eeg_manager_set_channel_gain(instance, BA_EEG_CHANNEL_ID_ELECTRODE_MEASUREMENT + ch, g) for each channel you wish to configure.

• Call ba_eeg_manager_load_config(instance, callback, data) and wait for the callback, then start the stream.

Requirements:

• Call before starting the stream (changes take effect on stream start).

• The manager must be connected for the configuration to be applied to the device via load_config.

Parameters:

• instance – Handle of the EEG Manager instance to configure.

• ch – Channel ID to modify.

• g – Gain mode to set for the specified channel.

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

Sets an electrode channel to be used as the bias reference.

This setting takes effect on the next stream start and is reset when the stream stops.

Channel selection:

• Use BA_EEG_CHANNEL_ID_ELECTRODE_MEASUREMENT + ch to target an electrode measurement channel, where ch is the zero-based electrode index. This ensures the bias is applied to a valid electrode channel.

How to set values:

• Compute the target channel as BA_EEG_CHANNEL_ID_ELECTRODE_MEASUREMENT + ch.

• Call ba_eeg_manager_set_channel_bias(instance, computed_channel).

• Apply settings with ba_eeg_manager_load_config(instance, callback,

  data) and wait for the callback, then start streaming.

Requirements:

• Call before starting the stream (changes take effect on stream start).

• The manager must be connected for the configuration to be pushed using load_config.

Parameters:

• instance – Handle of the EEG Manager instance to configure.

• ch – Channel ID of the electrode to set as bias (use BA_EEG_CHANNEL_ID_ELECTRODE_MEASUREMENT + index).

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

Sets electrode impedance measurement mode.

Prepares the device for electrode impedance measurement by injecting a small AC current (7 nA at a fixed frequency) through the bias electrodes to the measurement electrodes. The per-channel voltage response (Vpp) recorded during streaming can then be used to estimate electrode impedance using: Impedance = Vpp / 7 nA.

Modes:

• BA_IMPEDANCE_MEASUREMENT_MODE_OFF: No active impedance measurement.

• BA_IMPEDANCE_MEASUREMENT_MODE_HZ_7_8: 7.8 Hz test wave.

• BA_IMPEDANCE_MEASUREMENT_MODE_HZ_31_2: 31.2 Hz test wave.

• BA_IMPEDANCE_MEASUREMENT_MODE_DR_DIV4: Test wave at sample_rate/4.

Effect lifetime:

• Takes effect on the next stream start and is reset when the stream stops. Call this before every stream where impedance measurement is desired.

How to set values:

• Choose the desired impedance mode (mode).

• Call ba_eeg_manager_set_impedance_mode(instance, mode).

• Apply settings with ba_eeg_manager_load_config(instance, callback,

  data) and wait for the callback, then start streaming.

Requirements and notes:

• Call before starting the stream (changes take effect on stream start).

• The manager must be connected for the configuration to be pushed using load_config.

• At least one valid bias electrode should be configured when enabling impedance measurement to ensure proper current injection.

Parameters:

• instance – Handle of the EEG Manager instance for which to set the mode.

• mode – Impedance measurement mode to set (see a list above).

BA_CORE_DLL_EXPORT ba_error ba_eeg_manager_set_data_stream_rate (ba_eeg_manager *instance, ba_data_stream_rate rate) NOEXCEPT

Sets the data stream rate for the EEG device.

Configures how many samples per second are produced during streaming. The selected value is applied on the next stream start and does not change the rate of an already active stream.

How to set:

• Choose a supported rate from ba_data_stream_rate (e.g., 250 Hz).

• Call ba_eeg_manager_set_data_stream_rate(instance, rate).

• Apply settings with ba_eeg_manager_load_config(instance, callback,

  data), wait for the callback to complete, then start streaming.

How to check:

• Call ba_eeg_manager_get_sample_frequency(instance).

  • Before streaming: returns the configured rate that will be used on the next start.

  • During streaming: returns the active device sample rate.

Defaults:

• If not explicitly configured before streaming, the default rate is 250 Hz.

Requirements and notes:

• Call before starting the stream (changes take effect on stream start).

• The manager must be connected for the configuration to be pushed using load_config.

• If called while streaming, the new rate will take effect only after the next successful start_stream following load_config.

Device-specific supported rates:

• HALO: 250 Hz, 500 Hz, 1K Hz

• MINI: 250 Hz, 500 Hz, 1K Hz

• MIDI: 250 Hz

• MAXI: 250 Hz

Attempting to set a rate not supported by the connected device returns an error and leaves the previously configured rate unchanged.

Parameters:

• instance – Handle of the EEG Manager instance to set the stream rate for.

• rate – Desired data stream rate (see ba_data_stream_rate).

Returns:

ba_error

• BA_ERROR_OK: rate accepted and stored; will apply on the next stream start.

• BA_ERROR_UNSUPPORTED_DEVICE: a connected device does not support the requested rate.

• BA_ERROR_INVALID_ARGUMENT: rate value is invalid or out of defined range.

• BA_ERROR_CONNECTION: not connected when attempting to push configuration via load_config.

• Other error codes may be returned if underlying operations fail.

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

Retrieves a pointer to information about the connected EEG device.

Returns a pointer to a structure describing the currently connected device. The pointer refers to memory owned by the manager; do not free or modify the returned data. The contents are updated internally when the device is initialized or queried.

Usage and lifetime:

• Valid only after a successful connection.

• The returned pointer remains valid until the device is disconnected or the manager is destroyed.

• Treat the data as read-only.

Requirements:

• The manager must be connected.

Parameters:

instance – A pointer to the EEG manager instance.

Returns:

A read-only pointer to a ba_device_info structure describing the connected device, or nullptr if no device is connected.

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

Retrieves a pointer to information about the connected EEG device.

Returns a pointer to a structure describing the currently connected device. The pointer refers to memory owned by the manager; do not free or modify the returned data. The contents are updated internally when the device is initialized or queried.

Usage and lifetime:

• Valid only after a successful connection.

• The returned pointer remains valid until the device is disconnected or the manager is destroyed.

• Treat the data as read-only.

Requirements:

• The manager must be connected.

Parameters:

instance – A pointer to the EEG manager instance.

Returns:

A read-only pointer to a ba_device_info structure describing the connected device, or nullptr if no device is connected.

BA_CORE_DLL_EXPORT ba_data_stream_rate ba_eeg_manager_get_sample_frequency (const ba_eeg_manager *instance) NOEXCEPT

Retrieves the current sample frequency setting of the device.

Returns the data stream rate that the manager/device will use:

• Before streaming: the configured rate that will be applied on the next stream start (as last set by ba_eeg_manager_set_data_stream_rate).

• During streaming: the active device sample rate.

Defaults:

• If not explicitly configured, the default sample rate is 250 Hz.

Usage notes:

• Use this to verify the rate you set before starting the stream or to check the active rate while streaming.

Parameters:

instance – A pointer to the EEG manager instance.

Returns:

The current or active sample frequency as a ba_data_stream_rate value.

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 invoked whenever a new data chunk is available.

Registers a function that is called each time the manager assembles a complete data chunk during streaming. The callback may be executed on an internal reader/worker thread; keep it short and thread-safe to avoid blocking device communication. Pass NULL as a callback to disable.

Chunk size:

• Default chunk size is 25 samples.

• To change it, call ba_core_config_set_chunk_size(size) before starting streaming and while no managers are active (requires to be initialized core).

• Valid range is 1–100 samples. Larger chunks reduce callback frequency but increase latency; smaller chunks do the opposite.

Usage notes:

• Register the callback before starting the stream to avoid missing the first chunks.

• The provided data pointer is forwarded to the callback on each invocation.

• The callback will stop being invoked after the stream stops or the callback is unregistered.

Threading:

• The thread on which the callback runs is not guaranteed. Protect any shared state with synchronization primitives.

Parameters:

• instance – Handle of the EEG Manager to attach the callback to.

• callback – Function to call for each available chunk (or NULL to unregister).

• data – User-defined pointer passed through 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 invoked whenever the device reports a battery update.

Registers a function called when new battery information is received from the device. The callback may run on an internal reader/worker thread; keep it short and thread-safe to avoid blocking device communication. Pass NULL as callback to disable.

How it works:

• the device event-drives Battery updates; there is no polling.

• The manager caches the latest battery values. Inside your callback (or afterward), call ba_eeg_manager_get_battery_info(instance) to read the most recent cached data.

Usage notes:

• You can register the callback before or after connecting; updates will only arrive while connected and when the device publishes them.

• The provided data pointer is forwarded to the callback on each invocation.

• The callback stops when the device disconnects, streaming stops (if applicable), or when unregistered.

Threading:

• The execution thread is not guaranteed. Protect shared state with synchronization primitives.

Parameters:

• instance – Handle of the EEG Manager to attach the callback to.

• callback – Function to call on battery updates (or NULL to unregister).

• data – User-defined pointer passed through 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 invoked when the device disconnects.

Registers a function to be called whenever the connection to the device is lost, whether due to an expected user-initiated disconnect or an unexpected drop (e.g., out of range, power off). The callback may run on an internal reader/worker thread; keep it short and thread-safe to avoid blocking device communication. Pass NULL as callback to disable.

Usage notes:

• You may register the callback before or after connecting.

• The callback is invoked on both graceful and unexpected disconnects.

• The provided data pointer is forwarded to the callback on each invocation.

• After the callback returns, the manager remains valid but is no longer connected. Reconnect if further interaction is required.

Threading:

• The execution thread is not guaranteed. Protect shared state with synchronization primitives.

Parameters:

• instance – Handle of the EEG Manager to attach the callback to.

• callback – Function to call on device disconnect (or NULL to unregister).

• data – User-defined pointer passed through to the callback.

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

Adds an annotation at the current stream timestamp.

Records the provided text together with the current sample timestamp in the manager’s in-memory annotation list. You can later retrieve all accumulated annotations using ba_eeg_manager_get_annotations. All annotations are cleared on device disconnect.

Calibration notes:

• After starting the stream, wait for a short period to ensure annotation timestamps are properly calibrated.

• Setting annotations immediately after stream start may result in inaccurate timestamps.

• Use annotations to mark calibration events (e.g., start/end of calibration, electrode adjustment) during streaming.

• This helps synchronize calibration steps with recorded EEG data for later analysis.

Usage notes:

• Call only while streaming; before stream start the current timestamp is undefined and the operation may fail.

• Keep annotation strings reasonably short to avoid unnecessary memory usage.

Requirements:

• The manager must be connected and streaming.

Possible return values:

Parameters:

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

• annotation – Null-terminated string to record as the annotation text.

Return values:

• error::OK – Annotation recorded successfully.

• error::CONNECTION – Not connected or stream not running.

• error::ANNOTATION_UNAVAILABLE_CALIBRATING – Annotation unavailable due to calibration in progress.

Returns:

A ba_error indicating the outcome of the operation.

BA_CORE_DLL_EXPORT ba_error ba_eeg_manager_start_update (ba_eeg_manager *instance, ba_callback_ota_update callback, void *data) NOEXCEPT

Starts an over-the-air (OTA) update process for the EEG device.

This function initiates the OTA update process, allowing the device’s firmware to be updated. The operation is asynchronous, and the provided callback is invoked upon completion or failure of the update process.

Usage notes:

• Ensure the device is connected before calling this function.

• The callback function should handle both success and failure scenarios.

• The data parameter allows passing user-defined context to the callback.

Requirements:

• The manager must be connected to the device.

Possible return values:

• BA_ERROR_CONNECTION: Indicates a connection issue, such as the device not being connected.

• BA_ERROR_UPDATE_FILE_NOT_FOUND: The update file required for the operation could not be located.

• BA_ERROR_UPDATE_FAILED_DEVICE_DISCONNECTED: The update process failed because the device was disconnected.

• BA_ERROR_UPDATE_INITIATED_UNSUCCESSFULLY: The update process was started but was not successful.

• BA_ERROR_OK: Indicates that the operation completed successfully.

Parameters:

• instance – A pointer to the EEG manager instance initiating the update.

• callback – A function to be called when the update process completes. The callback should handle success and error cases.

• data – A user-defined pointer passed to the callback for context.

Returns:

A ba_error indicating the outcome of the operation.

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

Retrieves all annotations recorded during the current streaming session.

This function provides access to the annotations added during the current streaming session. Each annotation includes a timestamp and the associated text. The annotations are cleared when the device disconnects.

Usage notes:

• Call this function only while the manager is connected.

• The annotations pointer will be populated with an array of annotations, and the annotations_size pointer will indicate the number of annotations.

• The memory for the annotations array is managed by the EEG manager and should not be freed by the caller.

Requirements:

• The manager must be connected and streaming.

Parameters:

• instance – A pointer to the EEG manager instance.

• annotations – A pointer to a ba_annotation array that will be populated with the recorded annotations.

• annotations_size – A pointer to a size_t variable that will be set to the number of annotations.

BA_CORE_DLL_EXPORT void ba_eeg_manager_clear_annotations (ba_eeg_manager *instance) NOEXCEPT

Clears all annotations recorded during the current streaming session.

This function removes all annotations that were added during the current streaming session. It is useful for resetting the annotation list without disconnecting the device. Once cleared, the annotations cannot be retrieved.

Usage notes:

• Call this function only while the manager is connected.

• This operation does not affect the streaming state or other configurations.

Requirements:

• The manager must be connected.

Parameters:

instance – A pointer to the EEG manager instance.

Version numbers.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

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.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

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.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

Typedefs

typedef enum e_ba_charge_states_t e_ba_charge_states_t

Enumerator containing battery charging state.

typedef enum e_ba_charge_level_t e_ba_charge_level_t

Enumerator containing battery level status.

Enums

enum e_ba_charge_states_t

Enumerator containing battery charging state.

Values:

enumerator e_ba_charge_states_first

Battery charging state first element.

enumerator e_ba_charge_states_unknown

Battery charging state unknown.

enumerator e_ba_charge_states_charging

Battery charging state charging.

enumerator e_ba_charge_states_discharging_active

Battery charging state discharging active

enumerator e_ba_charge_states_discharging_inactive

Battery charging state discharging inactive

enumerator e_ba_charge_states_last

Battery charging state last element.

enum e_ba_charge_level_t

Enumerator containing battery level status.

Values:

enumerator e_ba_charge_level_first

Battery level status first.

enumerator e_ba_charge_level_unknown

Battery level status unknown.

enumerator e_ba_charge_level_good

Battery level status good.

enumerator e_ba_charge_level_low

Battery level status low.

enumerator e_ba_charge_level_critical

Battery level status critical.

enumerator e_ba_charge_level_last

Battery level last.

struct ba_full_battery_info

#include <full_battery_info.h>

Struct containing extended battery information received from the device.

Public Members

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

e_ba_charge_states_t charging_state

Charging state.

e_ba_charge_level_t charge_level

Charging level.

Impedance measurement mode constants.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

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.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

struct ba_annotation

#include <annotation.h>

Struct containing annotation information.

Public Members

size_t timestamp

Sample number corresponding to the time the annotation was recorded

char *annotation

Annotation text.

Gain mode.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

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

polarity modes constants

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2024 Neurotechnology

Defines

BA_POLARITY_NONE

Polarity mode none.

BA_POLARITY_BOTH

Polarity mode both (positive and negative).

BA_POLARITY_POSITIVE

Polarity mode positive.

BA_POLARITY_NEGATIVE

Polarity mode negative.

Typedefs

typedef uint8_t ba_polarity

Device features query functionality.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

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_accel (const ba_device_features *f) NOEXCEPT

Whether the device can capture accelerometer data.

Parameters:

f – Device features handle

Returns:

true if a device has an accelerometer, false otherwise

BA_CORE_DLL_EXPORT bool ba_core_device_features_has_gyro (const ba_device_features *f) NOEXCEPT

Whether the device can capture gyroscope data.

Parameters:

f – Device features handle

Returns:

true if a device has a gyroscope, false otherwise

BA_CORE_DLL_EXPORT bool ba_core_device_features_is_bipolar (const ba_device_features *f) NOEXCEPT

Whether 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 a 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:

info – Device for which to get features. The serial number is ignored.

Returns:

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

BrainAccess device info.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

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.

size_t sample_per_packet

Samples per packet.

BrainAccess device model numbers.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

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_HALO_V2

BrainAccess Halo V2.

BA_DEVICE_MODEL_UNKNOWN

Unknown device.

Typedefs

typedef uint8_t ba_device_model

Device model type.

BrainAccess BLE device.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2024 Neurotechnology

struct ba_ble_device

#include <ble_device.h>

Struct containing ble device.

Public Members

char *name

Device name.

char *mac_address

Device MAC address.

Core library info and lifecycle API.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

Defines

BA_INIT_ERROR_UNKNOWN

BA_INIT_ERROR_OK

BA_INIT_ERROR_CONFIG_TYPE

BA_INIT_ERROR_WRONG_ADAPTER_VALUE

BA_INIT_ERROR_INCOMPATIBLE_VERSION

BA_INIT_ERROR_NOT_ENABLED

BA_INIT_ERROR_NOT_FOUND

BA_INIT_ERROR_CONFIG_PARSE

BA_INIT_ERROR_INVALID_PATH

BA_INIT_WARNING_ALREADY_INITIALIZED

Typedefs

typedef struct sBACORE_Config_t sBACORE_Config_t

typedef uint8_t ba_init_error

Functions

BA_CORE_DLL_EXPORT ba_init_error ba_core_init () NOEXCEPT

Initializes the core system of the application.

This function sets up the core system, ensuring that all necessary parts and resources are properly initialized. It must be called before performing any operations that depend on the core system.

Returns:

A ba_error indicating the success or failure of the initialization. Possible error codes include:

• error::ALREADY_INITIALIZED: If the core system has already been initialized.

• error::OK: If the core system was successfully initialized.

BA_CORE_DLL_EXPORT ba_error ba_core_get_config (sBACORE_Config_t *config) NOEXCEPT

Retrieves the current core configuration.

Copies the library’s current configuration into the caller-provided sBACORE_Config_t structure. The core must be initialized with ba_core_init() before calling this function.

Parameters:

config – [out] Pointer to a pre-allocated sBACORE_Config_t structure that receives the current configuration. Must not be NULL.

Returns:

A ba_error indicating the result:

• error::OK: Configuration successfully copied.

• error::COREX_NOT_INITIALIZED: Core has not been initialized.

BA_CORE_DLL_EXPORT ba_error ba_core_set_config (sBACORE_Config_t *config) NOEXCEPT

Sets the core configuration.

Applies the provided configuration to the library. The core must be initialized with ba_core_init() before calling this function. On success, the logging subsystem is reinitialized, according to the new settings (log_buffer_size, log_path, append_logs, log_level, timestamps_enabled, thread_ids_enabled, enable_logs, autoflush). Other fields (e.g., adapter_index, chunk_size) affect later operations where relevant.

Parameters:

config – [in] Pointer to the configuration to apply. Must not be NULL.

Returns:

A ba_error indicating the result:

• error::OK: Configuration successfully applied.

• error::COREX_NOT_INITIALIZED: Core has not been initialized.

BA_CORE_DLL_EXPORT const ba_version * ba_core_get_version () NOEXCEPT

Retrieves a pointer to the library’s version information.

Provides the library’s version information, including major, minor, and patch numbers using semantic versioning. This information can be used to ensure compatibility.

Returns:

Pointer to a ba_version structure containing the library’s version information.

BA_CORE_DLL_EXPORT ba_error ba_core_scan (ba_ble_device **device_list, size_t *device_list_size) NOEXCEPT

Scans for available Bluetooth devices.

This function triggers a scan to discover nearby Bluetooth devices and populates the provided device list with the scan results.

Parameters:

• device_list – Pointer to an array of ba_ble_device pointers that will store the discovered devices

• device_list_size – Pointer to size_t that will store the number of discovered devices

Returns:

A ba_error indicating the success or failure of the scanning process. Possible error codes include:

• error::NOT_INITIALIZED: If the core system has not been initialized before the scan.

• error::OK: If the scan was successfully completed.

• error::ALREADY_SCANNING: If a scan is already in progress

• error::BLUETOOTH_NOT_ENABLED: If Bluetooth is disabled

• error::BLUETOOTH_NOT_AVAILABLE: If no Bluetooth adapter is available

• error::INVALID_PARAMETERS: If device_list or device_list_size are NULL

BA_CORE_DLL_EXPORT ba_init_error ba_core_close () NOEXCEPT

Shuts down the core system of the application.

This function performs cleanup operations, releasing all resources and components initialized by the core system. It should be called when the core system is no longer needed or before application termination.

Returns:

A ba_error indicating the success or failure of the shutdown process. Possible error codes include:

• error::NOT_INITIALIZED: If the core system was not initialized before calling this function.

• error::OK: If the core system was successfully shut down.

struct sBACORE_Config_t

Public Members

size_t log_buffer_size

char log_path[200]

Size of the log buffer (in bytes).

ba_log_level log_level

Path to the log file. Max length is 200

bool append_logs

Log level (2 = Warning).

bool timestamps_enabled

Appending to log files (false = overwrite).

bool autoflush

Enabling timestamps in logs.

bool thread_ids_enabled

Enabling autoflush of logs.

size_t chunk_size

Including thread IDs in logs.

bool enable_logs

Chunk size for data processing.

char update_path[200]

Enabling logging.

uint8_t adapter_index

Path to the firmware update file. Max length is 200

Callback function typedefs.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

Typedefs

typedef void (*ba_callback_chunk)(const void*const*, size_t, void*)

Callback function for handling EEG data stream chunks.

Param data:

Pointer to the array of EEG data stream chunk values

Param data_size:

Size of the EEG data stream chunk array

Param user_data:

User-defined data passed to the callback function

typedef void (*ba_callback_battery)(const ba_battery_info*, void*)

Callback function for handling battery information updates.

Param battery_info:

Pointer to the battery information structure

Param user_data:

User-defined data passed to the callback function

typedef void (*ba_callback_disconnect)(void*)

Callback function for handling device disconnection events.

Param user_data:

User-defined data passed to the callback function

typedef void (*ba_callback_future_void)(void*)

Callback function for handling future void results.

Param user_data:

User-defined data passed to the callback function

typedef void (*ba_callback_ota_update)(void*, const size_t, const size_t)

typedef void (*ba_callback_future_bool)(bool, void*)

Callback function for handling future boolean results.

Param result:

Boolean result

Param user_data:

User-defined data passed to the callback function

typedef void (*ba_callback_future_float)(float, void*)

Callback function for handling future float results.

Param result:

Float result

Param user_data:

User-defined data passed to the callback function

typedef void (*ba_callback_future_full_battery_info)(const ba_full_battery_info*, void*)

Callback function for handling future full battery information results.

Param result:

Pointer to the full battery information structure

Param user_data:

User-defined data passed to the callback function

Macros used to export/import library functions.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

Defines

BA_CORE_DLL_EXPORT

Macro to define export/import for Windows and GCC.

This macro is used to define the export/import symbols for Windows and GCC. When compiling the library, define BA_CORE_DLL_IS_EXPORTING to export the symbols. When using the library, do not define BA_CORE_DLL_IS_EXPORTING.

Note

This macro is used to ensure that the library functions are properly exported/imported on Windows and GCC.

NOT_BA_CORE_DLL_EXPORT

NOEXCEPT

Macro to define ‘NOEXCEPT’ for C++ and ‘NOTHROW’ for C.

This macro is used to define the ‘NOEXCEPT’ keyword for C++ and ‘NOTHROW’ for C. It ensures that the library functions are properly marked as noexcept or nothrow, depending on the language being used.

EEG data stream channel ID constants.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

Defines

BA_EEG_CHANNEL_ID_SAMPLE_NUMBER

The number of the sample starting from 0 at the 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_P

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

Data type: bool

BA_EEG_CHANNEL_ID_ELECTRODE_CONTACT

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

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

Gyroscope value.

Data type: float

BA_EEG_CHANNEL_ID_ACCELEROMETER

Accelerometer value.

Data type: float

BA_EEG_CHANNEL_ID_STREAMING

check if Sample is from a stream

Data type: bool

Typedefs

typedef uint16_t ba_eeg_channel

Type for representing EEG data stream channel IDs.

This file defines error codes used in the library.

Author

Neurotechnology (brainaccess@neurotechnology.com)

Copyright

Copyright (c) 2022 Neurotechnology

Defines

BA_ERROR_OK

No error.

BA_ERROR_CONNECTION

Connection error.

BA_ERROR_UNSUPPORTED_DEVICE

Unsupported device error.

BA_ERROR_WRONG_VALUE

Wrong value error.

BA_ERROR_BLUETOOTH_DISABLED

Bluetooth disabled error.

BA_ERROR_BLUETOOTH_ADAPTER_NOT_FOUND

Bluetooth adapter didn’t find error.

BA_ERROR_ADAPTER_OUT_OF_INDEX

Adapter out of index error.

BA_ERROR_UPDATE_FILE_NOT_FOUND

OTA update file not found.

BA_ERROR_UPDATE_INITIATED_UNSUCCESSFULLY

OTA update initiated unsuccessfully.

BA_ERROR_UPDATE_FAILED_DEVICE_DISCONNECTED

OTA update failed, device disconnect.

BA_ERROR_ANNOTATION_UNAVAILABLE_CALIBRATING

Unavailable to set annotation. Calibrating, try in a few seconds.

BA_ERROR_NO_DEVICES_FOUND

0 devices were found

BA_ERROR_NOT_ALL_MANAGERS_CLOSED

Not all managers were closed properly.

BA_ERROR_CORE_NOT_INITIALIZED

Core not initialized error.

BA_ERROR_PATH_NOT_FOUND

Path not found.

BA_ERROR_UNKNOWN

Unknown error.

Typedefs

typedef uint8_t ba_error

Type definition for error code.