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

<port>_<MODEL>_BrainAccess — <MODEL> is HALO, MINI, MIDI, MAXI, EXG8 or Synthetic Data

type

EEG

channel format

double64 (earlier Board versions sent float32, which rounds the Sample counter once it passes 2^24 — after 9.3 h at 500 Hz)

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

BrainAccessBoardMarkers

type

Markers

channels / format

1 / string

nominal rate

0 (irregular)

source_id

BrainAccessBoardMarkers@<computer name>:<port> — unique for each running Board

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

type

unit

1

EEG electrodes in template order (Fp1, O1, …)

EEG

microvolts (kOhm in impedance mode)

2

contact_<label>, one per EEG electrode — electrode contact indicator

CONTACT

value

3

Accel_x, Accel_y, Accel_z (devices with an accelerometer)

ACCEL

m/s2

4

Gyro_x, Gyro_y, Gyro_z (devices with a gyroscope)

GYRO

deg/s

5

Digital — the headset’s digital input, 0 or 1 per sample (only when connected with “Digital input”, a support-debug-mode option)

TRIG

value

6

Sample — the device’s sample number, counted from the start of the stream (the device connect)

SAMPLE

value

7

Streaming — 1 for a sample received from the device, 0 for a sample Board filled in

MISC

value

8

Battery — battery level

BATTERY

pct

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

Accel, ACC

ACCEL

Gyro, GYR

GYRO

Battery

BATTERY

contact

CONTACT

Sample

SAMPLE

misc

MISC

Marker, Markers

MARKER

Digital

TRIG

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 unknown text. 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 filtering node 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

manufacturer

Neurotechnology (copy for older readers)

yes

yes

model

product family (copy for older readers)

yes

yes

acquisition/manufacturer

Neurotechnology

yes

yes

acquisition/model

product family (MAXI) / Synthetic Data

yes

yes

acquisition/model_variant

exact device model (HALO_V2)

yes

no

acquisition/serial_number

device serial number

yes

not_applicable

acquisition/firmware_version

major.minor.patch

yes

not_applicable

acquisition/hardware_version

device hardware version

yes

not_applicable

acquisition/precision

ADC resolution in bits: 24

yes

no

synchronization/can_drop_samples

false (see “Dropped samples”)

yes

yes

channels/channel/label

channel label

yes

yes

channels/channel/unit

unit

yes

yes

channels/channel/type

channel type

yes

yes

channels/channel/location/X

EEG channels: standard 10-05 position (mm)

yes

yes

channels/channel/location/Y

“

yes

yes

channels/channel/location/Z

“

yes

yes

channels/channel/filtering

empty: no hardware filter applied

yes

yes

channels/channel/hardware/manufacturer

EEG channels: Neurotechnology

yes

no

channels/channel/hardware/coupling

Dry

yes

no

channels/channel/hardware/material

Gold-plated

yes

no

channels/channel/hardware/surface

Pad (forehead gold pad) or Pins (spring-loaded spikes)

yes

no

reference/label

reference electrode

yes

not_applicable

reference/subtracted

No

yes

not_applicable

reference/common_average

No

yes

not_applicable

fiducials/fiducial/label

Ground

yes

not_applicable

fiducials/fiducial/location

position of the ground electrode (X/Y/Z, mm)

yes

not_applicable

cap/name

BrainAccess CAP / BrainAccess HALO

yes

not_applicable

cap/manufacturer

Neurotechnology

yes

not_applicable

cap/labelscheme

10-05

yes

yes

versions/board

BrainAccess Board version

yes

yes

versions/ba_core

BrainAccess SDK version

yes

no

versions/liblsl

LSL library version (1.17)

yes

yes

versions/lsl_protocol

LSL protocol version (1.10)

yes

yes

versions/contract

this contract’s version: 1

yes

yes

brainaccess/template_name

template file name (template_maxi)

yes

yes

brainaccess/template

device family (maxi, default)

yes

yes

brainaccess/ground

ground electrode label (Fp2; HALO Fpz)

yes

not_applicable

brainaccess/template_json

JSON text: the template’s montage settings

yes

yes

brainaccess/bias_channels

JSON text: bias feedback channels

yes

no

brainaccess/gain

JSON text: gain of each active channel

yes

no

brainaccess/hardware_filters

JSON text: {} = none applied

yes

yes

brainaccess/test_signal

true when the device sends its internal square-wave test signal instead of EEG

yes

no

brainaccess/impedance_mode

true when EEG channels carry electrode impedance (kOhm)

yes

no

brainaccess/location_source

standard_1005 (template positions, not measured)

yes

yes

brainaccess/not_applicable

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

Manufacturer

acquisition/manufacturer

ManufacturersModelName

acquisition/model (exact model: acquisition/model_variant)

DeviceSerialNumber

acquisition/serial_number

SoftwareVersions

acquisition/firmware_version

SamplingFrequency

stream nominal rate

EEGReference

reference/label

EEGGround

brainaccess/ground (position: fiducials Ground)

CapManufacturer / CapManufacturersModelName

cap/manufacturer / cap/name

EEGPlacementScheme

cap/labelscheme

HardwareFilters

channels/channel/filtering (empty = none)

EEGChannelCount, …

counted from channels/channel/type

channels.tsv name, type, units

label, type, unit

electrodes.tsv x, y, z

location/X, Y, Z

electrodes.tsv material, type

hardware/material, hardware/surface