homebridge-roborock-matter 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 3.2.0
+
+Field feedback on the Q7 series: the live room in Apple Home lagged badly behind the robot. One run took 90 seconds to name the first room; another took seven minutes.
+
+- **The first room of a run now appears as soon as the robot is seen cleaning.** Two throttles were stacking. The status poll backed off to 45 seconds while the robot looked idle, so a clean started from the Roborock app or a schedule was invisible for up to that long; then the live-room map fetch applied its own 20-second gap on top, counted from the last attempt rather than from the start of the run. The idle poll is now 25 seconds, the map gap is 10 seconds, and the transition from idle to cleaning clears the gap so the first fetch goes out immediately. Steady-state pacing during a run is unchanged in spirit — the map payload is still an order of magnitude heavier than a status read and is still paced deliberately.
+- **A robot that cannot place itself on the map now says so.** When the robot's position doesn't fall inside any known room outline, the plugin used to return silently at debug level. That is the most likely explanation for a run going minutes without a room — in the field a Q7 spent seven minutes doing exactly this — and it was indistinguishable from the feature being broken. Repeated misses are now reported at a level you can actually see, with a count.
+
+## 3.1.1
+
+- **The Apple Home Features checkbox still said "Returning status".** 3.1.0 renamed the setting in the config schema but not in the plugin's own settings UI, which is the one most people actually see — so the first person to install it reasonably wondered whether the update had applied at all. Both now read **Dock & Returning status**, and the description spells out that Emptying and Washing only appear while the dock is genuinely doing that, and that mop drying has no Matter equivalent.
+
 ## 3.1.0
 
 Driven by two open model reports, plus the parts of the 3.0.2 audit that were too large to rush. Nothing here requires re-pairing unless you turn on the dock statuses below.

package/homebridge-ui/public/index.html

@@ -206,11 +206,15 @@
     <label class="checkbox">
       <input id="enable-matter-extended-states" type="checkbox" />
       <span>
-        Returning status
+        Dock &amp; Returning status
         <small
-          >Shows the extended Matter Returning state while the robot heads back
-          to the dock. Off by default for maximum Apple Home
-          compatibility.</small
+          >Shows the extended Matter states: Returning to the dock, Emptying the
+          dust bin, Washing the mop, and Updating maps. Requires removing and
+          re-pairing the robot in Apple Home once. Which of them Apple Home
+          draws is Apple's decision, and Emptying/Washing only appear while the
+          dock is actually doing that. Mop drying has no equivalent in the
+          Matter vacuum specification, so it cannot be reported. Off by default
+          for maximum Apple Home compatibility.</small
         >
       </span>
     </label>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "3.1.0",
+  "version": "3.2.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/roborockAPI.js

@@ -39,8 +39,11 @@ const B01_LIVE_ROOM_CLEAR_V1_STATES = new Set([3, 8]);
 
 // Minimum gap between live-room map fetch attempts while cleaning. The map
 // payload is an order of magnitude heavier than get_status, so it rides a
-// slower cadence than the ~12s active status polls.
-const B01_LIVE_ROOM_MIN_FETCH_GAP_MS = 20000;
+// slower cadence than the active status polls — but 20s meant a robot could
+// walk through a whole small room before Apple Home named it, which is the
+// opposite of what a "live" room display is for. 10s keeps the map traffic
+// modest while making the room track the robot closely enough to be useful.
+const B01_LIVE_ROOM_MIN_FETCH_GAP_MS = 10000;
 
 // Scheduler granularity for the classic (v1-protocol) status refresh. The
 // refresh itself is throttled per robot inside vacuum.getParameter, so this
@@ -3605,7 +3608,8 @@ class Roborock {
     //
     // The 1-second poll tick relies on getParameter's internal throttling for
     // classic robots; this path must throttle itself or every tick becomes a
-    // cloud request. Periodic refreshes run at most every 45s, forced
+    // cloud request. Periodic refreshes are paced by the adaptive cadence
+    // below, forced
     // refreshes (post-command, robot pushes) at most every 1.5s, and
     // concurrent callers share one in-flight request.
     if (!this._b01StatusState) {
@@ -3630,9 +3634,14 @@ class Roborock {
     // Adaptive cadence: while the robot is actively working (cleaning,
     // returning, docking) every 15s loop tick is allowed through so state
     // transitions reach Matter controllers within seconds; at rest the
-    // conservative 45s cloud cadence applies.
+    // conservative cadence below applies.
     const isActive = B01_ACTIVE_V1_STATES.has(refreshState.lastKnownV1State);
-    const minimumGapMs = options.force ? 1500 : isActive ? 12000 : 45000;
+    // 45s while idle was the dominant part of the delay before a run showed
+    // up at all: a clean started from the Roborock app or a schedule is
+    // invisible to the plugin until the next poll gets through. 25s halves
+    // that worst case for one extra request per robot per minute while
+    // parked, which is negligible next to the active cadence.
+    const minimumGapMs = options.force ? 1500 : isActive ? 12000 : 25000;
     if (Date.now() - refreshState.lastAttemptAt < minimumGapMs) {
       return null;
     }
@@ -3646,6 +3655,23 @@ class Roborock {
           []
         );
         const v1Status = b01Q7Adapter.mapStatusToV1(data);
+        // A run that has just started is the moment the user is watching, and
+        // it was also the slowest: the live-room fetch below rides its own
+        // throttle, counted from the last attempt, so the first room of a run
+        // could wait a further gap on top of the poll that noticed the robot
+        // at all. Clearing the stamp on the idle -> active transition makes
+        // that first fetch immediate; the throttle still paces every fetch
+        // after it.
+        const wasFetching = B01_LIVE_ROOM_FETCH_V1_STATES.has(
+          refreshState.lastKnownV1State
+        );
+        const isFetching = B01_LIVE_ROOM_FETCH_V1_STATES.has(v1Status.state);
+        if (isFetching && !wasFetching) {
+          const liveState = this._b01LiveRoomState?.get(duid);
+          if (liveState) {
+            liveState.lastAttemptAt = 0;
+          }
+        }
         refreshState.lastKnownV1State = v1Status.state;
         refreshState.lastV1Status = v1Status;
 
@@ -3970,11 +3996,24 @@ class Roborock {
         liveState.consecutiveFailures = 0;
 
         if (roomId === null) {
-          this.log.debug(
-            `Live room for ${duid}: robot pose is outside every room outline (or pose/geometry missing from the map payload).`
-          );
+          // Debug-only used to make this invisible, and it is the single most
+          // likely reason a run goes minutes without naming a room: in the
+          // field a Q7 took 7 minutes to report its first room while every
+          // attempt in between resolved to nothing and said so only at debug
+          // level. Count the misses and say something at a level the user
+          // actually sees, so "no room yet" is distinguishable from "the
+          // feature is broken".
+          liveState.unresolvedPoseCount =
+            (liveState.unresolvedPoseCount || 0) + 1;
+          const message = `Live room for ${duid}: the robot's position did not fall inside any known room outline (attempt ${liveState.unresolvedPoseCount} this run). The map may still be building, or the robot may be between rooms.`;
+          if (liveState.unresolvedPoseCount % 5 === 0) {
+            this.log.info(message);
+          } else {
+            this.log.debug(message);
+          }
           return liveState.current;
         }
+        liveState.unresolvedPoseCount = 0;
 
         const roomName =
           parsed.rooms.find((room) => room.roomId === roomId)?.roomName ||