homebridge-roborock-matter 3.4.9 → 3.4.10

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.4.10
+
+**The Q7 position that never resolved to a room is not a position at all.** 3.4.9 asked the two Q7s to report the range their room outlines occupy, and they answered: Garage sat in a map spanning cells 52–171 by 43–187, 1. Sal in one spanning 38–293 by 90–227. Back-computing through each map's own origin and resolution gives the same coordinate for both — exactly (1100.0, 1100.0), on two robots, two maps, and twelve minutes of active cleaning. A number that identical is arithmetic, not a place a robot stood, which means live-room tracking on these models has never worked from that field.
+
+- **The miss line now surveys the payload rather than asserting anything about it.** It prints the size of every top-level field and every scalar inside the small ones, keyed by field path. Two consecutive lines are then a diff: the value that changed while the robot was driving is the position, and the submessage that grew is the trail behind it.
+- **Varints are surveyed, not just floats.** The pose message carries an `update` flag alongside its coordinates, so a float-only dump would have printed two plausible-looking numbers and hidden the field saying they were stale.
+- **The survey descends one level.** A pose trail's last point is by construction where the robot is now, and repeated paths overwrite, so the end of a trail lands in the log under a stable key.
+- **A bare scalar on the map itself is now visible.** The parse loop only ever descended into submessages, so a position stored as a plain float would not have appeared anywhere.
+- **It is bounded and it cannot throw.** The occupancy grid is measured rather than walked, the scalar count is capped, recursion is capped, and bytes that turn out not to be protobuf are swallowed. A diagnostic must never be the reason a robot stops reporting its room.
+
+This changes no behaviour. It exists because guessing another field number would have been the third guess in a row on this code path, and the robots were running.
+
 ## 3.4.9
 
 - **A live-room miss now says where the rooms actually are.** Two Q7s produced position cells around 22,000 while a Roborock map is a couple of thousand cells across at most — so those robots were never "between rooms", their computed position was nowhere near the map. One of them reported x exactly equal to y, which is arithmetic rather than a place a robot stood. The position on its own cannot separate a unit mismatch from a wrong origin, so the miss line now carries the range the room outlines occupy plus the map origin and resolution the transform used. This changes no behaviour; it turns the next log from a hypothesis into a measurement. The bounding box is computed only on the failure path, so a run that resolves every position pays nothing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "3.4.9",
+  "version": "3.4.10",
   "description": "The most complete Roborock plugin for Apple Home. Supports the entire Roborock lineup — from the classic S-series to the new 2025 Q7 series that no other plugin can control. Sign in with your Roborock account and get native start/stop, room cleaning, suction levels, battery, and live 'cleaning in the kitchen' room tracking. Verified by Homebridge.",
   "license": "MIT",
   "author": {

package/roborockLib/lib/b01Q7Adapter.js

@@ -186,6 +186,14 @@ function readVarint(buf, pos) {
   throw new Error("Malformed varint in SCMap payload");
 }
 
+// Bounds for the raw field survey below. They exist to keep a diagnostic
+// from becoming a liability: the survey is pointed at fields whose schema is
+// unknown, so it must not be able to produce an unbounded log line, walk the
+// occupancy grid as if it were protobuf, or recurse without end.
+const RAW_SURVEY_MAX_SCALARS = 48;
+const RAW_SURVEY_MAX_SUBMESSAGE_BYTES = 16384;
+const RAW_SURVEY_MAX_DEPTH = 2;
+
 /** @param {Buffer} buf @param {number} pos @param {number} wireType */
 function skipField(buf, pos, wireType) {
   switch (wireType) {
@@ -284,6 +292,11 @@ function parseRoomsFromScMap(buffer) {
  * @returns {{
  *   head: {sizeX: number, sizeY: number, minX: number, minY: number, resolution: number} | null,
  *   pose: {x: number, y: number} | null,
+ *   rawSurvey: {
+ *     fields: Array<{field: number, count: number, bytes: number}>,
+ *     scalars: Record<string, number>,
+ *     truncated: boolean,
+ *   },
  *   rooms: Array<{roomId: number, roomName: string}>,
  *   roomChains: Array<{roomId: number, points: Array<{x: number, y: number}>}>,
  * }}
@@ -293,6 +306,26 @@ function parseScMapLiveState(buffer) {
   let head = null;
   /** @type {{x: number, y: number} | null} */
   let pose = null;
+  // Diagnostic. Both Q7s in the field reported a pose of exactly
+  // (1100.0, 1100.0) — the same value on two robots, two maps and twelve
+  // minutes of active cleaning. That is a constant, not a position, so the
+  // number being read as the robot's position is not the robot's position.
+  //
+  // The schema above is not obviously wrong, which is what makes guessing
+  // another field number a bad move: it would be the third guess in a row on
+  // this code path. Two candidates fit the evidence and the survey separates
+  // them without a second release. DeviceCurrentPoseInfo carries an `update`
+  // varint, so field 8 may simply be marked stale on this firmware — a
+  // float-only dump would not have shown it. And field 6 is a pose *trail*,
+  // whose last point is by construction where the robot is now — which needs
+  // one level of nesting to see. So the survey records varints as well as
+  // floats, and descends one level: repeated paths overwrite, which leaves
+  // the last point of a trail sitting in the log under a stable key.
+  /** @type {Array<{field: number, count: number, bytes: number}>} */
+  const surveyFields = [];
+  /** @type {Record<string, number>} */
+  const surveyScalars = {};
+  let surveyTruncated = false;
   /** @type {Array<{roomId: number, roomChainPoints?: unknown}>} */
   const roomChains = [];
 
@@ -347,6 +380,109 @@ function parseScMapLiveState(buffer) {
       : null;
   }
 
+  /**
+   * Record that a top-level field was seen, and how many bytes it carried.
+   *
+   * The sizes matter as much as the values: a submessage that grows between
+   * two consecutive log lines while the robot is driving is a trail of where
+   * it has been, and the field that does that is the one worth reading.
+   *
+   * @param {number} field
+   * @param {number} bytes
+   */
+  function noteField(field, bytes) {
+    const seen = surveyFields.find((entry) => entry.field === field);
+    if (seen) {
+      seen.count += 1;
+      seen.bytes += bytes;
+    } else if (surveyFields.length < RAW_SURVEY_MAX_SCALARS) {
+      surveyFields.push({ field, count: 1, bytes });
+    } else {
+      surveyTruncated = true;
+    }
+  }
+
+  /**
+   * @param {string} path
+   * @param {number} value
+   */
+  function noteScalar(path, value) {
+    if (
+      surveyScalars[path] === undefined &&
+      Object.keys(surveyScalars).length >= RAW_SURVEY_MAX_SCALARS
+    ) {
+      surveyTruncated = true;
+      return;
+    }
+    // Deliberately last-wins. A repeated submessage collapses to its final
+    // occurrence, which for a pose trail is the current position.
+    surveyScalars[path] = value;
+  }
+
+  /**
+   * Walk a submessage recording every scalar it contains, keyed by dotted
+   * field path, to a bounded depth.
+   *
+   * Diagnostic only, and defensive by necessity: it is pointed at fields
+   * whose schema is unknown, so bytes that are not protobuf at all will
+   * reach it. A throw here would take live-room tracking down with it, so
+   * the caller swallows the error and keeps whatever was collected.
+   *
+   * @param {Buffer} buf
+   * @param {string} prefix
+   * @param {number} depth
+   */
+  function surveyMessage(buf, prefix, depth) {
+    let pos = 0;
+    while (pos < buf.length) {
+      const tag = readVarint(buf, pos);
+      pos = tag.pos;
+      const fieldNumber = Math.floor(tag.value / 8);
+      const wireType = tag.value % 8;
+      const path = `${prefix}.${fieldNumber}`;
+      if (wireType === 0) {
+        const value = readVarint(buf, pos);
+        pos = value.pos;
+        noteScalar(path, value.value);
+      } else if (wireType === 5) {
+        noteScalar(path, buf.readFloatLE(pos));
+        pos += 4;
+      } else if (wireType === 1) {
+        noteScalar(path, buf.readDoubleLE(pos));
+        pos += 8;
+      } else if (wireType === 2) {
+        const len = readVarint(buf, pos);
+        if (depth > 1 && len.value > 0) {
+          surveyMessage(
+            buf.subarray(len.pos, len.pos + len.value),
+            path,
+            depth - 1
+          );
+        }
+        pos = len.pos + len.value;
+      } else {
+        pos = skipField(buf, pos, wireType);
+      }
+    }
+  }
+
+  /**
+   * @param {Buffer} buf
+   * @param {number} field
+   */
+  function surveyTopLevelSubmessage(buf, field) {
+    if (buf.length > RAW_SURVEY_MAX_SUBMESSAGE_BYTES) {
+      // The occupancy grid is tens of kilobytes of raw cells, not protobuf.
+      // Its size is recorded; walking it would be nonsense and slow.
+      return;
+    }
+    try {
+      surveyMessage(buf, String(field), RAW_SURVEY_MAX_DEPTH);
+    } catch {
+      surveyTruncated = true;
+    }
+  }
+
   /** @param {Buffer} buf */
   function parseChainPoint(buf) {
     const point = { x: 0, y: 0 };
@@ -440,6 +576,8 @@ function parseScMapLiveState(buffer) {
     if (wireType === 2) {
       const len = readVarint(buffer, pos);
       const body = buffer.subarray(len.pos, len.pos + len.value);
+      noteField(fieldNumber, len.value);
+      surveyTopLevelSubmessage(body, fieldNumber);
       if (fieldNumber === 3) {
         head = parseMapHead(body);
       } else if (fieldNumber === 8) {
@@ -457,6 +595,17 @@ function parseScMapLiveState(buffer) {
       }
       pos = len.pos + len.value;
     } else {
+      // A position could just as easily be a bare float or varint on the
+      // RobotMap itself; the loop above only ever looked at submessages, so
+      // such a field would never have been seen at all.
+      noteField(fieldNumber, 0);
+      if (wireType === 0) {
+        noteScalar(String(fieldNumber), readVarint(buffer, pos).value);
+      } else if (wireType === 5) {
+        noteScalar(String(fieldNumber), buffer.readFloatLE(pos));
+      } else if (wireType === 1) {
+        noteScalar(String(fieldNumber), buffer.readDoubleLE(pos));
+      }
       pos = skipField(buffer, pos, wireType);
     }
   }
@@ -464,6 +613,11 @@ function parseScMapLiveState(buffer) {
   return {
     head,
     pose,
+    rawSurvey: {
+      fields: surveyFields,
+      scalars: surveyScalars,
+      truncated: surveyTruncated,
+    },
     rooms,
     roomChains:
       /** @type {Array<{roomId: number, points: Array<{x: number, y: number}>}>} */ (

package/roborockLib/roborockAPI.js

@@ -123,6 +123,64 @@ function describeOutlineBounds(resolution) {
   return `, outlines span ${Math.round(bounds.minX)}-${Math.round(bounds.maxX)} x ${Math.round(bounds.minY)}-${Math.round(bounds.maxY)}${origin}`;
 }
 
+/**
+ * The raw SCMap fields behind a live-room miss.
+ *
+ * Two Q7s reported a position of exactly (1100, 1100) — the same value on two
+ * robots, two maps and twelve minutes of active cleaning. A constant is not a
+ * position, so the number being read as the robot's position is not the
+ * robot's position.
+ *
+ * Rather than guess another field number, this prints what the payload
+ * actually contains: the size of every top-level field and every scalar in
+ * the small ones. Two consecutive lines are then a diff — the value that
+ * changed while the robot was driving is the position, and the submessage
+ * that grew is the trail it left. That turns the next fix into a reading
+ * rather than a fourth guess.
+ *
+ * @param {{rawSurvey?: {fields?: Array<{field: number, count: number, bytes: number}>,
+ *                      scalars?: Record<string, number>,
+ *                      truncated?: boolean} | null}} parsed
+ * @returns {string}
+ */
+function describeRawMapFields(parsed) {
+  const survey = parsed?.rawSurvey;
+  const fields = survey?.fields;
+  if (!Array.isArray(fields) || fields.length === 0) {
+    return "";
+  }
+
+  const shape = fields
+    .map(
+      (entry) =>
+        `${entry.field}:${entry.bytes}B${entry.count > 1 ? `x${entry.count}` : ""}`
+    )
+    .join(" ");
+
+  const scalars = Object.entries(survey?.scalars || {})
+    .map(([path, value]) => `${path}=${formatSurveyScalar(value)}`)
+    .join(" ");
+
+  return `, map fields ${shape}${scalars ? `, scalars ${scalars}` : ""}${
+    survey?.truncated ? " (truncated)" : ""
+  }`;
+}
+
+/**
+ * A survey value short enough to sit in a log line, precise enough to see a
+ * robot move. Three decimals of a metre is a millimetre; three decimals of a
+ * millimetre is far below anything a vacuum reports.
+ *
+ * @param {number} value
+ * @returns {string}
+ */
+function formatSurveyScalar(value) {
+  if (!Number.isFinite(value)) {
+    return String(value);
+  }
+  return Number.isInteger(value) ? String(value) : value.toFixed(3);
+}
+
 const B01_STATUS_TICK_MS = 15000;
 const B01_STATUS_FORCED_GAP_MS = 1500;
 const B01_STATUS_ACTIVE_GAP_MS = 12000;
@@ -4319,7 +4377,7 @@ class Roborock {
           // because they call for different fixes.
           liveState.unresolvedPoseCount =
             (liveState.unresolvedPoseCount || 0) + 1;
-          const message = `Live room for ${this.describeDevice(duid)}: ${B01_LIVE_ROOM_MISS_REASONS[resolution2.reason]} (attempt ${liveState.unresolvedPoseCount} this run, ${resolution2.outlineCount} room outline(s) in the map${resolution2.cell ? `, position cell ${Math.round(resolution2.cell.x)},${Math.round(resolution2.cell.y)}` : ""}${describeOutlineBounds(resolution2)}).`;
+          const message = `Live room for ${this.describeDevice(duid)}: ${B01_LIVE_ROOM_MISS_REASONS[resolution2.reason]} (attempt ${liveState.unresolvedPoseCount} this run, ${resolution2.outlineCount} room outline(s) in the map${resolution2.cell ? `, position cell ${Math.round(resolution2.cell.x)},${Math.round(resolution2.cell.y)}` : ""}${describeOutlineBounds(resolution2)}${describeRawMapFields(parsed)}).`;
           if (liveState.unresolvedPoseCount % 5 === 0) {
             this.log.info(message);
           } else {