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), typeEEG,double64at the device sample rate;columns in order: EEG electrodes (
microvolts,kOhmin impedance mode),contact_<label>(CONTACT),Accel_x/y/z(ACCEL,m/s2) andGyro_x/y/z(GYRO,deg/s) when the hardware has them,Digital(TRIG) when the stream was started withdigitalInput: 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 (
brainaccessnode), built fromDeviceSession.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).