@neurodevs/node-lsl 23.1.1 → 23.2.0

package/src/__tests__/impl/LslStreamInlet.test.ts

@@ -1,13 +1,5 @@
 import { FakeLiblsl } from '@neurodevs/ndx-native'
 import { test, assert } from '@neurodevs/node-tdd'
-import {
-    createPointer,
-    DataType,
-    FieldType,
-    JsExternal,
-    PointerType,
-    unwrapPointer,
-} from 'ffi-rs'
 
 import LslStreamInlet, { LslInletOptions } from '../../impl/LslStreamInlet.js'
 import SpyLslInlet from '../../testDoubles/LslInlet/SpyLslInlet.js'
@@ -21,27 +13,6 @@ export default class LslStreamInletTest extends AbstractPackageTest {
         timestamps: number[]
     }[]
 
-    private static readonly sampleBufferPtr = unwrapPointer(
-        createPointer({
-            paramsType: [DataType.U8Array],
-            paramsValue: [new Float32Array(this.channelCount * this.chunkSize)],
-        })
-    )[0]
-
-    private static readonly timestampBufferPtr = unwrapPointer(
-        createPointer({
-            paramsType: [DataType.U8Array],
-            paramsValue: [new Float64Array(this.chunkSize)],
-        })
-    )[0]
-
-    private static readonly errorCodePtr = unwrapPointer(
-        createPointer({
-            paramsType: [DataType.U8Array],
-            paramsValue: [new Int32Array(1)],
-        })
-    )[0]
-
     protected static async beforeAll() {
         assert.isEqual(
             LslStreamInlet.waitAfterOpenStreamMs,
@@ -60,7 +31,6 @@ export default class LslStreamInletTest extends AbstractPackageTest {
 
         LslStreamInlet.waitAfterOpenStreamMs = 0
         LslStreamInlet.lsl = this.fakeLiblsl
-        LslStreamInlet.freePointer = () => {}
 
         this.instance = await this.LslStreamInlet()
     }
@@ -81,6 +51,7 @@ export default class LslStreamInletTest extends AbstractPackageTest {
             {
                 infoHandle: this.inletHandle,
                 maxBufferedMs: this.maxBufferedMs,
+                chunkSize: this.chunkSize,
             },
             'Should have called createInlet!'
         )
@@ -101,46 +72,39 @@ export default class LslStreamInletTest extends AbstractPackageTest {
 
     @test()
     protected static async destroyCallsLslBinding() {
-        await this.startPullingThenDestroy()
+        await this.startPulling()
+        const inletHandle = this.inletHandle
 
-        assert.isEqualDeep(
-            this.fakeLiblsl.lastDestroyInletOptions,
-            { inletHandle: this.inletHandle },
+        this.destroy()
+
+        assert.isTrue(
+            inletHandle !== undefined &&
+                this.fakeLiblsl.lastDestroyInletOptions?.inletHandle ===
+                    inletHandle,
             'Did not destroy inlet!'
         )
     }
 
     @test()
-    protected static async destroyFreesAllPointers() {
-        interface FreePointerParams {
-            paramsType: FieldType[]
-            paramsValue: JsExternal[]
-            pointerType: PointerType
-        }
-
-        let calls: FreePointerParams[] = []
+    protected static async destroyDoesNotDestroyInletThatWasNeverCreated() {
+        this.destroy()
 
-        LslStreamInlet.freePointer = (params: FreePointerParams) => {
-            calls.push(params)
-        }
+        assert.isEqual(
+            this.fakeLiblsl.destroyInletHitCount,
+            0,
+            'Should not have destroyed an inlet that was never created!'
+        )
+    }
 
+    @test()
+    protected static async destroyingTwiceDestroysInletOnce() {
         await this.startPullingThenDestroy()
+        this.destroy()
 
-        const { paramsType, pointerType } = calls[0]
-
-        assert.isEqualDeep(
-            { paramsType, pointerType },
-            {
-                paramsType: [
-                    DataType.U8Array,
-                    DataType.U8Array,
-                    DataType.U8Array,
-                    DataType.U8Array,
-                ],
-                pointerType: PointerType.CPointer,
-            },
-
-            'Destroy did not free all pointers!'
+        assert.isEqual(
+            this.fakeLiblsl.destroyInletHitCount,
+            1,
+            'Should have destroyed inlet only once!'
         )
     }
 
@@ -207,7 +171,6 @@ export default class LslStreamInletTest extends AbstractPackageTest {
             {
                 inletHandle: this.inletHandle,
                 timeoutMs: aboutOneYearInMs,
-                errorCodePtr: this.errorCodePtr,
             },
             'Did not open inlet stream!'
         )
@@ -230,7 +193,6 @@ export default class LslStreamInletTest extends AbstractPackageTest {
             {
                 inletHandle: instance['inletHandle'],
                 timeoutMs: openStreamTimeoutMs,
-                errorCodePtr: this.errorCodePtr,
             },
             'Did not open inlet stream with passed timeout!'
         )
@@ -316,13 +278,7 @@ export default class LslStreamInletTest extends AbstractPackageTest {
 
         assert.isEqualDeep(
             this.fakeLiblsl.lastPullSampleOptions,
-            {
-                inletHandle: this.inletHandle,
-                sampleBufferPtr: this.sampleBufferPtr,
-                sampleBufferElements: this.channelCount,
-                timeoutMs: 0,
-                errorCodePtr: this.errorCodePtr,
-            },
+            { inletHandle: this.inletHandle, timeoutMs: 0 },
             'Should have called pullSample!'
         )
     }
@@ -333,33 +289,36 @@ export default class LslStreamInletTest extends AbstractPackageTest {
 
         assert.isEqualDeep(
             this.fakeLiblsl.lastPullChunkOptions,
-            {
-                inletHandle: this.inletHandle,
-                sampleBufferPtr: this.sampleBufferPtr,
-                timestampBufferPtr: this.timestampBufferPtr,
-                sampleBufferElements: this.chunkSize * this.channelCount,
-                timestampBufferElements: this.chunkSize,
-                timeoutMs: 0,
-                errorCodePtr: this.errorCodePtr,
-            },
+            { inletHandle: this.inletHandle, timeoutMs: 0 },
             'Should have called pullChunk!'
         )
     }
 
     @test()
-    protected static async pushSampleHandlesErrorCode() {
-        let passedErrorCode: number | undefined
+    protected static async passesEachPulledSampleToOnData() {
+        await this.runChunkSizeOne()
 
-        LslStreamInlet.handleLslError = (errorCode: number) => {
-            passedErrorCode = errorCode
-        }
+        assert.isEqualDeep(
+            this.callsToOnData,
+            FakeLiblsl.fakeSamples.map((sample) => ({
+                samples: Array.from(sample),
+                timestamps: [FakeLiblsl.fakeSampleTimestampSec],
+            })),
+            'Did not pass each pulled sample to onData!'
+        )
+    }
 
+    @test()
+    protected static async passesEachPulledChunkToOnData() {
         await this.startThenStop()
 
         assert.isEqualDeep(
-            passedErrorCode,
-            FakeLiblsl.fakeErrorCode,
-            'Did not pass the expected error code to handleLslError!'
+            this.callsToOnData,
+            FakeLiblsl.fakeChunks.map((chunk, i) => ({
+                samples: Array.from(chunk),
+                timestamps: Array.from(FakeLiblsl.fakeTimestamps[i]),
+            })),
+            'Did not pass each pulled chunk to onData!'
         )
     }
 

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/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

@@ -24,6 +24,10 @@ export default class BleGattController implements BleGatt {
             rssiIntervalMs,
         } = options
 
+        if (deviceUuid && deviceNamePrefix) {
+            this.throwTooManyParams()
+        }
+
         this.state = { status: 'disconnected', uuid: deviceUuid }
         this.deviceNamePrefix = deviceNamePrefix
         this.charCallbacks = charCallbacks
@@ -35,6 +39,12 @@ export default class BleGattController implements BleGatt {
         return new (this.Class ?? this)(options)
     }
 
+    private throwTooManyParams() {
+        throw new Error(
+            'Cannot pass both deviceUuid and deviceNamePrefix! Please pass only one.'
+        )
+    }
+
     public async connect() {
         if (!this.state.uuid) {
             await this.discoverUuid()
@@ -191,8 +201,8 @@ export default class BleGattController implements BleGatt {
 }
 
 export interface BleGatt {
-    uuid: string
-    name: string
+    readonly uuid: string
+    readonly name: string
 
     connect(): Promise<void>
 

package/src/impl/controllers/BleObserverController.ts

@@ -3,14 +3,21 @@ import { LibndxAdapter, NativeAdvertisement } from '@neurodevs/ndx-native'
 export default class BleObserverController implements BleObserver {
     public static Class?: BleObserverConstructor
 
-    private readonly deviceUuid: string
+    private readonly deviceNamePrefix?: string
     private readonly onAdvertisement?: OnAdvertisement
     private readonly ndx = LibndxAdapter.getInstance()
 
+    private deviceUuid: string
+
     protected constructor(options: BleObserverOptions) {
-        const { deviceUuid, onAdvertisement } = options
+        const { deviceUuid, deviceNamePrefix, onAdvertisement } = options
+
+        if (deviceUuid && deviceNamePrefix) {
+            this.throwTooManyParams()
+        }
 
         this.deviceUuid = deviceUuid ?? ''
+        this.deviceNamePrefix = deviceNamePrefix
         this.onAdvertisement = onAdvertisement
     }
 
@@ -18,11 +25,35 @@ export default class BleObserverController implements BleObserver {
         return new (this.Class ?? this)(options)
     }
 
+    private throwTooManyParams() {
+        throw new Error(
+            'Cannot pass both deviceUuid and deviceNamePrefix! Please pass only one.'
+        )
+    }
+
     public async startObserving() {
+        if (!this.deviceUuid && this.deviceNamePrefix) {
+            await this.discoverUuid(this.deviceNamePrefix)
+        }
+
         this.createBleObserverBackend()
         this.startBleObserverBackend()
     }
 
+    private discoverUuid(namePrefix: string) {
+        return new Promise<void>((resolve) => {
+            const { status, error } = this.ndx.discoverBleUuid({
+                namePrefix,
+                onDiscovered: (uuid: string) => {
+                    this.deviceUuid = uuid
+                    resolve()
+                },
+            })
+
+            this.throwIfError(status, error)
+        })
+    }
+
     private createBleObserverBackend() {
         const { status, error } = this.ndx.createBleObserverBackend({
             deviceUuid: this.deviceUuid,
@@ -70,9 +101,11 @@ export type BleObserverConstructor = new (
 ) => BleObserver
 
 export type BleObserverOptions = {
-    deviceUuid: string
     onAdvertisement?: OnAdvertisement
-}
+} & (
+    | { deviceUuid: string; deviceNamePrefix?: string }
+    | { deviceUuid?: string; deviceNamePrefix: string }
+)
 
 export type BleAdvertisement = NativeAdvertisement