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.