@robotical/raftjs 2.1.3 → 2.1.4

package/examples/dashboard/src/DeviceLineChart.tsx

@@ -148,10 +148,11 @@ const DeviceLineChart: React.FC<DeviceLineChartProps> = memo(({ deviceKey, lastU
                     min: axis.range[0],
                     max: axis.range[1],
                     callback: (value: number) => {
-                        if (typeof value === 'number' && Math.abs(value) > 0 && Math.abs(value) < 1) {
-                            return value.toPrecision(2);
-                        }
-                        return value;
+                        if (typeof value !== 'number') return value;
+                        if (value === 0) return '0';
+                        const abs = Math.abs(value);
+                        if (abs < 1) return Number(value.toPrecision(2)).toString();
+                        return Number(value.toPrecision(6)).toString();
                     },
                 },
             };

package/examples/dashboard/src/DevicePanel.tsx

@@ -173,6 +173,9 @@ const DevicePanel = ({ deviceKey, lastUpdated }: DevicePanelProps) => {
     if (bracketsAdded) {
         headerText += `)`;
     }
+    if (deviceState?.deviceTypeInfo?.role?.toLowerCase() === "system") {
+        headerText += " System";
+    }
     if (deviceState?.onlineState !== DeviceOnlineState.Online) {
         headerText += " (Offline)";
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robotical/raftjs",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "Javascript/TS library for Raft library",
   "main": "dist/web/main.js",
   "types": "dist/web/main.d.ts",

package/src/RaftAttributeHandler.ts

@@ -11,6 +11,23 @@ import CustomAttrHandler from "./RaftCustomAttrHandler";
 import { DeviceTypeAttribute, DeviceTypePollRespMetadata, decodeAttrUnitsEncoding, isAttrTypeSigned } from "./RaftDeviceInfo";
 import { DeviceAttributesState, DeviceTimeline } from "./RaftDeviceStates";
 import { structSizeOf, structUnpack } from "./RaftStruct";
+import RaftUtils from "./RaftUtils";
+
+// Optional diagnostic context for attribute decoding. When provided, the
+// handler emits a detailed warning if an attribute would read past the
+// declared sample boundary or the end of the message buffer. This is used to
+// track down firmware/schema mismatches.
+export interface AttrDecodeDiagContext {
+    deviceKey?: string;
+    deviceType?: string;
+    debugMsgIndex?: number;
+    // Inclusive start (in msgBuffer) of the current sample's bytes (after the
+    // 1-byte sampleLen prefix). When provided together with sampleEndIdx, the
+    // handler will bound-check attribute reads against this range.
+    sampleStartIdx?: number;
+    // Exclusive end (in msgBuffer) of the current sample's bytes.
+    sampleEndIdx?: number;
+}
 
 export default class AttributeHandler {
 
@@ -23,8 +40,18 @@ export default class AttributeHandler {
     private POLL_RESULT_RESOLUTION_US = 100;
 
     public processMsgAttrGroup(msgBuffer: Uint8Array, msgBufIdx: number, deviceTimeline: DeviceTimeline, pollRespMetadata: DeviceTypePollRespMetadata,
-                        devAttrsState: DeviceAttributesState, maxDataPoints: number, msgEndIdx = msgBuffer.length): number {
-
+                        devAttrsState: DeviceAttributesState, maxDataPoints: number,
+                        msgEndIdxOrDiagCtx: number | AttrDecodeDiagContext = msgBuffer.length,
+                        diagCtx?: AttrDecodeDiagContext): number {
+
+        // Merge rationale: Robotical's devbin compatibility parser needs an
+        // explicit sample boundary; upstream's diagnostics need per-sample
+        // context. Accept both call styles so malformed samples are skipped
+        // without losing useful overrun warnings.
+        const msgEndIdx = typeof msgEndIdxOrDiagCtx === "number"
+            ? msgEndIdxOrDiagCtx
+            : msgEndIdxOrDiagCtx.sampleEndIdx ?? msgBuffer.length;
+        const effectiveDiagCtx = typeof msgEndIdxOrDiagCtx === "number" ? diagCtx : msgEndIdxOrDiagCtx;
         // console.log(`processMsgAttrGroup msg ${msgHexStr} timestamp ${timestamp} origTimestamp ${origTimestamp} msgBufIdx ${msgBufIdx}`)
         const boundedMsgEndIdx = Math.min(Math.max(msgEndIdx, msgBufIdx), msgBuffer.length);
 
@@ -39,6 +66,11 @@ export default class AttributeHandler {
 
         // New attribute values (in order as they appear in the attributes JSON)
         let newAttrValues: (number | string)[][] = [];
+        // Tracks whether any individual attribute decode failed in the non-custom path.
+        // When true, the detailed per-attribute overrun warning has already been emitted
+        // by processMsgAttribute, so we suppress the redundant downstream length/empty
+        // warnings that would otherwise fire every poll.
+        let attrDecodeFailed = false;
         if ("c" in pollRespMetadata) {
 
             // Extract attribute values using custom handler
@@ -83,13 +115,15 @@ export default class AttributeHandler {
                 if (!("t" in attrDef)) {
                     console.warn(`DeviceManager msg unknown msgBuffer ${msgBuffer} tsUs ${timestampUs} attrDef ${JSON.stringify(attrDef)}`);
                     newAttrValues.push([]);
+                    attrDecodeFailed = true;
                     continue;
                 }
 
                 // console.log(`RaftAttrHdlr.processMsgAttrGroup attr ${attrDef.n} msgBufIdx ${msgBufIdx} timestampUs ${timestampUs} attrDef ${JSON.stringify(attrDef)}`);
 
                 // Process the attribute
-                const { values, newMsgBufIdx } = this.processMsgAttribute(attrDef, msgBuffer, msgBufIdx, msgDataStartIdx, boundedMsgEndIdx);
+                const { values, newMsgBufIdx } = this.processMsgAttribute(attrDef, msgBuffer, msgBufIdx, msgDataStartIdx,
+                    boundedMsgEndIdx, pollRespMetadata, effectiveDiagCtx);
                 if (newMsgBufIdx < 0) {
                     return -1;
                 }
@@ -114,14 +148,18 @@ export default class AttributeHandler {
         const numNewDataPoints = newAttrValues[0].length;
         for (let i = 1; i < newAttrValues.length; i++) {
             if (newAttrValues[i].length !== numNewDataPoints) {
-                console.warn(`DeviceManager msg attrGroup ${pollRespMetadata} attrName ${pollRespMetadata.a[i].n} newAttrValues ${newAttrValues} do not have the same length`);
+                if (!attrDecodeFailed) {
+                    console.warn(`DeviceManager msg attrGroup ${JSON.stringify(pollRespMetadata)} attrName ${pollRespMetadata.a[i].n} newAttrValues lengths ${newAttrValues.map(v => v.length).join(",")} do not match`);
+                }
                 return msgDataStartIdx+pollRespSizeBytes;
             }
         }
 
         // All attributes in the schema should have values
         if (newAttrValues.length !== pollRespMetadata.a.length) {
-            console.warn(`DeviceManager msg attrGroup ${pollRespMetadata} newAttrValues ${newAttrValues} length does not match attrGroup.a length`);
+            if (!attrDecodeFailed) {
+                console.warn(`DeviceManager msg attrGroup ${JSON.stringify(pollRespMetadata)} newAttrValues length ${newAttrValues.length} does not match attrGroup.a length ${pollRespMetadata.a.length}`);
+            }
             return msgDataStartIdx+pollRespSizeBytes;
         }
 
@@ -272,7 +310,9 @@ export default class AttributeHandler {
         }
     }
 
-    private processMsgAttribute(attrDef: DeviceTypeAttribute, msgBuffer: Uint8Array, msgBufIdx: number, msgDataStartIdx: number, msgEndIdx: number): { values: (number | string)[], newMsgBufIdx: number} {
+    private processMsgAttribute(attrDef: DeviceTypeAttribute, msgBuffer: Uint8Array, msgBufIdx: number, msgDataStartIdx: number,
+                                msgEndIdx: number, pollRespMetadata?: DeviceTypePollRespMetadata,
+                                diagCtx?: AttrDecodeDiagContext): { values: (number | string)[], newMsgBufIdx: number} {
 
         // Current field message string index
         let curFieldBufIdx = msgBufIdx;
@@ -295,7 +335,9 @@ export default class AttributeHandler {
                 // Copy bytes from the specified positions
                 for (let i = 0; i < attrDef.at.length && i < elemSize; i++) {
                     const sourceIdx = msgDataStartIdx + attrDef.at[i];
-                    if (sourceIdx >= boundedMsgEndIdx) {
+                    if (sourceIdx < msgDataStartIdx || sourceIdx >= boundedMsgEndIdx) {
+                        this.warnAttrOverrun(attrDef, msgBuffer, sourceIdx, elemSize, msgDataStartIdx,
+                            true, pollRespMetadata, diagCtx, sourceIdx >= msgBuffer.length ? "msgBuffer" : "sample");
                         return { values: [], newMsgBufIdx: -1 };
                     }
                     bytesForType[i] = msgBuffer[sourceIdx];
@@ -312,11 +354,15 @@ export default class AttributeHandler {
             attrUsesAbsPos = true;
         }
 
-        // Check if outside bounds of message
+        // Merge rationale: keep Robotical's hard sample bounds as the source of
+        // truth, but emit upstream's one-shot diagnostic when a schema tries to
+        // read beyond the sample or buffer.
         const attrEndIdx = curFieldBufIdx + numBytesConsumed;
         const effectiveMsgEndIdx = Math.min(Math.max(msgEndIdx, curFieldBufIdx), msgBuffer.length);
         if (curFieldBufIdx >= effectiveMsgEndIdx || attrEndIdx > effectiveMsgEndIdx) {
-            // console.warn(`DeviceManager msg outside bounds msgBuffer ${msgBuffer} attrName ${attrDef.n}`);
+            this.warnAttrOverrun(attrDef, msgBuffer, curFieldBufIdx, numBytesConsumed, msgDataStartIdx,
+                                 attrUsesAbsPos, pollRespMetadata, diagCtx,
+                                 attrEndIdx > msgBuffer.length ? "msgBuffer" : "sample");
             return { values: [], newMsgBufIdx: -1 };
         }
 
@@ -439,6 +485,40 @@ export default class AttributeHandler {
         return { values: attrValues, newMsgBufIdx: msgBufIdx };
     }
 
+    // One-shot detailed warning when an attribute decode would overrun the
+    // sample/message bounds. Includes the exact bytes and schema so the
+    // firmware vs. registered device-type schema can be reconciled.
+    private _overrunWarnSeen: Set<string> = new Set();
+    private warnAttrOverrun(attrDef: DeviceTypeAttribute, msgBuffer: Uint8Array, curFieldBufIdx: number,
+                            attrTypeSize: number, msgDataStartIdx: number, attrUsesAbsPos: boolean,
+                            pollRespMetadata: DeviceTypePollRespMetadata | undefined,
+                            diagCtx: AttrDecodeDiagContext | undefined, overrunOf: "msgBuffer" | "sample"): void {
+        const sampleStart = diagCtx?.sampleStartIdx ?? msgDataStartIdx;
+        const sampleEnd = diagCtx?.sampleEndIdx;
+        const dedupeKey = `${diagCtx?.deviceKey ?? "?"}|${diagCtx?.deviceType ?? "?"}|${attrDef.n}|${attrDef.t}|${attrUsesAbsPos ? attrDef.at : "rel"}`;
+        if (this._overrunWarnSeen.has(dedupeKey)) {
+            return;
+        }
+        this._overrunWarnSeen.add(dedupeKey);
+        const sampleHex = sampleEnd !== undefined
+            ? RaftUtils.bufferToHex(msgBuffer.slice(sampleStart, sampleEnd))
+            : "<unknown sample bounds>";
+        const availableInSample = sampleEnd !== undefined ? Math.max(0, sampleEnd - curFieldBufIdx) : -1;
+        const availableInBuffer = Math.max(0, msgBuffer.length - curFieldBufIdx);
+        console.warn(
+            `AttributeHandler decode overrun (${overrunOf}): ` +
+            `deviceKey=${diagCtx?.deviceKey ?? "?"} deviceType=${diagCtx?.deviceType ?? "?"} ` +
+            `debugMsgIndex=${diagCtx?.debugMsgIndex ?? "?"} attr.n=${attrDef.n} attr.t=${attrDef.t} ` +
+            `attrTypeSize=${attrTypeSize} attrUsesAbsPos=${attrUsesAbsPos} attr.at=${JSON.stringify(attrDef.at)} ` +
+            `curFieldBufIdx=${curFieldBufIdx} msgBuffer.length=${msgBuffer.length} ` +
+            `sampleStartIdx=${sampleStart} sampleEndIdx=${sampleEnd ?? "?"} ` +
+            `availableInSample=${availableInSample} availableInBuffer=${availableInBuffer} ` +
+            `sampleHex=${sampleHex} ` +
+            `pollRespMetadata.b=${pollRespMetadata?.b} ` +
+            `schema=${JSON.stringify(pollRespMetadata?.a)}`
+        );
+    }
+
     private signExtend(value: number, mask: number): number {
         const signBitMask = (mask + 1) >> 1;
         const signBit = value & signBitMask;

package/src/RaftChannelSimulated.test.ts

@@ -0,0 +1,62 @@
+import AttributeHandler from "./RaftAttributeHandler";
+import RaftChannelSimulated from "./RaftChannelSimulated";
+import { DeviceAttributesState, DeviceTimeline } from "./RaftDeviceStates";
+
+function hexToBytes(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let idx = 0; idx < bytes.length; idx++) {
+    bytes[idx] = parseInt(hex.slice(idx * 2, idx * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+function createTimeline(): DeviceTimeline {
+  return {
+    timestampsUs: [],
+    lastReportTimestampUs: 0,
+    reportTimestampOffsetUs: 0,
+    totalSamplesAdded: 0,
+    emaLastSampleTimeUs: 0,
+    emaIntervalUs: 0,
+    emaPrevPollTimeUs: 0,
+    emaCalibrated: false,
+    emaCalibrationPolls: 0,
+  };
+}
+
+describe("RaftChannelSimulated", () => {
+  test("generates decodable SCD30 CO2, temperature and humidity data", () => {
+    const channel = new RaftChannelSimulated() as any;
+    const deviceTypeInfo = channel._deviceTypeInfo.SCD30;
+    expect(deviceTypeInfo).toBeDefined();
+
+    const msg = channel._createSimulatedDeviceInfoMsg(1000, "SCD30", deviceTypeInfo, 2500) as Uint8Array;
+    const publishedJson = JSON.parse(new TextDecoder().decode(msg.slice(2)));
+    const payload = hexToBytes(publishedJson["1"].SCD30.pub);
+
+    const attrs: DeviceAttributesState = {};
+    const timeline = createTimeline();
+    const handler = new AttributeHandler();
+
+    const nextIdx = handler.processMsgAttrGroup(payload, 0, timeline, deviceTypeInfo.resp, attrs, 100);
+    expect(nextIdx).toBe(26);
+
+    expect(attrs.CO2.values).toHaveLength(1);
+    expect(attrs.temperature.values).toHaveLength(1);
+    expect(attrs.humidity.values).toHaveLength(1);
+
+    const co2 = attrs.CO2.values[0] as number;
+    const temperature = attrs.temperature.values[0] as number;
+    const humidity = attrs.humidity.values[0] as number;
+
+    expect(Number.isFinite(co2)).toBe(true);
+    expect(Number.isFinite(temperature)).toBe(true);
+    expect(Number.isFinite(humidity)).toBe(true);
+    expect(co2).toBeGreaterThanOrEqual(400);
+    expect(co2).toBeLessThanOrEqual(2000);
+    expect(temperature).toBeGreaterThanOrEqual(-40);
+    expect(temperature).toBeLessThanOrEqual(125);
+    expect(humidity).toBeGreaterThanOrEqual(0);
+    expect(humidity).toBeLessThanOrEqual(100);
+  });
+});

package/src/RaftChannelSimulated.ts

@@ -586,6 +586,34 @@ export default class RaftChannelSimulated implements RaftChannel {
 
         return true;
       }
+      case "SCD30": {
+        if (dataBlockSizeBytes < 24) {
+          return false;
+        }
+
+        const clamp = (value: number, min: number, max: number) => Math.max(min, Math.min(max, value));
+        const co2Ppm = clamp(
+          850 + 320 * Math.sin(deviceTimeMs / 6500) + 45 * Math.sin(deviceTimeMs / 1400),
+          400,
+          2000
+        );
+        const temperatureC = clamp(
+          22 + 2.2 * Math.sin(deviceTimeMs / 11000 + Math.PI / 5),
+          -40,
+          125
+        );
+        const humidityPercent = clamp(
+          48 + 14 * Math.sin(deviceTimeMs / 9000 + Math.PI / 2),
+          0,
+          100
+        );
+
+        return (
+          this._writeFloat32BytesAtOffsets(dataView, bytePos, [6, 7, 9, 10], co2Ppm) &&
+          this._writeFloat32BytesAtOffsets(dataView, bytePos, [12, 13, 15, 16], temperatureC) &&
+          this._writeFloat32BytesAtOffsets(dataView, bytePos, [18, 19, 21, 22], humidityPercent)
+        );
+      }
       case "RoboticalLEDRing": {
         if (dataBlockSizeBytes < 1) {
           return false;
@@ -665,6 +693,30 @@ export default class RaftChannelSimulated implements RaftChannel {
     }
   }
 
+  private _writeFloat32BytesAtOffsets(
+    dataView: DataView,
+    baseBytePos: number,
+    offsets: number[],
+    value: number
+  ): boolean {
+    if (offsets.length < 4) {
+      return false;
+    }
+
+    const maxOffset = Math.max(...offsets);
+    if (baseBytePos + maxOffset >= dataView.byteLength) {
+      return false;
+    }
+
+    const scratchBuffer = new ArrayBuffer(4);
+    new DataView(scratchBuffer).setFloat32(0, value, false);
+    const bytes = new Uint8Array(scratchBuffer);
+    for (let idx = 0; idx < 4; idx++) {
+      dataView.setUint8(baseBytePos + offsets[idx], bytes[idx]);
+    }
+    return true;
+  }
+
   private _getGridDimensions(attr: any, repeatCount: number): { rows: number; cols: number } {
     if (attr && typeof attr.resolution === "string") {
       const match = attr.resolution.match(/(\d+)\s*x\s*(\d+)/i);
@@ -1017,6 +1069,45 @@ export default class RaftChannelSimulated implements RaftChannel {
         "us": 100000
       }
     },
+    "SCD30": {
+      "name": "CO2 Sensor",
+      "desc": "",
+      "manu": "Sensirion",
+      "type": "SCD30",
+      "clas": ["CO2", "TEMP", "RH"],
+      "resp": {
+        "b": 24,
+        "a": [
+          {
+            "n": "CO2",
+            "t": ">f",
+            "at": [6, 7, 9, 10],
+            "u": "ppm",
+            "r": [0, 40000],
+            "f": ".1f",
+            "o": "float"
+          },
+          {
+            "n": "temperature",
+            "t": ">f",
+            "at": [12, 13, 15, 16],
+            "u": "C",
+            "r": [-40, 125],
+            "f": ".2f",
+            "o": "float"
+          },
+          {
+            "n": "humidity",
+            "t": ">f",
+            "at": [18, 19, 21, 22],
+            "u": "%RH",
+            "r": [0, 100],
+            "f": ".2f",
+            "o": "float"
+          }
+        ]
+      }
+    },
     "RoboticalServo": {
       "name": "Robotical Servo",
       "desc": "Servo",

package/src/RaftDeviceInfo.ts

@@ -136,6 +136,7 @@ export interface DeviceTypeInfo {
     desc: string;
     manu: string;
     type: string;
+    role?: string;
     resp?: DeviceTypePollRespMetadata;
     clas?: Array<string>;
     actions?: DeviceTypeAction[];
@@ -148,5 +149,8 @@ export interface DeviceTypeInfoRecs {
 export type RaftDevTypeInfoResponse = {
     req: string;
     rslt: string;
-    devinfo: DeviceTypeInfo;
+    devinfo?: DeviceTypeInfo;
+    dtIdx?: number;
+    name?: string;
+    role?: string;
   };

package/src/RaftDeviceManager.test.ts

@@ -2,7 +2,7 @@ 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 {
+function makeTypeInfo(name: string, respBytes: number, attrs: Array<{ n: string; t: string; at?: number | number[] }>): DeviceTypeInfo {
     return {
         name,
         desc: name,
@@ -123,6 +123,40 @@ describe("DeviceManager binary devbin parsing", () => {
         expect(deviceState.deviceAttributes.status.values).toEqual([4]);
     });
 
+    it("decodes current length-prefixed records with sparse absolute attribute offsets", async () => {
+        const scd30Info = makeTypeInfo("SCD30", 24, [
+            { n: "CO2", t: ">f", at: [6, 7, 9, 10] },
+            { n: "temperature", t: ">f", at: [12, 13, 15, 16] },
+            { n: "humidity", t: ">f", at: [18, 19, 21, 22] }
+        ]);
+        const deviceManager = await makeDeviceManager({ "42": scd30Info });
+        const rxMsg = Uint8Array.from([
+            0x00, 0x80,
+            0xDB, 0xFF, 0x00,
+            0x00, 0x23,
+            0x81,
+            0x00, 0x00, 0x02, 0x61,
+            0x00, 0x2a,
+            0x07,
+            0x1a,
+            0x00, 0x01,
+            0x00, 0x01, 0xb0,
+            0x00, 0x01, 0xb0,
+            0x43, 0xfa, 0x00, 0x00, 0x00, 0x00,
+            0x41, 0xc8, 0x00, 0x00, 0x00, 0x00,
+            0x42, 0x5e, 0x00, 0x00, 0x00, 0x00
+        ]);
+
+        await deviceManager.handleClientMsgBinary(rxMsg);
+
+        const deviceState = deviceManager.getDeviceState("1_261");
+        expect(deviceState.deviceType).toBe("SCD30");
+        expect(deviceState.deviceTimeline.totalSamplesAdded).toBe(1);
+        expect(deviceState.deviceAttributes.CO2.values).toEqual([500]);
+        expect(deviceState.deviceAttributes.temperature.values).toEqual([25]);
+        expect(deviceState.deviceAttributes.humidity.values).toEqual([55.5]);
+    });
+
     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" },