Streaming data#
Each EegChunk is one decoded BLE packet, not one sample. This keeps allocation and callback
counts low at 250–500 Hz.
Chunk layout#
Field |
Meaning |
|---|---|
|
Per-app CoreBluetooth UUID of the device. |
|
Active EEG channel labels in column order. |
|
Rate the device streams at, in hertz: |
|
Flat row-major |
|
Number of rows in this packet. |
|
Optional flat x/y/z rows in m/s². |
|
Optional flat x/y/z rows in degrees/second on V3 hardware. |
|
Device sample counter for the first row, exact for the whole 32-bit counter. Each |
|
Raw footer counter of the source packet ( |
|
Length of the BLE notification the chunk was decoded from. |
|
Host monotonic timestamp, in nanoseconds, taken as the packet leaves the transport (before the queue to the decoder). |
|
Per-row gap-fill marker; |
|
Per-active-channel contact flags; |
|
Last known battery percentage, |
Process rows#
import BrainAccessKit
func printRows(_ chunk: EegChunk) {
let columns = chunk.channels.count
for sample in 0..<chunk.sampleCount where !chunk.isDummy[sample] {
let start = sample * columns
let row = Array(chunk.samples[start ..< start + columns])
print("index", chunk.firstSampleIndex + sample, "values", row)
}
}
Hardware generation and motion units#
DeviceSession.hardware resolves the board generation from the Device Information Service Model
Number string. Missing, unparseable or other-montage values fall back to the model’s V2 board.
Sensor presence belongs to hardware, not montage:
HALO V1/V2: no IMU.
MINI V2, MIDI, MAXI: accelerometer only, converted from ADXL343 counts to m/s².
HALO V3 and EXG8: accelerometer plus gyroscope, converted from ICM-42670-P counts to m/s² and deg/s.
The current API exposes physical units in EegChunk. Raw IMU counts remain only at the protocol
EegFrame layer.
Output mode and test signal#
DeviceSession.stream(outputMode:) selects what the device streams. OutputMode.normal (the
default) streams electrode data; OutputMode.testSignal streams the ADS1299’s internal test
signal — a square wave of about 3.74 mV peak-to-peak at ~1 Hz, the same µV at every gain — on every
channel, exercising the whole acquisition and decode path without electrodes.
The output-mode characteristic exists on firmware 3.7.0 and later; gate on
DeviceSession.supportsTestSignal. The device keeps the selected mode until it is powered off, so
the SDK writes the mode on every stream start (OutputMode.normal included) whenever the
characteristic is present, and never writes it on older firmware. OutputMode.testSignal throws
BrainAccessError.testSignalNotSupported on firmware without the characteristic and
TestSignalRequiresImpedanceOff when impedance mode is on (the test signal replaces the impedance
measurement).
import BrainAccessKit
func streamTestSignal(_ session: DeviceSession) async throws {
guard session.supportsTestSignal else { return }
for try await chunk in session.stream(outputMode: .testSignal) {
print(chunk.sampleCount, "samples of test signal")
break
}
}
The test signal also exposes two limits of the firmware’s packet encoding that the decoder reproduces bit-for-bit (they are firmware limits, not SDK bugs): a sample-to-sample change beyond ±8188 counts wraps the 12-bit delta field, and the delta truncation drifts about −1.5 counts per sample inside each packet and snaps back at the next absolute sample. Real EEG transients faster than the packet rate wrap the same way.
Digital input#
Firmware 3.8.1 and later can send the level of the headset’s digital input (the first ADS1299’s
GPIO1) with every sample. session.supportsDigitalInput says whether the headset has it;
stream(digitalInput: true) on a headset without it throws
BrainAccessError.digitalInputNotSupported before anything is written.
import BrainAccessKit
func streamDigitalInput(_ session: DeviceSession) async throws {
guard session.supportsDigitalInput else { return }
for try await chunk in session.stream(digitalInput: true) {
// one Bool per sample; gap-filled samples are false
print(chunk.digitalInput ?? [])
}
}
chunk.digitalInput is nil for a stream that did not ask for it. The option is written right
before every start that asks for it (the device applies it to one start only) and never otherwise, so
a default stream writes the same sequence on every firmware. Over LSL,
streamToLsl(digitalInput: true, …) adds the Digital channel (type TRIG) of the BrainAccess
Board LSL contract. Not every board wires the pin to a connector: on one that does not, the level
reads high for the whole stream.
Markers and time sync#
To mark an event on the sample the headset was converting when it happened, ask the session at the moment of the event rather than using the newest received sample, which is late by the packet’s trip over the radio and any buffering:
import BrainAccessKit
// nil when no stream is running
let sample: Int? = session.sampleIndexAt() // now; or pass a DispatchTime uptime in nanoseconds
The time argument is on the clock of EegChunk.hostTimeNs (DispatchTime.now().uptimeNanoseconds).
The number is in the EegChunk.firstSampleIndex space (while sampleCounterJumps is 0). On
firmware 3.8.0 and later the session pings the headset’s time-sync characteristic while it streams
and maps phone time to the device’s sample counter; on older firmware, in impedance mode and in the
first half second of a stream it extrapolates from the newest packet. session.timeSyncInfo() reports which applies and how well the clocks fit.
Two more calls use the device clock only, with no packet-timing fallback (nil without a stream,
in impedance mode or without a valid fit):
session.sampleHostTimeNs(sample)— the host time at which a device sample was taken (half a conversion after its DRDY): its acquisition timestamp, as the LSL outlet uses it;session.sampleNearest(hostTime)— the sample whose acquisition time is nearest a host time, for a marker that should sit on the closest sample rather than on the one being converted.
On iOS the pings are stamped around CBPeripheral.readValue(for:) and its delegate callback, which
sit further from the radio than a lower-level BLE stack’s hooks; the fit keeps the quickest pings, which dodge most of
that, but its accuracy through CoreBluetooth has not been measured against a headset.
Gap-fill polarity#
chunk.streaming(i) returns 1 for a received sample and 0 for a zero-filled gap. The label
EegChunk.streamingLabel is the canonical companion-channel name when persisting or exporting that
mask.
Raw packet capture#
To capture packets for diagnostics or offline decoding, set DeviceSession.rawPacketCapture to a
sink. It is a static,
lock-protected (@Sendable (String) -> Void)?; nil (the default) is off and costs one locked
read per packet. While it is set, every stream packet of every session is passed to the sink as one
line in the BACAP format:
BACAP template=HALO;hw=HALO_V3;imp=false;srate=250;active=1,1,1,1;gain=8,8,8,8;mode=NORMAL;pkt=<hex>
hw is the resolved DeviceHardware (it fixes the footer layout used to decode the packet)
and mode is the stream’s OutputMode; di=1;
(just before pkt=, only for a stream started with digitalInput: true) marks a packet that
ends with the digital-input block. The sink
runs on the stream task, not the main actor, so keep it cheap and thread-safe; your app chooses the
destination.