Usage#

This page shows a complete no-UI flow: scan, connect, observe state, stream chunks and disconnect. The code bodies are real Swift; replace print calls with your app’s DSP or UI updates.

Scan, connect and stream#

 1import BrainAccessKit
 2
 3func streamFirstDevice() async {
 4    let client = BrainAccessClient(transport: CoreBluetoothTransport())
 5
 6    do {
 7        for await device in client.scan() {
 8            let session = try await client.connect(device).get()
 9
10            let stateTask = Task {
11                for await state in session.state.stream {
12                    print("state:", state)
13                }
14            }
15            defer { stateTask.cancel() }
16
17            for try await chunk in session.stream() {
18                print("samples:", chunk.sampleCount, "channels:", chunk.channels)
19                if let first = chunk.samples.first {
20                    print("first value:", first)
21                }
22            }
23            break
24        }
25    } catch {
26        print("BrainAccess stream failed:", error.localizedDescription)
27    }
28
29    await client.disconnectAll()
30}

Step by step#

  1. Construct BrainAccessClient with a Transport. On iOS, use CoreBluetoothTransport.

  2. Iterate client.scan(). Stop iterating or cancel the task to stop scanning.

  3. connect(_:) performs the handshake to DeviceState.ready and returns Result<DeviceSession, Error>. Call .get() to throw the failure value.

  4. Iterating session.stream() starts the device stream (stream(outputMode:digitalInput:) selects electrode data or the ADS1299 test signal, and optionally the digital input; see Streaming data). The stream throws if the session is not ready, a GATT operation fails, firmware 3.7.0+ rejects the config blob (BrainAccessError.configRejected) or cannot start its ADC (BrainAccessError.streamStartFailed). Each collection numbers its samples from its own first packet, and a configuration applied with configure(_:) takes effect at the next start.

  5. End the stream by cancelling the task or breaking the loop, then disconnect one session or all sessions with disconnect(_:) / disconnectAll().

Device state#

A session exposes observable values as CurrentValue: read the current value synchronously and collect stream for a replaying async sequence.

import BrainAccessKit

func observeSession(_ client: BrainAccessClient, _ session: DeviceSession) -> [Task<Void, Never>] {
    [
        Task { for await state in session.state.stream { print("state", state) } },
        Task { for await battery in session.battery.stream { print("battery", battery) } },
        Task { for await contact in session.contact.stream { print("contact", contact) } },
        Task { for await on in client.bluetoothState.stream { print("bluetooth", on) } },
    ]
}

Errors#

Fallible one-shot operations return Result. Stream operations throw while iterating:

import BrainAccessKit

func connectHandlingErrors(_ client: BrainAccessClient, device: DiscoveredDevice) async {
    switch await client.connect(device) {
    case .success(let session):
        print("connected", session.id.value)
    case .failure(let error as BrainAccessError) where error == .bluetoothOff:
        print("Ask the user to turn Bluetooth on.")
    case .failure(let error):
        print("connection failed", error.localizedDescription)
    }
}

The iOS error set is timeout, gattError, bluetoothOff, missingPermission, disconnected, notConnected, configRejected, streamStartFailed, testSignalNotSupported, digitalInputNotSupported (firmware before 3.8.1) and the OTA-specific errors. configure(_:) and stream(…) refuse a configuration with no active channel with NoActiveChannel, before anything is written. There is no LocationOff case on iOS.

After a successful firmware update the headset reboots switched off: it advertises again only after the user long-presses its power button. A completed update is not proof the new firmware runs (a headset can keep or roll back to its old image); compare session.info’s firmware version after reconnecting.