homebridge-roborock-matter 3.30.0 → 3.32.0

package/CHANGELOG.md

@@ -1,5 +1,146 @@
 # 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.**
+
+### The give-up rule tripped on network trouble — the exact thing it promised not to do
+
+3.30.0 added a register that stops asking a robot a request it never answers, and said, in the source and in the line the user reads: it never trips on a transport error, because those come back on their own.
+
+It did. The exclusion was dead code.
+
+`messageQueueHandler` builds its two timeout messages with the connection state interpolated as a **boolean**:
+
+```
+… timed out after 10 seconds. MQTT connection state: false
+… timed out after 10 seconds Local connect state: false
+```
+
+The rule looked for `EAI_AGAIN`, `ENOTFOUND`, `ECONNREFUSED`, `ECONNRESET`, "not connected", "offline" — every one of which belongs to an error that never contains "timed out after" in the first place, and so had already been excluded a line earlier. The second gate had nothing left to exclude.
+
+A four-minute network blip during a clean is 24 failed live-room polls at 10-second intervals. Six is all it takes. Live-room tracking then died for six hours, under a log line telling you this was not a connection failure.
+
+It now reads the boolean, and also stands down when the cloud timeout reports that nothing is coming back over MQTT at all. The tests use the exact strings the plugin emits — 3.30.0's used hand-written messages the code cannot produce, which is precisely why they passed against a broken rule.
+
+### A robot was punished for a request it answered perfectly
+
+The B01/Q7 live-room fetch is two requests: `get_map_list` (cheap) and `service.upload_by_mapid` (the heavy map payload, with its own 20-second timeout). 3.30.0 wrapped both in one try, acknowledged `get_map_list` only after the second had been fetched, decoded and cached, and recorded every failure — including the upload leg's own timeout — against `get_map_list`.
+
+So a robot answering `get_map_list` in 200 ms every time, with a silent upload channel, had the wrong counter climb to six. The diagnostics then named `get_map_list`: the one channel that was working.
+
+Each leg is now counted on its own.
+
+### The heartbeat stopped healing a write that never landed
+
+Suppressing an unchanged `operationalState` is what stopped the tank notification repeating every 2 minutes. It also broke the safety net the whole publish-dedup design rests on.
+
+A cluster write can be rejected by matter.js **after** `updateAccessoryState` has resolved — this codebase has documented that for months: `#assertCurrentPhase` throws, Homebridge swallows the throw, and the controller keeps what it last accepted. From 3.30.0, one such rejection made the plugin believe a value was published that never was, and nothing wrote that attribute again. A permanently stale tile, recoverable only by the robot reaching a different state, or a restart. Before 3.30.0 the heartbeat repaired it inside a minute.
+
+A forced heartbeat now re-asserts `operationalState` once every 10 cycles — about once every 10 minutes. Measured: 6 re-assertions an hour instead of 60, the stale tile heals within 10 minutes, and the notification stays gone.
+
+### A map reply can be thrown away in silence — and now it says so
+
+This is the one I care most about.
+
+`get_map_v1` on a classic robot times out after 10 seconds, forever, while the same robot answers everything else. 95 times in a row on my own a70, 225 twelve days earlier, 40 on the a75 in #9. Nobody has ever been able to say why.
+
+Map replies do not come back on the ordinary reply path — they arrive as protocol 301 frames. The 301 handler had several ways to drop one, every one of them a bare `return`. No log, no counter, nothing. A dropped 301 leaves the request to die on its timer, which looks **exactly** like a robot that never answered. There was nothing to diagnose it with.
+
+One of those drops was also wrong:
+
+```js
+if (!endpoint.startsWith(data2.endpoint)) return;
+```
+
+`endpoint` is our own 8-character key. `data2.endpoint` is a 15-byte wire field with only _trailing_ nulls stripped. python-roborock, the reference implementation, compares it the other way round — `received.startswith(ours)`. As written, a robot that echoes our 8 characters followed by anything that is not a trailing null leaves a longer string, and an 8-character string can never `startsWith` a longer one. It failed closed, on a reply addressed to us, without a word.
+
+The comparison now matches the reference, and **every** 301 drop explains itself and names the robot. I am not claiming this is the cause of the a70's timeouts. I am saying that from this release, if it is, the log says so.
+
+### One robot's unfinished photo could swallow every other robot's map
+
+`photoGzipChunks` and `photoChunkID` were module-level variables shared by every robot on the account, cleared only when a photo transfer **completed**. A robot going offline between chunk 1 and chunk 2 left the id set forever — and from then on every 301 frame with `seq == 2`, from any robot, was swallowed into that stale buffer instead of being decoded as a map reply. A permanent, silent map outage on a multi-robot account, with no error anywhere.
+
+The buffer is now per robot, and one whose request is no longer waiting is discarded.
+
+### Smaller things
+
+- **A robot that comes back online starts with clean counters.** `forgetDevice` existed since 3.30.0 and was never called once. A robot offline for hours kept the counts it collected while unreachable, and because the rule deliberately keeps the counter when it lets one request through, a single probe timing out during the reconnect closed the method for another six hours.
+- **Three polls were bypassing the register entirely** — `get_multi_maps_list` and `get_room_mapping`, two of the seven methods named in the 647 suppressed timeouts that motivated the rule. The test that was supposed to catch this asserted "exactly 3 call sites", a number that silently excluded them. It now asserts the rule instead: no optional poll reaches the robot except through the register.
+- **`cleaning_info` is printed in full while a robot is cleaning.** Not a feature — a measurement. Every status poll already receives this object and throws it away, and it is documented as carrying `{target_segment_id, segment_id, …}`. If `segment_id` tracks the room, live-room tracking on classic robots needs no map at all, which would route around the timeout above entirely. One clean answers it.
+
+2031 tests, 33 of them new.
+
 ## 3.30.0
 
 **The water-tank notification that repeated every two minutes was us. Three people reported it, and for three releases this project told them it was Apple.**

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. 1998 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 1998 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/dist/matter_vacuum_accessory.js

@@ -219,6 +219,16 @@ const DOCK_ERROR_CLEAN_WATER_TANK_EMPTY = 38;
  * writeOperationalStateCluster().
  */
 const OPERATIONAL_STATE_CLUSTER = "rvcOperationalState";
+/**
+ * How many forced publishes (heartbeats) may pass before `operationalState`
+ * is re-written even though it has not changed.
+ *
+ * 10 heartbeats is about 10 minutes. That restores the self-healing the
+ * heartbeat provided before 3.30.0, at a rate far too low for the
+ * wipe/raise pair matter.js 0.17.9 performs to become a notification anyone
+ * notices — the fault cycle needed one every single minute.
+ */
+const RESYNC_OPERATIONAL_STATE_EVERY_FORCED_WRITES = 10;
 const RVC_OPERATIONAL_ERROR = {
     NO_ERROR: 0,
     UNABLE_TO_START_OR_RESUME: 1,
@@ -665,6 +675,10 @@ class RoborockMatterVacuumAccessory {
         // dropped on failure, and (c) the heartbeat performs a forced full publish
         // every cycle, self-healing any residual divergence within a minute.
         this.lastPublishedClusterJson = new Map();
+        // How many forced publishes in a row have skipped operationalState. See
+        // writeOperationalStateCluster(): without this, a write matter.js rejects
+        // silently can never come back.
+        this.forcedWritesSinceOperationalState = 0;
         this.serviceAreaProgress = [];
         this.selectedCleanMode = CLEAN_MODE_VACUUM;
         this.selectedCleanModeNeedsApply = false;
@@ -1218,6 +1232,7 @@ class RoborockMatterVacuumAccessory {
         this.lastPublishedClusterJson.clear();
         this.publishedOperationalState = undefined;
         this.publishedOperationalError = undefined;
+        this.forcedWritesSinceOperationalState = 0;
         // …and nothing has been stated about it either, so the evidence line is
         // restated for the new node instead of being suppressed as unchanged.
         this.lastLoggedMatterPublishLine = null;
@@ -1770,13 +1785,41 @@ class RoborockMatterVacuumAccessory {
      * the store really was cleared); clearing and re-raising the tank still
      * produce exactly one event each.
      */
-    async writeOperationalStateCluster(matter, attributes) {
+    async writeOperationalStateCluster(matter, attributes, options = {}) {
         const { operationalState, operationalError, ...rest } = attributes;
         const first = { ...rest };
-        const stateChanged = operationalState !== undefined &&
+        let stateChanged = operationalState !== undefined &&
             operationalState !== this.publishedOperationalState;
+        // THE HOLE 3.30.0 LEFT, AND WHY IT NEEDED CLOSING.
+        //
+        // Suppressing an unchanged `operationalState` is what stops the tank
+        // fault being cleared and re-raised every minute. But the whole dedup
+        // design rests on the heartbeat being a forced full write that self-heals
+        // any divergence within a minute — and a cluster write can be rejected by
+        // matter.js AFTER `updateAccessoryState` has already resolved. This file
+        // documents that elsewhere: `OperationalStateServer.#assertCurrentPhase`
+        // throws, and Homebridge swallows the throw, so the whole cluster write
+        // is silently rejected and the controller keeps what it last accepted.
+        //
+        // Believing such a write landed and then never writing that attribute
+        // again turns a one-off rejection into a permanently stale tile,
+        // recoverable only by the robot reaching a different state or a restart.
+        // Before 3.30.0 the heartbeat repaired it inside a minute.
+        //
+        // So: never on an ordinary publish, but a forced write re-asserts it once
+        // every RESYNC_OPERATIONAL_STATE_EVERY_FORCED_WRITES heartbeats.
+        if (!stateChanged &&
+            options.force === true &&
+            operationalState !== undefined) {
+            this.forcedWritesSinceOperationalState += 1;
+            if (this.forcedWritesSinceOperationalState >=
+                RESYNC_OPERATIONAL_STATE_EVERY_FORCED_WRITES) {
+                stateChanged = true;
+            }
+        }
         if (stateChanged) {
             first.operationalState = operationalState;
+            this.forcedWritesSinceOperationalState = 0;
         }
         if (Object.keys(first).length > 0) {
             await matter.updateAccessoryState(this.accessory.UUID, OPERATIONAL_STATE_CLUSTER, first);
@@ -1802,7 +1845,7 @@ class RoborockMatterVacuumAccessory {
         await matter.updateAccessoryState(this.accessory.UUID, OPERATIONAL_STATE_CLUSTER, { operationalError });
         this.publishedOperationalError = errorStateId;
     }
-    async updateMatterState(partialClusters, reason = "state update") {
+    async updateMatterState(partialClusters, reason = "state update", options = {}) {
         if (!this.registered) {
             return false;
         }
@@ -1829,7 +1872,9 @@ class RoborockMatterVacuumAccessory {
             await Promise.all(clusterEntries.map(async ([cluster, attributes]) => {
                 try {
                     if (cluster === OPERATIONAL_STATE_CLUSTER) {
-                        await this.writeOperationalStateCluster(matter, attributes);
+                        await this.writeOperationalStateCluster(matter, attributes, {
+                            force: options.force === true,
+                        });
                     }
                     else {
                         await matter.updateAccessoryState(this.accessory.UUID, cluster, attributes);
@@ -1846,6 +1891,7 @@ class RoborockMatterVacuumAccessory {
                         // re-assert them.
                         this.publishedOperationalState = undefined;
                         this.publishedOperationalError = undefined;
+                        this.forcedWritesSinceOperationalState = 0;
                     }
                     failures.push(error);
                     this.platform.log.debug(`Matter publish for cluster ${cluster} on ${this.accessory.UUID} failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -1944,7 +1990,12 @@ class RoborockMatterVacuumAccessory {
                 },
             }, "Battery resync nudge");
         }
-        const updated = await this.updateMatterState(clusters, reason);
+        // `force` is carried down so writeOperationalStateCluster can tell a
+        // heartbeat from an ordinary publish; it is the only cluster for which
+        // the distinction still means anything.
+        const updated = await this.updateMatterState(clusters, reason, {
+            force: options.force === true,
+        });
         if (updated) {
             this.logMatterPublishIfChanged(snapshot, reason);
         }