@robotical/raftjs 2.0.11 → 2.1.2

package/src/RaftChannelWebSocket.ts

@@ -175,6 +175,16 @@ export default class RaftChannelWebSocket implements RaftChannel {
     //     return false;
     // }
     this._webSocket = null;
+    // Close any existing WebSocket before creating new one
+    RaftLog.verbose(`[RaftChannelWebSocket._wsConnect] START existing WebSocket?, ${!!this._webSocket}`);
+    if (this._webSocket) {
+      RaftLog.verbose(`[RaftChannelWebSocket._wsConnect] Closing existing WebSocket...`);
+      try {
+        this._webSocket.close(1000);
+      } catch (e) {
+        RaftLog.warn(`[RaftChannelWebSocket._wsConnect] Error closing existing WebSocket: ${e}`);
+      }
+    }
     return new Promise((resolve: (value: boolean | PromiseLike<boolean>) => void,
       reject: (reason?: unknown) => void) => {
       this._webSocketOpen(wsURL).then((ws) => {
@@ -222,6 +232,7 @@ export default class RaftChannelWebSocket implements RaftChannel {
 
       // Open the socket
       try {
+        RaftLog.verbose(`[RaftChannelWebSocket._webSocketOpen] Creating WebSocket: ${url}`);
         const webSocket = new WebSocket(url);
 
         // Open socket
@@ -232,10 +243,13 @@ export default class RaftChannelWebSocket implements RaftChannel {
           this._isConnected = true;
           resolve(webSocket);
         };
-        webSocket.onerror = function (evt: WebSocket.ErrorEvent) {
+        webSocket.onerror = (evt: WebSocket.ErrorEvent) => {
           RaftLog.warn(`RaftChannelWebSocket._webSocketOpen - onerror: ${evt.message}`);
           reject(evt);
-        }
+        };
+        webSocket.onclose = (evt: WebSocket.CloseEvent) => {
+          RaftLog.info(`[RaftChannelWebSocket._webSocketOpen] onclose fired! code: ${evt.code} reason: ${evt.reason} wasClean: ${evt.wasClean}`);
+        };
       } catch (error: unknown) {
         RaftLog.warn(`RaftChannelWebSocket._webSocketOpen - open failed ${error}`);
         reject(error);

package/src/RaftConnector.ts

@@ -14,7 +14,7 @@ import RaftChannelWebSocket from "./RaftChannelWebSocket";
 import RaftChannelWebSerial from "./RaftChannelWebSerial";
 import RaftChannelSimulated from "./RaftChannelSimulated";
 import RaftCommsStats from "./RaftCommsStats";
-import { RaftEventFn, RaftOKFail, RaftFileSendType, RaftFileDownloadResult, RaftProgressCBType, RaftBridgeSetupResp, RaftFileDownloadFn, RaftReportMsg } from "./RaftTypes";
+import { RaftEventFn, RaftOKFail, RaftFileSendType, RaftFileDownloadResult, RaftProgressCBType, RaftStreamDataProgressCBType, RaftBridgeSetupResp, RaftFileDownloadFn, RaftReportMsg } from "./RaftTypes";
 import RaftSystemUtils from "./RaftSystemUtils";
 import RaftFileHandler from "./RaftFileHandler";
 import RaftStreamHandler from "./RaftStreamHandler";
@@ -23,8 +23,7 @@ import { RaftConnEvent, RaftConnEventNames } from "./RaftConnEvents";
 import { RaftGetSystemTypeCBType, RaftSystemType } from "./RaftSystemType";
 import { RaftUpdateEvent, RaftUpdateEventNames } from "./RaftUpdateEvents";
 import RaftUpdateManager from "./RaftUpdateManager";
-import { createBLEChannel } from "./RaftChannelBLEFactory";
-
+import { createBLEChannel } from "./RaftChannelBLEFactory";import { getHostPosixTZ } from './RaftTimezone';
 
 export default class RaftConnector {
 
@@ -214,7 +213,22 @@ export default class RaftConnector {
    * Initialize the Raft channel
    */
   async initializeChannel(method: string): Promise<boolean> {
+    // Disconnect any existing channel first to avoid stale connections
+    RaftLog.verbose(`[RaftConnector.initializeChannel] START method=${method} hasExistingChannel=${!!this._raftChannel}`);
+    if (this._raftChannel) {
+      RaftLog.verbose(`[RaftConnector.initializeChannel] Disconnecting existing channel...`);
+      try {
+        await this._raftChannel.disconnect();
+        RaftLog.verbose(`[RaftConnector.initializeChannel] Existing channel disconnected successfully`);
+      } catch (e) {
+        RaftLog.warn(`[RaftConnector.initializeChannel] Error disconnecting existing channel: ${e}`);
+      }
+      this._raftChannel = null;
+      RaftLog.verbose(`[RaftConnector.initializeChannel] Existing channel nulled`);
+    }
+
     // Initialize raft channel
+    RaftLog.verbose(`[RaftConnector.initializeChannel] Creating new channel...`);
     if (method === 'WebBLE' || method === 'PhoneBLE') {
       const RaftChannelBLE = createBLEChannel();
       this._raftChannel = new RaftChannelBLE();
@@ -226,7 +240,7 @@ export default class RaftConnector {
       this._raftChannel = new RaftChannelWebSerial();
       this._channelConnMethod = 'WebSerial';
     } else if (method === 'Simulated') {
-      this._raftChannel = new RaftChannelSimulated(); 
+      this._raftChannel = new RaftChannelSimulated();
       this._channelConnMethod = 'Simulated';
     } else {
       RaftLog.warn('Unknown method: ' + method);
@@ -268,7 +282,7 @@ export default class RaftConnector {
     // Store locator
     this._channelConnLocator = locator;
 
-    // Connect
+    // Connect channel first (system type resolution needs a live connection)
     let connOk = false;
     try {
       // Event
@@ -281,9 +295,9 @@ export default class RaftConnector {
     }
 
     if (connOk) {
-      // Get system type
+
+      // Resolve system type now that the channel is connected
       if (this._getSystemTypeCB) {
-        // Get system type
         this._systemType = await this._getSystemTypeCB(this._raftSystemUtils);
 
         // Set defaults
@@ -310,14 +324,36 @@ export default class RaftConnector {
         }
       }
 
+      // configure file handler
+      this.configureFileHandler(this._raftChannel.fhFileBlockSize(), this._raftChannel.fhBatchAckSize());
+
+      // Sync time to device if enabled (default: true)
+      const syncTime = this._systemType?.connectorOptions?.syncTimeOnConnect ?? true;
+      if (syncTime) {
+        try {
+          const now = new Date();
+          const utc = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+          const params: Record<string, string> = { UTC: utc };
+          const posixTZ = getHostPosixTZ();
+          if (posixTZ) {
+            params.tz = posixTZ;
+          }
+          await this.sendRICRESTMsg('datetime', params);
+          RaftLog.info(`connect synced time to device: ${utc}${posixTZ ? ` tz=${posixTZ}` : ''}`);
+        } catch (error) {
+          RaftLog.warn(`connect time sync failed: ${error}`);
+        }
+      }
+
       // Send connected event
       this.onConnEvent(RaftConnEvent.CONN_CONNECTED);
 
     } else {
       // Failed Event
       this.onConnEvent(RaftConnEvent.CONN_CONNECTION_FAILED);
-      // configure file handler
-      this.configureFileHandler(this._raftChannel.fhFileBlockSize(), this._raftChannel.fhBatchAckSize());
+
+      // Clear system type
+      this._systemType = null;
     }
 
     return connOk;
@@ -327,8 +363,12 @@ export default class RaftConnector {
     // Disconnect
     this._retryIfLostIsConnected = false;
     if (this._raftChannel) {
+      // Store reference to channel before async operations to avoid race condition
+      const channelToDisconnect = this._raftChannel;
+      this._raftChannel = null;
+
       // Check if there is a RICREST command to send before disconnecting
-      const ricRestCommand = this._raftChannel.ricRestCmdBeforeDisconnect();
+      const ricRestCommand = channelToDisconnect.ricRestCmdBeforeDisconnect();
       if (ricRestCommand) {
         console.log(`sending RICREST command before disconnect: ${ricRestCommand}`);
         await this.sendRICRESTMsg(ricRestCommand, {});
@@ -336,8 +376,24 @@ export default class RaftConnector {
       // Pause a little before disconnecting
       await new Promise(resolve => setTimeout(resolve, 1000));
       // await this.sendRICRESTMsg("bledisc", {});
-      await this._raftChannel.disconnect();
-      this._raftChannel = null;
+      await channelToDisconnect.disconnect();
+    }
+  }
+
+  disconnectForPageUnload(): void {
+    this._retryIfLostIsConnected = false;
+
+    if (!this._raftChannel) {
+      return;
+    }
+
+    const channelToDisconnect = this._raftChannel;
+    this._raftChannel = null;
+
+    try {
+      void channelToDisconnect.disconnect();
+    } catch (error) {
+      RaftLog.warn(`RaftConnector.disconnectForPageUnload failed ${error}`);
     }
   }
 
@@ -456,6 +512,28 @@ export default class RaftConnector {
 
   // Mark: Streaming --------------------------------------------------------------------------------
 
+  /**
+   * streamData - stream arbitrary data to a named firmware endpoint using the RT_STREAM protocol.
+   * @param streamContents data to stream
+   * @param fileName logical filename sent in ufStart (e.g. "pattern.thr")
+   * @param targetEndpoint REST API endpoint name on the firmware (e.g. "streampattern")
+   * @param progressCallback optional (sent, total, progress) callback
+   * @returns Promise<boolean> true on success
+   */
+  async streamData(
+    streamContents: Uint8Array,
+    fileName: string,
+    targetEndpoint: string,
+    progressCallback?: RaftStreamDataProgressCBType,
+  ): Promise<boolean> {
+    if (this._raftStreamHandler && this.isConnected()) {
+      return this._raftStreamHandler.streamData(
+        streamContents, fileName, targetEndpoint, progressCallback,
+      );
+    }
+    return false;
+  }
+
   /**
    * streamAudio - stream audio
    * @param streamContents audio data
@@ -534,7 +612,7 @@ export default class RaftConnector {
    */
   async checkConnPerformance(): Promise<number | undefined> {
 
-    // Sends a magic sequence of bytes followed by blocks of random data 
+    // Sends a magic sequence of bytes followed by blocks of random data
     // these will be ignored by the Raft library (as it recognises magic sequence)
     // and is used performance evaluation
     let prbsState = 1;
@@ -681,8 +759,8 @@ export default class RaftConnector {
 
   /**
    * onUpdateEvent - handle update event
-   * @param eventEnum 
-   * @param data 
+   * @param eventEnum
+   * @param data
    */
   _onUpdateEvent(eventEnum: RaftUpdateEvent, data: object | string | null | undefined = undefined): void {
     // Notify

package/src/RaftCustomAttrHandler.ts

@@ -8,6 +8,7 @@
 /////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
 import { CustomFunctionDefinition, DeviceTypePollRespMetadata } from "./RaftDeviceInfo";
+import { transpilePseudocodeToJs } from "./PseudocodeTranspiler";
 
 type CustomAttrJsFn = (
     buf: Uint8Array,
@@ -22,8 +23,8 @@ type CustomAttrJsFn = (
 export default class CustomAttrHandler {
 
     private _jsFunctionCache = new Map<string, CustomAttrJsFn>();
-    
-    public handleAttr(pollRespMetadata: DeviceTypePollRespMetadata, msgBuffer: Uint8Array, msgBufIdx: number): number[][] {
+
+    public handleAttr(pollRespMetadata: DeviceTypePollRespMetadata, msgBuffer: Uint8Array, msgBufIdx: number, msgEndIdx = msgBuffer.length): number[][] {
 
         // Number of bytes in each message
         const numMsgBytes = pollRespMetadata.b;
@@ -45,59 +46,48 @@ export default class CustomAttrHandler {
             return attrValueVecs;
         }
 
-        // Provide the message buffer sliced to the data portion
-        const buf = msgBuffer.slice(msgBufIdx);
-        if (buf.length < numMsgBytes) {
+        // Provide this poll block to the custom handler. Use the smaller of
+        // pollRespMetadata.b and the bytes actually available — variable-length
+        // samples may be shorter than b, and the last sample in a frame may not
+        // have b bytes remaining in the buffer.
+        const boundedMsgEndIdx = Math.min(Math.max(msgEndIdx, msgBufIdx), msgBuffer.length);
+        const availableBytes = Math.min(numMsgBytes, boundedMsgEndIdx - msgBufIdx);
+        if (availableBytes <= 0) {
             return [];
         }
+        const buf = msgBuffer.slice(msgBufIdx, msgBufIdx + availableBytes);
 
-        // Execute supplied JS implementation if provided
-        if (customFnDef.j && customFnDef.j.trim().length > 0) {
-            const jsFn = this.getOrCompileJsFunction(customFnDef);
-            if (!jsFn) {
-                return attrValueVecs;
-            }
-            try {
-                jsFn(buf, attrValues, attrValueVecs, pollRespMetadata, msgBuffer, msgBufIdx, numMsgBytes);
-            } catch (err) {
-                console.error(`CustomAttrHandler JS function ${customFnDef.n} execution failed`, err);
-            }
+        const fn = this.getOrCompileFunction(customFnDef);
+        if (!fn) {
             return attrValueVecs;
         }
 
-        // Custom code for each device type handled natively
-        if (customFnDef.n === "max30101_fifo") {
-            // Generated code ...
-            const N = (buf[0] + 32 - buf[2]) % 32;
-            let k = 3;
-            let i = 0;
-            while (i < N) {
-                attrValues["Red"].push(0);
-                attrValues["Red"][attrValues["Red"].length - 1] = (buf[k] << 16) | (buf[k + 1] << 8) | buf[k + 2];
-                attrValues["IR"].push(0);
-                attrValues["IR"][attrValues["IR"].length - 1] = (buf[k + 3] << 16) | (buf[k + 4] << 8) | buf[k + 5];
-                k += 6;
-                i++;
-            }
-        } else if (customFnDef.n === "gravity_o2_calc") {
-            const key = 20.9 / 120.0;
-            const val = key * (buf[0] + buf[1] / 10.0 + buf[2] / 100.0);
-            attrValues["oxygen"].push(val);
+        try {
+            fn(buf, attrValues, attrValueVecs, pollRespMetadata, msgBuffer, msgBufIdx, numMsgBytes);
+        } catch (err) {
+            console.error(`CustomAttrHandler function ${customFnDef.n} execution failed`, err);
         }
         return attrValueVecs;
     }
 
-    private getOrCompileJsFunction(customFnDef: CustomFunctionDefinition): CustomAttrJsFn | null {
-        if (!customFnDef.j) {
+    private getOrCompileFunction(customFnDef: CustomFunctionDefinition): CustomAttrJsFn | null {
+        // Prefer explicit JS if provided, otherwise transpile from pseudocode
+        let jsSource = customFnDef.j?.trim();
+        if (!jsSource && customFnDef.c) {
+            jsSource = transpilePseudocodeToJs(customFnDef.c);
+        }
+        if (!jsSource) {
             return null;
         }
-        const cacheKey = `${customFnDef.n}::${customFnDef.j}`;
-        const cachedFn = this._jsFunctionCache.get(cacheKey);
-        if (cachedFn) {
-            return cachedFn;
+
+        const cacheKey = `${customFnDef.n}::${jsSource}`;
+        const cached = this._jsFunctionCache.get(cacheKey);
+        if (cached) {
+            return cached;
         }
+
         try {
-            const compiledFn = new Function(
+            const fn = new Function(
                 "buf",
                 "attrValues",
                 "attrValueVecs",
@@ -105,12 +95,12 @@ export default class CustomAttrHandler {
                 "msgBuffer",
                 "msgBufIdx",
                 "numMsgBytes",
-                customFnDef.j
+                jsSource
             ) as CustomAttrJsFn;
-            this._jsFunctionCache.set(cacheKey, compiledFn);
-            return compiledFn;
+            this._jsFunctionCache.set(cacheKey, fn);
+            return fn;
         } catch (err) {
-            console.error(`CustomAttrHandler failed to compile JS function ${customFnDef.n}`, err);
+            console.error(`CustomAttrHandler failed to compile function ${customFnDef.n}`, err);
             return null;
         }
     }

package/src/RaftDeviceInfo.ts

@@ -89,6 +89,31 @@ export interface DeviceTypePollRespMetadata {
     us?: number;                    // Time between consecutive samples in microseconds 
 }
 
+export interface SampleRateResult {
+    ok: boolean;
+    requestedRateHz: number;
+    actualRateHz: number;           // Closest supported rate from _conf.rate map
+    intervalUs: number;             // Polling interval set
+    numSamples: number;             // Buffer depth set
+    error?: string;
+}
+
+export interface ActionMapEntry {
+    w: string;                      // Hex bytes to write (may contain &-separated multi-writes)
+    i?: number;                     // Recommended polling interval in microseconds
+    s?: number;                     // Recommended number of poll result samples (buffer depth)
+}
+
+export type ActionMapValue = string | ActionMapEntry;
+
+export function getActionMapHex(entry: ActionMapValue): string {
+    return typeof entry === 'string' ? entry : entry.w;
+}
+
+export function getActionMapEntry(entry: ActionMapValue): ActionMapEntry | null {
+    return typeof entry === 'object' ? entry : null;
+}
+
 export interface DeviceTypeAction {
     n: string;                      // Action name
     t?: string;                     // Action type using python struct module format (e.g. 'H' for unsigned short, 'h' for signed short, 'f' for float etc.)
@@ -102,6 +127,8 @@ export interface DeviceTypeAction {
     mul?: number;                   // Multiplier to apply
     sub?: number;                   // Value to subtract before multiplying
     d?: number;                     // Default value
+    map?: Record<string, ActionMapValue>; // Discrete value mapping (display value -> hex string or {w, i, s} object)
+    desc?: string;                  // Human-readable description
 }
 
 export interface DeviceTypeInfo {

package/src/RaftDeviceManager.test.ts

@@ -0,0 +1,164 @@
+import { DeviceManager } from "./RaftDeviceManager";
+import { DeviceTypeInfo } from "./RaftDeviceInfo";
+import RaftSystemUtils from "./RaftSystemUtils";
+
+function makeTypeInfo(name: string, respBytes: number, attrs: Array<{ n: string; t: string }>): DeviceTypeInfo {
+    return {
+        name,
+        desc: name,
+        manu: "Robotical",
+        type: name,
+        resp: {
+            b: respBytes,
+            a: attrs.map(attr => ({ ...attr, u: "", r: [0, 0] }))
+        }
+    };
+}
+
+async function makeDeviceManager(typeInfos: Record<string, DeviceTypeInfo>): Promise<DeviceManager> {
+    const msgHandler = {
+        sendRICRESTURL: jest.fn(async (cmd: string) => {
+            const deviceType = new URLSearchParams(cmd.split("?")[1]).get("type");
+            const devinfo = deviceType ? typeInfos[deviceType] : undefined;
+            return devinfo ? { rslt: "ok", devinfo } : { rslt: "fail" };
+        })
+    };
+    const systemUtils = {
+        getMsgHandler: () => msgHandler,
+        getPublishTopicName: () => "devbin"
+    } as unknown as RaftSystemUtils;
+
+    const deviceManager = new DeviceManager();
+    await deviceManager.setup(systemUtils);
+    return deviceManager;
+}
+
+describe("DeviceManager binary devbin parsing", () => {
+    const accelInfo = makeTypeInfo("MXC400xXC", 7, [
+        { n: "x", t: ">h" },
+        { n: "y", t: ">h" },
+        { n: "z", t: ">h" },
+        { n: "status", t: "B" }
+    ]);
+
+    it("decodes current length-prefixed records", async () => {
+        const deviceManager = await makeDeviceManager({ "4": accelInfo });
+        const rxMsg = Uint8Array.from([
+            0x00, 0x80,
+            0xDB, 0xFF, 0x00,
+            0x00, 0x12,
+            0x81,
+            0x00, 0x00, 0x00, 0x15,
+            0x00, 0x04,
+            0x05,
+            0x09,
+            0x00, 0x01,
+            0x00, 0x01,
+            0x00, 0x02,
+            0x00, 0x03,
+            0x04
+        ]);
+
+        await deviceManager.handleClientMsgBinary(rxMsg);
+
+        const deviceState = deviceManager.getDeviceState("1_15");
+        expect(deviceState.deviceType).toBe("MXC400xXC");
+        expect(deviceState.deviceTimeline.totalSamplesAdded).toBe(1);
+        expect(deviceState.deviceAttributes.x.values).toEqual([1]);
+        expect(deviceState.deviceAttributes.y.values).toEqual([2]);
+        expect(deviceState.deviceAttributes.z.values).toEqual([3]);
+        expect(deviceState.deviceAttributes.status.values).toEqual([4]);
+    });
+
+    it("decodes Cog v1.9.5 legacy raw accelerometer records", async () => {
+        const deviceManager = await makeDeviceManager({ "4": accelInfo });
+        const rxMsg = Uint8Array.from([
+            0x00, 0x80,
+            0x00, 0x10,
+            0x81,
+            0x00, 0x00, 0x00, 0x15,
+            0x00, 0x04,
+            0x00, 0x01,
+            0x00, 0x01,
+            0x00, 0x02,
+            0x00, 0x03,
+            0x04
+        ]);
+
+        await deviceManager.handleClientMsgBinary(rxMsg);
+
+        const deviceState = deviceManager.getDeviceState("1_15");
+        expect(deviceState.deviceType).toBe("MXC400xXC");
+        expect(deviceState.deviceTimeline.totalSamplesAdded).toBe(1);
+        expect(deviceState.deviceAttributes.x.values).toEqual([1]);
+        expect(deviceState.deviceAttributes.y.values).toEqual([2]);
+        expect(deviceState.deviceAttributes.z.values).toEqual([3]);
+        expect(deviceState.deviceAttributes.status.values).toEqual([4]);
+    });
+
+    it("decodes Cog v1.9.5 legacy raw records inside a devbin envelope", async () => {
+        const deviceManager = await makeDeviceManager({ "4": accelInfo });
+        const rxMsg = Uint8Array.from([
+            0x00, 0x80,
+            0xDB, 0xFF, 0x00,
+            0x00, 0x10,
+            0x81,
+            0x00, 0x00, 0x00, 0x15,
+            0x00, 0x04,
+            0x00, 0x01,
+            0x00, 0x01,
+            0x00, 0x02,
+            0x00, 0x03,
+            0x04
+        ]);
+
+        await deviceManager.handleClientMsgBinary(rxMsg);
+
+        const deviceState = deviceManager.getDeviceState("1_15");
+        expect(deviceState.deviceType).toBe("MXC400xXC");
+        expect(deviceState.deviceTimeline.totalSamplesAdded).toBe(1);
+        expect(deviceState.deviceAttributes.x.values).toEqual([1]);
+        expect(deviceState.deviceAttributes.y.values).toEqual([2]);
+        expect(deviceState.deviceAttributes.z.values).toEqual([3]);
+        expect(deviceState.deviceAttributes.status.values).toEqual([4]);
+    });
+
+    it("keeps Cog v1.9.5 direct device records distinct when bus and address are both zero", async () => {
+        const lightInfo = makeTypeInfo("LightSensors", 16, [
+            { n: "ch0", t: ">H" },
+            { n: "ch1", t: ">H" },
+            { n: "ch2", t: ">H" },
+            { n: "ch3", t: ">H" }
+        ]);
+        const powerInfo = makeTypeInfo("Power", 1, [
+            { n: "battery", t: "B" }
+        ]);
+        const deviceManager = await makeDeviceManager({ "2": lightInfo, "3": powerInfo });
+        const rxMsg = Uint8Array.from([
+            0x00, 0x80,
+            0x00, 0x11,
+            0x80,
+            0x00, 0x00, 0x00, 0x00,
+            0x00, 0x02,
+            0x00, 0x01,
+            0x00, 0x0a,
+            0x00, 0x0b,
+            0x00, 0x0c,
+            0x00, 0x0d,
+            0x00, 0x0a,
+            0x80,
+            0x00, 0x00, 0x00, 0x00,
+            0x00, 0x03,
+            0x00, 0x02,
+            0x63
+        ]);
+
+        await deviceManager.handleClientMsgBinary(rxMsg);
+
+        const devicesState = deviceManager.getDevicesState();
+        expect(devicesState["0_0_2"].deviceType).toBe("LightSensors");
+        expect(devicesState["0_0_2"].deviceAttributes.ch0.values).toEqual([10]);
+        expect(devicesState["0_0_3"].deviceType).toBe("Power");
+        expect(devicesState["0_0_3"].deviceAttributes.battery.values).toEqual([99]);
+    });
+});