@robotical/raftjs 2.1.0 → 2.1.3

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, RaftRtStreamDataCBType, RaftRtStreamHandle, RaftRtStreamOptions, RaftRtStreamStartResp } 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 {
 
@@ -88,6 +87,10 @@ export default class RaftConnector {
   // Update manager
   private _raftUpdateManager: RaftUpdateManager | null = null;
 
+  // Open-ended RT stream callbacks keyed by streamID
+  private _rtStreamCallbacks = new Map<number, RaftRtStreamDataCBType>();
+  private _fallbackRtStreamCallback: { streamID: number, callback: RaftRtStreamDataCBType } | null = null;
+
   /**
    * RaftConnector constructor
    * @param getSystemTypeCB - callback to get system type
@@ -194,6 +197,22 @@ export default class RaftConnector {
     return this._commsStats;
   }
 
+  /**
+   * getOperationQueueDepth
+   * @returns number of high-level device operations queued or running
+   */
+  getOperationQueueDepth(): number {
+    return 0;
+  }
+
+  /**
+   * isOperationBusy
+   * @returns true when a high-level device operation is queued or running
+   */
+  isOperationBusy(): boolean {
+    return false;
+  }
+
   /**
    * Get Raft message handler (to allow message sending and receiving)
    * @returns RaftMsgHandler - Raft message handler
@@ -214,7 +233,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 +260,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 +302,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 +315,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 +344,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 +383,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 +396,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}`);
     }
   }
 
@@ -352,6 +428,11 @@ export default class RaftConnector {
    *
    */
   async sendRICRESTMsg(commandName: string, params: object,
+    bridgeID: number | undefined = undefined): Promise<RaftOKFail> {
+    return this._sendRICRESTMsg(commandName, params, bridgeID);
+  }
+
+  private async _sendRICRESTMsg(commandName: string, params: object,
     bridgeID: number | undefined = undefined): Promise<RaftOKFail> {
     try {
       // Format the paramList as query string
@@ -359,11 +440,12 @@ export default class RaftConnector {
       let paramQueryStr = '';
       for (const param of paramEntries) {
         if (paramQueryStr.length > 0) paramQueryStr += '&';
-        paramQueryStr += param[0] + '=' + param[1];
+        paramQueryStr += `${encodeURIComponent(param[0])}=${encodeURIComponent(String(param[1]))}`;
       }
       // Format the url to send
       if (paramQueryStr.length > 0) commandName += '?' + paramQueryStr;
-      return await this._raftMsgHandler.sendRICRESTURL<RaftOKFail>(commandName, bridgeID);
+      const response = await this._raftMsgHandler.sendRICRESTURL<RaftOKFail | null>(commandName, bridgeID);
+      return response ?? { rslt: 'fail' };
     } catch (error) {
       RaftLog.warn(`sendRICRESTMsg failed ${error}`);
       return { rslt: 'fail' };
@@ -417,6 +499,13 @@ export default class RaftConnector {
     fileBlockData: Uint8Array
   ): void {
     // RaftLog.info(`onRxFileBlock filePos ${filePos} fileBlockData ${RaftUtils.bufferToHex(fileBlockData)}`);
+    const streamID = (filePos >>> 24) & 0xff;
+    const streamFilePos = filePos & 0x00ffffff;
+    const streamCallback = this._rtStreamCallbacks.get(streamID);
+    if (streamID !== 0 && streamCallback) {
+      streamCallback(fileBlockData, streamFilePos, streamID);
+      return;
+    }
     this._raftFileHandler.onFileBlock(filePos, fileBlockData);
   }
 
@@ -456,6 +545,104 @@ 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;
+  }
+
+  /**
+   * openRtStream - open an indefinite bidirectional RT stream.
+   * The returned handle can send byte blocks and closes with ufEnd.
+   */
+  async openRtStream(options: RaftRtStreamOptions): Promise<RaftRtStreamHandle> {
+    const cmdMsg = JSON.stringify({
+      cmdName: "ufStart",
+      reqStr: "ufStart",
+      fileType: "rtstream",
+      fileName: options.fileName,
+      endpoint: options.endpoint,
+      fileLen: 0,
+    });
+
+    const startResp = await this._raftMsgHandler.sendRICRESTCmdFrame<RaftRtStreamStartResp>(cmdMsg);
+    if (!startResp || startResp.rslt !== "ok" || startResp.streamID === undefined) {
+      throw new Error(`openRtStream failed ${startResp?.rslt ?? "no response"}`);
+    }
+
+    const streamID = startResp.streamID;
+    const maxBlockSize = startResp.maxBlockSize || this._raftStreamHandler.maxBlockSize;
+    let txFilePos = 0;
+    let sendQueue = Promise.resolve();
+    this._rtStreamCallbacks.set(streamID, options.onData);
+    this._fallbackRtStreamCallback = { streamID, callback: options.onData };
+
+    const sendBytes = async (bytes: Uint8Array): Promise<boolean> => {
+      let sentOk = false;
+      sendQueue = sendQueue
+        .catch(() => {
+          // Keep later terminal input flowing even if an earlier block failed.
+        })
+        .then(async () => {
+          sentOk = await this._raftMsgHandler.sendStreamBlock(bytes, txFilePos, streamID);
+          if (sentOk) {
+            txFilePos = (txFilePos + bytes.length) & 0x00ffffff;
+          }
+        });
+      await sendQueue;
+      return sentOk;
+    };
+
+    const close = async (): Promise<boolean> => {
+      this._rtStreamCallbacks.delete(streamID);
+      if (this._fallbackRtStreamCallback?.streamID === streamID) {
+        this._fallbackRtStreamCallback = null;
+      }
+      const endMsg = JSON.stringify({
+        cmdName: "ufEnd",
+        reqStr: "ufEnd",
+        streamID,
+      });
+      try {
+        const endResp = await this._raftMsgHandler.sendRICRESTCmdFrame<RaftOKFail>(endMsg);
+        return endResp?.rslt === "ok";
+      } catch (error) {
+        RaftLog.warn(`closeRtStream failed ${streamID}: ${error}`);
+        return false;
+      }
+    };
+
+    // Some endpoints use an initial empty block as an attach signal.
+    // Keep this opt-in because older endpoints reject zero-length ufBlock frames.
+    if (options.sendInitialEmptyBlock) {
+      await sendBytes(new Uint8Array());
+    }
+
+    return {
+      streamID,
+      maxBlockSize,
+      sendBytes,
+      sendText: (text: string) => sendBytes(new TextEncoder().encode(text)),
+      close,
+    };
+  }
+
   /**
    * streamAudio - stream audio
    * @param streamContents audio data
@@ -534,7 +721,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 +868,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 {