@robdobsn/raftjs 1.10.7 → 1.11.5

package/src/RaftDeviceStates.ts

@@ -69,14 +69,29 @@ export interface DeviceTimeline {
     lastReportTimestampUs: number;
     reportTimestampOffsetUs: number;
 }
-    
+
+export interface DeviceStats {
+    totalSamples: number;
+    windowMs: number;
+    windowSamples: number;
+    sampleRateHz: number;
+    lastSampleTimeMs: number | null;
+    lastUpdateTimeMs: number | null;
+}
+
+export enum DeviceOnlineState {
+    Offline = 0,
+    Online = 1,
+    PendingDeletion = 2,
+}
+
 export interface DeviceState {
     deviceTypeInfo: DeviceTypeInfo | undefined;
     deviceTimeline: DeviceTimeline;
     deviceAttributes: DeviceAttributesState;
     deviceIsNew: boolean;
     stateChanged: boolean;
-    isOnline: boolean;
+    onlineState: DeviceOnlineState;
     deviceAddress: string;
     deviceType: string;
     busName: string;
@@ -86,7 +101,22 @@ export class DevicesState {
     [deviceKey: string]: DeviceState;
 }
 
-// Add the getDeviceKey method to generate a composite key
-export function getDeviceKey(busName: string, devAddr: string): string {
-    return `${busName}_${devAddr}`;
+// Format a numeric device address as canonical hex string:
+// lowercase, no "0x" prefix, no leading zeros
+export function formatDeviceAddrHex(addr: number): string {
+    return addr.toString(16);
+}
+
+// Generate a composite device key from bus number and hex address
+export function getDeviceKey(busNumberAsString: string, devAddrHexStr: string): string {
+    return `${busNumberAsString}_${devAddrHexStr}`;
+}
+
+// Parse a device key into its bus and address components
+export function parseDeviceKey(deviceKey: string): { bus: string; addr: string } {
+    const sep = deviceKey.indexOf('_');
+    if (sep < 0) {
+        return { bus: deviceKey, addr: '' };
+    }
+    return { bus: deviceKey.substring(0, sep), addr: deviceKey.substring(sep + 1) };
 }

package/src/RaftPublish.ts

@@ -0,0 +1,92 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+//
+// RaftSystem
+// Part of RaftJS
+//
+// Rob Dobson 2025
+// (C) 2020-2025 All rights reserved
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+import { RaftPublishFrameMeta } from "./RaftTypes";
+
+const RAFT_PUBLISH_PREFIX_LEN = 2;
+const DEVBIN_MAGIC_MIN = 0xDB;
+const DEVBIN_MAGIC_MAX = 0xDF;
+const DEVBIN_VERSION_BASE = 0xDA;
+
+export function inspectPublishFrame(
+  payload: Uint8Array,
+  topicLookup?: (topicIndex: number) => string | undefined,
+): RaftPublishFrameMeta {
+
+  if (payload.length < RAFT_PUBLISH_PREFIX_LEN) {
+    return { frameType: "unknown" };
+  }
+
+  const payloadStartPos = RAFT_PUBLISH_PREFIX_LEN;
+  if (payload.length <= payloadStartPos) {
+    return { frameType: "unknown" };
+  }
+
+  // Try JSON first
+  if (payload[payloadStartPos] === 0x7B) {
+    try {
+      const jsonString = new TextDecoder("utf-8").decode(payload.slice(payloadStartPos));
+      const jsonObj = JSON.parse(jsonString) as Record<string, unknown>;
+
+      let topicIndex: number | undefined = undefined;
+      let topicName: string | undefined = undefined;
+      if (typeof jsonObj._t === "number") {
+        topicIndex = jsonObj._t;
+        topicName = topicLookup ? topicLookup(topicIndex) : undefined;
+      } else if (typeof jsonObj._t === "string") {
+        topicName = jsonObj._t;
+      }
+
+      const version = typeof jsonObj._v === "number" ? jsonObj._v : undefined;
+
+      return {
+        frameType: "json",
+        topicIndex,
+        topicName,
+        version,
+        jsonString,
+      };
+    } catch {
+      return { frameType: "unknown" };
+    }
+  }
+
+  // Binary (devbin legacy or enveloped)
+  const firstBinaryByte = payload[payloadStartPos];
+  if ((firstBinaryByte & 0xF0) === 0xD0) {
+    if (firstBinaryByte < DEVBIN_MAGIC_MIN || firstBinaryByte > DEVBIN_MAGIC_MAX) {
+      return {
+        frameType: "binary",
+        binaryHasEnvelope: true,
+      };
+    }
+
+    const topicIndex = payload.length > payloadStartPos + 1 ? payload[payloadStartPos + 1] : undefined;
+    const topicName = (topicIndex !== undefined && topicIndex !== 0xFF && topicLookup)
+      ? topicLookup(topicIndex)
+      : undefined;
+
+    return {
+      frameType: "binary",
+      topicIndex,
+      topicName,
+      version: firstBinaryByte - DEVBIN_VERSION_BASE,
+      binaryHasEnvelope: true,
+      binaryPayloadOffset: payloadStartPos + 2,
+    };
+  }
+
+  // Legacy binary format (no envelope)
+  return {
+    frameType: "binary",
+    binaryHasEnvelope: false,
+    binaryPayloadOffset: payloadStartPos,
+  };
+}

package/src/RaftStreamHandler.ts

@@ -11,7 +11,7 @@
 import RaftLog from './RaftLog'
 import RaftMsgHandler from './RaftMsgHandler';
 import RaftCommsStats from './RaftCommsStats';
-import { RaftOKFail, RaftStreamStartResp, RaftStreamType } from './RaftTypes';
+import { RaftOKFail, RaftStreamStartResp, RaftStreamType, RaftStreamDataProgressCBType } from './RaftTypes';
 import RaftConnector from './RaftConnector';
 import { RaftConnEvent } from './RaftConnEvents';
 import { RICRESTElemCode } from './RaftProtocolDefs'
@@ -77,6 +77,89 @@ export default class RaftStreamHandler {
     this._legacySoktoMode = legacyMode;
   }
 
+  /**
+   * streamData - stream arbitrary data to a named firmware endpoint using the RT_STREAM protocol.
+   * Returns a promise that resolves when the stream is complete or rejects on failure.
+   * @param streamContents data to stream
+   * @param fileName logical filename sent in ufStart (used by firmware to detect format, e.g. "pattern.thr")
+   * @param targetEndpoint REST API endpoint name registered on the firmware (e.g. "streampattern")
+   * @param progressCallback optional callback reporting (bytesSent, totalBytes, progressFraction)
+   * @returns Promise<boolean> true if stream completed successfully
+   */
+  async streamData(
+    streamContents: Uint8Array,
+    fileName: string,
+    targetEndpoint: string,
+    progressCallback?: RaftStreamDataProgressCBType,
+  ): Promise<boolean> {
+    // Reject if another stream is starting
+    if (this._streamIsStarting || this._lastStreamStartTime > (Date.now() - 500)) {
+      RaftLog.warn(`streamData: unable to start, too soon since last request`);
+      return false;
+    }
+
+    this._streamIsStarting = true;
+    this._lastStreamStartTime = Date.now();
+    this._soktoReceived = false;
+    this._soktoPos = 0;
+    this._streamPos = 0;
+    this._streamBuffer = RaftUtils.toArrayBufferView(streamContents);
+
+    // Send ufStart
+    const startOk = await this._sendStreamStartMsg(
+      fileName, targetEndpoint, RaftStreamType.REAL_TIME_STREAM, streamContents,
+    );
+    this._streamIsStarting = false;
+
+    if (!startOk) {
+      RaftLog.warn(`streamData: ufStart failed`);
+      return false;
+    }
+
+    // Send blocks
+    if (this._streamID === null) {
+      return false;
+    }
+
+    let pos = 0;
+    while (pos < this._streamBuffer.length) {
+      // Respect SOKTO feedback — if firmware reported a position mismatch, rewind
+      if (this._soktoReceived) {
+        RaftLog.verbose(`streamData: sokto received, pos was ${pos}, soktoPos ${this._soktoPos}`);
+        this._soktoReceived = false;
+        // Slow down on backpressure
+        await new Promise(r => setTimeout(r, 50));
+      }
+
+      const blockSize = Math.min(this._streamBuffer.length - pos, this._maxBlockSize);
+      const block = this._streamBuffer.slice(pos, pos + blockSize);
+      if (block.length > 0) {
+        const sentOk = await this._msgHandler.sendStreamBlock(block, pos, this._streamID);
+        this._commsStats.recordStreamBytes(block.length);
+        if (!sentOk) {
+          RaftLog.warn(`streamData: sendStreamBlock failed at pos ${pos}`);
+          return false;
+        }
+        pos += blockSize;
+        this._streamPos = pos;
+
+        // Progress callback
+        if (progressCallback) {
+          const progress = this._streamBuffer.length > 0 ? pos / this._streamBuffer.length : 1;
+          progressCallback(pos, this._streamBuffer.length, progress);
+        }
+      }
+
+      // Yield to avoid hogging the event loop
+      await new Promise(r => setTimeout(r, 1));
+    }
+
+    // Send ufEnd
+    const endOk = await this._sendStreamEndMsg(this._streamID);
+    RaftLog.debug(`streamData: complete, endOk=${endOk}`);
+    return endOk;
+  }
+
   // Start streaming audio
   streamAudio(streamContents: Uint8Array, clearExisting: boolean, audioDuration: number): void {
     if (!clearExisting)

package/src/RaftSystemUtils.ts

@@ -20,6 +20,9 @@ import {
   RaftFileList,
   RaftFriendlyName,
   RaftOKFail,
+  RaftPubTopicRec,
+  RaftPubTopicsResponse,
+  RaftSubscriptionUpdateResponse,
   RaftSysModInfoBLEMan,
   RaftSystemInfo,
   RaftWifiScanResults,
@@ -40,6 +43,10 @@ export default class RaftSystemUtils {
   private _defaultWiFiHostname = "Raft";
   private _maxSecsToWaitForWiFiConn = 20;
 
+  // Publish topic index/name lookup tables (session scoped)
+  private _pubTopicIdxToName: { [idx: number]: string } = {};
+  private _pubTopicNameToIdx: { [name: string]: number } = {};
+
   /**
    * constructor
    * @param raftMsgHandler 
@@ -56,6 +63,58 @@ export default class RaftSystemUtils {
     return this._msgHandler;
   }
 
+  /**
+   * Update publish topic maps from topic records.
+   */
+  updatePublishTopicMap(topicRecs: Array<RaftPubTopicRec> | undefined): void {
+    if (!topicRecs || !Array.isArray(topicRecs)) {
+      return;
+    }
+    for (const topicRec of topicRecs) {
+      if (!topicRec || typeof topicRec.name !== "string" || typeof topicRec.idx !== "number") {
+        continue;
+      }
+      this._pubTopicIdxToName[topicRec.idx] = topicRec.name;
+      this._pubTopicNameToIdx[topicRec.name] = topicRec.idx;
+    }
+  }
+
+  /**
+   * Update publish topic maps from subscription response.
+   */
+  updatePublishTopicMapFromSubscriptionResponse(resp: RaftSubscriptionUpdateResponse | RaftOKFail | null | undefined): void {
+    if (!resp || typeof resp !== "object") {
+      return;
+    }
+    if ("topics" in resp) {
+      this.updatePublishTopicMap((resp as RaftSubscriptionUpdateResponse).topics);
+    }
+  }
+
+  /**
+   * Fetch publish topic map from firmware endpoint.
+   */
+  async refreshPublishTopicMap(): Promise<boolean> {
+    try {
+      const pubTopicsResp = await this._msgHandler.sendRICRESTURL<RaftPubTopicsResponse>("pubtopics");
+      if (pubTopicsResp && pubTopicsResp.rslt === "ok") {
+        this.updatePublishTopicMap(pubTopicsResp.topics);
+        return true;
+      }
+    } catch (error) {
+      RaftLog.debug(`refreshPublishTopicMap failed ${error}`);
+    }
+    return false;
+  }
+
+  getPublishTopicName(topicIndex: number): string | undefined {
+    return this._pubTopicIdxToName[topicIndex];
+  }
+
+  getPublishTopicIndex(topicName: string): number | undefined {
+    return this._pubTopicNameToIdx[topicName];
+  }
+
   /**
    * setDefaultWiFiHostname
    * @param defaultWiFiHostname

package/src/RaftTypes.ts

@@ -72,6 +72,31 @@ export class RaftOKFail {
   rslt = 'failComms';
 }
 
+export type RaftPubTopicRec = {
+  name: string;
+  idx: number;
+};
+
+export type RaftSubscriptionUpdateResponse = RaftOKFail & {
+  topics?: Array<RaftPubTopicRec>;
+};
+
+export type RaftPubTopicsResponse = RaftOKFail & {
+  topics?: Array<RaftPubTopicRec>;
+};
+
+export type RaftPublishFrameType = 'json' | 'binary' | 'unknown';
+
+export type RaftPublishFrameMeta = {
+  frameType: RaftPublishFrameType;
+  topicIndex?: number;
+  topicName?: string;
+  version?: number;
+  binaryHasEnvelope?: boolean;
+  binaryPayloadOffset?: number;
+  jsonString?: string;
+};
+
 export type RaftReportMsg = {
   msgType?: string;
   rslt?: string;
@@ -181,6 +206,8 @@ export class RaftSysModInfoBLEMan {
 
 export type RaftProgressCBType = (received: number, total: number) => void;
 
+export type RaftStreamDataProgressCBType = (sent: number, total: number, progress: number) => void;
+
 export class RaftFileDownloadResult {
   fileData: Uint8Array | null = null;
   downloadedOk = false;

package/src/main.ts

@@ -29,6 +29,7 @@ export { default as RaftDeviceMgrIF } from './RaftDeviceMgrIF';
 export { DeviceManager as RaftDeviceManager } from './RaftDeviceManager';
 export type { DeviceDecodedData } from './RaftDeviceManager';
 
+export * from './RaftPublish';
 export * from './RaftTypes';
 export * from './RaftSystemType';
 export * from './RaftWifiTypes';