homebridge-roborock-matter 3.10.2 → 3.11.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 3.11.0
+
+**A Q7 said it was between rooms two hundred and twenty-six times during one clean. It was in the bedroom the whole time.**
+
+I caught a run on my own robots and pulled the numbers rather than the impressions. One Q7, 47 minutes, 227 live-room fetches. 226 of them placed it at cell 22280,22100 — the same cell every time — while the room outlines on that map span 38 to 293. The pose behind it was exactly (1100, 1100), which is the same constant two other people's Q7s reported back in August. The remaining fetches resolved Stue, then Gang, then Soveværelse, in the order the robot actually moved.
+
+So the robot does send a real position. It just serves a placeholder in between, and every one of those was being written up as "the robot's position did not fall inside any known room outline (it may be between rooms, or the map may still be building)". That sentence was wrong twice over: the robot was not between rooms, and there was nothing anyone could do about it. It also fed the miss counter, which is how a robot cleaning one bedroom produced "after 46 unresolved position(s)".
+
+A position further outside the map than the map is wide is now recognised for what it is and named as a placeholder, once per run at a level you see and quietly thereafter. The test is geometry rather than the number 1100: the robot cannot be somewhere it has never mapped, which stays true if Roborock picks a different constant. A robot genuinely outside every outline — a doorway, a hallway nobody named, a strip the outlines do not cover — is still a real miss and still counts as one, because that is the case the miss line exists for. Classic S- and Q-series robots resolve every fetch and are untouched.
+
+Two things fall out of it. The room still updates on a Q7, on the fetches that carry a true position; nothing about the tile changes. And a resolved room now prints the cell it resolved at, so a working position and a failing one can be compared in one log instead of across two field sessions — which is what this one cost.
+
+**Also: fifty log lines a minute, per robot, that could never mean anything.** With debug on, every known status attribute produced `Skipping known get_status attribute without a Homebridge state object` on every poll. That check dates from this library's ioBroker origins, where the object it looks for exists; under Homebridge it never does, so the branch fired for every attribute forever and reported only that the plugin is not ioBroker. On my own server the log ring had shrunk to ninety minutes — the window you need when something real goes wrong. It is gone. An attribute nobody has mapped yet is still named once with its value, which is the half that carries information.
+
 ## 3.10.2
 
 **You asked for vacuum-only, the robot mopped, and Apple Home showed vacuum anyway — because the plugin believed a command it had already logged that it lost.**

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. 1108 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. 1134 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
 
@@ -79,6 +79,8 @@ Progress stays honest: a room is only shown as _completed_ once the robot was ac
 
 While a robot is actively cleaning, the plugin fetches its live position from the map channel (the first room of a run goes out immediately, then ~10 s apart, active runs only, nothing while docked or paused) and publishes the room it is inside as the Matter Service Area `currentArea`. Both robot generations are covered: **B01/Q7** robots via the encrypted SCMap protobuf (position ray-cast against per-room boundary outlines), **classic S/Q-series** robots via the RRMap segment grid (position resolved against per-pixel room segments — a single-byte lookup on the raw map buffer, ~1 µs per check).
 
+**A B01/Q7 robot answers most of those fetches with a placeholder rather than its position, and that is normal.** Measured over a 47-minute clean, 227 fetches: 226 returned exactly the same cell, far outside the map the robot itself had built, while the rest resolved real rooms in the order the robot moved through them. So the room still updates on a Q7 — just on the fetches that carry a true position, which arrive alongside the robot's own map uploads rather than on every poll. A placeholder is now named as one instead of being reported as "the robot is between rooms", and it is said once per run rather than every ten seconds. Classic S/Q-series robots are unaffected and resolve every fetch.
+
 </details>
 
 ## Suction modes (optional)
@@ -215,7 +217,7 @@ The complete path — robot → plugin → Homebridge → matter.js store — wa
 
 ## Contributing
 
-Model reports, diagnostics exports, and pull requests are very welcome. The codebase ships with 1108 tests (protocol fixtures verified against the [python-roborock](https://github.com/Python-roborock/python-roborock) reference), strict TypeScript checking, and CI across Node 22/24 × Homebridge 1.11/2.x — `npm test` before you push and you're set.
+Model reports, diagnostics exports, and pull requests are very welcome. The codebase ships with 1134 tests (protocol fixtures verified against the [python-roborock](https://github.com/Python-roborock/python-roborock) reference), strict TypeScript checking, and CI across Node 22/24 × Homebridge 1.11/2.x — `npm test` before you push and you're set.
 
 ## Support the project
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "3.10.2",
+  "version": "3.11.0",
   "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

@@ -641,11 +641,13 @@ function parseScMapLiveState(buffer) {
  * whether the point-in-polygon test genuinely rejected the position. Those
  * three call for three different fixes.
  *
- * @param {{head?: {minX: number, minY: number, resolution: number} | null,
+ * @param {{head?: {minX: number, minY: number, resolution: number,
+ *                 sizeX?: number, sizeY?: number} | null,
  *          pose?: {x: number, y: number} | null,
  *          roomChains?: Array<{roomId: number, points: Array<{x: number, y: number}>}>} | null} liveState
  * @returns {{roomId: number | null,
- *            reason: "resolved" | "no-map-header" | "no-pose" | "no-room-outlines" | "pose-outside-outlines",
+ *            reason: "resolved" | "no-map-header" | "no-pose" | "no-room-outlines"
+ *              | "pose-outside-outlines" | "pose-placeholder",
  *            outlineCount: number,
  *            cell: {x: number, y: number} | null,
  *            outlineBounds?: {minX: number, minY: number, maxX: number, maxY: number} | null,
@@ -677,20 +679,107 @@ function describeLiveRoomResolution(liveState) {
 
   for (const chain of chains) {
     if (pointInPolygon(cellX, cellY, chain.points)) {
+      // The cell rides along on a hit too. Without it the log could say which
+      // attempts failed and with what position, but never what a SUCCEEDING
+      // position looked like — so the two could not be compared, and the
+      // measurement below took a second field session to make.
       return { roomId: chain.roomId, reason: "resolved", outlineCount, cell };
     }
   }
 
+  const outlineBounds = outlineBoundingBox(chains);
+
+  // A pose that is not merely outside the rooms but nowhere near the map is a
+  // different thing, and calling both "outside the outlines" sent every
+  // investigation down the same wrong path for three weeks.
+  //
+  // Measured on a Q7 over a 47-minute clean, 227 fetches: 226 of them placed
+  // the robot at cell 22280,22100 — the same cell every time — while the room
+  // outlines spanned 38-293 x 90-227. The underlying pose was exactly
+  // (1100, 1100) in every one, the same constant two other Q7s reported in
+  // August. The remaining fetches resolved a real room in the right order, so
+  // the robot DOES send a true pose sometimes; it just serves a placeholder in
+  // between, and those are the fetches that must not be counted as the robot
+  // being between rooms.
+  //
+  // The test is deliberately about distance rather than about the value 1100:
+  // a placeholder is a position further outside the map than the map is wide,
+  // which no real robot can be, and which stays true if Roborock picks a
+  // different constant tomorrow.
+  if (isOffTheMap(cell, head, outlineBounds)) {
+    return {
+      roomId: null,
+      reason: "pose-placeholder",
+      outlineCount,
+      cell,
+      outlineBounds,
+      head: { minX: head.minX, minY: head.minY, resolution },
+    };
+  }
+
   return {
     roomId: null,
     reason: "pose-outside-outlines",
     outlineCount,
     cell,
-    outlineBounds: outlineBoundingBox(chains),
+    outlineBounds,
     head: { minX: head.minX, minY: head.minY, resolution },
   };
 }
 
+/**
+ * Whether a cell is outside the map raster itself.
+ *
+ * The map's own `sizeX`/`sizeY` is the right yardstick and the outline
+ * bounding box is not: outlines cover rooms, while the raster covers
+ * everywhere the robot has ever been. A robot standing in a doorway, in a
+ * hallway nobody named, or against a wall the outlines do not reach is
+ * legitimately outside every outline and inside the map — that is a real miss
+ * and must keep counting as one. Being outside the raster is not a position
+ * at all; the robot cannot be somewhere it has never mapped.
+ *
+ * One raster width of slack on each side, because the transform can put a
+ * genuine edge case a little past the boundary and this must not swallow a
+ * real coordinate bug. The measured placeholder sat at cell 22280 on a map
+ * 500 cells wide — 44 times out — so the margin costs nothing.
+ *
+ * Falls back to the outline bounds when a header carries no size, which is
+ * the only case where there is nothing better to compare against.
+ *
+ * @param {{x: number, y: number}} cell
+ * @param {{minX: number, minY: number, resolution: number,
+ *          sizeX?: number, sizeY?: number}} head
+ * @param {{minX: number, minY: number, maxX: number, maxY: number} | null} outlineBounds
+ * @returns {boolean}
+ */
+function isOffTheMap(cell, head, outlineBounds) {
+  const sizeX = Number(head?.sizeX) || 0;
+  const sizeY = Number(head?.sizeY) || 0;
+
+  if (sizeX > 0 && sizeY > 0) {
+    return (
+      cell.x < -sizeX ||
+      cell.x > sizeX * 2 ||
+      cell.y < -sizeY ||
+      cell.y > sizeY * 2
+    );
+  }
+
+  if (!outlineBounds) {
+    return false;
+  }
+
+  const spanX = Math.max(outlineBounds.maxX - outlineBounds.minX, 1);
+  const spanY = Math.max(outlineBounds.maxY - outlineBounds.minY, 1);
+
+  return (
+    cell.x < outlineBounds.minX - spanX * 4 ||
+    cell.x > outlineBounds.maxX + spanX * 4 ||
+    cell.y < outlineBounds.minY - spanY * 4 ||
+    cell.y > outlineBounds.maxY + spanY * 4
+  );
+}
+
 /**
  * Bounding box of every room outline, in the same cell space the
  * point-in-polygon test uses.

package/roborockLib/lib/vacuum.js

@@ -567,17 +567,26 @@ class vacuum {
                   attribute
                 );
 
-              if (isKnownStatusAttribute) {
-                this.adapter.log.debug(
-                  `Skipping known get_status attribute without a Homebridge state object: ${attribute}. Model: ${this.robotModel}`
-                );
-              } else if (
+              // A known attribute is skipped in silence. The line that used
+              // to be written here dated from this library's ioBroker origins,
+              // where `getObjectAsync` returns a state object that exists;
+              // under Homebridge it never exists, so the branch fired for
+              // EVERY known attribute on EVERY poll and said only that the
+              // plugin is not ioBroker. Measured on three robots with debug
+              // on: fifty lines a minute, and the log ring — the thing you
+              // need when something real goes wrong — held ninety minutes.
+              //
+              // The distinction below is the part that carries information
+              // and it is untouched: an attribute nobody has mapped yet is
+              // still reported once, by name and value.
+              if (
+                !isKnownStatusAttribute &&
                 this.rememberUnmappedStatusAttribute(duid, attribute)
               ) {
                 newlyUnmappedAttributes.push(
                   `${attribute}=${describeStatusValue(deviceStatus[0][attribute])}`
                 );
-              } else {
+              } else if (!isKnownStatusAttribute) {
                 this.adapter.log.debug(
                   `Unmapped get_status attribute ${attribute}=${describeStatusValue(deviceStatus[0][attribute])} for ${describeDevice(this.adapter, duid)}; already reported, not repeating.`
                 );

package/roborockLib/roborockAPI.js

@@ -92,6 +92,12 @@ const B01_LIVE_ROOM_MISS_REASONS = {
     "the map payload carried no room outlines, so there was nothing to match the position against",
   "pose-outside-outlines":
     "the robot's position did not fall inside any known room outline (it may be between rooms, or the map may still be building)",
+  // Not a miss the user can do anything about, and not the robot being
+  // between rooms: the map payload carried a placeholder where the position
+  // should be. Measured at 226 of 227 fetches on a Q7 during a 47-minute
+  // clean, always the same cell. See describeLiveRoomResolution.
+  "pose-placeholder":
+    "the map payload carried a placeholder instead of the robot's position, so this fetch could not place it (the robot sends a real position only on some fetches)",
 };
 
 /**
@@ -4571,6 +4577,26 @@ class Roborock {
           // actually sees, so "no room yet" is distinguishable from "the
           // feature is broken" — and say WHICH of the four causes it was,
           // because they call for different fixes.
+          // A placeholder pose is not the robot failing to be in a room, so
+          // it does not join the count that says how long the robot has gone
+          // unplaced. Counting it produced "after 46 unresolved position(s)"
+          // for a robot that had been cleaning one room the whole time, which
+          // reads as a fault and is not one.
+          //
+          // It is said once per run at a level the user sees, with the numbers
+          // that make it diagnosable, and then held at debug. In the field
+          // that turns 226 info-and-debug lines per clean into one.
+          if (resolution2.reason === "pose-placeholder") {
+            const placeholderMessage = `Live room for ${this.describeDevice(duid)}: ${B01_LIVE_ROOM_MISS_REASONS[resolution2.reason]} (${resolution2.outlineCount} room outline(s) in the map${resolution2.cell ? `, position cell ${Math.round(resolution2.cell.x)},${Math.round(resolution2.cell.y)}` : ""}${describeOutlineBounds(resolution2)}).`;
+            if (!liveState.placeholderReported) {
+              liveState.placeholderReported = true;
+              this.log.info(placeholderMessage);
+            } else {
+              this.log.debug(placeholderMessage);
+            }
+            return liveState.current;
+          }
+
           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)}${describeRawMapFields(parsed)}).`;
@@ -4601,7 +4627,7 @@ class Roborock {
 
         if (!previous || previous.segmentId !== roomId) {
           this.log.info(
-            `Live room for ${this.describeDevice(duid)}: ${roomName} (${roomId})${previous ? ` — was ${previous.roomName} (${previous.segmentId})` : ""}${missedBeforeThis > 0 ? ` (after ${missedBeforeThis} unresolved position(s))` : ""}.`
+            `Live room for ${this.describeDevice(duid)}: ${roomName} (${roomId})${previous ? ` — was ${previous.roomName} (${previous.segmentId})` : ""}${missedBeforeThis > 0 ? ` (after ${missedBeforeThis} unresolved position(s))` : ""}${resolution2.cell ? ` [position cell ${Math.round(resolution2.cell.x)},${Math.round(resolution2.cell.y)}]` : ""}.`
           );
           const lastV1Status = this._b01StatusState?.get(duid)?.lastV1Status;
           if (this.deviceNotify && lastV1Status) {