@neurodevs/node-lsl 18.0.0 → 18.1.0

package/src/impl/controllers/BleDeviceController.ts

@@ -0,0 +1,223 @@
+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 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>
+
+    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/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,13 @@
-// BackpressureMonitor
+// DeviceController
 
-export { default as LslBackpressureMonitor } from './impl/LslBackpressureMonitor.js'
-export * from './impl/LslBackpressureMonitor.js'
+export { default as BleDeviceController } from './impl/controllers/BleDeviceController.js'
+export * from './impl/controllers/BleDeviceController.js'
 
-export { default as FakeBackpressureMonitor } from './testDoubles/BackpressureMonitor/FakeBackpressureMonitor.js'
-export * from './testDoubles/BackpressureMonitor/FakeBackpressureMonitor.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
 

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/testDoubles/BleController/FakeBleController.ts

@@ -0,0 +1,70 @@
+import generateId from '@neurodevs/generate-id'
+import {
+    BleController,
+    BleControllerOptions,
+} 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 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 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.numCallsToDisconnect = 0
+    }
+}
+
+export interface CallToBleControllerConstructor {
+    options: BleControllerOptions
+}

package/src/testDoubles/BleController/SpyBleController.ts

@@ -0,0 +1,61 @@
+import BleDeviceController, {
+    BleControllerOptions,
+} from '../../impl/controllers/BleDeviceController.js'
+
+export default class SpyBleController extends BleDeviceController {
+    public infoLogs: string[] = []
+    public warnLogs: string[] = []
+    public errorLogs: string[] = []
+
+    public constructor(options: BleControllerOptions) {
+        super(options)
+    }
+
+    public getCharacteristicCallbacks() {
+        return this.charCallbacks
+    }
+
+    public getRssiIntervalMs() {
+        return this.rssiIntervalMs
+    }
+
+    public getConnected() {
+        return this.connected
+    }
+
+    public setLogInfoSpy() {
+        this.infoLogs = []
+
+        this.log.info = (...args: unknown[]) => {
+            const message = args.join(' ')
+            this.infoLogs.push(message)
+            return message
+        }
+    }
+
+    public setLogWarnSpy() {
+        this.warnLogs = []
+
+        this.log.warn = (...args: unknown[]) => {
+            const message = args.join(' ')
+            this.warnLogs.push(message)
+            return message
+        }
+    }
+
+    public setLogErrorSpy() {
+        this.errorLogs = []
+
+        this.log.error = (...args: unknown[]) => {
+            const message = args.join(' ')
+            this.errorLogs.push(message)
+            return message
+        }
+    }
+
+    public resetTestDouble() {
+        this.infoLogs = []
+        this.warnLogs = []
+        this.errorLogs = []
+    }
+}

package/src/testDoubles/StreamOutlet/FakeStreamOutlet.ts

@@ -13,7 +13,7 @@ export default class FakeStreamOutlet implements StreamOutlet {
 
     public static callsToPushSample: {
         sample: LslSample
-        timestamp?: number
+        timestampSec?: number
     }[] = []
 
     public static numCallsToDestroy = 0
@@ -29,8 +29,11 @@ export default class FakeStreamOutlet implements StreamOutlet {
         FakeStreamOutlet.numCallsToDestroy++
     }
 
-    public pushSample(sample: LslSample, timestamp?: number) {
-        FakeStreamOutlet.callsToPushSample.push({ sample, timestamp })
+    public pushSample(sample: LslSample, timestampSec?: number) {
+        FakeStreamOutlet.callsToPushSample.push({
+            sample,
+            timestampSec,
+        })
     }
 
     public get name() {

package/src/testDoubles/generateRandomOutletOptions.ts

@@ -1,4 +1,5 @@
-import { randomInt } from 'crypto'
+import { randomInt } from 'node:crypto'
+
 import generateId from '@neurodevs/generate-id'
 
 import { StreamOutletOptions } from '../impl/LslStreamOutlet.js'

package/tsconfig.json

@@ -1,28 +1,24 @@
 {
-	"compilerOptions": {
-		"module": "nodenext",
-		"moduleResolution": "nodenext",
-		"target": "ES2022",
-		"lib": ["ES2022"],
-		"types": ["node"],
-		"baseUrl": "src",
-		"outDir": "build",
-		"sourceMap": false,
-		"strict": true,
-		"noImplicitAny": true,
-		"noImplicitReturns": true,
-		"noUnusedLocals": true,
-		"forceConsistentCasingInFileNames": true,
-		"declaration": true,
-		"skipLibCheck": true,
-		"esModuleInterop": true,
-		"moduleDetection": "force",
-		"allowJs": true,
-		"resolveJsonModule": true,
-		"experimentalDecorators": true
-	},
-	"include": [
-		"./src/*.ts",
-		"./src/**/*.ts"
-	]
-}
+  "compilerOptions": {
+    "module": "nodenext",
+    "target": "esnext",
+    "lib": ["esnext"],
+    "types": ["node"],
+    "rootDir": "src",
+    "outDir": "build",
+    "sourceMap": false,
+    "strict": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "moduleDetection": "force",
+    "allowJs": true,
+    "resolveJsonModule": true,
+    "experimentalDecorators": true
+  },
+  "include": ["./src/*.ts", "./src/**/*.ts"]
+}

package/.regressionproof.json

@@ -1,7 +0,0 @@
-{
-  "version": "0.8.0",
-  "projectName": "node-lsl",
-  "remote": {
-    "url": "https://git.regressionproof.ai/liquidg3/node-lsl.git"
-  }
-}