@neurodevs/node-lsl 18.0.0 → 19.0.0

package/src/impl/controllers/BleDeviceController.ts

@@ -0,0 +1,240 @@
+import { LibndxAdapter, Libndx, NativePeripheral } from '@neurodevs/ndx-native'
+
+export default class BleDeviceController implements BleController {
+    public static Class?: BleControllerConstructor
+    public static setTimeout = setTimeout
+    public static waitAfterMs = 1000
+
+    private static _ndx?: Libndx
+
+    public static get ndx() {
+        if (!this._ndx) {
+            this._ndx = LibndxAdapter.getInstance()
+        }
+        return this._ndx
+    }
+
+    public static set ndx(value: Libndx) {
+        this._ndx = value
+    }
+
+    protected charCallbacks: CharacteristicCallbacks
+    protected rssiIntervalMs?: number
+    protected connected = false
+    protected log = console
+
+    private deviceUuid?: string
+    private deviceNamePrefix?: string
+    private deviceName?: string
+    private onConnected?: (peripheral: NativePeripheral) => void
+
+    protected constructor(options: BleControllerOptions) {
+        const {
+            deviceUuid,
+            deviceNamePrefix,
+            charCallbacks,
+            onConnected,
+            rssiIntervalMs,
+        } = options
+
+        this.deviceUuid = deviceUuid
+        this.deviceNamePrefix = deviceNamePrefix
+        this.charCallbacks = charCallbacks
+        this.onConnected = onConnected
+        this.rssiIntervalMs = rssiIntervalMs
+    }
+
+    public static async Create(options: BleControllerOptions) {
+        return new (this.Class ?? this)(options)
+    }
+
+    public async connect() {
+        if (!this.deviceUuid) {
+            await this.discoverUuid()
+        }
+
+        this.createBleBackend()
+        this.startBleBackend()
+
+        await this.waitForOnConnected()
+        await this.waitToDiscoverServices()
+
+        this.setBleRssiInterval()
+    }
+
+    private async discoverUuid() {
+        const { status, error } = this.ndx.discoverBleUuid({
+            namePrefix: this.deviceNamePrefix as string,
+            onDiscovered: (uuid: string) => {
+                this.deviceUuid = uuid
+            },
+        })
+
+        this.throwIfError(status, error)
+
+        await this.waitForDiscoveredUuid()
+    }
+
+    private async waitForDiscoveredUuid() {
+        await new Promise<void>((resolve) => {
+            const checkDiscovered = () => {
+                if (this.deviceUuid) {
+                    resolve()
+                } else {
+                    BleDeviceController.setTimeout(checkDiscovered, 100)
+                }
+            }
+            checkDiscovered()
+        })
+    }
+
+    private createBleBackend() {
+        const { status, error } = this.ndx.createBleBackend({
+            deviceUuid: this.uuid,
+        })
+
+        this.throwIfError(status, error)
+    }
+
+    private throwIfError(status: number, error: string | undefined) {
+        if (status !== 200) {
+            throw new Error(`${status} error: ${error ?? 'Unknown error'}`)
+        }
+    }
+
+    private setBleRssiInterval() {
+        if (this.rssiIntervalMs) {
+            this.ndx.setBleRssiInterval({
+                deviceUuid: this.uuid,
+                intervalMs: this.rssiIntervalMs,
+                onRssi: (rssi: number) => {
+                    this.log.info(`[RSSI=${rssi}]`)
+                },
+            })
+        }
+    }
+
+    private startBleBackend() {
+        const { status, error } = this.ndx.startBleBackend({
+            deviceUuid: this.uuid,
+            onConnected: (peripheral: NativePeripheral) => {
+                const { name } = peripheral
+                this.deviceName = name
+                this.connected = true
+                this.log.info(`Connected to device ${this.uuid}!`)
+                this.onConnected?.(peripheral)
+            },
+            charCallbacks: this.charCallbacks,
+        })
+
+        this.throwIfError(status, error)
+    }
+
+    private async waitForOnConnected() {
+        await new Promise<void>((resolve) => {
+            const checkConnected = () => {
+                if (this.connected) {
+                    resolve()
+                } else {
+                    BleDeviceController.setTimeout(checkConnected, 100)
+                }
+            }
+            checkConnected()
+        })
+    }
+
+    private async waitToDiscoverServices() {
+        await new Promise<void>((resolve) =>
+            BleDeviceController.setTimeout(
+                resolve,
+                BleDeviceController.waitAfterMs
+            )
+        )
+    }
+
+    public async writeCharacteristic(
+        charUuid: CharacteristicUuid,
+        value: string
+    ) {
+        const { status, error } = this.ndx.writeBleCharacteristic({
+            deviceUuid: this.uuid,
+            charUuid,
+            value,
+        })
+
+        this.throwIfError(status, error)
+    }
+
+    public async subscribeCharacteristics(
+        charCallbacks: CharacteristicCallbacks
+    ) {
+        const { status, error } = this.ndx.addBleCharCallbacks({
+            deviceUuid: this.uuid,
+            charCallbacks,
+        })
+
+        this.throwIfError(status, error)
+
+        this.charCallbacks = [...this.charCallbacks, ...charCallbacks]
+    }
+
+    public async disconnect() {
+        const { status, error } = this.ndx.stopBleBackend({
+            deviceUuid: this.uuid,
+        })
+
+        this.throwIfError(status, error)
+        this.connected = false
+    }
+
+    public get uuid() {
+        return this.deviceUuid ?? ''
+    }
+
+    public get name() {
+        return this.deviceName ?? 'N/A'
+    }
+
+    private get ndx() {
+        return BleDeviceController.ndx
+    }
+}
+
+export interface BleController {
+    uuid: string
+    name: string
+
+    connect(): Promise<void>
+
+    subscribeCharacteristics(
+        charCallbacks: CharacteristicCallbacks
+    ): Promise<void>
+
+    writeCharacteristic(
+        charUuid: CharacteristicUuid,
+        value: string
+    ): Promise<void>
+
+    disconnect(): Promise<void>
+}
+
+export type BleControllerOptions = {
+    charCallbacks: CharacteristicCallbacks
+    onConnected?: (peripheral: NativePeripheral) => void
+    rssiIntervalMs?: number
+} & (
+    | { deviceUuid: string; deviceNamePrefix?: string }
+    | { deviceUuid?: string; deviceNamePrefix: string }
+)
+
+export type BleControllerConstructor = new (
+    options: BleControllerOptions
+) => BleController
+
+export type CharacteristicCallbacks = {
+    charUuid: string
+    charName?: string
+    onData: (data: Buffer, length: number, timestampSec: number) => void
+}[]
+
+export type CharacteristicUuid = string

package/src/impl/controllers/UsbDeviceController.ts

@@ -0,0 +1,65 @@
+import { LibndxAdapter } from '@neurodevs/ndx-native'
+
+export default class UsbDeviceController implements UsbController {
+    public static Class?: UsbControllerConstructor
+
+    private onData: (data: Buffer, length: number, timestampSec: number) => void
+    private serialNumber: string
+
+    private ndx = LibndxAdapter.getInstance()
+
+    protected constructor(options: UsbControllerOptions) {
+        const { onData, serialNumber } = options ?? {}
+
+        this.onData = onData
+        this.serialNumber = serialNumber ?? ''
+    }
+
+    public static Create(options: UsbControllerOptions) {
+        return new (this.Class ?? this)(options)
+    }
+
+    public async connect() {
+        this.ndx.createUsbBackend(this.usbControllerOptions)
+        this.ndx.startUsbBackend(this.startUsbControllerOptions)
+    }
+
+    private get usbControllerOptions() {
+        return {
+            serialNumber: this.serialNumber,
+        }
+    }
+
+    private get startUsbControllerOptions() {
+        return {
+            ...this.usbControllerOptions,
+            onData: this.onData,
+        }
+    }
+
+    public async writeUsb(value: string) {
+        this.ndx.writeUsbBackend({
+            ...this.usbControllerOptions,
+            value,
+        })
+    }
+
+    public async disconnect() {
+        this.ndx.stopUsbBackend(this.usbControllerOptions)
+    }
+}
+
+export interface UsbController {
+    connect(): Promise<void>
+    writeUsb(value: string): Promise<void>
+    disconnect(): Promise<void>
+}
+
+export interface UsbControllerOptions {
+    onData: (data: Buffer, length: number, timestampSec: number) => void
+    serialNumber?: string
+}
+
+export type UsbControllerConstructor = new (
+    options?: UsbControllerOptions
+) => UsbController

package/src/impl/workers/inlet/StreamInletWorker.ts

@@ -1,5 +1,5 @@
 import {
-    handleError,
+    handleLslError,
     InfoHandle,
     InletHandle,
     LiblslAdapter,
@@ -18,7 +18,7 @@ import { CreateInletPayload } from './LslStreamInlet.worker.js'
 
 export default class StreamInletWorker {
     public static lsl = LiblslAdapter.getInstance()
-    public static handleError = handleError
+    public static handleLslError = handleLslError
     public static freePointer = freePointer
 
     private sourceId!: string
@@ -179,12 +179,12 @@ export default class StreamInletWorker {
     }
 
     private pullSample = () => {
-        const timestamp = this.doPullsample()
+        const timestampSec = this.doPullsample()
 
-        if (timestamp > 0) {
+        if (timestampSec > 0) {
             return {
                 samples: this.readSamplesFromBuffer(),
-                timestamps: [timestamp],
+                timestamps: [timestampSec],
             }
         }
         return { samples: undefined, timestamps: undefined }
@@ -210,9 +210,9 @@ export default class StreamInletWorker {
     }
 
     private pullChunk = () => {
-        const firstTimestamp = this.doPullChunk()
+        const firstTimestampSec = this.doPullChunk()
 
-        if (firstTimestamp > 0) {
+        if (firstTimestampSec > 0) {
             return {
                 samples: this.readSamplesFromBuffer(),
                 timestamps: this.readTimestampsFromBuffer(),
@@ -274,16 +274,16 @@ export default class StreamInletWorker {
 
     private async pullDataOnce() {
         const { samples, timestamps } = this.pullMethod()
-        this.handleErrorIfPresent()
+        this.handleLslErrorIfPresent()
 
         if (samples && timestamps) {
             this.onData(samples, timestamps)
         }
     }
 
-    private handleErrorIfPresent() {
+    private handleLslErrorIfPresent() {
         const errorCode = this.pullErrorBuffer.readInt32LE()
-        this.handleError(errorCode)
+        this.handleLslError(errorCode)
     }
 
     private async waitBetweenPulls() {
@@ -338,8 +338,8 @@ export default class StreamInletWorker {
         return StreamInletWorker.lsl
     }
 
-    private get handleError() {
-        return StreamInletWorker.handleError
+    private get handleLslError() {
+        return StreamInletWorker.handleLslError
     }
 
     private get freePointer() {

package/src/impl/workers/outlet/LslStreamOutlet.worker.ts

@@ -4,7 +4,7 @@ import {
     LiblslAdapter,
     Liblsl,
     OutletHandle,
-    handleError,
+    handleLslError,
     LslErrorCode,
 } from '@neurodevs/ndx-native'
 
@@ -20,10 +20,10 @@ export function setOutletLiblslAdapter(adapter: Liblsl) {
     lsl = LiblslAdapter.getInstance()
 }
 
-let handleErrorFn = handleError
+let handleLslErrorFn = handleLslError
 
-export function setOutletHandleError(fn: typeof handleError) {
-    handleErrorFn = fn
+export function setOutletHandleLslError(fn: typeof handleLslError) {
+    handleLslErrorFn = fn
 }
 
 let info: StreamInfo
@@ -84,7 +84,7 @@ export function pushSample(msg: {
     payload: PushSamplePayload
 }) {
     const { payload } = msg
-    const { sample, timestamp = lsl.localClock() } = payload
+    const { sample, timestampSec = lsl.localClock() } = payload
 
     if (!handle || !pushMethod) {
         throw new Error('Outlet not initialized')
@@ -93,11 +93,11 @@ export function pushSample(msg: {
     const errorCode = pushMethod({
         outletHandle: handle,
         sample,
-        timestamp,
+        timestampSec,
     })
 
     try {
-        handleErrorFn(errorCode)
+        handleLslErrorFn(errorCode)
     } catch {
         parentPort?.postMessage({
             type: 'error',
@@ -140,5 +140,5 @@ export interface CreateOutletPayload {
 
 export interface PushSamplePayload {
     sample: unknown
-    timestamp?: number
+    timestampSec?: number
 }

package/src/index.ts

@@ -1,10 +1,21 @@
-// BackpressureMonitor
+// ClockRegressor
 
-export { default as LslBackpressureMonitor } from './impl/LslBackpressureMonitor.js'
-export * from './impl/LslBackpressureMonitor.js'
+export { default as WindowedClockRegressor } from './impl/WindowedClockRegressor.js'
+export * from './impl/WindowedClockRegressor.js'
 
-export { default as FakeBackpressureMonitor } from './testDoubles/BackpressureMonitor/FakeBackpressureMonitor.js'
-export * from './testDoubles/BackpressureMonitor/FakeBackpressureMonitor.js'
+export { default as FakeClockRegressor } from './testDoubles/ClockRegressor/FakeClockRegressor.js'
+export * from './testDoubles/ClockRegressor/FakeClockRegressor.js'
+
+// DeviceController
+
+export { default as BleDeviceController } from './impl/controllers/BleDeviceController.js'
+export * from './impl/controllers/BleDeviceController.js'
+
+export { default as FakeBleController } from './testDoubles/BleController/FakeBleController.js'
+export * from './testDoubles/BleController/FakeBleController.js'
+
+export { default as SpyBleController } from './testDoubles/BleController/SpyBleController.js'
+export * from './testDoubles/BleController/SpyBleController.js'
 
 // EventMarkerEmitter
 
@@ -47,6 +58,14 @@ export * from './impl/LslStreamOutlet.js'
 export { default as FakeStreamOutlet } from './testDoubles/StreamOutlet/FakeStreamOutlet.js'
 export * from './testDoubles/StreamOutlet/FakeStreamOutlet.js'
 
+// UsbController
+
+export { default as UsbDeviceController } from './impl/controllers/UsbDeviceController.js'
+export * from './impl/controllers/UsbDeviceController.js'
+
+export { default as FakeUsbController } from './testDoubles/UsbController/FakeUsbController.js'
+export * from './testDoubles/UsbController/FakeUsbController.js'
+
 // WebSocketBridge
 
 export { default as LslWebSocketBridge } from './impl/LslWebSocketBridge.js'

package/src/scripts/discoverMuse.ts

@@ -0,0 +1,50 @@
+import koffi from 'koffi'
+
+import BleDeviceController from '../impl/controllers/BleDeviceController.js'
+
+const MUSE_CHARACTERISTIC_UUIDS: Record<string, string> = {
+    CONTROL: '273E0001-4C4D-454D-96BE-F03BAC821358',
+    TELEMETRY: '273E000B-4C4D-454D-96BE-F03BAC821358',
+    GYROSCOPE: '273E0009-4C4D-454D-96BE-F03BAC821358',
+    ACCELEROMETER: '273E000A-4C4D-454D-96BE-F03BAC821358',
+    PPG_AMBIENT: '273E000F-4C4D-454D-96BE-F03BAC821358',
+    PPG_INFRARED: '273E0010-4C4D-454D-96BE-F03BAC821358',
+    PPG_RED: '273E0011-4C4D-454D-96BE-F03BAC821358',
+    EEG_TP9: '273E0003-4C4D-454D-96BE-F03BAC821358',
+    EEG_AF7: '273E0004-4C4D-454D-96BE-F03BAC821358',
+    EEG_AF8: '273E0005-4C4D-454D-96BE-F03BAC821358',
+    EEG_TP10: '273E0006-4C4D-454D-96BE-F03BAC821358',
+    EEG_AUX: '273E0007-4C4D-454D-96BE-F03BAC821358',
+}
+
+const CONTROL_UUID = MUSE_CHARACTERISTIC_UUIDS['CONTROL']
+
+const charCallbacks = Object.entries(MUSE_CHARACTERISTIC_UUIDS).map(
+    ([name, uuid]) => {
+        return {
+            charUuid: uuid,
+            charName: name,
+            onData: (data: Buffer, length: number, timestampSec: number) => {
+                const bytes = koffi.decode(data, 'uint8', length) as number[]
+                console.info(`[${timestampSec}] length=${length}`, bytes)
+            },
+        }
+    }
+)
+
+const muse = await BleDeviceController.Create({
+    deviceNamePrefix: 'Muse',
+    charCallbacks,
+    rssiIntervalMs: 1000,
+})
+
+await muse.connect()
+
+for (const cmd of ['h', 'p50', 's', 'd']) {
+    await muse.writeCharacteristic(CONTROL_UUID, cmd)
+    await new Promise((resolve) => setTimeout(resolve, 100))
+}
+
+await new Promise((resolve) => setTimeout(resolve, 5 * 1000))
+
+await muse.disconnect()

package/src/scripts/runMuse.ts

@@ -0,0 +1,50 @@
+import koffi from 'koffi'
+
+import BleDeviceController from '../impl/controllers/BleDeviceController.js'
+
+const MUSE_CHARACTERISTIC_UUIDS: Record<string, string> = {
+    CONTROL: '273E0001-4C4D-454D-96BE-F03BAC821358',
+    TELEMETRY: '273E000B-4C4D-454D-96BE-F03BAC821358',
+    GYROSCOPE: '273E0009-4C4D-454D-96BE-F03BAC821358',
+    ACCELEROMETER: '273E000A-4C4D-454D-96BE-F03BAC821358',
+    PPG_AMBIENT: '273E000F-4C4D-454D-96BE-F03BAC821358',
+    PPG_INFRARED: '273E0010-4C4D-454D-96BE-F03BAC821358',
+    PPG_RED: '273E0011-4C4D-454D-96BE-F03BAC821358',
+    EEG_TP9: '273E0003-4C4D-454D-96BE-F03BAC821358',
+    EEG_AF7: '273E0004-4C4D-454D-96BE-F03BAC821358',
+    EEG_AF8: '273E0005-4C4D-454D-96BE-F03BAC821358',
+    EEG_TP10: '273E0006-4C4D-454D-96BE-F03BAC821358',
+    EEG_AUX: '273E0007-4C4D-454D-96BE-F03BAC821358',
+}
+
+const CONTROL_UUID = MUSE_CHARACTERISTIC_UUIDS['CONTROL']
+
+const charCallbacks = Object.entries(MUSE_CHARACTERISTIC_UUIDS).map(
+    ([name, uuid]) => {
+        return {
+            charUuid: uuid,
+            charName: name,
+            onData: (data: Buffer, length: number, timestampSec: number) => {
+                const bytes = koffi.decode(data, 'uint8', length) as number[]
+                console.info(`[${timestampSec}] length=${length}`, bytes)
+            },
+        }
+    }
+)
+
+const muse = await BleDeviceController.Create({
+    deviceUuid: 'CA6A61B7-B7A8-AF24-3C9E-04A6A5012554',
+    charCallbacks,
+    rssiIntervalMs: 1000,
+})
+
+await muse.connect()
+
+for (const cmd of ['h', 'p50', 's', 'd']) {
+    await muse.writeCharacteristic(CONTROL_UUID, cmd)
+    await new Promise((resolve) => setTimeout(resolve, 100))
+}
+
+await new Promise((resolve) => setTimeout(resolve, 5 * 1000))
+
+await muse.disconnect()

package/src/scripts/runUsb.ts

@@ -0,0 +1,20 @@
+import UsbDeviceController from '../impl/controllers/UsbDeviceController.js'
+
+console.info('\nCreating UsbDeviceController...')
+
+const controller = UsbDeviceController.Create({
+    serialNumber: 'DP04WG8J',
+    onData: (_data: Buffer, length: number, timestampSec: number) => {
+        console.info(`[${timestampSec}] Buffer length: ${length}`)
+    },
+})
+
+console.info('Connecting to UsbDeviceController...')
+
+await controller.connect()
+
+console.info('Waiting for 10 seconds...')
+
+await new Promise((resolve) => setTimeout(resolve, 10000))
+
+console.info('Done!')

package/src/testDoubles/BleController/FakeBleController.ts

@@ -0,0 +1,81 @@
+import generateId from '@neurodevs/generate-id'
+import {
+    BleController,
+    BleControllerOptions,
+    CharacteristicCallbacks,
+} from '../../impl/controllers/BleDeviceController.js'
+
+export default class FakeBleController implements BleController {
+    public static callsToConstructor: (BleControllerOptions | undefined)[] = []
+
+    public static numCallsToConnect = 0
+
+    public static callsToWriteCharacteristic: {
+        characteristicUuid: string
+        value: string
+    }[] = []
+
+    public static callsToSubscribeCharacteristics: CharacteristicCallbacks[] =
+        []
+
+    public static numCallsToDisconnect = 0
+
+    public static fakeCharacteristics: Record<string, unknown> = {}
+    public static fakeName = `fake-${generateId()}`
+
+    private _uuid: string
+    private _name: string
+
+    public constructor(options?: BleControllerOptions) {
+        const { deviceUuid } = options ?? {}
+
+        this._uuid = deviceUuid ?? generateId()
+        this._name = FakeBleController.fakeName
+
+        FakeBleController.callsToConstructor.push(options)
+    }
+
+    public async connect() {
+        FakeBleController.numCallsToConnect++
+    }
+
+    public async writeCharacteristic(
+        characteristicUuid: string,
+        value: string
+    ) {
+        FakeBleController.callsToWriteCharacteristic.push({
+            characteristicUuid,
+            value,
+        })
+    }
+
+    public async subscribeCharacteristics(
+        charCallbacks: CharacteristicCallbacks
+    ) {
+        FakeBleController.callsToSubscribeCharacteristics.push(charCallbacks)
+    }
+
+    public async disconnect() {
+        FakeBleController.numCallsToDisconnect++
+    }
+
+    public get uuid() {
+        return this._uuid
+    }
+
+    public get name() {
+        return this._name
+    }
+
+    public static resetTestDouble() {
+        this.callsToConstructor = []
+        this.numCallsToConnect = 0
+        this.callsToWriteCharacteristic = []
+        this.callsToSubscribeCharacteristics = []
+        this.numCallsToDisconnect = 0
+    }
+}
+
+export interface CallToBleControllerConstructor {
+    options: BleControllerOptions
+}