homebridge-roborock-matter 3.4.7 → 3.4.9

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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.
+
+On a v1 robot the difference between "Vacuum" and "Vacuum and mop" **is** the water-box mode: choosing Vacuum sends water-box OFF. Fan power only picks a suction level within the chosen mode. The prep sequence sent fan power first and, if that command timed out, returned — so the water command was never sent at all. In his log, `set_custom_mode` timed out after two seconds, `set_water_box_custom_mode` never appeared, and the robot kept the mopping setting it already had from the Roborock app. A cosmetic command that did not answer in time cancelled the one carrying the user's actual choice.
+
+- **The water command now goes out first, and no command in the sequence is cancelled by another's failure.** Dropping the early return cannot delay the start: the caller already races the whole prep against its own timeout, so the early return was buying latency protection that was paid for one level up.
+- **A partial apply is now announced at warn level**, naming the robot and what was not confirmed. It was a debug line before, which meant that on a default log level the robot simply did the wrong job in silence while the Matter tile reported the mode that had been selected. That mismatch took two rounds of #8 to pin down.
+- **The rule is enumerated over the sequence, not over the two commands in it today:** no clean-mode prep command may return out of the middle of the sequence. A third setting added later is covered by construction.
+
 ## 3.4.7
 
 **The diagnostic report told Q7 owners their robot had tried to reach the LAN and failed. It never tried.** Following [#7](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/7), jawnlydon unpaired his robot from Apple Home, uninstalled the plugin, reinstalled it and paired fresh — and his report still read `markedRemote: true`, `remoteReason: marked-remote-after-connect-failure`, `connectionStatus: Cloud fallback`, "usually because LAN TCP was not connected at that moment". His `roborock.vacuum.sc05` speaks the B01 protocol, which has no LAN request surface at all: the plugin marks these robots cloud-only at startup precisely so it never opens a local socket to them. Every line above described a network fault that could not occur, and he spent an evening chasing it.

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.7",
+  "version": "3.4.9",
   "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

@@ -504,7 +504,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 +543,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,34 @@ 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}`;
+}
+
 const B01_STATUS_TICK_MS = 15000;
 const B01_STATUS_FORCED_GAP_MS = 1500;
 const B01_STATUS_ACTIVE_GAP_MS = 12000;
@@ -2355,6 +2383,49 @@ class Roborock {
       return;
     }
 
+    // The water command goes first, and no failure below cancels a later
+    // command.
+    //
+    // On a v1 robot the difference between "Vacuum" and "Vacuum and mop" IS
+    // the water-box mode: selecting Vacuum sends water-box OFF. Fan power is a
+    // suction level *within* the chosen mode. The fan command used to run
+    // first and, on timeout, return — skipping the water command entirely. So
+    // skmzwanke selected Vacuum in Apple Home, the fan command timed out after
+    // two seconds, the water command was never sent, and his Saros 10 ran a
+    // vacuum-and-mop over the room he had asked to be vacuumed (#8). A
+    // cosmetic command that did not answer in time cancelled the one that
+    // carried the user's actual choice.
+    //
+    // Dropping the early return cannot run the start command late: the caller
+    // races this whole sequence against its own prep timeout, which is what
+    // bounds the delay. The early return was buying latency protection that
+    // was already paid for one level up.
+    const failedCommands = [];
+
+    if (Number.isInteger(settings?.waterBoxMode)) {
+      const waterCommands = this.getMatterWaterModeCommandCandidates(duid);
+
+      if (waterCommands.length === 0) {
+        this.log.debug(
+          `Matter clean mode requested water mode ${settings.waterBoxMode} for ${duid}, but no supported Roborock water command was detected.`
+        );
+      } else {
+        try {
+          await this.runFirstMatterSettingCommand(
+            duid,
+            waterCommands,
+            settings.waterBoxMode,
+            commandOptions
+          );
+        } catch (error) {
+          failedCommands.push("water mode");
+          this.log.debug(
+            `Matter clean mode water commands failed for ${duid}; continuing with start command. ${error.message || error}`
+          );
+        }
+      }
+    }
+
     if (
       Number.isInteger(settings?.fanPower) &&
       this.getMatterCleanModeCapabilities(duid).canControlFanPower
@@ -2372,40 +2443,21 @@ class Roborock {
           "set_custom_mode",
           error
         );
-        if (this.isMatterSettingTimeoutError(error)) {
-          this.log.debug(
-            `Matter clean mode fan command timed out for ${duid}; skipping remaining clean-mode prep and continuing with start command. ${error.message || error}`
-          );
-          return;
-        }
+        failedCommands.push("suction level");
         this.log.debug(
           `Matter clean mode fan command failed for ${duid}; continuing with start command. ${error.message || error}`
         );
       }
     }
 
-    if (!Number.isInteger(settings?.waterBoxMode)) {
-      return;
-    }
-
-    const waterCommands = this.getMatterWaterModeCommandCandidates(duid);
-    if (waterCommands.length === 0) {
-      this.log.debug(
-        `Matter clean mode requested water mode ${settings.waterBoxMode} for ${duid}, but no supported Roborock water command was detected.`
-      );
-      return;
-    }
-
-    try {
-      await this.runFirstMatterSettingCommand(
-        duid,
-        waterCommands,
-        settings.waterBoxMode,
-        commandOptions
-      );
-    } catch (error) {
-      this.log.debug(
-        `Matter clean mode water commands failed for ${duid}; continuing with start command. ${error.message || error}`
+    // At warn level on purpose. The clean is about to start and the Matter
+    // tile will report the mode the user selected, so a silent partial apply
+    // leaves the tile stating something the robot is not doing. That mismatch
+    // is exactly what took two rounds of #8 to pin down, and the log is where
+    // the next person will look.
+    if (failedCommands.length > 0) {
+      this.log.warn(
+        `Roborock did not confirm the ${failedCommands.join(" and ")} for ${this.describeDevice(duid)} before starting; the robot may keep its previous settings for this run, so the clean may not match the mode selected in your controller.`
       );
     }
   }
@@ -2521,11 +2573,6 @@ class Roborock {
     ].some((pattern) => message.includes(pattern));
   }
 
-  isMatterSettingTimeoutError(error) {
-    const message = `${error?.message || error || ""}`.toLowerCase();
-    return message.includes("request") && message.includes("timed out after");
-  }
-
   /**
    * Self-healing capability detection for periodic poll commands: once a
    * robot definitively answers a request with an "unsupported"-class error,
@@ -4272,7 +4319,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)}).`;
           if (liveState.unresolvedPoseCount % 5 === 0) {
             this.log.info(message);
           } else {