@neurodevs/node-lsl 18.1.0 → 19.0.0

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

@@ -0,0 +1,262 @@
+import { randomInt } from 'node:crypto'
+
+import { test, assert } from '@neurodevs/node-tdd'
+
+import WindowedClockRegressor, {
+    ClockRegressor,
+} from '../../impl/WindowedClockRegressor.js'
+import AbstractPackageTest from '../AbstractPackageTest.js'
+
+export default class WindowedClockRegressorTest extends AbstractPackageTest {
+    private static instance: ClockRegressor
+
+    protected static readonly chunkSize = randomInt(10, 20)
+
+    private static readonly nominalHz = 50 + Math.random() * 50
+    private static readonly deviceTime = Math.random()
+    private static readonly earliestLslTime = Math.random()
+
+    protected static async beforeEach() {
+        await super.beforeEach()
+
+        this.instance = this.WindowedClockRegressor()
+    }
+
+    @test()
+    protected static async createsInstance() {
+        assert.isTruthy(this.instance, 'Failed to create instance!')
+    }
+
+    @test()
+    protected static async deriveReturnsChunkSizeEntries() {
+        const timestamps = this.deriveTimestamps()
+
+        assert.isEqual(
+            timestamps.length,
+            this.chunkSize,
+            'Should return an array with chunkSize entries!'
+        )
+    }
+
+    @test()
+    protected static async deriveAnchorsLastTimestampOnRegressionLine() {
+        const nominalChunkStep = this.chunkSize / this.nominalHz
+
+        let deviceTime = this.deviceTime
+        let lslTime = this.earliestLslTime
+
+        for (let i = 0; i < 100; i++) {
+            deviceTime += nominalChunkStep
+            lslTime += nominalChunkStep
+            this.deriveTimestamps(deviceTime, lslTime)
+        }
+
+        deviceTime += nominalChunkStep
+        lslTime += nominalChunkStep
+
+        const jitter = nominalChunkStep * Math.random()
+
+        const timestamps = this.deriveTimestamps(deviceTime, lslTime + jitter)
+
+        for (let i = 0; i < timestamps.length; i++) {
+            const stepsFromLast = timestamps.length - 1 - i
+            const expected = lslTime - stepsFromLast / this.nominalHz
+
+            assert.isBetweenInclusive(
+                timestamps[i],
+                expected - jitter * 0.1,
+                expected + jitter * 0.1,
+                `Timestamp at index ${i} should be anchored on the fitted regression line, not the jittery arrival time!`
+            )
+        }
+    }
+
+    @test()
+    protected static async deriveSpacesEntriesByNominalHz() {
+        const timestamps = this.deriveTimestamps()
+
+        const expected = Array(this.chunkSize)
+            .fill(0)
+            .map((_, i) => {
+                return (
+                    this.earliestLslTime -
+                    (this.chunkSize - 1 - i) / this.nominalHz
+                )
+            })
+
+        assert.isEqualDeep(
+            timestamps,
+            expected,
+            'Entries should be spaced 1/nominalHz apart, working backward from earliestLslTime!'
+        )
+    }
+
+    @test()
+    protected static async deriveUsesFittedSlopeOnceHistoryAccumulates() {
+        const trueSlope = 2
+        const nominalStep = this.chunkSize / this.nominalHz
+        const lslStep = nominalStep * trueSlope
+
+        let deviceTime = this.deviceTime
+        let earliestLslTime = this.earliestLslTime
+
+        for (let i = 0; i < 50; i++) {
+            deviceTime += nominalStep
+            earliestLslTime += lslStep
+
+            this.deriveTimestamps(deviceTime, earliestLslTime)
+        }
+
+        deviceTime += nominalStep
+        earliestLslTime += lslStep
+
+        const timestamps = this.deriveTimestamps(deviceTime, earliestLslTime)
+
+        const expectedSpacing = trueSlope / this.nominalHz
+
+        for (let i = 1; i < timestamps.length; i++) {
+            const actualSpacing = timestamps[i] - timestamps[i - 1]
+
+            assert.isBetweenInclusive(
+                actualSpacing,
+                expectedSpacing * 0.99,
+                expectedSpacing * 1.01,
+                `Spacing at index ${i} should reflect the fitted slope once history has accumulated!`
+            )
+        }
+    }
+
+    @test()
+    protected static async deriveThrowsWhenDeviceTimeDoesNotIncreaseMonotonically() {
+        this.deriveTimestamps()
+
+        assert.doesThrow(
+            () =>
+                this.deriveTimestamps(
+                    this.deviceTime,
+                    this.earliestLslTime + Math.random()
+                ),
+            `\nDevice time (${this.deviceTime}) did not increase from the previous device time (${this.deviceTime})! Device time is expected to always increase between calls, so this likely indicates a bug in the calling code.\n`
+        )
+    }
+
+    @test()
+    protected static async deriveForgetsHistoryOutsideWindowLenSec() {
+        const nominalChunkStep = this.chunkSize / this.nominalHz
+
+        // With chunkSize in [10, 20) and nominalHz in [50, 100), nominalChunkStep
+        // stays within [0.1, 0.4). A fixed 700 iterations always spans at least
+        // 70 device-seconds — comfortably more than 2x the 30s windowLenSec.
+        const oldPhaseCount = 700
+        const newPhaseCount = 700
+
+        let deviceTime = this.deviceTime
+        let earliestLslTime = this.earliestLslTime
+
+        const oldSlope = 2
+
+        for (let i = 0; i < oldPhaseCount; i++) {
+            deviceTime += nominalChunkStep
+            earliestLslTime += nominalChunkStep * oldSlope
+
+            this.deriveTimestamps(deviceTime, earliestLslTime)
+        }
+
+        const newSlope = 5
+        let timestamps: number[] = []
+
+        for (let i = 0; i < newPhaseCount; i++) {
+            deviceTime += nominalChunkStep
+            earliestLslTime += nominalChunkStep * newSlope
+
+            timestamps = this.deriveTimestamps(deviceTime, earliestLslTime)
+        }
+
+        const expectedSpacing = newSlope / this.nominalHz
+
+        for (let i = 1; i < timestamps.length; i++) {
+            const actualSpacing = timestamps[i] - timestamps[i - 1]
+
+            assert.isBetweenInclusive(
+                actualSpacing,
+                expectedSpacing * 0.99,
+                expectedSpacing * 1.01,
+                `Spacing at index ${i} should reflect the new slope once old history falls outside windowLenSec!`
+            )
+        }
+    }
+
+    @test()
+    protected static async deriveAllowsOverridingWindowLenSec() {
+        const nominalChunkStep = this.chunkSize / this.nominalHz
+        const customWindowLenSec = 5
+
+        // With nominalChunkStep in [0.1, 0.4), 150 iterations always spans at
+        // least 15 device-seconds — more than 2x the 5s customWindowLenSec,
+        // but well short of 2x the 30s default, so this only passes if the
+        // override actually takes effect.
+        const phaseCount = 150
+
+        const instance = WindowedClockRegressor.Create(this.nominalHz, {
+            windowLenSec: customWindowLenSec,
+        })
+
+        let deviceTime = this.deviceTime
+        let earliestLslTime = this.earliestLslTime
+
+        const oldSlope = 2
+
+        for (let i = 0; i < phaseCount; i++) {
+            deviceTime += nominalChunkStep
+            earliestLslTime += nominalChunkStep * oldSlope
+
+            instance.deriveTimestamps(
+                deviceTime,
+                earliestLslTime,
+                this.chunkSize
+            )
+        }
+
+        const newSlope = 5
+        let timestamps: number[] = []
+
+        for (let i = 0; i < phaseCount; i++) {
+            deviceTime += nominalChunkStep
+            earliestLslTime += nominalChunkStep * newSlope
+
+            timestamps = instance.deriveTimestamps(
+                deviceTime,
+                earliestLslTime,
+                this.chunkSize
+            )
+        }
+
+        const expectedSpacing = newSlope / this.nominalHz
+
+        for (let i = 1; i < timestamps.length; i++) {
+            const actualSpacing = timestamps[i] - timestamps[i - 1]
+
+            assert.isBetweenInclusive(
+                actualSpacing,
+                expectedSpacing * 0.99,
+                expectedSpacing * 1.01,
+                `Spacing at index ${i} should reflect the new slope once old history falls outside the custom windowLenSec!`
+            )
+        }
+    }
+
+    private static deriveTimestamps(
+        deviceTime = this.deviceTime,
+        earliestLslTime = this.earliestLslTime
+    ) {
+        return this.instance.deriveTimestamps(
+            deviceTime,
+            earliestLslTime,
+            this.chunkSize
+        )
+    }
+
+    private static WindowedClockRegressor() {
+        return WindowedClockRegressor.Create(this.nominalHz)
+    }
+}

package/src/impl/LslStreamInlet.ts

@@ -4,6 +4,7 @@ export default class LslStreamInlet implements StreamInlet {
     public static Class?: StreamInletConstructor
     public static Worker = Worker
     public static waitAfterOpenStreamMs = 100
+    public static setTimeout = setTimeout
 
     private sourceId: string
     private chunkSize: number
@@ -91,7 +92,9 @@ export default class LslStreamInlet implements StreamInlet {
             this.postCreate()
 
             while (!this.workerReady) {
-                await new Promise((resolve) => setTimeout(resolve, 10))
+                await new Promise((resolve) =>
+                    LslStreamInlet.setTimeout(resolve, 10)
+                )
             }
 
             this.postStartPulling()

package/src/impl/LslStreamOutlet.ts

@@ -13,6 +13,7 @@ import {
 export default class LslStreamOutlet implements StreamOutlet {
     public static Class?: StreamOutletConstructor
     public static Worker = Worker
+    public static setTimeout = setTimeout
 
     public readonly name: string
     public readonly type: string
@@ -153,7 +154,7 @@ export default class LslStreamOutlet implements StreamOutlet {
 
     private static async waitForSetup(waitAfterConstructionMs: number) {
         await new Promise((resolve) =>
-            setTimeout(resolve, waitAfterConstructionMs)
+            LslStreamOutlet.setTimeout(resolve, waitAfterConstructionMs)
         )
     }
 }

package/src/impl/WindowedClockRegressor.ts

@@ -0,0 +1,136 @@
+export default class WindowedClockRegressor implements ClockRegressor {
+    public static Class?: ClockRegressorConstructor
+
+    private readonly nominalHz: number
+    private readonly windowLenSec: number
+    private readonly defaultWindowLenSec = 30
+    private readonly history: {
+        deviceTime: number
+        earliestLslTime: number
+    }[] = []
+
+    private slope = 1 // lsl-host-seconds per device-second
+
+    protected constructor(
+        nominalHz: number,
+        options?: WindowedClockRegressorOptions
+    ) {
+        const { windowLenSec = this.defaultWindowLenSec } = options ?? {}
+
+        this.nominalHz = nominalHz
+        this.windowLenSec = windowLenSec
+    }
+
+    public static Create(
+        nominalHz: number,
+        options?: WindowedClockRegressorOptions
+    ) {
+        return new (this.Class ?? this)(nominalHz, options)
+    }
+
+    public deriveTimestamps(
+        deviceTime: number,
+        earliestLslTime: number,
+        chunkSize: number
+    ) {
+        this.throwIfDeviceTimeDoesNotIncrease(deviceTime)
+
+        this.history.push({ deviceTime, earliestLslTime })
+        this.pruneHistoryOutsideWindow()
+        this.refitSlope()
+
+        const anchor = this.anchorTimeFor(deviceTime)
+
+        const timestamps = Array(chunkSize).fill(0)
+
+        for (let i = 0; i <= chunkSize - 1; i++) {
+            const stepsFromLast = chunkSize - 1 - i
+            const deviceTimeOffset = -stepsFromLast / this.nominalHz
+            const lslTimeOffset = deviceTimeOffset * this.slope
+
+            timestamps[i] = anchor + lslTimeOffset
+        }
+
+        return timestamps
+    }
+
+    private anchorTimeFor(deviceTime: number) {
+        const xMean = this.currentMeanDeviceTime
+        const yMean = this.currentMeanLslTime
+
+        return yMean + this.slope * (deviceTime - xMean)
+    }
+
+    private throwIfDeviceTimeDoesNotIncrease(deviceTime: number) {
+        const last = this.history[this.history.length - 1]
+
+        if (last && deviceTime <= last.deviceTime) {
+            throw new Error(
+                `\nDevice time (${deviceTime}) did not increase from the previous device time (${last.deviceTime})! Device time is expected to always increase between calls, so this likely indicates a bug in the calling code.\n`
+            )
+        }
+    }
+
+    private pruneHistoryOutsideWindow() {
+        const { deviceTime: latest } = this.history[this.history.length - 1]
+        const cutoff = latest - this.windowLenSec
+
+        while (this.history.length > 0 && this.history[0].deviceTime < cutoff) {
+            this.history.shift()
+        }
+    }
+
+    private refitSlope() {
+        if (this.history.length < 2) {
+            return
+        }
+
+        const xMean = this.currentMeanDeviceTime
+        const yMean = this.currentMeanLslTime
+
+        let numerator = 0
+        let denominator = 0
+
+        for (const { deviceTime, earliestLslTime } of this.history) {
+            const xCentered = deviceTime - xMean
+
+            numerator += xCentered * (earliestLslTime - yMean)
+            denominator += xCentered * xCentered
+        }
+
+        this.slope = numerator / denominator
+    }
+
+    private get currentMeanDeviceTime() {
+        const totalDeviceTime = this.history.reduce(
+            (sum, { deviceTime }) => sum + deviceTime,
+            0
+        )
+        return totalDeviceTime / this.history.length
+    }
+
+    private get currentMeanLslTime() {
+        const totalLslTime = this.history.reduce(
+            (sum, { earliestLslTime }) => sum + earliestLslTime,
+            0
+        )
+        return totalLslTime / this.history.length
+    }
+}
+
+export interface ClockRegressor {
+    deriveTimestamps(
+        deviceTime: number,
+        earliestLslTime: number,
+        chunkSize: number
+    ): number[]
+}
+
+export type ClockRegressorConstructor = new (
+    nominalHz: number,
+    options?: WindowedClockRegressorOptions
+) => ClockRegressor
+
+export interface WindowedClockRegressorOptions {
+    windowLenSec?: number
+}

package/src/impl/controllers/BleDeviceController.ts

@@ -165,6 +165,19 @@ export default class BleDeviceController implements BleController {
         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,
@@ -193,6 +206,10 @@ export interface BleController {
 
     connect(): Promise<void>
 
+    subscribeCharacteristics(
+        charCallbacks: CharacteristicCallbacks
+    ): Promise<void>
+
     writeCharacteristic(
         charUuid: CharacteristicUuid,
         value: 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/index.ts

@@ -1,3 +1,11 @@
+// ClockRegressor
+
+export { default as WindowedClockRegressor } from './impl/WindowedClockRegressor.js'
+export * from './impl/WindowedClockRegressor.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'
@@ -50,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/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

@@ -2,6 +2,7 @@ import generateId from '@neurodevs/generate-id'
 import {
     BleController,
     BleControllerOptions,
+    CharacteristicCallbacks,
 } from '../../impl/controllers/BleDeviceController.js'
 
 export default class FakeBleController implements BleController {
@@ -14,6 +15,9 @@ export default class FakeBleController implements BleController {
         value: string
     }[] = []
 
+    public static callsToSubscribeCharacteristics: CharacteristicCallbacks[] =
+        []
+
     public static numCallsToDisconnect = 0
 
     public static fakeCharacteristics: Record<string, unknown> = {}
@@ -45,6 +49,12 @@ export default class FakeBleController implements BleController {
         })
     }
 
+    public async subscribeCharacteristics(
+        charCallbacks: CharacteristicCallbacks
+    ) {
+        FakeBleController.callsToSubscribeCharacteristics.push(charCallbacks)
+    }
+
     public async disconnect() {
         FakeBleController.numCallsToDisconnect++
     }
@@ -61,6 +71,7 @@ export default class FakeBleController implements BleController {
         this.callsToConstructor = []
         this.numCallsToConnect = 0
         this.callsToWriteCharacteristic = []
+        this.callsToSubscribeCharacteristics = []
         this.numCallsToDisconnect = 0
     }
 }

package/src/testDoubles/ClockRegressor/FakeClockRegressor.ts

@@ -0,0 +1,46 @@
+import {
+    ClockRegressor,
+    WindowedClockRegressorOptions,
+} from '../../impl/WindowedClockRegressor.js'
+
+export default class FakeClockRegressor implements ClockRegressor {
+    public static callsToConstructor: {
+        nominalHz: number
+        options?: WindowedClockRegressorOptions
+    }[] = []
+    public static callsToDeriveTimestamps: {
+        deviceTime: number
+        earliestLslTime: number
+        chunkSize: number
+    }[] = []
+
+    public static fakeResultValue = 0
+
+    public readonly nominalHz: number
+
+    public constructor(
+        nominalHz: number,
+        options?: WindowedClockRegressorOptions
+    ) {
+        FakeClockRegressor.callsToConstructor.push({ nominalHz, options })
+        this.nominalHz = nominalHz
+    }
+
+    public deriveTimestamps(
+        deviceTime: number,
+        earliestLslTime: number,
+        chunkSize: number
+    ) {
+        FakeClockRegressor.callsToDeriveTimestamps.push({
+            deviceTime,
+            earliestLslTime,
+            chunkSize,
+        })
+        return Array(chunkSize).fill(FakeClockRegressor.fakeResultValue)
+    }
+
+    public static resetTestDouble() {
+        FakeClockRegressor.callsToConstructor = []
+        FakeClockRegressor.callsToDeriveTimestamps = []
+    }
+}

package/src/testDoubles/UsbController/FakeUsbController.ts

@@ -0,0 +1,34 @@
+import {
+    UsbController,
+    UsbControllerOptions,
+} from '../../impl/controllers/UsbDeviceController.js'
+
+export default class FakeUsbController implements UsbController {
+    public static callsToConstructor: (UsbControllerOptions | undefined)[] = []
+    public static numCallsToConnect = 0
+    public static callsToWriteUsb: string[] = []
+    public static numCallsToDisconnect = 0
+
+    public constructor(options?: UsbControllerOptions) {
+        FakeUsbController.callsToConstructor.push(options)
+    }
+
+    public async connect() {
+        FakeUsbController.numCallsToConnect++
+    }
+
+    public async writeUsb(value: string) {
+        FakeUsbController.callsToWriteUsb.push(value)
+    }
+
+    public async disconnect() {
+        FakeUsbController.numCallsToDisconnect++
+    }
+
+    public static resetTestDouble() {
+        FakeUsbController.callsToConstructor.length = 0
+        FakeUsbController.numCallsToConnect = 0
+        FakeUsbController.callsToWriteUsb.length = 0
+        FakeUsbController.numCallsToDisconnect = 0
+    }
+}