LSL contract (v1)#
This page is the published contract for the Lab Streaming Layer (LSL) streams BrainAccess Board sends. Any LSL client — another Board, LabRecorder, pyxdf, MNE / mnelab, your own code — can rely on it.
The stream header follows the XDF meta-data conventions
(EEG meta-data,
synchronization meta-data),
so general LSL tools read it without Board. Values specific to
BrainAccess live in a brainaccess node.
The contract version is published in every data stream as
versions/contract. This page describes version 1.
Streams#
Data stream (one per connected device)#
Property |
Value |
|---|---|
name |
|
type |
|
channel format |
|
nominal rate |
the device sample rate (template Sample Rate; synthetic data: 250 Hz) |
source_id |
the device’s port / Bluetooth name (the stream-name prefix) — stable, so LSL clients can reconnect after an interruption |
chunks |
25 samples per chunk, stamped with the acquisition computer’s LSL clock |
Marker stream (one per Board)#
Property |
Value |
|---|---|
name |
|
type |
|
channels / format |
1 / |
nominal rate |
|
source_id |
|
The marker stream carries the text of every marker added in Board (View screen or the Board API). It has no further header meta-data.
Channels#
BrainAccess devices#
Channels appear in this order:
Order |
Channel labels |
|
|
|---|---|---|---|
1 |
EEG electrodes in template order ( |
|
|
2 |
|
|
|
3 |
|
|
|
4 |
|
|
|
5 |
|
|
|
6 |
|
|
|
7 |
|
|
|
8 |
|
|
|
Channels named in the template as EOG / EMG / ECG electrodes (for
example EOG1) get the type EOG / EMG / ECG instead of EEG.
Synthetic data#
Only the template’s active channels, typed from the channel name
(normally EEG, unit microvolts). No contact, motion, sample,
streaming or battery channels.
Channel types#
The full set of types Board uses: EEG, EOG, EMG, ECG,
FNIRS, FNIRS_OD, HBO, HBR, ACCEL, GYRO, BATTERY,
CONTACT, SAMPLE, MISC, MARKER, TRIG.
Board versions before contract v1 wrote some types in other spellings. Board still reads those streams and recordings and converts the types:
Older spelling |
Contract v1 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Dropped samples#
The data stream never skips samples: if the device loses a packet
(for example on a weak Bluetooth link), Board fills the missing
samples so the stream keeps its regular rate. The header therefore
states synchronization/can_drop_samples = false.
Filled samples have Streaming = 0 and zero in the EEG, motion and
contact channels (in impedance mode the last impedance value is
repeated). They are numbered in sequence like received
samples, so Sample keeps counting through them: use Streaming,
not Sample, to find them. A gap too long to fill (several seconds)
is left unfilled; Sample then jumps by the number of samples lost.
The stream is double64 so Sample stays exact however long the
device streams.
Header reference#
The header is written once, when the device connects, and does not change while the stream exists. Impedance mode, test signal and the template are fixed for the stream — reconnect the device to change them.
Value rules#
Unknown values are left out — no empty node, no
unknowntext. A missing node means “not stated”.Values that cannot exist for the source (synthetic data has no serial number, firmware, reference, ground or cap) are left out and listed in
brainaccess/not_applicable.Booleans are
true/false; numbers are plain decimal text.Positions are in millimetres: X to the right, Y to the front, Z up (standard 10-05 electrode positions from the template, not measured positions).
An empty
filteringnode means no hardware filter was applied; BrainAccess devices apply none.
Nodes#
Paths are relative to the header’s desc element.
BA = BrainAccess device stream, Syn = synthetic stream;
yes = always written, no / not_applicable = not written.
channels/channel/… entries describe each EEG channel.
Path |
Content |
BA |
Syn |
|---|---|---|---|
|
|
yes |
yes |
|
product family (copy for older readers) |
yes |
yes |
|
|
yes |
yes |
|
product family ( |
yes |
yes |
|
exact device model ( |
yes |
no |
|
device serial number |
yes |
|
|
|
yes |
|
|
device hardware version |
yes |
|
|
ADC resolution in bits: |
yes |
no |
|
|
yes |
yes |
|
channel label |
yes |
yes |
|
unit |
yes |
yes |
|
channel type |
yes |
yes |
|
EEG channels: standard 10-05 position (mm) |
yes |
yes |
|
“ |
yes |
yes |
|
“ |
yes |
yes |
|
empty: no hardware filter applied |
yes |
yes |
|
EEG channels: |
yes |
no |
|
|
yes |
no |
|
|
yes |
no |
|
|
yes |
no |
|
reference electrode |
yes |
|
|
|
yes |
|
|
|
yes |
|
|
|
yes |
|
|
position of the ground electrode (X/Y/Z, mm) |
yes |
|
|
|
yes |
|
|
|
yes |
|
|
|
yes |
yes |
|
BrainAccess Board version |
yes |
yes |
|
BrainAccess SDK version |
yes |
no |
|
LSL library version ( |
yes |
yes |
|
LSL protocol version ( |
yes |
yes |
|
this contract’s version: |
yes |
yes |
|
template file name ( |
yes |
yes |
|
device family ( |
yes |
yes |
|
ground electrode label ( |
yes |
|
|
JSON text: the template’s montage settings |
yes |
yes |
|
JSON text: bias feedback channels |
yes |
no |
|
JSON text: gain of each active channel |
yes |
no |
|
JSON text: |
yes |
yes |
|
|
yes |
no |
|
|
yes |
no |
|
|
yes |
yes |
|
comma-separated fields that cannot exist for the source |
no |
yes |
Electrodes#
BrainAccess CAP and HALO electrodes are dry-contact and gold-plated.
The forehead electrodes Fp1 and Fp2 are gold pads, published as
surface Pad; every other EEG electrode has spring-loaded spikes,
published as Pins. This holds for every BrainAccess device (HALO,
MINI, MIDI, MAXI, EXG8).
If your cap has pads at other positions, change electrode_pad_channels
in the template file (see Device templates).
Impedance mode and test signal#
In impedance mode the EEG channels carry electrode impedance in
kOhm and brainaccess/impedance_mode is true. With the test
signal on, the device sends its internal square wave instead of
electrode data and brainaccess/test_signal is true — such a
stream is never real EEG.
Not published yet#
acquisition/compensated_lag (the delay from the electrode to the
LSL time stamp) will be added once it has been measured.
Mapping to BIDS#
How the contract fields fill a BIDS EEG dataset. Task, power-line frequency, subject, session and run describe the recording, not the device, and are not in the stream.
BIDS field |
Contract field |
|---|---|
|
|
|
|
|
|
|
|
|
stream nominal rate |
|
|
|
|
|
|
|
|
|
|
|
counted from |
|
|
|
|
|
|