@neurodevs/node-lsl 20.0.0 → 22.1.0

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

@@ -28,7 +28,6 @@ export default class LslStreamOutletTest extends AbstractPackageTest {
 
         this.randomOutletOptions = generateRandomOutletOptions()
 
-        this.setFakeLiblsl()
         this.setFakeLslInfo()
 
         LslStreamOutlet.lsl = this.fakeLiblsl

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

@@ -18,7 +18,6 @@ export default class LslWebSocketBridgeTest extends AbstractPackageTest {
     protected static async beforeEach() {
         await super.beforeEach()
 
-        this.setFakeLiblsl()
         this.setFakeLslInlet()
         this.setFakeWebSocket()
         this.setFakeWebSocketServer()

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

@@ -1,13 +1,13 @@
 import { test, assert } from '@neurodevs/node-tdd'
 
 import UsbDeviceController, {
-    UsbController,
+    UsbDevice,
 } from '../../impl/controllers/UsbDeviceController.js'
 import AbstractPackageTest from '../AbstractPackageTest.js'
 import { FakeLibndx } from '@neurodevs/ndx-native'
 
 export default class UsbDeviceControllerTest extends AbstractPackageTest {
-    private static instance: UsbController
+    private static instance: UsbDevice
 
     private static readonly serialNumber = this.generateId()
     private static readonly valueToWrite = this.generateId()

package/src/impl/{LslEventMarkerEmitter.ts → LslEventMarkerOutlet.ts}

@@ -5,8 +5,8 @@ import LslStreamOutlet, {
     LslOutlet,
 } from './LslStreamOutlet.js'
 
-export default class LslEventMarkerEmitter implements LslEmitter {
-    public static Class?: LslEmitterConstructor
+export default class LslEventMarkerOutlet implements EventMarkerOutlet {
+    public static Class?: EventMarkerOutletConstructor
 
     protected outlet: LslOutlet
     private isRunning = false
@@ -17,7 +17,7 @@ export default class LslEventMarkerEmitter implements LslEmitter {
         this.outlet = outlet
     }
 
-    public static async Create(options?: LslEmitterOptions) {
+    public static async Create(options?: EventMarkerOutletOptions) {
         const outlet = await this.LslStreamOutlet(options)
         return new (this.Class ?? this)(outlet)
     }
@@ -110,16 +110,18 @@ export default class LslEventMarkerEmitter implements LslEmitter {
     }
 }
 
-export interface LslEmitter {
+export interface EventMarkerOutlet {
     emit(markerName: string, options?: EmitOptions): Promise<void>
     emitMany(markers: TimedEventMarker[]): Promise<void>
     interrupt(): void
     destroy(): void
 }
 
-export type LslEmitterOptions = Partial<LslOutletOptions>
+export type EventMarkerOutletOptions = Partial<LslOutletOptions>
 
-export type LslEmitterConstructor = new (outlet: LslOutlet) => LslEmitter
+export type EventMarkerOutletConstructor = new (
+    outlet: LslOutlet
+) => EventMarkerOutlet
 
 export interface EmitOptions {
     waitAfterMs?: number

package/src/impl/LslJsonOutlet.ts

@@ -0,0 +1,87 @@
+import LslStreamOutlet, { LslOutlet } from './LslStreamOutlet.js'
+
+export default class LslJsonOutlet implements JsonOutlet {
+    public static Class?: JsonOutletConstructor
+    public static backupIdCounter = 0
+
+    private outlet: LslOutlet
+    private maxBytesPerSample?: number
+
+    protected constructor(outlet: LslOutlet, maxBytesPerSample?: number) {
+        this.outlet = outlet
+        this.maxBytesPerSample = maxBytesPerSample
+    }
+
+    public static async Create(options?: JsonOutletOptions) {
+        const outlet = await this.LslStreamOutlet(options)
+        return new (this.Class ?? this)(outlet, options?.maxBytesPerSample)
+    }
+
+    public pushJson(data: Json) {
+        const json = JSON.stringify(data)
+        this.throwIfPayloadTooLarge(json)
+        this.outlet.pushSample([json])
+    }
+
+    private throwIfPayloadTooLarge(json: string) {
+        const totalBytes = Buffer.byteLength(json)
+
+        if (this.maxBytesPerSample && totalBytes > this.maxBytesPerSample) {
+            throw new Error(
+                `Payload of ${totalBytes} bytes exceeds maxBytesPerSample of ${this.maxBytesPerSample}!`
+            )
+        }
+    }
+
+    public destroy() {
+        this.outlet.destroy()
+    }
+
+    private static LslStreamOutlet(options?: JsonOutletOptions) {
+        this.backupIdCounter++
+
+        const { channelName, maxBytesPerSample: _, ...rest } = options ?? {}
+
+        return LslStreamOutlet.Create({
+            name: `JSON (json-${this.backupIdCounter})`,
+            type: 'JSON',
+            sourceId: `json-${this.backupIdCounter}`,
+            channelNames: [channelName ?? 'JSON'],
+            channelFormat: 'string',
+            sampleRateHz: 0,
+            chunkSize: 1,
+            ...rest,
+        })
+    }
+}
+
+export interface JsonOutlet {
+    pushJson(data: Json): void
+    destroy(): void
+}
+
+export type Json = Record<string, unknown>
+
+export type JsonOutletConstructor = new (
+    outlet: LslOutlet,
+    maxBytesPerSample?: number
+) => JsonOutlet
+
+export interface JsonOutletOptions {
+    name?: string
+    type?: string
+    sourceId?: string
+    channelName?: string
+    sampleRateHz?: number
+    chunkSize?: number
+    maxBufferedMs?: number
+    maxBytesPerSample?: number
+    manufacturer?: string
+    units?: string
+    waitAfterConstructionMs?: number
+}
+
+export type JsonOutletConstructorOptions = Omit<
+    JsonOutletOptions,
+    'waitAfterConstructionMs'
+>

package/src/impl/LslStreamOutlet.ts

@@ -180,11 +180,7 @@ export interface LslOutlet {
 
 export type LslOutletConstructor = new (options: LslOutletOptions) => LslOutlet
 
-export interface LslOutletOptions extends LslOutletConstructorOptions {
-    waitAfterConstructionMs?: number
-}
-
-export interface LslOutletConstructorOptions {
+export interface LslOutletOptions {
     name: string
     type: string
     sourceId: string
@@ -195,4 +191,10 @@ export interface LslOutletConstructorOptions {
     maxBufferedMs?: number
     manufacturer?: string
     units?: string
+    waitAfterConstructionMs?: number
 }
+
+export type LslOutletConstructorOptions = Omit<
+    LslOutletOptions,
+    'waitAfterConstructionMs'
+>

package/src/impl/controllers/{BleDeviceController.ts → BleGattController.ts}

@@ -1,7 +1,7 @@
 import { LibndxAdapter, Libndx, NativePeripheral } from '@neurodevs/ndx-native'
 
-export default class BleDeviceController implements BleController {
-    public static Class?: BleControllerConstructor
+export default class BleGattController implements BleGatt {
+    public static Class?: BleGattConstructor
     public static setTimeout = setTimeout
     public static waitAfterMs = 1000
 
@@ -28,7 +28,7 @@ export default class BleDeviceController implements BleController {
     private deviceName?: string
     private onConnected?: (peripheral: NativePeripheral) => void
 
-    protected constructor(options: BleControllerOptions) {
+    protected constructor(options: BleGattOptions) {
         const {
             deviceUuid,
             deviceNamePrefix,
@@ -44,7 +44,7 @@ export default class BleDeviceController implements BleController {
         this.rssiIntervalMs = rssiIntervalMs
     }
 
-    public static Create(options: BleControllerOptions) {
+    public static Create(options: BleGattOptions) {
         return new (this.Class ?? this)(options)
     }
 
@@ -53,13 +53,13 @@ export default class BleDeviceController implements BleController {
             await this.discoverUuid()
         }
 
-        this.createBleBackend()
-        this.startBleBackend()
+        this.createBleGattBackend()
+        this.startBleGattBackend()
 
         await this.waitForOnConnected()
         await this.waitToDiscoverServices()
 
-        this.setBleRssiInterval()
+        this.startBleGattRssiPolling()
     }
 
     private async discoverUuid() {
@@ -81,15 +81,15 @@ export default class BleDeviceController implements BleController {
                 if (this.deviceUuid) {
                     resolve()
                 } else {
-                    BleDeviceController.setTimeout(checkDiscovered, 100)
+                    BleGattController.setTimeout(checkDiscovered, 100)
                 }
             }
             checkDiscovered()
         })
     }
 
-    private createBleBackend() {
-        const { status, error } = this.ndx.createBleBackend({
+    private createBleGattBackend() {
+        const { status, error } = this.ndx.createBleGattBackend({
             deviceUuid: this.uuid,
         })
 
@@ -102,9 +102,9 @@ export default class BleDeviceController implements BleController {
         }
     }
 
-    private setBleRssiInterval() {
+    private startBleGattRssiPolling() {
         if (this.rssiIntervalMs) {
-            this.ndx.setBleRssiInterval({
+            this.ndx.startBleGattRssiPolling({
                 deviceUuid: this.uuid,
                 intervalMs: this.rssiIntervalMs,
                 onRssi: (rssi: number) => {
@@ -114,8 +114,8 @@ export default class BleDeviceController implements BleController {
         }
     }
 
-    private startBleBackend() {
-        const { status, error } = this.ndx.startBleBackend({
+    private startBleGattBackend() {
+        const { status, error } = this.ndx.startBleGattBackend({
             deviceUuid: this.uuid,
             onConnected: (peripheral: NativePeripheral) => {
                 const { name } = peripheral
@@ -136,7 +136,7 @@ export default class BleDeviceController implements BleController {
                 if (this.connected) {
                     resolve()
                 } else {
-                    BleDeviceController.setTimeout(checkConnected, 100)
+                    BleGattController.setTimeout(checkConnected, 100)
                 }
             }
             checkConnected()
@@ -145,10 +145,7 @@ export default class BleDeviceController implements BleController {
 
     private async waitToDiscoverServices() {
         await new Promise<void>((resolve) =>
-            BleDeviceController.setTimeout(
-                resolve,
-                BleDeviceController.waitAfterMs
-            )
+            BleGattController.setTimeout(resolve, BleGattController.waitAfterMs)
         )
     }
 
@@ -156,7 +153,7 @@ export default class BleDeviceController implements BleController {
         charUuid: CharacteristicUuid,
         value: string
     ) {
-        const { status, error } = this.ndx.writeBleCharacteristic({
+        const { status, error } = this.ndx.writeBleGattChar({
             deviceUuid: this.uuid,
             charUuid,
             value,
@@ -168,7 +165,7 @@ export default class BleDeviceController implements BleController {
     public async subscribeCharacteristics(
         charCallbacks: CharacteristicCallbacks
     ) {
-        const { status, error } = this.ndx.addBleCharCallbacks({
+        const { status, error } = this.ndx.registerBleGattCharCallbacks({
             deviceUuid: this.uuid,
             charCallbacks,
         })
@@ -179,7 +176,7 @@ export default class BleDeviceController implements BleController {
     }
 
     public async disconnect() {
-        const { status, error } = this.ndx.stopBleBackend({
+        const { status, error } = this.ndx.stopBleGattBackend({
             deviceUuid: this.uuid,
         })
 
@@ -196,11 +193,11 @@ export default class BleDeviceController implements BleController {
     }
 
     private get ndx() {
-        return BleDeviceController.ndx
+        return BleGattController.ndx
     }
 }
 
-export interface BleController {
+export interface BleGatt {
     uuid: string
     name: string
 
@@ -218,7 +215,7 @@ export interface BleController {
     disconnect(): Promise<void>
 }
 
-export type BleControllerOptions = {
+export type BleGattOptions = {
     charCallbacks: CharacteristicCallbacks
     onConnected?: (peripheral: NativePeripheral) => void
     rssiIntervalMs?: number
@@ -227,9 +224,7 @@ export type BleControllerOptions = {
     | { deviceUuid?: string; deviceNamePrefix: string }
 )
 
-export type BleControllerConstructor = new (
-    options: BleControllerOptions
-) => BleController
+export type BleGattConstructor = new (options: BleGattOptions) => BleGatt
 
 export type CharacteristicCallbacks = {
     charUuid: string

package/src/impl/controllers/BleObserverController.ts

@@ -0,0 +1,85 @@
+import { LibndxAdapter } from '@neurodevs/ndx-native'
+
+export default class BleObserverController implements BleObserver {
+    public static Class?: BleObserverConstructor
+
+    private readonly deviceUuid: string
+    private readonly onAdvertisement?: OnAdvertisement
+    private readonly ndx = LibndxAdapter.getInstance()
+
+    protected constructor(options: BleObserverOptions) {
+        const { deviceUuid, onAdvertisement } = options
+
+        this.deviceUuid = deviceUuid ?? ''
+        this.onAdvertisement = onAdvertisement
+    }
+
+    public static Create(options: BleObserverOptions) {
+        return new (this.Class ?? this)(options)
+    }
+
+    public async startObserving() {
+        this.createBleObserverBackend()
+        this.startBleObserverBackend()
+    }
+
+    private createBleObserverBackend() {
+        const { status, error } = this.ndx.createBleObserverBackend({
+            deviceUuid: this.deviceUuid,
+        })
+
+        this.throwIfError(status, error)
+    }
+
+    private startBleObserverBackend() {
+        const { status, error } = this.ndx.startBleObserverBackend({
+            deviceUuid: this.deviceUuid,
+            onAdvertisement: (
+                data: Buffer,
+                length: number,
+                timestampSec: number
+            ) => {
+                this.onAdvertisement?.(data, length, timestampSec)
+            },
+        })
+
+        this.throwIfError(status, error)
+    }
+
+    public async stopObserving() {
+        this.stopBleObserverBackend()
+    }
+
+    private stopBleObserverBackend() {
+        const { status, error } = this.ndx.stopBleObserverBackend({
+            deviceUuid: this.deviceUuid,
+        })
+
+        this.throwIfError(status, error)
+    }
+
+    private throwIfError(status: number, error: string | undefined) {
+        if (status !== 200) {
+            throw new Error(`${status} error: ${error ?? 'Unknown error'}`)
+        }
+    }
+}
+export interface BleObserver {
+    startObserving(): Promise<void>
+    stopObserving(): Promise<void>
+}
+
+export type BleObserverConstructor = new (
+    options: BleObserverOptions
+) => BleObserver
+
+export type BleObserverOptions = {
+    deviceUuid: string
+    onAdvertisement?: OnAdvertisement
+}
+
+export type OnAdvertisement = (
+    data: Buffer,
+    length: number,
+    timestampSec: number
+) => void

package/src/impl/controllers/UsbDeviceController.ts

@@ -1,65 +1,63 @@
 import { LibndxAdapter } from '@neurodevs/ndx-native'
 
-export default class UsbDeviceController implements UsbController {
-    public static Class?: UsbControllerConstructor
+export default class UsbDeviceController implements UsbDevice {
+    public static Class?: UsbDeviceConstructor
 
     private onData: (data: Buffer, length: number, timestampSec: number) => void
     private serialNumber: string
 
     private ndx = LibndxAdapter.getInstance()
 
-    protected constructor(options: UsbControllerOptions) {
+    protected constructor(options: UsbDeviceOptions) {
         const { onData, serialNumber } = options ?? {}
 
         this.onData = onData
         this.serialNumber = serialNumber ?? ''
     }
 
-    public static Create(options: UsbControllerOptions) {
+    public static Create(options: UsbDeviceOptions) {
         return new (this.Class ?? this)(options)
     }
 
     public async connect() {
-        this.ndx.createUsbBackend(this.usbControllerOptions)
-        this.ndx.startUsbBackend(this.startUsbControllerOptions)
+        this.ndx.createUsbBackend(this.usbDeviceOptions)
+        this.ndx.startUsbBackend(this.startUsbDeviceOptions)
     }
 
-    private get usbControllerOptions() {
+    private get usbDeviceOptions() {
         return {
             serialNumber: this.serialNumber,
         }
     }
 
-    private get startUsbControllerOptions() {
+    private get startUsbDeviceOptions() {
         return {
-            ...this.usbControllerOptions,
+            ...this.usbDeviceOptions,
             onData: this.onData,
         }
     }
 
     public async writeUsb(value: string) {
         this.ndx.writeUsbBackend({
-            ...this.usbControllerOptions,
+            ...this.usbDeviceOptions,
             value,
         })
     }
 
     public async disconnect() {
-        this.ndx.stopUsbBackend(this.usbControllerOptions)
+        this.ndx.stopUsbBackend(this.usbDeviceOptions)
     }
 }
 
-export interface UsbController {
+export interface UsbDevice {
     connect(): Promise<void>
     writeUsb(value: string): Promise<void>
     disconnect(): Promise<void>
 }
 
-export interface UsbControllerOptions {
+export interface UsbDeviceOptions {
     onData: (data: Buffer, length: number, timestampSec: number) => void
     serialNumber?: string
 }
 
-export type UsbControllerConstructor = new (
-    options?: UsbControllerOptions
-) => UsbController
+export type UsbDeviceConstructor = new (options?: UsbDeviceOptions) => UsbDevice

package/src/index.ts

@@ -1,3 +1,11 @@
+// BleObserver
+
+export { default as BleObserverController } from './impl/controllers/BleObserverController.js'
+export * from './impl/controllers/BleObserverController.js'
+
+export { default as FakeBleObserver } from './testDoubles/BleObserver/FakeBleObserver.js'
+export * from './testDoubles/BleObserver/FakeBleObserver.js'
+
 // ClockRegressor
 
 export { default as WindowedClockRegressor } from './impl/clocks/WindowedClockRegressor.js'
@@ -6,16 +14,38 @@ export * from './impl/clocks/WindowedClockRegressor.js'
 export { default as FakeClockRegressor } from './testDoubles/ClockRegressor/FakeClockRegressor.js'
 export * from './testDoubles/ClockRegressor/FakeClockRegressor.js'
 
-// DeviceController
+// BleGatt
+
+export { default as BleGattController } from './impl/controllers/BleGattController.js'
+export * from './impl/controllers/BleGattController.js'
+
+export { default as SpyBleGatt } from './testDoubles/BleGatt/SpyBleGatt.js'
+export * from './testDoubles/BleGatt/SpyBleGatt.js'
+
+export { default as FakeBleGatt } from './testDoubles/BleGatt/FakeBleGatt.js'
+export * from './testDoubles/BleGatt/FakeBleGatt.js'
+
+// EventMarkerOutlet
+
+export { default as LslEventMarkerOutlet } from './impl/LslEventMarkerOutlet.js'
+export * from './impl/LslEventMarkerOutlet.js'
 
-export { default as BleDeviceController } from './impl/controllers/BleDeviceController.js'
-export * from './impl/controllers/BleDeviceController.js'
+export { default as SpyEventMarkerOutlet } from './testDoubles/EventMarkerOutlet/SpyEventMarkerOutlet.js'
+export * from './testDoubles/EventMarkerOutlet/SpyEventMarkerOutlet.js'
 
-export { default as SpyBleController } from './testDoubles/BleController/SpyBleController.js'
-export * from './testDoubles/BleController/SpyBleController.js'
+export { default as FakeEventMarkerOutlet } from './testDoubles/EventMarkerOutlet/FakeEventMarkerOutlet.js'
+export * from './testDoubles/EventMarkerOutlet/FakeEventMarkerOutlet.js'
 
-export { default as FakeBleController } from './testDoubles/BleController/FakeBleController.js'
-export * from './testDoubles/BleController/FakeBleController.js'
+export { default as ThrowingEventMarkerOutlet } from './testDoubles/EventMarkerOutlet/ThrowingEventMarkerOutlet.js'
+export * from './testDoubles/EventMarkerOutlet/ThrowingEventMarkerOutlet.js'
+
+// JsonOutlet
+
+export { default as LslJsonOutlet } from './impl/LslJsonOutlet.js'
+export * from './impl/LslJsonOutlet.js'
+
+export { default as FakeJsonOutlet } from './testDoubles/JsonOutlet/FakeJsonOutlet.js'
+export * from './testDoubles/JsonOutlet/FakeJsonOutlet.js'
 
 // LslWsBridge
 
@@ -28,20 +58,6 @@ export * from './testDoubles/LslWsBridge/SpyLslWsBridge.js'
 export { default as FakeLslWsBridge } from './testDoubles/LslWsBridge/FakeLslWsBridge.js'
 export * from './testDoubles/LslWsBridge/FakeLslWsBridge.js'
 
-// LslEmitter
-
-export { default as LslEventMarkerEmitter } from './impl/LslEventMarkerEmitter.js'
-export * from './impl/LslEventMarkerEmitter.js'
-
-export { default as SpyLslEmitter } from './testDoubles/LslEmitter/SpyLslEmitter.js'
-export * from './testDoubles/LslEmitter/SpyLslEmitter.js'
-
-export { default as FakeLslEmitter } from './testDoubles/LslEmitter/FakeLslEmitter.js'
-export * from './testDoubles/LslEmitter/FakeLslEmitter.js'
-
-export { default as ThrowingLslEmitter } from './testDoubles/LslEmitter/ThrowingLslEmitter.js'
-export * from './testDoubles/LslEmitter/ThrowingLslEmitter.js'
-
 // LslInfo
 
 export { default as LslStreamInfo } from './impl/LslStreamInfo.js'
@@ -74,13 +90,13 @@ export * from './testDoubles/LslOutlet/FakeLslOutlet.js'
 
 export { default as generateRandomOutletOptions } from './testDoubles/generateRandomOutletOptions.js'
 
-// UsbController
+// UsbDevice
 
 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'
+export { default as FakeUsbDevice } from './testDoubles/UsbDevice/FakeUsbDevice.js'
+export * from './testDoubles/UsbDevice/FakeUsbDevice.js'
 
 // WebSockets
 

package/src/scripts/{runLslEmitter.ts → runEventMarkerOutlet.ts}

@@ -1,6 +1,6 @@
-import LslEventMarkerEmitter from '../impl/LslEventMarkerEmitter.js'
+import LslEventMarkerOutlet from '../impl/LslEventMarkerOutlet.js'
 
-const emitter = await LslEventMarkerEmitter.Create()
+const outlet = await LslEventMarkerOutlet.Create()
 
 const markers = [
     { name: 'phase-1-begin', waitAfterMs: 100 },
@@ -8,9 +8,9 @@ const markers = [
     { name: 'never-reached-marker', waitAfterMs: 100 },
 ]
 
-void emitter.emitMany(markers)
+void outlet.emitMany(markers)
 
 await new Promise((resolve) => setTimeout(resolve, 250))
 
-emitter.interrupt()
-emitter.destroy()
+outlet.interrupt()
+outlet.destroy()

package/src/scripts/runMuse.ts

@@ -1,6 +1,6 @@
 import koffi from 'koffi'
 
-import BleDeviceController from '../impl/controllers/BleDeviceController.js'
+import BleGattController from '../impl/controllers/BleGattController.js'
 
 const MUSE_CHARACTERISTIC_UUIDS: Record<string, string> = {
     CONTROL: '273E0001-4C4D-454D-96BE-F03BAC821358',
@@ -32,7 +32,7 @@ const charCallbacks = Object.entries(MUSE_CHARACTERISTIC_UUIDS).map(
     }
 )
 
-const muse = BleDeviceController.Create({
+const muse = BleGattController.Create({
     deviceUuid: 'CA6A61B7-B7A8-AF24-3C9E-04A6A5012554',
     charCallbacks,
     rssiIntervalMs: 1000,