@neurodevs/node-lsl 23.1.0 → 23.1.2

package/src/impl/LslStreamInlet.ts

@@ -1,24 +1,9 @@
-import {
-    handleLslError,
-    InfoHandle,
-    InletHandle,
-    LiblslAdapter,
-} from '@neurodevs/ndx-native'
-import {
-    JsExternal,
-    unwrapPointer,
-    createPointer,
-    DataType,
-    freePointer,
-    PointerType,
-} from 'ffi-rs'
+import { InfoHandle, InletHandle, LiblslAdapter } from '@neurodevs/ndx-native'
 
 export default class LslStreamInlet implements LslInlet {
     public static Class?: LslInletConstructor
     public static waitAfterOpenStreamMs = 100
     public static lsl = LiblslAdapter.getInstance()
-    public static handleLslError = handleLslError
-    public static freePointer = freePointer
 
     public isRunning = false
 
@@ -32,37 +17,12 @@ export default class LslStreamInlet implements LslInlet {
     private onData: OnDataCallback
 
     private infoHandle!: InfoHandle
-    private inletHandle!: InletHandle
-    private channelCount!: number
-
-    private pullMethod!: () => {
-        samples: number[] | undefined
-        timestamps: number[] | undefined
-    }
-
-    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 inletHandle?: InletHandle
+    private pullMethod: () => PulledData | undefined
 
     private readonly sixMinutesInMs = 360 * 1000
     private readonly aboutOneYearInMs = 32000000 * 1000
 
-    private readonly bytesPerFloat = 4
-    private readonly bytesPerDouble = 8
-    private readonly bytesPerI32 = 4
-
     protected constructor(options: LslInletOptions, onData: OnDataCallback) {
         const {
             sourceId,
@@ -82,6 +42,10 @@ export default class LslStreamInlet implements LslInlet {
         this.waitBetweenPullsMs = waitBetweenPullsMs ?? 1
         this.flushInletOnStop = flushInletOnStop ?? true
         this.onData = onData
+
+        this.pullMethod = (
+            chunkSize === 1 ? this.pullSample : this.pullChunk
+        ).bind(this)
     }
 
     public static async Create(
@@ -106,10 +70,6 @@ export default class LslStreamInlet implements LslInlet {
     private async createInlet() {
         this.infoHandle = this.resolveInfoHandle()
         this.inletHandle = this.doCreateInlet()
-        this.channelCount = this.getChannelCount()
-
-        this.allocateWritableBuffers()
-        this.setPullMethod()
 
         this.openStream()
     }
@@ -146,144 +106,14 @@ export default class LslStreamInlet implements LslInlet {
         return this.lsl.createInlet({
             infoHandle: this.infoHandle,
             maxBufferedMs: this.maxBufferedMs,
+            chunkSize: this.chunkSize,
         })
     }
 
-    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,
+            inletHandle: this.inletHandle!,
             timeoutMs: this.openStreamTimeoutMs,
-            errorCodePtr: this.openStreamErrorBufferPtr,
         })
     }
 
@@ -295,17 +125,26 @@ export default class LslStreamInlet implements LslInlet {
     }
 
     private async pullDataOnce() {
-        const { samples, timestamps } = this.pullMethod()
-        this.handleLslErrorIfPresent()
+        const pulled = this.pullMethod()
 
-        if (samples && timestamps) {
-            this.onData(samples, timestamps)
+        if (pulled) {
+            this.onData(pulled.samples, pulled.timestamps)
         }
     }
 
-    private handleLslErrorIfPresent() {
-        const errorCode = this.pullErrorBuffer.readInt32LE()
-        this.handleLslError(errorCode)
+    private pullSample() {
+        return this.lsl.pullSample(this.pullOptions)
+    }
+
+    private pullChunk() {
+        return this.lsl.pullChunk(this.pullOptions)
+    }
+
+    private get pullOptions() {
+        return {
+            inletHandle: this.inletHandle!,
+            timeoutMs: this.pullTimeoutMs,
+        }
     }
 
     private async waitBetweenPulls() {
@@ -313,7 +152,7 @@ export default class LslStreamInlet implements LslInlet {
     }
 
     public flushInlet() {
-        this.lsl.flushInlet({ inletHandle: this.inletHandle })
+        this.lsl.flushInlet({ inletHandle: this.inletHandle! })
     }
 
     public stopPulling() {
@@ -326,7 +165,7 @@ export default class LslStreamInlet implements LslInlet {
     }
 
     private closeStream() {
-        this.lsl.closeStream({ inletHandle: this.inletHandle })
+        this.lsl.closeStream({ inletHandle: this.inletHandle! })
     }
 
     public destroy() {
@@ -334,43 +173,19 @@ export default class LslStreamInlet implements LslInlet {
             this.stopPulling()
         }
 
-        this.doDestroyInlet()
-        this.freeNativePointers()
-    }
-
-    private doDestroyInlet() {
-        this.lsl.destroyInlet({ inletHandle: this.inletHandle })
+        this.destroyInletIfCreated()
     }
 
-    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 destroyInletIfCreated() {
+        if (this.inletHandle) {
+            this.lsl.destroyInlet({ inletHandle: this.inletHandle })
+            delete this.inletHandle
+        }
     }
 
     private get lsl() {
         return LslStreamInlet.lsl
     }
-
-    private get handleLslError() {
-        return LslStreamInlet.handleLslError
-    }
-
-    private get freePointer() {
-        return LslStreamInlet.freePointer
-    }
 }
 
 export interface LslInlet {
@@ -396,4 +211,9 @@ export interface LslInletOptions {
     flushInletOnStop?: boolean
 }
 
+export interface PulledData {
+    samples: number[]
+    timestamps: number[]
+}
+
 export type OnDataCallback = (samples: number[], timestamps: number[]) => void

package/src/impl/LslStreamOutlet.ts

@@ -25,7 +25,7 @@ export default class LslStreamOutlet implements LslOutlet {
     public readonly name: string
     public readonly type: string
     public readonly sourceId: string
-    public readonly channelNames: string[]
+    public readonly channelNames: readonly string[]
     public readonly channelFormat: ChannelFormat
     public readonly channelCount: number
     public readonly sampleRateHz: number
@@ -168,7 +168,7 @@ export interface LslOutlet {
     readonly name: string
     readonly type: string
     readonly sourceId: string
-    readonly channelNames: string[]
+    readonly channelNames: readonly string[]
     readonly channelCount: number
     readonly channelFormat: ChannelFormat
     readonly sampleRateHz: number
@@ -184,7 +184,7 @@ export interface LslOutletOptions {
     name: string
     type: string
     sourceId: string
-    channelNames: string[]
+    channelNames: readonly string[]
     channelFormat: ChannelFormat
     sampleRateHz: number
     chunkSize: number

package/src/impl/clocks/WindowedClockRegressor.ts

@@ -41,7 +41,7 @@ export default class WindowedClockRegressor implements ClockRegressor {
 
         const anchor = this.anchorTimeFor(deviceTime)
 
-        const timestamps = Array(chunkSize).fill(0)
+        const timestamps: number[] = Array(chunkSize).fill(0)
 
         for (let i = 0; i <= chunkSize - 1; i++) {
             const stepsFromLast = chunkSize - 1 - i

package/src/impl/controllers/BleGattController.ts

@@ -1,33 +1,20 @@
-import { LibndxAdapter, Libndx, NativePeripheral } from '@neurodevs/ndx-native'
+import { LibndxAdapter, NativePeripheral } from '@neurodevs/ndx-native'
 
 export default class BleGattController implements BleGatt {
     public static Class?: BleGattConstructor
     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 state: BleGattState = { status: 'disconnected' }
     protected log = console
 
-    private deviceUuid?: string
     private deviceNamePrefix?: string
-    private deviceName?: string
     private onConnected?: (peripheral: NativePeripheral) => void
 
+    private readonly ndx = LibndxAdapter.getInstance()
+
     protected constructor(options: BleGattOptions) {
         const {
             deviceUuid,
@@ -37,7 +24,7 @@ export default class BleGattController implements BleGatt {
             rssiIntervalMs,
         } = options
 
-        this.deviceUuid = deviceUuid
+        this.state = { status: 'disconnected', uuid: deviceUuid }
         this.deviceNamePrefix = deviceNamePrefix
         this.charCallbacks = charCallbacks
         this.onConnected = onConnected
@@ -49,10 +36,12 @@ export default class BleGattController implements BleGatt {
     }
 
     public async connect() {
-        if (!this.deviceUuid) {
+        if (!this.state.uuid) {
             await this.discoverUuid()
         }
 
+        this.state = { status: 'connecting', uuid: this.uuid }
+
         this.createBleGattBackend()
         this.startBleGattBackend()
 
@@ -66,7 +55,7 @@ export default class BleGattController implements BleGatt {
         const { status, error } = this.ndx.discoverBleUuid({
             namePrefix: this.deviceNamePrefix as string,
             onDiscovered: (uuid: string) => {
-                this.deviceUuid = uuid
+                this.state = { status: 'disconnected', uuid }
             },
         })
 
@@ -78,7 +67,7 @@ export default class BleGattController implements BleGatt {
     private async waitForDiscoveredUuid() {
         await new Promise<void>((resolve) => {
             const checkDiscovered = () => {
-                if (this.deviceUuid) {
+                if (this.uuid) {
                     resolve()
                 } else {
                     BleGattController.setTimeout(checkDiscovered, 100)
@@ -119,12 +108,11 @@ export default class BleGattController implements BleGatt {
             deviceUuid: this.uuid,
             onConnected: (peripheral: NativePeripheral) => {
                 const { name } = peripheral
-                this.deviceName = name
-                this.connected = true
+                this.state = { status: 'connected', uuid: this.uuid, name }
                 this.log.info(`Connected to device ${this.uuid}!`)
                 this.onConnected?.(peripheral)
             },
-            charCallbacks: this.charCallbacks,
+            charCallbacks: [...this.charCallbacks],
         })
 
         this.throwIfError(status, error)
@@ -133,7 +121,7 @@ export default class BleGattController implements BleGatt {
     private async waitForOnConnected() {
         await new Promise<void>((resolve) => {
             const checkConnected = () => {
-                if (this.connected) {
+                if (this.state.status === 'connected') {
                     resolve()
                 } else {
                     BleGattController.setTimeout(checkConnected, 100)
@@ -154,7 +142,7 @@ export default class BleGattController implements BleGatt {
         value: string
     ) {
         const { status, error } = this.ndx.writeBleGattChar({
-            deviceUuid: this.uuid,
+            deviceUuid: this.requireUuid(),
             charUuid,
             value,
         })
@@ -166,8 +154,8 @@ export default class BleGattController implements BleGatt {
         charCallbacks: CharacteristicCallbacks
     ) {
         const { status, error } = this.ndx.registerBleGattCharCallbacks({
-            deviceUuid: this.uuid,
-            charCallbacks,
+            deviceUuid: this.requireUuid(),
+            charCallbacks: [...charCallbacks],
         })
 
         this.throwIfError(status, error)
@@ -177,29 +165,34 @@ export default class BleGattController implements BleGatt {
 
     public async disconnect() {
         const { status, error } = this.ndx.stopBleGattBackend({
-            deviceUuid: this.uuid,
+            deviceUuid: this.requireUuid(),
         })
 
         this.throwIfError(status, error)
-        this.connected = false
+        this.state = { status: 'disconnected', uuid: this.state.uuid }
     }
 
     public get uuid() {
-        return this.deviceUuid ?? ''
+        return this.state.uuid ?? ''
     }
 
     public get name() {
-        return this.deviceName ?? 'N/A'
+        return this.state.name ?? 'N/A'
     }
 
-    private get ndx() {
-        return BleGattController.ndx
+    private requireUuid() {
+        if (!this.uuid) {
+            throw new Error(
+                'Device uuid is not resolved yet! Must either pass as option to Create or call connect() first.'
+            )
+        }
+        return this.uuid
     }
 }
 
 export interface BleGatt {
-    uuid: string
-    name: string
+    readonly uuid: string
+    readonly name: string
 
     connect(): Promise<void>
 
@@ -226,7 +219,12 @@ export type BleGattOptions = {
 
 export type BleGattConstructor = new (options: BleGattOptions) => BleGatt
 
-export type CharacteristicCallbacks = {
+export type BleGattState =
+    | { status: 'disconnected'; uuid?: string; name?: string }
+    | { status: 'connecting'; uuid: string; name?: string }
+    | { status: 'connected'; uuid: string; name: string }
+
+export type CharacteristicCallbacks = readonly {
     charUuid: string
     charName?: string
     onData: (data: Buffer, length: number, timestampSec: number) => void

package/src/testDoubles/BleGatt/FakeBleGatt.ts

@@ -22,21 +22,24 @@ export default class FakeBleGatt implements BleGatt {
 
     public static fakeCharacteristics: Record<string, unknown> = {}
     public static fakeName = `fake-${generateId()}`
+    public static fakeDiscoveredUuid = `fake-uuid-${generateId()}`
 
-    private _uuid: string
-    private _name: string
+    private _uuid?: string
+    private _name?: string
 
     public constructor(options?: BleGattOptions) {
         const { deviceUuid } = options ?? {}
 
-        this._uuid = deviceUuid ?? generateId()
-        this._name = FakeBleGatt.fakeName
+        this._uuid = deviceUuid
 
         FakeBleGatt.callsToConstructor.push(options)
     }
 
     public async connect() {
         FakeBleGatt.numCallsToConnect++
+
+        this._uuid = this._uuid ?? FakeBleGatt.fakeDiscoveredUuid
+        this._name = FakeBleGatt.fakeName
     }
 
     public async writeCharacteristic(
@@ -60,11 +63,11 @@ export default class FakeBleGatt implements BleGatt {
     }
 
     public get uuid() {
-        return this._uuid
+        return this._uuid ?? ''
     }
 
     public get name() {
-        return this._name
+        return this._name ?? 'N/A'
     }
 
     public static resetTestDouble() {

package/src/testDoubles/BleGatt/SpyBleGatt.ts

@@ -19,8 +19,8 @@ export default class SpyBleGatt extends BleGattController {
         return this.rssiIntervalMs
     }
 
-    public getConnected() {
-        return this.connected
+    public getState() {
+        return this.state
     }
 
     public setLogInfoSpy() {