Usage#

This guide demonstrates how to connect to a BrainAccess device and acquire EEG data from MATLAB using the public ba_* functions.

Quickstart: Data Acquisition with MATLAB Wrappers#

The typical MATLAB workflow involves these steps:

  1. Initialize the runtime: Call ba_setup() and ba_init().

  2. Discover or select a device: Use ba_scan() and choose a Bluetooth device name.

  3. Configure EEG: Call ba_configure_eeg(...) with the desired channels and sample rate.

  4. Start acquisition: Call ba_start_stream().

  5. Retrieve data: Use ba_read_chunk(...) or ba_collect_seconds(...) to pull data into MATLAB arrays.

  6. Stop acquisition: Call ba_stop_stream(), then disconnect and close.

Here is the recommended minimal acquisition flow:

ba_setup();
ba_init();

devices = ba_scan();
device_name = devices(1).name;

ba_connect(device_name);
features = ba_get_device_features();
channel_ids = 0:(features.electrode_count - 1);
ba_configure_eeg(channel_ids, 250, 8, []);
ba_start_stream();

[data, meta] = ba_collect_seconds(5.0, 250, true);

ba_stop_stream();
ba_disconnect();
ba_close();

plot(data');

Continuous Data Acquisition with Annotations#

This mirrors the Python acquisition example that starts a stream, sends annotations while the stream is running, then saves and plots the collected data. In MATLAB the session is typically saved to a .mat file.

ba_setup();
ba_init();

devices = ba_scan();
device_name = devices(1).name;

ba_connect(device_name);
features = ba_get_device_features();
channel_ids = 0:(features.electrode_count - 1);
ba_configure_eeg(channel_ids, 250, 8, []);
ba_start_stream();

pause(5.0);

all_data = [];
for annotation = 1:10
    pause(1.0);
    ba_annotate(num2str(annotation));

    [chunk, meta] = ba_read_chunk(1000, true);
    if meta.available && ~isempty(chunk)
        all_data = [all_data, chunk];
    end
end

annotations = ba_get_annotations();

ba_stop_stream();
ba_disconnect();
ba_close();

save("brainaccess-session.mat", "all_data", "annotations");
plot(all_data');

Minimal Data Acquisition#

This is the MATLAB equivalent of the low-level Python core acquisition example. It keeps the flow explicit: scan, connect, configure, stream, read, stop.

ba_setup();
ba_init();

devices = ba_scan();
device_name = devices(1).name;

ba_connect(device_name);
features = ba_get_device_features();
channel_ids = 0:(features.electrode_count - 1);
ba_configure_eeg(channel_ids, 250, 8, []);
ba_start_stream();

pause(2.0);
[chunk, meta] = ba_read_chunk(1000, true);

ba_stop_stream();
ba_disconnect();
ba_close();

disp(meta);
plot(chunk');

Full Example Files#

Runnable example files that implement these flows:

API Reference#

For detailed information on all public MATLAB entry points, refer to the API Reference reference.