homebridge-roborock-matter 3.31.0 → 3.32.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 3.32.0
+
+**The give-up register had never counted a single poll failure. Not one, in two releases that were built around it.**
+
+### What I shipped twice and never verified
+
+3.30.0 introduced a register that stops asking a robot a question it never answers. 3.31.0 routed three more polls into it and fixed how it attributed blame. Both releases described it — in the changelog, and in the log line you read — as the thing that ends the flood of repeated timeouts, naming the seven methods from #22 and #24 that motivated it.
+
+It could not have counted any of them. `pollParameter` decided the outcome from its own `try/catch`:
+
+```js
+try {
+  const answer = await vacuum.getParameter(duid, method);
+  this.noteMethodAnswered(duid, method); // ran on EVERY poll
+  return answer;
+} catch (error) {
+  this.noteMethodUnanswered(duid, method, error); // unreachable
+  throw error;
+}
+```
+
+`vacuum.getParameter` swallows its own errors. Its catch calls `catchError`, which only logs, and the function resolves `undefined`. So the catch here never ran. Every timeout looked like a success, and `noteMethodAnswered` **reset the counter on each failed poll**.
+
+Measured on the real classes before the fix: 20 consecutive timeouts produced **0 entries** in the register. And a robot that had somehow been left alone was told `answers get_room_mapping again; it is back in the normal poll cycle` on the retry that had just timed out.
+
+The only methods it ever governed were the three map requests, because those go through `sendRequest` directly rather than `getParameter`. Everything else — `get_room_mapping`, `get_multi_maps_list`, `get_consumable`, `get_carpet_mode`, `get_carpet_clean_mode`, `get_water_box_custom_mode`, `get_timer` — was untouched. 3.31.0's "three polls were bypassing the register" fix wired them to nothing.
+
+### The register now watches the wire
+
+A request is answered or it is not, and the only place that knows is the message layer. So that is where the register is fed from: `messageQueueHandler` reports a reply when one arrives and a timeout when one does not. `pollParameter` no longer guesses at the outcome — it just declares which requests it is entitled to skip.
+
+That declaration matters, because the message layer sees **every** request, including `get_status` and every command. A robot/method pair is counted only after a caller that can skip it has claimed it, so the two things this register must never touch cannot be reached by construction. There are tests that fire a hundred `get_status` timeouts and a hundred command timeouts and assert nothing closes.
+
+Measured after: 200 polls at a silent method send **6 requests**.
+
+### And the transport exclusion was dead code again
+
+3.30.0's version looked for `EAI_AGAIN`, `offline` and friends — words the timeout message never contains. 3.31.0 replaced it with a regex for `MQTT connection state: false`, and I wrote a checklist entry about building test fixtures from real strings. That regex cannot match either: a down link is rejected **earlier**, with a refusal that has no "timed out after" in it, so the timeout arm is only ever reached with the flag reading `true`. Two releases, two dead gates, two green tests built from strings the code cannot produce.
+
+The timeout now carries what it knows as data — `unansweredRequest` and `transportWasUp`, the latter read at **rejection** time rather than copied before the send, because a link that dies mid-flight is the entire case the exclusion exists for. The register reads the fields. No prose is parsed.
+
+### The measurement I hid behind a log level
+
+3.31.0 added a line for every discarded protocol-301 map frame, to answer why `get_map_v1` times out forever on a robot that answers everything else. I put it at **debug**, which is off by default. On my own server it produced nothing; a user in #24 went looking and found nothing. We both read that as evidence. It was not evidence — it was a log level.
+
+Discarded frames are now counted per robot, and the count rides along in the give-up message, at info level, where nobody has to know to go looking:
+
+```
+Stueetage has not answered get_map_v1 6 times in a row, so the plugin stops
+asking for about 6 hour(s)… No reply frames for this robot were received and
+discarded, so the reply is not arriving at all rather than being lost on this
+side.
+```
+
+or, if it is our fault:
+
+```
+…NOTE: 6 map reply frame(s) for this robot were received and then discarded by
+the plugin (addressed-elsewhere: 6), so the robot IS answering and this side is
+throwing it away. Please report this — it is a bug here, not on your robot.
+```
+
+The same figure is in the diagnostic report. Either way the question gets answered by a log you were going to send anyway.
+
+### Field notes from 3.31.0
+
+The give-up rule did fire correctly on my own a70: `get_map_v1`, 6 in a row, paused for 6 hours — where the same request used to fail 95 and 225 times. That part worked, because the map path was the one path the register could actually see.
+
+2045 tests, 14 of them new and all 14 red against 3.31.0.
+
 ## 3.31.0
 
 **Six bugs, three of them mine from last week. And the oldest unexplained failure in this project finally has an instrument pointed at 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. 2031 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. 2045 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
 
@@ -264,7 +264,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 2031 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 2045 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.31.0",
+  "version": "3.32.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/messageQueueHandler.js

@@ -191,6 +191,23 @@ function describeCloudSilence(adapter, duid, receiptsAtSend) {
  * @property {boolean} [cloudOnlyMode]
  */
 
+/**
+ * A request that was sent and drew no reply, carrying what the transport knew
+ * at the moment it gave up. The give-up register reads these fields instead of
+ * parsing the message text — twice now a prose-matching rule has turned out to
+ * be dead code against a string the plugin cannot produce.
+ *
+ * @param {string} message
+ * @param {boolean} transportWasUp whether the link was up AT REJECTION TIME
+ * @returns {Error & {unansweredRequest: boolean, transportWasUp: boolean}}
+ */
+function unansweredRequestError(message, transportWasUp) {
+  return Object.assign(new Error(message), {
+    unansweredRequest: true,
+    transportWasUp,
+  });
+}
+
 /**
  * @typedef {Object} MessageQueueAdapter
  * @property {RoborockConfig} [config]
@@ -208,6 +225,8 @@ function describeCloudSilence(adapter, duid, receiptsAtSend) {
  * @property {(duid: string, update: TransportDiagnosticsUpdate) => Promise<void>} updateTransportDiagnostics
  * @property {(duid: string) => Promise<boolean>} [ensureLocalConnection]
  * @property {(duid: string, method?: string) => Promise<void>} [noteLocalRequestTimedOut]
+ * @property {(duid: string, method: string) => void} [noteRequestAnswered]
+ * @property {(duid: string, method: string, error: unknown) => void} [noteRequestUnanswered]
  * @property {(duid: string) => number} [getCloudMessageReceiptCount] How many
  *   decoded MQTT messages have been attributed to this robot since startup.
  *   Optional so an adapter that cannot count them keeps the old timeout text.
@@ -541,11 +560,20 @@ class messageQueueHandler {
             this.adapter.pendingRequests.delete(messageID);
             this.adapter.localConnector.clearChunkBuffer(duid);
             if (useCloudConnection) {
-              reject(
-                new Error(
-                  `Cloud request with id ${messageID} with method ${method} timed out after ${timeoutSeconds} seconds. MQTT connection state: ${mqttConnectionState}${describeCloudSilence(this.adapter, duid, receiptsAtSend)}`
-                )
+              // The link state READ NOW, not the copy taken before the send.
+              // A link that died mid-flight is the entire case the give-up
+              // register's transport exclusion exists for, and both previous
+              // attempts at that exclusion were dead code because they read a
+              // value captured before the request even went out.
+              const transportWasUp = Boolean(
+                this.adapter.rr_mqtt_connector?.isConnected?.()
               );
+              const error = unansweredRequestError(
+                `Cloud request with id ${messageID} with method ${method} timed out after ${timeoutSeconds} seconds. MQTT connection state: ${transportWasUp}${describeCloudSilence(this.adapter, duid, receiptsAtSend)}`,
+                transportWasUp
+              );
+              this.adapter.noteRequestUnanswered?.(duid, method, error);
+              reject(error);
             } else {
               // A socket that keeps reporting itself connected while every
               // request dies of silence is not a transport worth retrying
@@ -556,11 +584,15 @@ class messageQueueHandler {
                   this.adapter.noteLocalRequestTimedOut(duid, method)
                 ).catch(() => {});
               }
-              reject(
-                new Error(
-                  `Local request with id ${messageID} with method ${method} timed out after ${timeoutSeconds} seconds Local connect state: ${localConnectionState}`
-                )
+              const transportWasUp = Boolean(
+                this.adapter.localConnector?.isConnected?.(duid)
+              );
+              const error = unansweredRequestError(
+                `Local request with id ${messageID} with method ${method} timed out after ${timeoutSeconds} seconds Local connect state: ${transportWasUp}`,
+                transportWasUp
               );
+              this.adapter.noteRequestUnanswered?.(duid, method, error);
+              reject(error);
             }
           }, requestTimeout);
 
@@ -571,7 +603,18 @@ class messageQueueHandler {
           // reply IS the result). It used to guess by comparing the result to
           // the string "ok", which silently never matched.
           this.adapter.pendingRequests.set(messageID, {
-            resolve,
+            // Wrapped so the give-up register learns of an answer HERE, in the
+            // one place that knows a reply arrived. Until 3.32.0 the register
+            // was told by `pollParameter`, whose try/catch never fired:
+            // `vacuum.getParameter` swallows its own errors (it calls
+            // catchError, which only logs) and resolves `undefined`. So every
+            // poll looked like a success, the failure branch was unreachable,
+            // and the register never counted a single one — including all
+            // seven methods in #22/#24 that it was built for.
+            resolve: (value) => {
+              this.adapter.noteRequestAnswered?.(duid, method);
+              resolve(value);
+            },
             reject,
             timeout,
             secure,

package/roborockLib/lib/roborock_mqtt_connector.js

@@ -51,6 +51,42 @@ let rriot;
 // silent map outage with no error anywhere.
 const photoBuffers = new Map();
 
+// How many protocol-301 frames have been discarded per robot, and why.
+//
+// 3.31.0 added a log line for each drop — at DEBUG level, which is off by
+// default. So the measurement that was meant to answer this project's oldest
+// question (why `get_map_v1` times out forever on a robot that answers
+// everything else) could never appear in a log anyone would send. That is the
+// same mistake as the silent `return` it replaced: the information existed
+// and nobody could reach it.
+//
+// Counting it instead means the number rides along in the give-up message and
+// the diagnostic report, both of which are INFO level and both of which users
+// already paste.
+const droppedFrames = new Map();
+
+function noteDroppedFrame(duid, reason) {
+  let entry = droppedFrames.get(duid);
+  if (!entry) {
+    entry = { total: 0, byReason: {} };
+    droppedFrames.set(duid, entry);
+  }
+  entry.total += 1;
+  entry.byReason[reason] = (entry.byReason[reason] || 0) + 1;
+  return entry;
+}
+
+/**
+ * Protocol-301 frames discarded for one robot, for the give-up message and
+ * the diagnostic report.
+ *
+ * @param {string} duid
+ * @returns {{total: number, byReason: Record<string, number>}}
+ */
+function describeDroppedFrames(duid) {
+  return droppedFrames.get(duid) || { total: 0, byReason: {} };
+}
+
 function photoBufferFor(duid) {
   let entry = photoBuffers.get(duid);
   if (!entry) {
@@ -564,6 +600,7 @@ class roborock_mqtt_connector {
               // Whether that IS the cause is not settled here — it is
               // measured, because from 3.31.0 the drop says so.
               if (!String(data2.endpoint || "").startsWith(endpoint)) {
+                noteDroppedFrame(duid, "addressed-elsewhere");
                 this.adapter.log.debug(
                   `Dropped a protocol 301 message for ${duid}: it is addressed to endpoint '${data2.endpoint}', and this plugin's endpoint is '${endpoint}'. The reply was received and decrypted but is not ours, so the request that is waiting will time out. If you are seeing map or live-room requests time out on a robot that answers everything else, this line is the reason — please report it.`
                 );
@@ -584,6 +621,7 @@ class roborock_mqtt_connector {
               // this.adapter.log.debug("raw 301: " + decrypted);
 
               if (!this.adapter.pendingRequests.has(data2.id)) {
+                noteDroppedFrame(duid, "no-request-waiting");
                 // The other silent drop on this path. An unsolicited map push
                 // lands here legitimately, but so does a reply whose id we
                 // failed to match — and the waiting request then times out
@@ -839,6 +877,7 @@ function resolveB01PendingResponse(adapter, duid, dps) {
 }
 
 module.exports = {
+  describeDroppedFrames,
   resolveB01PendingResponse,
   roborock_mqtt_connector,
   parseProtocol301Header,

package/roborockLib/lib/unansweredMethodBreaker.js

@@ -67,6 +67,28 @@ const COOLDOWN_MS = 6 * 60 * 60 * 1000;
  * @returns {boolean}
  */
 function isUnansweredRequest(error) {
+  // THE STRUCTURED ANSWER FIRST, because parsing prose has now been wrong
+  // twice in two releases.
+  //
+  // 3.30.0 excluded transport failures by looking for `EAI_AGAIN`, `offline`
+  // and friends — words the timeout message never contains. 3.31.0 replaced
+  // that with a regex for `MQTT connection state: false`, which cannot occur
+  // either: messageQueueHandler rejects a down link EARLIER, with a refusal
+  // that has no "timed out after" in it at all, so the timeout arm is only
+  // ever reached with the flag reading `true`. Both gates were dead code, and
+  // both had a green test built from a hand-written string the code cannot
+  // produce.
+  //
+  // So the timeout now carries what it knows as data. `transportWasUp` is
+  // read at REJECTION time, not at send time — a link that died mid-flight is
+  // the whole case the exclusion exists for.
+  if (error && typeof error === "object" && "unansweredRequest" in error) {
+    if (error.unansweredRequest !== true) {
+      return false;
+    }
+    return error.transportWasUp !== false;
+  }
+
   const message = error instanceof Error ? error.message : String(error ?? "");
   if (!/timed out after/i.test(message)) {
     return false;
@@ -118,6 +140,8 @@ class UnansweredMethodBreaker {
     this.now = options.now ?? (() => Date.now());
     /** @type {Map<string, {failures: number, openedAt: number, retryAt: number}>} */
     this.entries = new Map();
+    /** @type {Set<string>} pairs a skipping caller has claimed; see govern() */
+    this.governed = new Set();
   }
 
   /**
@@ -129,6 +153,37 @@ class UnansweredMethodBreaker {
     return `${duid}:${method}`;
   }
 
+  /**
+   * Declare that a request is one this register governs.
+   *
+   * WHY THIS EXISTS. From 3.32.0 the register is fed by the message layer —
+   * the only place that actually knows whether a request was answered — and
+   * that layer sees EVERY request, including `get_status` and every command.
+   * Counting those would break the promise this class is built on: the tile
+   * lives on `get_status`, and a button the user just pressed must always be
+   * sent.
+   *
+   * So a (robot, method) pair is counted only after the caller that CAN skip
+   * it has said so. `pollParameter` and the two live-room fetches call this
+   * before sending; nothing else does, so nothing else can ever be closed.
+   *
+   * @param {string} duid
+   * @param {string} method
+   * @returns {void}
+   */
+  govern(duid, method) {
+    this.governed.add(this.key(duid, method));
+  }
+
+  /**
+   * @param {string} duid
+   * @param {string} method
+   * @returns {boolean}
+   */
+  isGoverned(duid, method) {
+    return this.governed.has(this.key(duid, method));
+  }
+
   /**
    * Whether this method should be skipped right now.
    *
@@ -183,6 +238,10 @@ class UnansweredMethodBreaker {
    * @returns {{counted: boolean, failures: number, opened: boolean, retryInMs: number}}
    */
   recordFailure(duid, method, error) {
+    // Only requests a skipping caller has claimed. See govern().
+    if (!this.isGoverned(duid, method)) {
+      return { counted: false, failures: 0, opened: false, retryInMs: 0 };
+    }
     if (!isUnansweredRequest(error)) {
       return { counted: false, failures: 0, opened: false, retryInMs: 0 };
     }

package/roborockLib/roborockAPI.js

@@ -26,6 +26,7 @@ const {
   parseCloudSceneSchedules,
 } = require("./lib/parseCloudSceneSchedules");
 const b01Q7Adapter = require("./lib/b01Q7Adapter");
+const { describeDroppedFrames } = require("./lib/roborock_mqtt_connector");
 const { UnansweredMethodBreaker } = require("./lib/unansweredMethodBreaker");
 
 // v1 states in which the robot is actively doing something and state
@@ -3365,14 +3366,48 @@ class Roborock {
       return undefined;
     }
 
-    try {
-      const answer = await vacuum.getParameter(duid, method);
-      this.noteMethodAnswered(duid, method);
-      return answer;
-    } catch (error) {
-      this.noteMethodUnanswered(duid, method, error);
-      throw error;
-    }
+    // Claim this request, then just send it.
+    //
+    // Until 3.32.0 this wrapped the call in a try/catch and reported the
+    // outcome itself. That never worked: `vacuum.getParameter` swallows its
+    // own errors — its catch calls `catchError`, which only logs — and
+    // resolves `undefined`. So the catch here was unreachable, every timeout
+    // looked like a success, and `noteMethodAnswered` actively RESET the
+    // counter on each failed poll. Measured: 20 consecutive timeouts produced
+    // 0 entries in the register, and a robot that had finally been left alone
+    // was told "answers get_room_mapping again" on the retry that timed out.
+    //
+    // The register is now fed by messageQueueHandler, the only place that
+    // knows whether a reply arrived. All this has to do is say which requests
+    // it is entitled to skip.
+    this.unansweredMethods.govern(duid, method);
+    return vacuum.getParameter(duid, method);
+  }
+
+  /**
+   * The message layer saw a reply. Called for EVERY request, including
+   * `get_status` and every command — the register ignores any pair no
+   * skipping caller has claimed with `govern()`, so those can never be closed.
+   *
+   * @param {string} duid
+   * @param {string} method
+   * @returns {void}
+   */
+  noteRequestAnswered(duid, method) {
+    this.noteMethodAnswered(duid, method);
+  }
+
+  /**
+   * The message layer saw a request die on its timer. Same filtering: only a
+   * claimed pair is counted.
+   *
+   * @param {string} duid
+   * @param {string} method
+   * @param {unknown} error
+   * @returns {void}
+   */
+  noteRequestUnanswered(duid, method, error) {
+    this.noteMethodUnanswered(duid, method, error);
   }
 
   /**
@@ -3420,9 +3455,37 @@ class Roborock {
           failures: entry.failures,
           retryInMinutes: Math.round(entry.retryInMs / 60000),
         })),
+      // Same question, in the report people paste: was the reply discarded
+      // here, or did it never arrive?
+      discardedReplyFrames: describeDroppedFrames(duid),
     });
+    // THE DIAGNOSIS, IN THE LINE PEOPLE ALREADY PASTE.
+    //
+    // 3.31.0 put the answer to "is the robot silent, or are we discarding its
+    // reply?" behind a DEBUG log line. Debug is off by default, so the
+    // measurement was invisible — on my own server it produced exactly
+    // nothing, and a user in #24 went looking for it and found nothing
+    // either. Both of us read that as evidence. It was not evidence; it was a
+    // log level.
+    //
+    // A map reply arrives as a protocol-301 frame, and a frame this plugin
+    // discards leaves the request to die on its timer — indistinguishable
+    // from a robot that never answered. So say which one it was, here, at
+    // info level, where the number cannot be missed.
+    const dropped = describeDroppedFrames(duid);
+    const verdict =
+      dropped.total > 0
+        ? ` NOTE: ${dropped.total} map reply frame(s) for this robot were received and then discarded by the plugin (${Object.entries(
+            dropped.byReason
+          )
+            .map(([reason, count]) => `${reason}: ${count}`)
+            .join(
+              ", "
+            )}), so the robot IS answering and this side is throwing it away. Please report this — it is a bug here, not on your robot.`
+        : " No reply frames for this robot were received and discarded, so the reply is not arriving at all rather than being lost on this side.";
+
     this.log.info(
-      `${this.describeDevice(duid)} has not answered ${method} ${outcome.failures} times in a row, so the plugin stops asking for about ${hours} hour(s) and then tries once more. Everything else about this robot is unaffected, and one answer puts it straight back in the normal cycle. This is the robot or the Roborock cloud declining to reply, not a connection failure — those are reported separately.`
+      `${this.describeDevice(duid)} has not answered ${method} ${outcome.failures} times in a row, so the plugin stops asking for about ${hours} hour(s) and then tries once more. Everything else about this robot is unaffected, and one answer puts it straight back in the normal cycle. This is the robot or the Roborock cloud declining to reply, not a connection failure — those are reported separately.${verdict}`
     );
     return true;
   }
@@ -6110,6 +6173,8 @@ class Roborock {
     ) {
       return liveState.current;
     }
+    this.unansweredMethods.govern(duid, "get_map_list");
+    this.unansweredMethods.govern(duid, b01Q7Adapter.B01_MAP_UPLOAD_METHOD);
     liveState.lastAttemptAt = Date.now();
 
     liveState.inflight = (async () => {
@@ -6436,6 +6501,7 @@ class Roborock {
     if (this.unansweredMethods.shouldSkip(duid, "get_map_v1")) {
       return liveState.current;
     }
+    this.unansweredMethods.govern(duid, "get_map_v1");
     liveState.lastAttemptAt = Date.now();
 
     liveState.inflight = (async () => {