homebridge-roborock-matter 3.36.0 → 3.38.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 3.38.0
+
+**Two log lines that could not tell two causes apart, and one of them was accusing this plugin of a bug that was not there.**
+
+Nothing about how the plugin talks to a robot changes in this release. What changes is what it says when something fails, in the two places where the sentence it printed was the reason a diagnosis stalled.
+
+### "Please report this — it is a bug here" was wrong (#28)
+
+[@CooperCGN](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/28)'s log says, about his S8 Pro Ultra:
+
+> NOTE: 30 map reply frame(s) for this robot were received and then discarded by the plugin (addressed-elsewhere: 30), so the robot IS answering and this side is throwing it away. Please report this — it is a bug here, not on your robot.
+
+It is not a bug here. `addressed-elsewhere` means the protocol-301 frame carried a different controller's endpoint, and the endpoint identifies a **controller on the account**, not this plugin: the Roborock app open on a phone, a second Homebridge, a voice assistant skill each have their own, and all of them share the robot's MQTT topic. Their replies reach this handler and are discarded, which is correct — they were never ours. His 30 frames arrived while a scheduled clean was being watched in the app.
+
+One case genuinely is ours: our own endpoint being wrong. It is told apart by a measurement the counter was missing — the frames that **were** addressed to us. If the key were wrong, nothing would ever be, so one accepted frame acquits it and convicts the other controller instead.
+
+The give-up line now distinguishes three outcomes instead of asserting one:
+
+- Frames addressed to this plugin and still discarded → unchanged; that is a bug here and still says so.
+- Frames for another controller, with frames of ours accepted → named as another controller's, with the Roborock app given as the usual cause, and no bug report asked for.
+- Frames for another controller with **nothing** ever accepted → that is the real bug's shape, and the line now points at the account key rather than at the robot.
+
+`accepted` rides along in the diagnostic report's `discardedReplyFrames`, so the next report settles it without a round trip.
+
+### A refused room selection now says what it refused (#24)
+
+[@Marrand](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/24) can add rooms one at a time and the selection holds; selecting all 8 reverts it to the 2 rooms from an earlier clean, repeatably. The only log line covering it read:
+
+> Matter service area selection request for S8: none.
+
+Three different causes print that: the controller really did send an empty list, the controller sent 8 ids and none of them could be read, or the set spanned 2 Roborock maps and was refused — and a refusal **is** a revert, because a controller that gets `InvalidSet` keeps the selection it last had accepted. At one run a week, that is a week per guess.
+
+- The request line now names what arrived as well as what was understood: no list, an empty list, or _n_ entries of which _m_ could not be read as an area id.
+- The multi-map refusal names the maps and the areas, and says in words that the selection is refused rather than cleared, so the controller will keep showing the previous one.
+
+### Tests
+
+2,201 tests, 14 more than 3.37.0, including the endpoint guard driven through the real protocol-301 handler for both an accepted frame and another controller's.
+
+## 3.37.0
+
+**When a cloud request times out, the diagnostics report can now say whether the MQTT session was actually carrying anything at the time.**
+
+All of this release is [@pponce](https://github.com/mathiashornbek/homebridge-roborock-matter/pull/29)'s work, in [#29](https://github.com/mathiashornbek/homebridge-roborock-matter/pull/29), the first of a four-part series. It is deliberately passive: nothing here reconnects, gates a request, changes transport selection, or touches the unanswered-method breaker. It only writes down what was observed.
+
+### Why
+
+A cloud timeout has always been ambiguous. `MQTT connection state: true` says the link believes it is up, which is exactly what it says when the link is up and delivering nothing — the failure #24, #27 and #28 all run into. Until now there was no way to tell those apart after the fact.
+
+The snapshot now separates things that used to be one word:
+
+- **`connected` and `subscriptionAcknowledged` are different claims.** A session can be connected with no usable subscription behind it.
+- **Inbound is measured in 4 stages** — the raw MQTT callback, attribution to a known robot, successful decoding, and correlation to a pending request. A link that delivers frames nobody can attribute looks very different from one that delivers nothing, and both used to read as silence.
+- **`rawSilenceDuringRequest`** records whether _any_ raw MQTT callback arrived between sending an eligible read and its timeout. This is a claim about the session, not about one robot, so unlike the two-robot correlation rule it works on a single-robot account — which is what #22 and #24 both are.
+
+The report carries ages and counts only: no robot IDs, no topics, no credentials, no payloads.
+
+### Found in review
+
+Two things were wrong when this was first proposed, and both were the same shape as faults in 3.30.0 and 3.31.0 — a value that is published but never reaches the disk the reader reads from:
+
+- **The snapshot never persisted.** `MqttSessionDiagnostics` was published through `setStateAsync` but was in neither `PERSISTED_STATE_IDS` nor `DEBOUNCED_PERSIST_IDS`, while the settings page reads it from `storagePath`. The new block would have rendered in tests and never in production. The suite was green because the UI test wrote the file itself. Both sets now contain it, and the shutdown flush was moved to _after_ transport teardown so the final disconnected snapshot reaches disk.
+- **A subscription could never be acknowledged after a reconnect.** mqtt.js resubscribes on its own, before our handler runs, so our `subscribe` callback comes back with no error and an empty grant list. Read as a result, that meant every reconnected session reported "subscription not acknowledged" forever. Acknowledgement is now taken from real SUBACK packets on the client's `packetreceive` event, and an empty grant list is treated as the no-op it is. A SUBACK whose grants are refusals still counts as unacknowledged.
+
+The second one was only visible because the test was rewritten to drive the real mqtt.js client against a loopback broker instead of a mock. The mock had been asserting the behaviour it was built to expect.
+
+### Tests
+
+2,187 tests, 36 more than 3.36.0, including a regression that drops the socket mid-session, withholds the second SUBACK, and verifies the session becomes acknowledged only when that packet actually arrives.
+
 ## 3.36.0
 
 **The LAN connection now asks the robot which protocol it speaks, the way python-roborock always has, and a cloud session that has gone quiet is restarted.**

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. 2153 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. 2201 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 2153 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 2201 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

@@ -3664,7 +3664,24 @@ class RoborockMatterVacuumAccessory {
         const supportedAreas = new Map(this.getMatterServiceAreas().map((area) => [area.areaId, area]));
         const selectedAreas = this.normalizeMatterAreaIds(newAreas);
         const unsupportedArea = selectedAreas.find((areaId) => !supportedAreas.has(areaId));
-        this.platform.log.info(`Matter service area selection request for ${this.getVacuumName()}: ${selectedAreas.join(", ") || "none"}.`);
+        // WHAT ARRIVED, NOT ONLY WHAT WAS UNDERSTOOD — #24.
+        //
+        // The line used to print the normalised ids alone, so "the controller
+        // cleared the selection" and "the controller sent eight ids and this
+        // plugin read none of them" were the same five characters: `none`. #24
+        // reported a selection that reverts when all eight rooms are picked, and
+        // the only log line covering it could not say which of the two had
+        // happened — a week per guess, at one run a week.
+        const requestedCount = Array.isArray(newAreas) ? newAreas.length : null;
+        const unreadable = requestedCount === null ? 0 : requestedCount - selectedAreas.length;
+        const requestDetail = requestedCount === null
+            ? " (the controller sent no area list)"
+            : requestedCount === 0
+                ? " (the controller sent an empty list)"
+                : unreadable > 0
+                    ? ` (the controller sent ${requestedCount} entr${requestedCount === 1 ? "y" : "ies"}, ${unreadable} of which could not be read as an area id)`
+                    : "";
+        this.platform.log.info(`Matter service area selection request for ${this.getVacuumName()}: ${selectedAreas.join(", ") || "none"}${requestDetail}.`);
         if (unsupportedArea !== undefined) {
             return {
                 status: SERVICE_AREA_SELECT_STATUS.UNSUPPORTED_AREA,
@@ -3675,7 +3692,11 @@ class RoborockMatterVacuumAccessory {
             .map((areaId) => supportedAreas.get(areaId))
             .filter((area) => area !== undefined));
         if (selectedMapIds.length > 1) {
-            this.platform.log.warn(`Ignoring Matter service area selection spanning multiple Roborock maps for ${this.getVacuumName()}; select areas from one map at a time.`);
+            // A refused selection is not a cleared one: the controller keeps the set
+            // it last had accepted. That is precisely the "it falls back to the two
+            // rooms I cleaned this morning" of #24, and the old warning described
+            // neither the cause (which maps) nor the visible effect (the revert).
+            this.platform.log.warn(`Ignoring Matter service area selection spanning ${selectedMapIds.length} Roborock maps for ${this.getVacuumName()} (maps ${selectedMapIds.join(", ")}; areas ${selectedAreas.join(", ")}); select areas from one map at a time. The selection is refused, not cleared, so the controller will keep showing the previous selection.`);
             return {
                 status: SERVICE_AREA_SELECT_STATUS.INVALID_SET,
                 statusText: "Select service areas from only one Roborock map at a time.",