@robotical/raftjs 2.1.3 → 2.1.5

package/devdocs/decode-overrun-investigation.md

@@ -0,0 +1,167 @@
+# Decode Overrun Error Investigation
+
+## Summary
+
+The raftjs example dashboard is receiving an `AttributeHandler decode overrun` error when processing light sensor data from a Cog device. The firmware is sending 9 bytes of sensor data, but the registered schema expects only 8 bytes.
+
+## Error Details
+
+**Error Message:**
+```
+AttributeHandler decode overrun (msgBuffer):
+  deviceKey=0_0
+  deviceType=Cog Light Sensors
+  debugMsgIndex=1
+  attr.n=amb0
+  attr.t=>H
+  attrTypeSize=2
+  curFieldBufIdx=45
+  msgBuffer.length=46
+  sampleStartIdx=37
+  sampleEndIdx=46
+  availableInSample=1
+  availableInBuffer=1
+```
+
+**Key Facts:**
+- Message buffer total length: 46 bytes
+- Sample data location: bytes 37-46 (9 bytes)
+- Declared sample size in schema: 8 bytes (`pollRespMetadata.b=8`)
+- **Mismatch: Firmware sends 9 bytes, schema expects 8 bytes**
+
+## Message Structure Analysis
+
+### Binary Message Format
+The firmware sends a binary message with this structure:
+1. **Timestamp** (2 bytes, big-endian) - handled separately before attribute decoding
+2. **Sample length** (1 byte) - value is 9, meaning 9 bytes of sensor data follow
+3. **Sensor data** (9 bytes) - the actual data being decoded
+   - IR sensor 0 (ir0): `5c 60` (0x5c60)
+   - IR sensor 1 (ir1): `00 05` (0x0005)
+   - IR sensor 2 (ir2): `03 00` (0x0300)
+   - Ambient sensor 0 (amb0): `02 57` (0x0257)
+   - **Extra byte**: `01` (unknown origin)
+
+### Expected vs Actual Schema
+
+**Schema Definition (from firmware):**
+```json
+{
+  "name": "Cog Light Sensors",
+  "desc": "Light Sensors",
+  "type": "RoboCogLightV1",
+  "resp": {
+    "b": 8,
+    "a": [
+      {"n": "ir0", "t": ">H", "u": "", "r": [0, 4095], "d": 1, "f": ".0f"},
+      {"n": "ir1", "t": ">H", "u": "", "r": [0, 4095], "d": 1, "f": ".0f"},
+      {"n": "ir2", "t": ">H", "u": "", "r": [918, 2259], "d": 1, "f": ".0f"},
+      {"n": "amb0", "t": ">H", "u": "L", "r": [0, 4095], "d": 1, "f": ".0f"}
+    ]
+  }
+}
+```
+
+**Expected data (based on schema):**
+- ir0: 2 bytes
+- ir1: 2 bytes
+- ir2: 2 bytes
+- amb0: 2 bytes
+- **Total: 8 bytes**
+
+**Actual data received:**
+- All 4 fields as expected (8 bytes)
+- **Plus 1 extra byte** = 9 bytes total
+
+## Root Cause
+
+The firmware's `DeviceLightSensors::formDeviceDataResponse()` function in `components/DeviceLightSensors/DeviceLightSensors.cpp` is generating sensor data, and there is a mismatch between:
+
+1. **What the firmware sends**: 9 bytes of sensor data (timestamp + data in the binary message)
+2. **What the schema declares**: 8 bytes of sensor data (`"b": 8`)
+
+The schema is generated dynamically by the firmware in `getDeviceTypeRecord()` based on the number of configured sensors:
+- 3 IR sensors × 2 bytes = 6 bytes
+- 1 ambient sensor × 2 bytes = 2 bytes
+- **Total: 8 bytes** (correct calculation)
+
+But the actual `formDeviceDataResponse()` is sending 9 bytes.
+
+## Investigation Points
+
+### 1. Extra Byte Origin
+The mysterious `01` byte at the end needs to be identified:
+- Is it padding?
+- Is it a sample count or indicator?
+- Is it an uninitialized buffer value?
+- Was it added in a recent firmware change?
+
+**Check:**
+- `git log -p components/DeviceLightSensors/DeviceLightSensors.cpp` around `formDeviceDataResponse()`
+- Look for recent changes that add bytes (new sensor data, flags, etc.)
+- Compare the byte count calculation in `getDeviceTypeRecord()` with actual `formDeviceDataResponse()` logic
+
+### 2. Binary Message Encoding
+The binary message encoding happens in `RaftDevice::genBinaryDataMsg()` (in RaftCore). Verify:
+- Is the framework adding extra metadata or padding?
+- Are sample boundaries being correctly calculated?
+- Is there a mismatch between the sample length byte and actual data written?
+
+**Check:**
+- `RaftDevice::genBinaryDataMsg()` implementation
+- Recent changes to binary message encoding
+- Sample length byte calculation
+
+### 3. Configuration/Build State
+- Check if the firmware was built with debug flags that add extra bytes
+- Verify that sensor configuration hasn't changed (more sensors added?)
+- Check if conditional compilation (#ifdef) is affecting byte counts
+
+## raftjs Side
+
+The raftjs library correctly detects the mismatch through the diagnostic context added in recent commits:
+- `AttrDecodeDiagContext` interface tracks sample boundaries
+- `RaftAttributeHandler.processMsgAttribute()` bounds-checks against these boundaries
+- `RaftDeviceManager` passes diagnostic context with `sampleStartIdx` and `sampleEndIdx`
+
+This is working as intended—the error indicates a real firmware/schema mismatch, not a bug in raftjs.
+
+## Recommended Fixes
+
+### Short Term (Workaround)
+Update the schema to match reality:
+```json
+"resp": {
+  "b": 9,  // Changed from 8 to 9
+  ...
+}
+```
+This will suppress the error but doesn't fix the root cause.
+
+### Long Term (Proper Fix)
+1. **Identify the source** of the extra byte in `formDeviceDataResponse()`
+2. **Either:**
+   - Remove the extra byte if it's unintended
+   - Properly account for it in the schema and sensor processing if it's intentional
+3. **Update documentation** if there's a reason for the extra byte
+4. **Add unit tests** to prevent this mismatch in future changes
+
+## Related Code Locations
+
+**Firmware:**
+- Schema definition: `RoboticalCogFW/components/DeviceLightSensors/DeviceLightSensors.cpp` - `getDeviceTypeRecord()`
+- Data encoding: `RoboticalCogFW/components/DeviceLightSensors/DeviceLightSensors.cpp` - `formDeviceDataResponse()`
+- Binary message: `RoboticalCogFW/raftdevlibs/RaftCore/components/core/RaftDevice/RaftDevice.cpp` - `genBinaryDataMsg()`
+
+**raftjs:**
+- Attribute handler: `raftjs/src/RaftAttributeHandler.ts` - `processMsgAttribute()`
+- Device manager: `raftjs/src/RaftDeviceManager.ts` - `handleClientMsgBinary()`
+- Diagnostic logging: Added in recent commit with `AttrDecodeDiagContext`
+
+## Next Steps
+
+1. Run `git log -p` on DeviceLightSensors to find when the extra byte was introduced
+2. Check the firmware build/compile to ensure no debug additions
+3. Examine `formDeviceDataResponse()` line-by-line against sensor configuration
+4. Test with a debugger to verify what bytes are actually being transmitted
+5. Once identified, decide whether to remove the byte or update the schema

package/devdocs/message-panel-design.md

@@ -0,0 +1,320 @@
+# Dashboard Message Panel — Cog-to-Cog IR Comms
+
+## Purpose
+
+Add a **Message Panel** to the RaftJS example dashboard so a developer can exercise the
+cog-to-cog IR communications feature described in the Cog firmware design document
+(`RoboticalCogFW/devdocs/cog-to-cog-ir-comms-design.md`).
+
+The panel sits alongside the existing Command Panel and provides:
+
+- A text box to enter an ASCII message.
+- A drop-down list of destinations to send the message to. Initially the only entry is the
+  IR channel of a Cog (side 2, the validated comms axis).
+- A button to send the message.
+- A scrolling log of messages received over the same IR channel by the connected device.
+
+**No code has been changed yet.** This document records the investigation and describes the
+work required to implement the panel.
+
+## Background
+
+### How the firmware exposes IR comms
+
+The Cog firmware feature is implemented by the `CogIRComms` SysMod and exposed through the
+standard RaftCore REST endpoint mechanism, so the same endpoints work over BLE RICREST,
+WebSocket, and serial. The relevant endpoints (from the firmware design doc, "Useful REST
+commands" and the 2026-05-15 validation section) are:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `ircomms/status` | Returns state plus rx/tx counters and config. Use it to confirm the feature is built/enabled. |
+| `ircomms/tx?side=2&type=<0-15>&seq=<0-15>&payload=<0-255>` | Send a tiny diagnostic packet (single payload byte). |
+| `ircomms/send?side=2&type=<0-15>&seq=<0-15>&hex=<even-length hex, up to 160 chars>` | Send a framed datagram with an arbitrary payload (up to 80 bytes). **This is the endpoint the Message Panel should use.** |
+| `ircomms/rx?pop=1` | Pop the oldest received tiny packet. |
+| `ircomms/rx?popFrame=1` | Pop the oldest received framed datagram. |
+| `ircomms/rx?clear=1` | Clear the receive queue. |
+| `ircomms/cfg?frameMarkUs=<us>&frameSpaceUs=<us>` | Runtime frame-timing tweak (not needed for v1). |
+
+The framed payload is the right fit for an ASCII message: `frameMaxPayloadBytes` is 80, i.e.
+160 hex characters, validated on hardware up to 48 bytes with overhead headroom.
+
+Side 2 (`IRTX2`/`IRRX2`, mux channel 2) is the only validated bidirectional axis; side 1 did
+not couple in the tested orientations. The destination drop-down should therefore default to
+side 2.
+
+### How the firmware notifies of received messages
+
+When `rxReportEnable` is true (it is in the default `Cog1` systype config), each CRC-valid
+received message also produces a **RICREST report frame** sent through `SysManager`. For the
+tiny-packet diagnostic the report looks like:
+
+```json
+{"msgType":"ircomms","msgName":"rx","rxMs":11134,"type":7,"seq":8,"payload":55,"crc":55883}
+```
+
+The firmware design doc's "Receive Notification Recommendation" section proposes a richer
+report for framed messages with `source`, `type`, and a `payload` field. The exact shape of
+the report emitted for **framed** `ircomms/send` datagrams is not pinned down in the firmware
+doc — see [Open questions](#open-questions-firmware-coordination).
+
+### How RaftJS sends and receives
+
+The dashboard talks to one device at a time through a single `RaftConnector` instance
+(`ConnManager.getInstance().getConnector()`).
+
+**Sending** — `CommandPanel.tsx` already shows the pattern:
+
+```ts
+connManager.getConnector().sendRICRESTMsg(commandName, params)
+```
+
+`sendRICRESTMsg(commandName, params)` (in `src/RaftConnector.ts:412`) builds a query string
+from `params`, URL-encodes each value, appends it to `commandName`, sends it as a RICREST URL
+message, and resolves to the parsed JSON response (typed `RaftOKFail`, but the full JSON of
+the device response is returned). So a framed send is simply:
+
+```ts
+const resp = await connManager.getConnector().sendRICRESTMsg('ircomms/send', {
+  side: 2, type: 1, seq: seqNo, hex: asciiToHex(messageText),
+});
+// resp e.g. { rslt: "ok", seq: 42, queued: 1 }
+```
+
+Polling the receive queue uses the same call:
+
+```ts
+const resp = await connManager.getConnector().sendRICRESTMsg('ircomms/rx', { popFrame: 1 });
+```
+
+**Receiving reports** — `RaftMsgHandler` decodes `MSG_TYPE_REPORT` frames, parses the JSON,
+and dispatches it to every callback registered via `reportMsgCallbacksSet`
+(`src/RaftMsgHandler.ts:144`). The connector exposes the handler publicly:
+
+```ts
+const handler = connManager.getConnector().getRaftMsgHandler();   // RaftConnector.ts:220
+handler.reportMsgCallbacksSet('messagePanel', async (report) => { ... });
+// on unmount:
+handler.reportMsgCallbacksDelete('messagePanel');
+```
+
+The callback receives a `RaftReportMsg` object (exported from `src/main.ts` via
+`export * from './RaftTypes'`). Note `RaftReportMsg` only declares a fixed set of fields;
+the `ircomms` report carries extra fields (`type`, `seq`, `payload`, `crc`, `rxMs`, …) that
+must be read by extending/casting the type.
+
+The connector already registers an internal `"eventHandler"` report callback for `sysevent`
+shutdown handling — adding a second `"messagePanel"` callback is independent and supported.
+
+## Proposed design
+
+### New component: `MessagePanel.tsx`
+
+Add `examples/dashboard/src/MessagePanel.tsx`, structured like `CommandPanel.tsx`:
+
+- A two-column `info-box` (reuse the existing `info-boxes` / `info-box` / `info-columns`
+  layout classes).
+- **Left column** — message composer: ASCII text input, destination `<select>`, Send button.
+- **Right column** — received-message log: a scrollable list, newest last (or newest first),
+  with a Clear button.
+
+Suggested layout:
+
+```text
++-------------------------- Message Panel ---------------------------+
+| Compose                          | Received (IR side 2)           |
+| [ Enter ASCII message_________ ]  | 12:01:03  src? "hello"         |
+| Destination: [ Cog IR side 2 v ]  | 12:01:09  src? "ping back"     |
+| [   Send Message   ]              | ...                            |
+| status: queued seq 42             | [ Clear log ]                  |
++--------------------------------------------------------------------+
+```
+
+### Destination drop-down (data-driven)
+
+Make the destination list a small array so future destinations are easy to add:
+
+```ts
+interface IRDestination {
+  label: string;        // shown in the drop-down
+  endpoint: string;     // e.g. 'ircomms/send'
+  baseParams: object;   // e.g. { side: 2, type: 1 }
+}
+
+const destinations: IRDestination[] = [
+  { label: 'Cog IR (side 2)', endpoint: 'ircomms/send', baseParams: { side: 2, type: 1 } },
+];
+```
+
+The `seq` and `hex` parameters are added per-send. Future entries could target side 1, the
+tiny-packet `ircomms/tx` endpoint, or other transports without changing the panel logic.
+
+### Send path
+
+1. Read the ASCII text from the input.
+2. Validate: non-empty, and ≤ 80 characters (160 hex chars — the `ircomms/send` limit). Show
+   an inline error otherwise.
+3. Convert ASCII → hex (see [helpers](#asciihex-helpers)).
+4. Maintain a rolling `seq` counter. The validated diagnostic commands use `seq` in the
+   `0-15` range, so wrap with `seq = (seq + 1) & 0x0f`.
+5. Call `sendRICRESTMsg(dest.endpoint, { ...dest.baseParams, seq, hex })`.
+6. Show the result (`resp.rslt`, `resp.seq`, `resp.queued`) as a small status line, and warn
+   on `rslt !== 'ok'`. Keep a local sent-message history (optional, mirrors CommandPanel's
+   command history / arrow-key recall).
+
+### Receive path
+
+The connected device receives IR messages from *another* Cog automatically via its wake-probe
+path and queues them. The dashboard surfaces them in the log. Two mechanisms are available:
+
+**A. Polling `ircomms/rx?popFrame=1` (recommended primary mechanism for v1).**
+
+- On a timer (e.g. every 750 ms) while connected, call `sendRICRESTMsg('ircomms/rx', { popFrame: 1 })`.
+- If the response contains a frame, decode its payload hex → ASCII and append a log entry,
+  then poll again immediately to drain the queue; stop when empty.
+- This reliably returns the full payload regardless of report-frame shape, which is why it is
+  preferred for the first implementation.
+
+**B. Report subscription (low-latency enhancement).**
+
+- Register a `messagePanel` report callback and filter for
+  `report.msgType?.toLowerCase() === 'ircomms' && report.msgName?.toLowerCase() === 'rx'`.
+- Use it either to display the message directly (if the report includes the payload) or
+  simply to trigger an immediate drain of `ircomms/rx?popFrame=1` instead of waiting for the
+  next poll tick.
+
+**Recommendation:** implement (A) first for a working, reliable panel. Add (B) as a latency
+improvement once the firmware report shape for framed messages is confirmed. Both can run
+together — the report callback just triggers an early poll.
+
+A "Clear log" button should clear the local log; optionally also call `ircomms/rx?clear=1` to
+clear the device-side queue so stale messages are not re-polled.
+
+### ASCII/hex helpers
+
+`ConnManager` already has `hexStringToBytes()`. Two more small pure functions are needed —
+put them in `MessagePanel.tsx` or a shared `examples/dashboard/src/utils.ts`:
+
+```ts
+// 'hi' -> '6869'
+function asciiToHex(text: string): string {
+  return Array.from(text, c => c.charCodeAt(0).toString(16).padStart(2, '0')).join('');
+}
+
+// '6869' -> 'hi'  (non-printable bytes shown as '.', or escaped)
+function hexToAscii(hex: string): string {
+  const out = (hex.match(/.{1,2}/g) ?? []).map(b => parseInt(b, 16));
+  return out.map(c => (c >= 0x20 && c < 0x7f) ? String.fromCharCode(c) : '.').join('');
+}
+```
+
+Restrict the input to the ASCII printable range (0x20–0x7e) on send, or document that
+non-ASCII characters are encoded as their lower byte only.
+
+### CSS
+
+Reuse `command-input` and `send-command-button` for the input and button. Add a few classes
+to `examples/dashboard/src/styles.css` for the new elements, following the existing dark
+theme (`#333`/`#444` backgrounds, `#666` borders):
+
+- `.message-destination-select` — the drop-down.
+- `.message-log` — scrollable container (`max-height`, `overflow-y: auto`).
+- `.message-log-entry` — one received message (timestamp + text).
+- `.message-status` — the send-result status line.
+
+### Integration into `Main.tsx`
+
+Render `<MessagePanel />` immediately after `<CommandPanel />` inside the
+`connected-panel` block (`examples/dashboard/src/Main.tsx:178`). It only makes sense when
+connected, which that block already guarantees.
+
+Optionally gate the panel so it only appears for Cog devices: on mount, call
+`ircomms/status` once and only enable the panel (or show a "not available on this device"
+note) if it returns `rslt: "ok"`. This avoids a confusing dead panel when connected to a
+Marty or generic device. For a first cut the panel can always render and simply report
+failures from `sendRICRESTMsg`.
+
+## Open questions / firmware coordination
+
+These should be confirmed against the actual firmware build before or during implementation:
+
+1. **Framed receive report shape.** The firmware doc shows the tiny-packet report
+   (`payload` as a single number). It does not pin down the report emitted for framed
+   `ircomms/send` datagrams. For mechanism (B) to display message text directly, the
+   `ircomms`/`rx` report should include the payload as `payloadHex` (or an escaped ASCII
+   string). If it does not, the panel must rely on polling (mechanism A). **Recommended
+   firmware change:** include `payloadHex` and `len` in the framed-receive report.
+2. **`ircomms/rx?popFrame=1` response fields.** Confirm the exact JSON field names returned
+   (the firmware doc variously mentions `frameHex`, `payloadHex`, `rxnext`/`rxpeek`,
+   `rx?popFrame`). The panel's decode step depends on the actual field name, and on what is
+   returned when the queue is empty (`rslt: "ok"` with no frame vs `rslt: "fail"`).
+3. **`text=` parameter.** Some diagnostic examples use `ircomms/send?...&text=hi` directly.
+   If `text=` is reliably supported, the dashboard could skip hex conversion. The validated
+   command list uses `hex=`, so `hex=` is the safer default.
+4. **Device prerequisites.** The connected Cog must be running a build with `CogIRComms`
+   compiled in and `CogIRComms.enable = 1` (and `rxReportEnable = 1` for mechanism B) in its
+   systype config. The dashboard cannot set these — they are firmware build/config
+   preconditions. Surface `ircomms/status` so the user can see whether the feature is live.
+5. **Two devices needed for a real test.** The dashboard connects to one Cog. Sends leave
+   that Cog over IR; the receive log shows what that Cog received over IR from a *second*
+   Cog. A meaningful round-trip test needs two Cogs physically aligned on side 2, and
+   typically two dashboard instances (one per Cog) — or the second Cog echoing messages.
+6. **`seq` range.** The framed envelope carries a 1-byte sequence number, but the validated
+   diagnostic commands constrain `seq` to `0-15`. Wrap the rolling counter at 16 unless
+   firmware confirms the full byte range is accepted by `ircomms/send`.
+
+## Implementation steps
+
+1. Add `asciiToHex` / `hexToAscii` helpers (in `MessagePanel.tsx` or a shared util).
+2. Create `examples/dashboard/src/MessagePanel.tsx`:
+   - State: message text, selected destination, rolling `seq`, send-status, received log.
+   - Send handler → `sendRICRESTMsg('ircomms/send', {...})`.
+   - Receive: poll `ircomms/rx?popFrame=1` on an interval via `useEffect`/`setInterval`
+     (clean up on unmount); decode hex payload → ASCII; append to log.
+   - Optional: register/deregister a `messagePanel` report callback for low-latency
+     notification.
+3. Add the destination array (one entry: Cog IR side 2).
+4. Add CSS classes to `styles.css`.
+5. Wire `<MessagePanel />` into `Main.tsx` after `<CommandPanel />`.
+6. (Optional) Gate the panel on an `ircomms/status` probe.
+
+## Related: feature-gating panels on capability probes
+
+The Message Panel will probe `ircomms/status` once on connect to decide whether to render
+(see step 6 above). The same pattern should be applied to the existing **datalog** panels
+(`LogConfigPanel`, `LoggingPanel`, `LogFilesPanel`), because some firmwares do not support
+that API and the dashboard currently produces noisy console errors against them:
+
+```text
+_handleResponseMessages RICREST rslt fail msgNum 115
+  resp {"req":"datalog?action=status","rslt":"fail","error":"failUnknownAPI"}
+```
+
+Proposed work (separate from but parallel to the Message Panel):
+
+1. On (re)connect, issue a single `datalog?action=status` (or equivalent capability) call.
+2. Cache the result as a "datalog supported" boolean on `ConnManager` or a small capability
+   context, keyed off the current connection.
+3. Conditionally render `LogConfigPanel` / `LoggingPanel` / `LogFilesPanel` and suppress any
+   periodic datalog polling when the capability is absent.
+4. Reset the cached capability on disconnect so reconnecting to a different device re-probes.
+
+A small shared helper — e.g. `useFeatureSupported(probeApi: string): boolean | undefined` —
+would let both the Message Panel and the datalog panels use the same gating pattern, and
+keep `failUnknownAPI` errors out of the console for any feature that is not built into the
+connected firmware.
+
+## Testing
+
+- **Single device, no peer:** connect to one Cog, send a message, confirm `sendRICRESTMsg`
+  resolves with `rslt: "ok"` and the status line updates. The receive log stays empty.
+- **Two devices:** align two Cogs side-2-to-side-2 (~10 mm gap, per the firmware validation
+  setup). Connect a dashboard to each. Send from one and confirm the message appears in the
+  other's receive log with the correct decoded ASCII text.
+- **Round-trip:** send in both directions; confirm sequence numbers advance and no messages
+  are dropped.
+- **Edge cases:** empty message rejected; over-length message (>80 chars) rejected with a
+  clear error; non-printable received bytes rendered safely; panel behaves correctly across
+  disconnect/reconnect (timers and report callbacks cleaned up).
+- **Regression:** confirm the existing Command Panel and other panels are unaffected by the
+  added report callback and polling.

package/dist/react-native/RaftAttributeHandler.d.ts

@@ -1,13 +1,22 @@
 import { DeviceTypePollRespMetadata } from "./RaftDeviceInfo";
 import { DeviceAttributesState, DeviceTimeline } from "./RaftDeviceStates";
+export interface AttrDecodeDiagContext {
+    deviceKey?: string;
+    deviceType?: string;
+    debugMsgIndex?: number;
+    sampleStartIdx?: number;
+    sampleEndIdx?: number;
+}
 export default class AttributeHandler {
     private _customAttrHandler;
     private POLL_RESULT_TIMESTAMP_SIZE;
     private POLL_RESULT_WRAP_VALUE;
     private POLL_RESULT_RESOLUTION_US;
-    processMsgAttrGroup(msgBuffer: Uint8Array, msgBufIdx: number, deviceTimeline: DeviceTimeline, pollRespMetadata: DeviceTypePollRespMetadata, devAttrsState: DeviceAttributesState, maxDataPoints: number, msgEndIdx?: number): number;
+    processMsgAttrGroup(msgBuffer: Uint8Array, msgBufIdx: number, deviceTimeline: DeviceTimeline, pollRespMetadata: DeviceTypePollRespMetadata, devAttrsState: DeviceAttributesState, maxDataPoints: number, msgEndIdxOrDiagCtx?: number | AttrDecodeDiagContext, diagCtx?: AttrDecodeDiagContext): number;
     private validateAttributes;
     private processMsgAttribute;
+    private _overrunWarnSeen;
+    private warnAttrOverrun;
     private signExtend;
     private extractTimestampAndAdvanceIdx;
     private isValueInRangeString;

package/dist/react-native/RaftAttributeHandler.js

@@ -12,6 +12,7 @@ const tslib_1 = require("tslib");
 const RaftCustomAttrHandler_1 = tslib_1.__importDefault(require("./RaftCustomAttrHandler"));
 const RaftDeviceInfo_1 = require("./RaftDeviceInfo");
 const RaftStruct_1 = require("./RaftStruct");
+const RaftUtils_1 = tslib_1.__importDefault(require("./RaftUtils"));
 class AttributeHandler {
     constructor() {
         // Custom attribute handler
@@ -20,8 +21,21 @@ class AttributeHandler {
         this.POLL_RESULT_TIMESTAMP_SIZE = 2;
         this.POLL_RESULT_WRAP_VALUE = this.POLL_RESULT_TIMESTAMP_SIZE === 2 ? 65536 : 4294967296;
         this.POLL_RESULT_RESOLUTION_US = 100;
+        // 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.
+        this._overrunWarnSeen = new Set();
     }
-    processMsgAttrGroup(msgBuffer, msgBufIdx, deviceTimeline, pollRespMetadata, devAttrsState, maxDataPoints, msgEndIdx = msgBuffer.length) {
+    processMsgAttrGroup(msgBuffer, msgBufIdx, deviceTimeline, pollRespMetadata, devAttrsState, maxDataPoints, msgEndIdxOrDiagCtx = msgBuffer.length, diagCtx) {
+        var _a;
+        // 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
+            : (_a = msgEndIdxOrDiagCtx.sampleEndIdx) !== null && _a !== void 0 ? _a : 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);
         // Extract msg timestamp
@@ -33,6 +47,11 @@ class AttributeHandler {
         const msgDataStartIdx = msgBufIdx;
         // New attribute values (in order as they appear in the attributes JSON)
         let newAttrValues = [];
+        // 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
             newAttrValues = this._customAttrHandler.handleAttr(pollRespMetadata, msgBuffer, msgBufIdx, boundedMsgEndIdx);
@@ -71,11 +90,12 @@ 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;
                 }
@@ -97,13 +117,17 @@ 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;
         }
         // Add the new attribute values to the device state
@@ -238,7 +262,7 @@ class AttributeHandler {
             }
         }
     }
-    processMsgAttribute(attrDef, msgBuffer, msgBufIdx, msgDataStartIdx, msgEndIdx) {
+    processMsgAttribute(attrDef, msgBuffer, msgBufIdx, msgDataStartIdx, msgEndIdx, pollRespMetadata, diagCtx) {
         // Current field message string index
         let curFieldBufIdx = msgBufIdx;
         let attrUsesAbsPos = false;
@@ -257,7 +281,8 @@ 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];
@@ -273,11 +298,13 @@ 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 };
         }
         // Slice into buffer
@@ -379,6 +406,31 @@ class AttributeHandler {
         // Return the value
         return { values: attrValues, newMsgBufIdx: msgBufIdx };
     }
+    warnAttrOverrun(attrDef, msgBuffer, curFieldBufIdx, attrTypeSize, msgDataStartIdx, attrUsesAbsPos, pollRespMetadata, diagCtx, overrunOf) {
+        var _a, _b, _c, _d, _e, _f;
+        const sampleStart = (_a = diagCtx === null || diagCtx === void 0 ? void 0 : diagCtx.sampleStartIdx) !== null && _a !== void 0 ? _a : msgDataStartIdx;
+        const sampleEnd = diagCtx === null || diagCtx === void 0 ? void 0 : diagCtx.sampleEndIdx;
+        const dedupeKey = `${(_b = diagCtx === null || diagCtx === void 0 ? void 0 : diagCtx.deviceKey) !== null && _b !== void 0 ? _b : "?"}|${(_c = diagCtx === null || diagCtx === void 0 ? void 0 : diagCtx.deviceType) !== null && _c !== void 0 ? _c : "?"}|${attrDef.n}|${attrDef.t}|${attrUsesAbsPos ? attrDef.at : "rel"}`;
+        if (this._overrunWarnSeen.has(dedupeKey)) {
+            return;
+        }
+        this._overrunWarnSeen.add(dedupeKey);
+        const sampleHex = sampleEnd !== undefined
+            ? RaftUtils_1.default.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=${(_d = diagCtx === null || diagCtx === void 0 ? void 0 : diagCtx.deviceKey) !== null && _d !== void 0 ? _d : "?"} deviceType=${(_e = diagCtx === null || diagCtx === void 0 ? void 0 : diagCtx.deviceType) !== null && _e !== void 0 ? _e : "?"} ` +
+            `debugMsgIndex=${(_f = diagCtx === null || diagCtx === void 0 ? void 0 : diagCtx.debugMsgIndex) !== null && _f !== void 0 ? _f : "?"} 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 !== null && sampleEnd !== void 0 ? sampleEnd : "?"} ` +
+            `availableInSample=${availableInSample} availableInBuffer=${availableInBuffer} ` +
+            `sampleHex=${sampleHex} ` +
+            `pollRespMetadata.b=${pollRespMetadata === null || pollRespMetadata === void 0 ? void 0 : pollRespMetadata.b} ` +
+            `schema=${JSON.stringify(pollRespMetadata === null || pollRespMetadata === void 0 ? void 0 : pollRespMetadata.a)}`);
+    }
     signExtend(value, mask) {
         const signBitMask = (mask + 1) >> 1;
         const signBit = value & signBitMask;