Lab Streaming Layer#

BrainAccessLSL adapts EegChunk streams to a liblsl outlet.

Note

LSL is supported only from the source Swift package; the prebuilt distribution zip contains no BrainAccessLSL. Enabling it needs BRAINACCESS_ENABLE_LSL=1, a caller-supplied vendor/liblsl.xcframework built from liblsl v1.17.7 (64988c6, matching the committed Sources/clsl headers), and an iOS 17.0 floor for the enabled build. Neurotechnology does not ship a liblsl binary. You are responsible for liblsl’s licence notices in your app (THIRD-PARTY-NOTICES.md lists liblsl, pugixml, loguru and Boost; they apply when you enable LSL, and the zip carries the file for reference).

Without enablement the BrainAccessLSL product exists in the source package but compiles to an empty module (all code is under #if canImport(clsl)), so Core/BLE consumers do not link liblsl.

Enable LSL#

Build liblsl v1.17.7 yourself for iOS device, iOS simulator (and macOS for host tests), package it as liblsl.xcframework (see Sources/BrainAccessLSL/README.md), place it at vendor/liblsl.xcframework in the source package, then:

BRAINACCESS_ENABLE_LSL=1 swift build --manifest-cache none --target BrainAccessLSL

Enabling LSL raises the package’s iOS deployment floor from 13.0 to 17.0. Any value other than 1 is a manifest error, and 1 without vendor/liblsl.xcframework is also a manifest error; the module never silently falls back to inert behavior.

Use the session helper#

import BrainAccessKit
import BrainAccessLSL

func startLsl(_ session: DeviceSession) throws -> Task<Void, Error> {
    try session.streamToLsl(software: ["mobile": "1.0"])
}

streamToLsl(outputMode:digitalInput:software:) throws BrainAccessLslError if liblsl cannot create the outlet. The returned task starts streaming (with stream(outputMode:digitalInput:)) and closes the outlet when cancelled or when streaming ends; await its value if you want stream or push errors to propagate. software adds entries to the header’s versions node; it is an insertion-ordered OrderedMap<String> written as a dictionary literal, because the published key order matters.

The stream follows the BrainAccess Board LSL contract v1, so BrainAccess Board, LabRecorder, pyxdf and MNE read it without SDK code:

  • stream name <BLE name>_<MODEL>_BrainAccess (BrainAccessLslOutlet.contractStreamName(sourceId:model:)), source_id = the advertised BLE name (DeviceSession.name, e.g. BA MAXI 016), type EEG, double64 at the device sample rate;

  • columns in order: EEG electrodes (microvolts, kOhm in impedance mode), contact_<label> (CONTACT), Accel_x/y/z (ACCEL, m/s2) and Gyro_x/y/z (GYRO, deg/s) when the hardware has them, Digital (TRIG) when the stream was started with digitalInput: true, Sample (device sample number; exact for any recording length), Streaming (0 on a gap-filled sample), Battery (pct, -1 unknown);

  • the header carries the serial number, firmware and hardware versions, standard 10-05 electrode positions and electrode hardware, reference/ground, cap, versions and the montage (brainaccess node), built from DeviceSession.streamMetadata(channels:outputMode:software:).

StreamMetadata.toJson() produces the same metadata as Board’s StreamMetadata schema v1 JSON, e.g. for a recording sidecar.

Timestamps#

streamToLsl stamps every sample with the moment the headset took it, from the headset’s own clock (firmware 3.8.0+, DeviceSession.sampleHostTimeNs(_:)), to within about a millisecond, instead of the moment its packet reached the phone, which is tens of milliseconds later and varies by several. Until the clock is fitted (the first seconds of a stream) chunks are held and then pushed in order with their exact timestamps. Without time sync (firmware before 3.8.0, impedance mode) the stream’s first chunks are held for 5 s, and from then on every chunk is stamped on arrival. The timestamps are on liblsl’s lsl_local_clock(), as LSL receivers expect.

BrainAccessLslOutlet takes the same time source as an optional sampleTimes argument (sampleTimes: { session.sampleHostTimeNs($0) }); without it, liblsl stamps each chunk when it is pushed.

Driving the outlet directly#

Build the metadata from the session and hand it to the outlet. The metadata’s channels must equal lslContractChannels(...) for their own shape (EEG labels, accelerometer/gyroscope presence, impedance mode); anything else is rejected with BrainAccessLslError.metadataMismatch.

import BrainAccessKit
import BrainAccessLSL

func pushToCustomOutlet(_ session: DeviceSession) async throws {
    let config = session.currentConfig()
    let activeChannels = config.channels.enumerated().compactMap { index, label in
        config.active[index] ? label : nil
    }
    let channels = lslContractChannels(
        eegLabels: activeChannels,
        hasAccel: session.hardware.hasAccel,
        hasGyro: session.hardware.hasGyro,
        impedance: config.impedanceMode.active
    )
    let outlet = try BrainAccessLslOutlet(
        streamName: BrainAccessLslOutlet.contractStreamName(sourceId: session.name, model: session.model),
        sourceId: session.name,
        metadata: session.streamMetadata(channels: channels, outputMode: .normal)
    )
    defer { outlet.close() }

    for try await chunk in session.stream() {
        try outlet.push(chunk)
    }
}

Errors and output mode#

Both the outlet initializer and push(_:) throw BrainAccessLslError: metadataMismatch, streamInfoCreationFailed and outletCreationFailed at construction, and columnMismatch or pushFailed from push. push surfaces negative liblsl push error codes.

The output mode is published as brainaccess/test_signal in the stream header, so a consumer can tell the ADS1299 test signal from electrode data. Pass the same outputMode to streamMetadata(channels:outputMode:software:) and session.stream(outputMode:).

Column layout#

[EEG…][contact_<label>…][Accel_x/y/z]?[Gyro_x/y/z]?[Digital]?[Sample][Streaming][Battery]. contact_* repeats the chunk’s contact flags (1 = connected) for every row; Digital is present only when the stream was started with digitalInput: true (type TRIG, unit value, 1 or 0 per sample: the level of the headset’s digital input, 0 on a gap-filled sample); Sample is firstSampleIndex + s; Streaming is 1 for samples that arrived over the air and 0 for zero-filled gap samples; Battery is the percentage or -1. The channel list is available without liblsl via the pure lslContractChannels(eegLabels:hasAccel:hasGyro:impedance:digitalInput:), which returns ChannelMetadata values (label, type, unit, location, hardware).