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#

EegChunk fields#

Field

Meaning

deviceId

Per-app CoreBluetooth UUID of the device.

channels

Active EEG channel labels in column order.

srate

Rate the device streams at, in hertz: DeviceConfig.deviceSrate, which in an impedance mode too slow for the configured rate is 250.

samples

Flat row-major [sampleCount * channels.count] array. Units are µV in normal mode and kΩ in impedance mode.

sampleCount

Number of rows in this packet.

accel

Optional flat x/y/z rows in m/s².

gyro

Optional flat x/y/z rows in degrees/second on V3 hardware.

firstSampleIndex

Device sample counter for the first row, exact for the whole 32-bit counter. Each stream(outputMode:) collection numbers from its own first packet. In impedance mode it is the ADC conversion the value was measured at, and impedance chunks carry no gap-fill rows.

wireLastSampleIndex

Raw footer counter of the source packet (-1 if absent). A decrease versus the previous chunk marks a late/out-of-order packet.

packetBytes

Length of the BLE notification the chunk was decoded from.

hostTimeNs

Host monotonic timestamp, in nanoseconds, taken as the packet leaves the transport (before the queue to the decoder).

isDummy

Per-row gap-fill marker; true means the value was zero-filled for a missing device sample.

contact

Per-active-channel contact flags; false means electrode not connected.

batteryPct

Last known battery percentage, -1 until first read.

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.