homebridge-roborock-matter 3.4.8 → 3.4.10

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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.
+
 ## 3.4.8
 
 **Selecting "Vacuum" and getting a vacuum-and-mop was not a display bug — one timed-out command cancelled the one that mattered.** skmzwanke reported in [#8](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/8) that he selected Vacuum for a single room and the robot mopped it anyway, and his 3.4.5 log names the cause outright.

package/README.md

@@ -37,7 +37,7 @@ This is the most feature-packed, most thoroughly engineered Roborock plugin for
 - 📍 **See where it's cleaning — live.** Apple Home shows _"Cleaning — Kitchen"_ with the room the robot is actually inside, updating as it moves from room to room. Works even for cleans started from the robot's button or the Roborock app. No other Homebridge plugin does this.
 - 🧭 **One robot, one tile — and as many robots as you own.** Sign in once and your whole fleet comes along: every vacuum on your account appears as its own clean, native accessory in Apple Home. No clutter of fake fans and helper switches, and rooms appear with the names you gave them in the Roborock app.
 - ⚡ **Fast and reliable.** Commands go directly to the robot over your own network whenever possible, with the Roborock cloud as automatic backup — and built-in diagnostics in the settings if you ever want to look under the hood.
-- 🛡️ **Verified by Homebridge.** Reviewed and endorsed by the Homebridge team. 419 automated tests, zero known vulnerabilities, no analytics, and a startup designed to never crash your Homebridge — even when your Wi-Fi or the Roborock cloud has a bad day.
+- 🛡️ **Verified by Homebridge.** Reviewed and endorsed by the Homebridge team. 463 automated tests, zero known vulnerabilities, no analytics, and a startup designed to never crash your Homebridge — even when your Wi-Fi or the Roborock cloud has a bad day.
 
 ## Features
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "3.4.8",
+  "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}>}>} */ (
@@ -504,7 +658,9 @@ function resolveLiveRoomId(liveState) {
  * @returns {{roomId: number | null,
  *            reason: "resolved" | "no-map-header" | "no-pose" | "no-room-outlines" | "pose-outside-outlines",
  *            outlineCount: number,
- *            cell: {x: number, y: number} | null}}
+ *            cell: {x: number, y: number} | null,
+ *            outlineBounds?: {minX: number, minY: number, maxX: number, maxY: number} | null,
+ *            head?: {minX: number, minY: number, resolution: number}}}
  */
 function describeLiveRoomResolution(liveState) {
   const head = liveState?.head;
@@ -541,9 +697,44 @@ function describeLiveRoomResolution(liveState) {
     reason: "pose-outside-outlines",
     outlineCount,
     cell,
+    outlineBounds: outlineBoundingBox(chains),
+    head: { minX: head.minX, minY: head.minY, resolution },
   };
 }
 
+/**
+ * Bounding box of every room outline, in the same cell space the
+ * point-in-polygon test uses.
+ *
+ * Field logs showed two Q7s reporting position cells around 22,000 while a
+ * Roborock map is at most a couple of thousand cells across — so the position
+ * is not "between rooms", it is nowhere near the map. Whether that is a unit
+ * mismatch (pose in millimetres against a resolution in metres) or a wrong
+ * origin cannot be told from the position alone: it needs the range the
+ * outlines actually occupy. Printing both next to each other turns a guess
+ * into a measurement.
+ *
+ * @param {Array<{points: Array<{x: number, y: number}>}>} chains
+ * @returns {{minX: number, minY: number, maxX: number, maxY: number} | null}
+ */
+function outlineBoundingBox(chains) {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+
+  for (const chain of chains) {
+    for (const point of chain.points || []) {
+      if (point.x < minX) minX = point.x;
+      if (point.y < minY) minY = point.y;
+      if (point.x > maxX) maxX = point.x;
+      if (point.y > maxY) maxY = point.y;
+    }
+  }
+
+  return Number.isFinite(minX) ? { minX, minY, maxX, maxY } : null;
+}
+
 /**
  * Standard ray-casting point-in-polygon test over a room boundary chain.
  * @param {number} x @param {number} y

package/roborockLib/roborockAPI.js

@@ -95,6 +95,92 @@ const B01_LIVE_ROOM_MISS_REASONS = {
     "the robot's position did not fall inside any known room outline (it may be between rooms, or the map may still be building)",
 };
 
+/**
+ * The outline range and map origin, appended to a live-room miss.
+ *
+ * A position cell on its own cannot distinguish "the robot is between rooms"
+ * from "the position was computed in the wrong units" — and the field logs
+ * showed cells near 22,000 where a Roborock map is a couple of thousand cells
+ * at most. Printing the range the outlines occupy, plus the origin and
+ * resolution the transform used, makes the difference measurable from one log
+ * line instead of inferable from none.
+ *
+ * @param {{outlineBounds?: {minX: number, minY: number, maxX: number, maxY: number} | null,
+ *          head?: {minX: number, minY: number, resolution: number}}} resolution
+ * @returns {string}
+ */
+function describeOutlineBounds(resolution) {
+  const bounds = resolution?.outlineBounds;
+  if (!bounds) {
+    return "";
+  }
+
+  const head = resolution.head;
+  const origin = head
+    ? `, map origin ${head.minX},${head.minY} at ${head.resolution}/cell`
+    : "";
+
+  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;
@@ -4291,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)}` : ""}).`;
+          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 {