Configuration#

DeviceConfig describes the montage sent to the headset: labels, gain, bias, active channels, sample rate and impedance mode. Every model has a factory default via DeviceModel.defaultConfig().

Apply a config#

import BrainAccessKit

func setHaloTo500Hz(_ session: DeviceSession) async throws {
    let base = DeviceModel.halo.defaultConfig()
    let config = DeviceConfig(
        model: base.model,
        channels: base.channels,
        gain: base.gain,
        bias: base.bias,
        active: base.active,
        srate: 500,
        impedanceMode: base.impedanceMode
    )
    try await session.configure(config).get()
}

A config whose model differs from the connected device fails with ConfigModelMismatch instead of writing a wrongly sized payload.

Persistence#

The default store is in-memory. To persist per-headset settings across launches, inject UserDefaultsConfigStore:

import BrainAccessKit

func makePersistentClient() -> BrainAccessClient {
    BrainAccessClient(
        transport: CoreBluetoothTransport(),
        store: UserDefaultsConfigStore()
    )
}

Configs are keyed by DeviceId (the app-scoped CoreBluetooth peripheral UUID), not by model. This prevents applying one physical headset’s edited montage to another unit of the same model.

Impedance modes#

ImpedanceMode.off streams EEG in microvolts. Any non-off mode makes the device inject a small AC test current and stream device-computed electrode impedance in kΩ in EegChunk.samples.

The rate the device streams at is DeviceConfig.deviceSrate, which is srate except in an impedance mode too slow for it: hz7_8 above 250 Hz and hz31_2 above 1000 Hz stream at 250 Hz (the firmware’s fixed 20-sample window cannot span the test wave’s flip faster). drDiv4 is never capped. EegChunk.srate and StreamMetadata report deviceSrate; srate itself is kept.

import BrainAccessKit

func measureImpedance(_ session: DeviceSession) async throws {
    let base = session.model.defaultConfig()
    let config = DeviceConfig(
        model: base.model,
        channels: base.channels,
        gain: base.gain,
        bias: base.bias,
        active: base.active,
        srate: base.srate,
        impedanceMode: .hz7_8
    )
    try await session.configure(config).get()
}

Sample-rate support#

Which rates a headset streams is a property of its board (DeviceHardware.supportedSrates): HALO, HALO V2, MINI, MIDI and MAXI stream 250 Hz and 500 Hz, HALO V3 also 1 kHz, EXG8 250 Hz, 500 Hz, 1 kHz and 2 kHz. DeviceConfig accepts only the rates with a wire code (DeviceConfig.supportedSrates — 250, 500, 1000 and 2000 Hz) and rejects any other rate at construction instead of sending an unknown code. DeviceSession.configure(_:) additionally fails with UnsupportedSampleRate — before writing anything — for a rate the connected board cannot stream (firmware before 3.7.0 would accept it silently and stream its defaults). A stored rate the board cannot stream is dropped for the defaults at connect.

Gains must be one of DeviceConfig.validGains (1, 2, 4, 6, 8, 12 or 24; an inactive channel may also carry 0): the firmware refuses the whole blob for any other gain byte, so DeviceConfig rejects it at construction.

A configuration takes effect at the next stream(outputMode:) start; configure(_:) does not touch a running stream. Each stream collection numbers its samples from its own first packet (firmware 3.7.0 restarts the device counter at 0 on every start).

Rejected configurations#

Firmware 3.7.0 and later reports a refused config blob as stream status 2 (older firmware refuses silently and streams its own defaults). configure(_:) and stream() read the stream-status characteristic after every config write and fail with BrainAccessError.configRejected on 2 — keeping the previously applied config and not persisting the rejected one — instead of decoding the device’s default stream with the wrong gains. An absent or unreadable status counts as accepted.