brainaccess.core

Main entry point for the BrainAccess Core Python API.

This module provides a high-level interface to the BrainAccess Core library, allowing for device discovery, connection, and data streaming.

Submodules

• brainaccess.core.annotation
• brainaccess.core.battery_info
• brainaccess.core.ble_device
• brainaccess.core.charging_settings
• brainaccess.core.device_features
• brainaccess.core.device_info
• brainaccess.core.device_model
• brainaccess.core.eeg_channel
• brainaccess.core.eeg_manager
• brainaccess.core.full_battery_info
• brainaccess.core.gain_mode
• brainaccess.core.impedance_measurement_mode
• brainaccess.core.log_level
• brainaccess.core.polarity
• brainaccess.core.sBacore_config_t
• brainaccess.core.stream_rate

Functions

close()	Closes the library and releases all underlying resources.
config_enable_logging(enable)	Enables or disables the core library's internal logging.
config_set_adapter_index(adapter_index)	Selects the Bluetooth adapter to be used for scanning and connections.
config_set_chunk_size(chunk_size)	Configures the size of data chunks for EEG streaming.
config_set_log_level(log_level)	Sets the logging level for the core library.
get_config()	Return current config as a Python dict
get_config_ctypes()	Return the current configuration as a BacoreConfig ctypes struct.
get_version()	Retrieves the version of the installed BrainAccess Core library.
init()	Initializes the BrainAccess Core library.
scan()	Performs a Bluetooth scan to discover nearby BrainAccess devices.
set_config_autoflush([enable])	Enables or disables automatic flushing of the log buffer.
set_config_fields(**fields)	Update one or more core configuration settings in a single call.
set_config_path(file_path[, append, buffer_size])	Sets the file path for the core library's log output.
set_config_thread_id([enable])	Enables or disables the inclusion of thread IDs in log entries.
set_config_timestamp([enable])	Enables or disables timestamps in the log file entries.
set_config_update_path(file_path)	Sets the file path for firmware update files.

Package Contents

brainaccess.core.close()

Closes the library and releases all underlying resources.

This function should be called when the application is finished with the BrainAccess Core library to ensure a clean shutdown.

Warning

• Must be called after all other BrainAccess Core library functions.

• Only call this function once.

• Do not call this function if init() failed.

Return type:

None

brainaccess.core.config_enable_logging(enable)

Enables or disables the core library’s internal logging.

Parameters:

enable (bool) – Set to True to enable logging, False to disable it.

Returns:

True if the logging state was changed successfully.

Return type:

bool

Raises:

BrainAccessException – If the logging state cannot be changed.

brainaccess.core.config_set_adapter_index(adapter_index)

Selects the Bluetooth adapter to be used for scanning and connections.

Parameters:

adapter_index (int) – The zero-based index of the Bluetooth adapter to use.

Returns:

True if the adapter was selected successfully.

Return type:

bool

Raises:

BrainAccessException – If the adapter_index is out of bounds for the number of available adapters.

brainaccess.core.config_set_chunk_size(chunk_size)

Configures the size of data chunks for EEG streaming.

This setting affects how much data is buffered before being made available for processing. Larger chunks can improve efficiency but increase latency.

Parameters:

chunk_size (int) – The desired number of data samples per chunk.

Returns:

True if the chunk size was set successfully.

Return type:

bool

Raises:

BrainAccessException – If the provided chunk_size is invalid (e.g., zero, negative, or outside an acceptable range).

brainaccess.core.config_set_log_level(log_level)

Sets the logging level for the core library.

This controls the verbosity of the log output.

Parameters:

log_level (LogLevel) – The desired logging level from the LogLevel enum.

Returns:

True if the log level was set successfully.

Return type:

bool

Raises:

BrainAccessException – If the provided log_level is not a valid LogLevel member.

brainaccess.core.get_config()

Return current config as a Python dict

Return type:

Dict[str, Any]

brainaccess.core.get_config_ctypes()

Return the current configuration as a BacoreConfig ctypes struct.

Return type:

BacoreConfig

brainaccess.core.get_version()

Retrieves the version of the installed BrainAccess Core library.

Returns:

An object containing the major, minor, and patch version numbers.

Return type:

Version

brainaccess.core.init()

Initializes the BrainAccess Core library.

This function sets up the necessary resources for the library to function, including reading the configuration file and initializing the logging system.

Returns:

Returns True on successful initialization.

Return type:

bool

Raises:

BrainAccessException – If the library fails to initialize. This can happen if the configuration is invalid or if system resources cannot be allocated.

Warning

This function must be called once before any other function in the BrainAccess Core library. Calling it more than once or failing to call it will result in undefined behavior.

brainaccess.core.scan()

Performs a Bluetooth scan to discover nearby BrainAccess devices.

The scan duration is fixed. This function will block until the scan is

complete.

Returns:

A list of BaBleDevice objects, each representing a discovered device. Returns an empty list if no devices are found.

Return type:

list[BaBleDevice]

Raises:

BrainAccessException – If the scan fails to start, which can happen if Bluetooth is disabled or if there are issues with the Bluetooth adapter.

brainaccess.core.set_config_autoflush(enable=True)

Enables or disables automatic flushing of the log buffer.

When autoflush is enabled, log messages are written to disk immediately. Disabling it can improve performance by buffering writes, but may result in lost log messages if the application crashes.

Parameters:

enable (bool, optional) – True to enable autoflush (default), False to disable it.

Returns:

True if the setting was applied successfully.

Return type:

bool

Raises:

BrainAccessException – If the autoflush configuration fails.

brainaccess.core.set_config_fields(**fields)

Update one or more core configuration settings in a single call.

This function provides a flexible way to modify the behavior of the BrainAccess core library. You can pass any combination of keyword arguments to change multiple settings at once. Fields not provided remain unchanged.

Parameters:

**fields (dict) –

Supported keys and expected value types:

• log_buffer_sizeint

  Size of the log buffer in bytes (must be ≥ 0).

• log_pathstr

  Path to the log file (max 199 UTF-8 bytes).

• log_levelint or LogLevel

  Logging verbosity level (e.g., Error, Warning, Info, Debug).

• append_logsbool

  Whether to append to an existing log file (True) or overwrite (False).

• timestamps_enabledbool

  Include timestamps in log entries if True.

• autoflushbool

  Flush logs to disk immediately if True; may reduce performance.

• thread_ids_enabledbool

  Include thread IDs in log entries if True.

• chunk_sizeint

  Number of data samples per EEG streaming chunk (must be > 0).

• enable_logsbool

  Master switch for logging; disables all logging if False.

• update_pathstr

  Path to the firmware update file. Must exist and be ≤199 UTF-8 bytes.

• adapter_indexint

  Index of the Bluetooth adapter to use (0–255).

Returns:

True if the configuration was updated successfully.

Return type:

bool

Raises:

BrainAccessException – If an unknown field is passed, a value has the wrong type or range, a string is too long, or the firmware update file does not exist.

Examples

Enable detailed logging and set a custom log file:

>>> set_config_fields(
...     log_level=LogLevel.DEBUG,
...     log_path="logs/session.log",
...     append_logs=False
... )

brainaccess.core.set_config_path(file_path, append=True, buffer_size=512)

Sets the file path for the core library’s log output.

By default, logs may be disabled or go to a standard location. Use this function to specify a custom file for logging.

Parameters:

• file_path (str) – The absolute or relative path to the desired log file.

• append (bool, optional) – If True (default), new logs will be appended to the file if it already exists. If False, the file will be overwritten.

• buffer_size (int, optional) – The size of the log buffer in bytes. A larger buffer can improve performance by reducing the frequency of disk writes. Defaults to 512.

Returns:

True if the log file path was configured successfully.

Return type:

bool

Raises:

BrainAccessException – If the path is invalid or not writable.

brainaccess.core.set_config_thread_id(enable=True)

Enables or disables the inclusion of thread IDs in log entries.

This can be useful for debugging multi-threaded applications.

Parameters:

enable (bool, optional) – True to include the thread ID (default), False to omit it.

Returns:

True if the setting was applied successfully.

Return type:

bool

Raises:

BrainAccessException – If the thread ID configuration fails.

brainaccess.core.set_config_timestamp(enable=True)

Enables or disables timestamps in the log file entries.

Parameters:

enable (bool, optional) – True to include timestamps (default), False to omit them.

Returns:

True if the setting was applied successfully.

Return type:

bool

Raises:

BrainAccessException – If the timestamp configuration fails.

brainaccess.core.set_config_update_path(file_path)

Sets the file path for firmware update files.

Parameters:

file_path (str) – The path to the firmware update file.

Returns:

True if the path was set successfully.

Return type:

bool

Raises:

BrainAccessException – If the path is invalid or the file does not exist.