Troubleshooting#

This page covers common issues with the packaged .mltbx toolbox install and the first device connection flow.

Toolbox Does Not Install#

Check these first:

  • use the toolbox package built for your platform

  • use desktop MATLAB R2025b or newer

  • uninstall older BrainAccess MATLAB API toolbox versions before reinstalling

If the installer reports a conflict, remove the older add-on from MATLAB’s Add-On Manager and install the new .mltbx again.

ba_setup Is Not Found#

If the toolbox appears installed but MATLAB cannot resolve ba_setup, refresh the toolbox cache and verify that the installed toolbox is on the path:

which ba_setup -all
rehash toolboxcache
which ba_setup -all

If which still returns nothing, reinstall the toolbox from the packaged .mltbx file.

No Devices Appear In ba_scan#

Use this minimal check after installation:

ba_setup();
ba_init();
devices = ba_scan();
disp({devices.name});
ba_close();

If the scan list is empty:

  • make sure the BrainAccess device is powered on

  • keep the device close to the machine running MATLAB

  • use the Bluetooth name printed on the device label

  • do not pair the device in the operating system Bluetooth settings

  • close other software that may already be talking to the device

Connection Or Stream Setup Fails#

If discovery works but connection or streaming does not:

  • rerun the first connection check from Installation

  • confirm that the selected channel IDs fit the reported features.electrode_count

  • retry after fully closing MATLAB so the native runtime starts from a clean session

  • reinstall the toolbox if which ba_setup -all resolves to an unexpected location

Linux Loader Check#

If ba_setup fails on Linux or MATLAB reports that a shared library cannot be opened, inspect the packaged MEX dependencies from a shell. First resolve the installed toolbox location from MATLAB:

which ba_setup -all

Then run ldd against the installed ba_core_mex.mexa64 file:

ldd /path/to/installed/toolbox/matlab/private/ba_core_mex.mexa64

The expected packaged resolutions are:

  • libbacore.so.3.6.0 from matlab/private

  • libsimpleble.so.0 from matlab/private

The Linux runtime also depends on the system libdbus-1.so.3 library.

Linux Bluetooth And D-Bus#

On Linux, BLE access goes through the system D-Bus bus. MATLAB ships its own libdbus-1 whose built-in system bus socket path does not exist on user machines, so ba_setup and ba_init automatically point the D-Bus client at the standard system bus by setting DBUS_SYSTEM_BUS_ADDRESS when it is unset. No action is normally required.

If scanning or connecting still fails on Linux:

  • confirm the system D-Bus daemon is running and its socket exists (/run/dbus/system_bus_socket)

  • confirm a Bluetooth adapter is present and powered (bluetoothctl show)

  • if your system bus uses a non-standard address, export it yourself before starting MATLAB, for example export DBUS_SYSTEM_BUS_ADDRESS=unix:path=/run/dbus/system_bus_socket; the toolbox never overrides an explicit value