@neurodevs/node-lsl 17.1.1 → 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/LslStreamInlet.worker.ts

@@ -0,0 +1,74 @@
+import { parentPort } from 'node:worker_threads'
+import StreamInletWorker from './StreamInletWorker.js'
+
+const worker = new StreamInletWorker()
+
+parentPort?.on('message', async (msg: InletMessage) => {
+    try {
+        switch (msg.type) {
+            case 'createInlet':
+                const { payload } = msg
+                await worker.createInlet(payload)
+                parentPort?.postMessage({ type: 'ready' })
+                break
+
+            case 'startPulling':
+                worker.startPulling((samples, timestamps) => {
+                    parentPort?.postMessage({
+                        type: 'data',
+                        payload: {
+                            samples,
+                            timestamps,
+                        },
+                    })
+                })
+                break
+
+            case 'stopPulling':
+                worker.stopPulling()
+                break
+            case 'flushInlet':
+                worker.flushInlet()
+                break
+
+            case 'destroyInlet':
+                worker.destroyInlet()
+                parentPort?.close()
+                break
+        }
+    } catch (err) {
+        parentPort?.postMessage({
+            type: 'error',
+            error: err instanceof Error ? err.message : String(err),
+        })
+    }
+})
+
+export type InletMessage =
+    | {
+          type: 'createInlet'
+          payload: CreateInletPayload
+      }
+    | {
+          type: 'startPulling'
+      }
+    | {
+          type: 'flushInlet'
+      }
+    | {
+          type: 'stopPulling'
+      }
+    | {
+          type: 'destroyInlet'
+      }
+
+export interface CreateInletPayload {
+    sourceId: string
+    chunkSize: number
+    maxBufferedMs: number
+    openStreamTimeoutMs: number
+    waitAfterOpenStreamMs: number
+    pullTimeoutMs: number
+    waitBetweenPullsMs: number
+    flushInletOnStop: boolean
+}

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

@@ -0,0 +1,348 @@
+import {
+    handleLslError,
+    InfoHandle,
+    InletHandle,
+    LiblslAdapter,
+} from '@neurodevs/ndx-native'
+import {
+    JsExternal,
+    unwrapPointer,
+    createPointer,
+    DataType,
+    freePointer,
+    PointerType,
+} from 'ffi-rs'
+
+import { OnDataCallback } from '../../LslStreamInlet.js'
+import { CreateInletPayload } from './LslStreamInlet.worker.js'
+
+export default class StreamInletWorker {
+    public static lsl = LiblslAdapter.getInstance()
+    public static handleLslError = handleLslError
+    public static freePointer = freePointer
+
+    private sourceId!: string
+    private chunkSize!: number
+    private maxBufferedMs!: number
+    private openStreamTimeoutMs!: number
+    private waitAfterOpenStreamMs!: number
+    private waitBetweenPullsMs!: number
+    private pullTimeoutMs!: number
+    private flushInletOnStop!: boolean
+
+    private pullMethod!: () => {
+        samples: number[] | undefined
+        timestamps: number[] | undefined
+    }
+
+    protected infoHandle!: InfoHandle
+    protected inletHandle!: InletHandle
+    private channelCount!: number
+
+    private sampleBuffer!: Buffer<ArrayBuffer>
+    private sampleBufferRef!: JsExternal[]
+    private sampleBufferPtr!: JsExternal
+
+    private timestampBuffer!: Buffer<ArrayBuffer>
+    private timestampBufferRef!: JsExternal[]
+    private timestampBufferPtr!: JsExternal
+
+    private pullErrorBuffer!: Buffer<ArrayBuffer>
+    private pullErrorBufferRef!: JsExternal[]
+    private pullErrorBufferPtr!: JsExternal
+
+    private openStreamErrorBuffer!: Buffer<ArrayBuffer>
+    private openStreamErrorBufferRef!: JsExternal[]
+    private openStreamErrorBufferPtr!: JsExternal
+
+    private onData!: OnDataCallback
+
+    private readonly bytesPerFloat = 4
+    private readonly bytesPerDouble = 8
+    private readonly bytesPerI32 = 4
+
+    private isRunning = false
+
+    public async createInlet(payload: CreateInletPayload) {
+        Object.assign(this, payload)
+
+        this.infoHandle = this.resolveInfoHandle()
+        this.inletHandle = this.doCreateInlet()
+        this.channelCount = this.getChannelCount()
+
+        this.allocateWritableBuffers()
+        this.setPullMethod()
+
+        this.openStream()
+        await this.waitForSetup()
+    }
+
+    private resolveInfoHandle() {
+        const handles = this.resolveByProp()
+
+        if (handles.length === 0) {
+            this.throwNoStreamFound()
+        } else if (handles.length > 1) {
+            this.warnMultipleStreamsFound()
+        }
+        return handles[0]
+    }
+
+    private resolveByProp() {
+        return this.lsl.resolveByProp({
+            prop: 'source_id',
+            value: this.sourceId,
+        })
+    }
+
+    private throwNoStreamFound() {
+        throw new Error(`No stream info for sourceId "${this.sourceId}"`)
+    }
+
+    private warnMultipleStreamsFound() {
+        console.warn(
+            `Multiple stream infos for sourceId "${this.sourceId}", using the first one.`
+        )
+    }
+
+    private doCreateInlet() {
+        return this.lsl.createInlet({
+            infoHandle: this.infoHandle,
+            maxBufferedMs: this.maxBufferedMs,
+        })
+    }
+
+    private getChannelCount() {
+        return this.lsl.getChannelCount({ infoHandle: this.infoHandle })
+    }
+
+    private allocateWritableBuffers() {
+        this.allocateDataBuffer()
+        this.allocateTimestampBuffer()
+        this.allocatePullErrorBuffer()
+        this.allocateOpenStreamErrorBuffer()
+    }
+
+    private allocateDataBuffer() {
+        this.sampleBuffer = Buffer.alloc(
+            this.channelCount * this.chunkSize * this.bytesPerFloat
+        )
+
+        this.sampleBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.sampleBuffer],
+        })
+
+        this.sampleBufferPtr = unwrapPointer(this.sampleBufferRef)[0]
+    }
+
+    private allocateTimestampBuffer() {
+        this.timestampBuffer = Buffer.alloc(
+            this.chunkSize * this.bytesPerDouble
+        )
+
+        this.timestampBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.timestampBuffer],
+        })
+
+        this.timestampBufferPtr = unwrapPointer(this.timestampBufferRef)[0]
+    }
+
+    private allocatePullErrorBuffer() {
+        this.pullErrorBuffer = Buffer.alloc(this.bytesPerI32)
+
+        this.pullErrorBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.pullErrorBuffer],
+        })
+
+        this.pullErrorBufferPtr = unwrapPointer(this.pullErrorBufferRef)[0]
+    }
+
+    private allocateOpenStreamErrorBuffer() {
+        this.openStreamErrorBuffer = Buffer.alloc(this.bytesPerI32)
+
+        this.openStreamErrorBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.openStreamErrorBuffer],
+        })
+
+        this.openStreamErrorBufferPtr = unwrapPointer(
+            this.openStreamErrorBufferRef
+        )[0]
+    }
+
+    private setPullMethod() {
+        this.pullMethod =
+            this.chunkSize === 1 ? this.pullSample : this.pullChunk
+    }
+
+    private pullSample = () => {
+        const timestampSec = this.doPullsample()
+
+        if (timestampSec > 0) {
+            return {
+                samples: this.readSamplesFromBuffer(),
+                timestamps: [timestampSec],
+            }
+        }
+        return { samples: undefined, timestamps: undefined }
+    }
+
+    private doPullsample() {
+        return this.lsl.pullSample({
+            inletHandle: this.inletHandle,
+            sampleBufferPtr: this.sampleBufferPtr,
+            sampleBufferElements: this.channelCount,
+            timeoutMs: this.pullTimeoutMs,
+            errorCodePtr: this.pullErrorBufferPtr,
+        })
+    }
+
+    private readSamplesFromBuffer() {
+        const floats = new Float32Array(
+            this.sampleBuffer.buffer,
+            this.sampleBuffer.byteOffset,
+            this.chunkSize * this.channelCount
+        )
+        return Array.from(floats)
+    }
+
+    private pullChunk = () => {
+        const firstTimestampSec = this.doPullChunk()
+
+        if (firstTimestampSec > 0) {
+            return {
+                samples: this.readSamplesFromBuffer(),
+                timestamps: this.readTimestampsFromBuffer(),
+            }
+        }
+        return { samples: undefined, timestamps: undefined }
+    }
+
+    private doPullChunk() {
+        return this.lsl.pullChunk({
+            inletHandle: this.inletHandle,
+            sampleBufferPtr: this.sampleBufferPtr,
+            sampleBufferElements: this.chunkSize * this.channelCount,
+            timestampBufferPtr: this.timestampBufferPtr,
+            timestampBufferElements: this.chunkSize,
+            timeoutMs: this.pullTimeoutMs,
+            errorCodePtr: this.pullErrorBufferPtr,
+        })
+    }
+
+    private readTimestampsFromBuffer() {
+        const doubles = new Float64Array(
+            this.timestampBuffer.buffer,
+            this.timestampBuffer.byteOffset,
+            this.chunkSize
+        )
+        return Array.from(doubles)
+    }
+
+    private openStream() {
+        this.lsl.openStream({
+            inletHandle: this.inletHandle,
+            timeoutMs: this.openStreamTimeoutMs,
+            errorCodePtr: this.openStreamErrorBufferPtr,
+        })
+    }
+
+    private async waitForSetup() {
+        return new Promise((r) => setTimeout(r, this.waitAfterOpenStreamMs))
+    }
+
+    public startPulling(onData: OnDataCallback) {
+        if (this.isRunning) {
+            console.warn('StreamInletWorker is already running.')
+            return
+        }
+        this.isRunning = true
+        this.onData = onData
+
+        void this.pullLoop()
+    }
+
+    private async pullLoop() {
+        while (this.isRunning) {
+            await this.pullDataOnce()
+            await this.waitBetweenPulls()
+        }
+    }
+
+    private async pullDataOnce() {
+        const { samples, timestamps } = this.pullMethod()
+        this.handleLslErrorIfPresent()
+
+        if (samples && timestamps) {
+            this.onData(samples, timestamps)
+        }
+    }
+
+    private handleLslErrorIfPresent() {
+        const errorCode = this.pullErrorBuffer.readInt32LE()
+        this.handleLslError(errorCode)
+    }
+
+    private async waitBetweenPulls() {
+        await new Promise((r) => setTimeout(r, this.waitBetweenPullsMs))
+    }
+
+    public flushInlet() {
+        this.lsl.flushInlet({ inletHandle: this.inletHandle })
+    }
+
+    public stopPulling() {
+        this.isRunning = false
+        this.closeStream()
+
+        if (this.flushInletOnStop) {
+            this.flushInlet()
+        }
+    }
+
+    private closeStream() {
+        this.lsl.closeStream({ inletHandle: this.inletHandle })
+    }
+
+    public destroyInlet() {
+        this.doDestroyInlet()
+        this.freeNativePointers()
+    }
+
+    private doDestroyInlet() {
+        this.lsl.destroyInlet({ inletHandle: this.inletHandle })
+    }
+
+    private freeNativePointers() {
+        this.freePointer({
+            paramsType: [
+                DataType.U8Array,
+                DataType.U8Array,
+                DataType.U8Array,
+                DataType.U8Array,
+            ],
+            paramsValue: [
+                this.openStreamErrorBufferPtr,
+                this.sampleBufferPtr,
+                this.timestampBufferPtr,
+                this.pullErrorBufferPtr,
+            ],
+            pointerType: PointerType.CPointer,
+        })
+    }
+
+    private get lsl() {
+        return StreamInletWorker.lsl
+    }
+
+    private get handleLslError() {
+        return StreamInletWorker.handleLslError
+    }
+
+    private get freePointer() {
+        return StreamInletWorker.freePointer
+    }
+}