homebridge-roborock-matter 3.19.1 → 3.19.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 3.19.2
+
+**Two releases in a row gated one caller each against the same defect. This one changes the shape of the error that kept producing them, so the next caller is calm without having to know.**
+
+3.19.0 stopped the status loop polling a Q10 (`ss*`) for a value the dialect cannot return. 3.19.1 did the same for the live-room loop. Both were the same class one loop apart, and a sweep of every send site has since confirmed no third loop is left. What had not been fixed was the reason the class kept surfacing as a warning rather than a debug line.
+
+The send choke point refuses an untranslatable Q10 read correctly and by design. But it built that refusal with `ROBOROCK_TRANSPORT_REFUSED`, and `catchError`'s calm early exit matches only `B01_METHOD_UNSUPPORTED`. So the refusal missed the calm branch, picked up the transient-warning path, and came out as `Failed to execute get_status on robot … Future transient warnings for this robot will be logged at most once every 360 minutes` — a line that reads as a failing robot when the plugin declined to send by design.
+
+**A Q10 having no equivalent for a read is a capability fact, not a transport fault.** It is permanent, identical for every Q10, and the same kind of condition as the B01/Q7 unsupported-method case that has always logged at debug. It now carries the unsupported code, so any caller that reaches it is quiet by construction rather than by remembering to gate itself.
+
+**The reclassification is deliberately narrow, and the guard is part of the change.** The same helper builds three genuine transport refusals — an offline robot, an unavailable cloud link, a missing local socket — and those must stay warnings, because for those the robot really is unreachable and the user does need to know. Only the dialect-capability refusal is reclassified; the three transport refusals are pinned by tests that fail if a future change widens it.
+
+One existing test asserted the old code. It was not wrong about the code — the code was the defect — and its two message assertions are untouched.
+
+**A flaky test in the release gate is fixed, and it was found by this release rather than reported.** Two tests start a real Node child process and wait for it to exit, on jest's default 5-second timeout — the only tests in the suite whose cost is a cold interpreter start. Under full-suite load that is a coin flip: two consecutive runs each failed one of the two, a different one each time, while the file passed 21 of 21 in nine seconds on its own. Both now carry an explicit ceiling generous enough that only a genuine hang reaches it, and the suite-wide default is raised from jest's 5 seconds to 20 seconds because the class is wider than those two — a socket test connecting to a closed port failed the next run for the same reason. Twenty seconds is roughly 220 times the suite's mean test, so a test that reaches it is stuck rather than unlucky. A gate that fails at random either blocks releases it should not or teaches whoever reads it to wave failures through, and the second is the worse outcome.
+
+Troubleshooting documentation for the Apple Home "Updating…" / "No Response" tile is corrected on two points, both from field reports rather than reasoning. An iOS update is no longer presented as the confirmed cure: one reporter's tile has stayed up since 26.6.1, while another on the same version has watched it lapse and return for six months, so restarting the affected Apple device is now the remedy the page leads with. And a note explains why the symptom appears on a robot vacuum and no other accessory — Apple Home requires a vacuum to be its own Matter node, so it is the only accessory Homebridge publishes outside the bridge, and therefore the only one whose subscription can die alone.
+
 ## 3.19.1
 
 **The live-room loop was polling a Q10 for a map it cannot answer, and counting each refusal as a failure. Same defect 3.19.0 fixed in the status loop, one loop over.**

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. 1611 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. 1620 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
 
@@ -243,8 +243,9 @@ The complete path — robot → plugin → Homebridge → matter.js store — wa
 - **Diagnostics first:** the plugin settings include per-device connection state, the last cloud/local transport used, a live **Test Local Connection** probe, and a **redacted diagnostics report** you can paste straight into a GitHub issue.
 - **Robot shows "Updating…" or "No Response" in Apple Home:** those two wordings are one tile condition, and Apple chooses between them for reasons of its own — so do not triage them as separate problems. **Open the same tile on a second Apple device before you change anything.** If another controller in the same Home draws it correctly at that same moment, the plugin is publishing and the pairing is sound, and re-pairing cannot help: what is broken is the controller in your hand. Then, cheapest first:
   1. **Restart the Apple device that shows it.** That cleared it outright for the reporter in [#11](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/11) — a restart makes the controller drop what it thinks it knows about the accessory and subscribe again.
-  2. **Update to iOS 26.6.1 or later.** On earlier versions the controller could declare its own subscription invalid (Matter status `0x7D INVALID_SUBSCRIPTION`) and then never subscribe again, so one controller kept rendering the accessory while another had no live subscription to it — the same tile, dead on the phone and alive on the Mac at the same moment. The bridge does the right thing in that situation (it drops the dead subscription and re-announces over mDNS), but no Matter device can force a controller to subscribe, so there is nothing to fix on this side. Confirmed fixed on 26.6.1 by the reporter in [#7](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/7). A restart without the update can drift back, because the bug that killed the subscription is still on the phone.
+  2. **Update to the newest iOS you can — but do not expect it to be the cure.** The underlying event is the controller declaring its own subscription invalid (Matter status `0x7D INVALID_SUBSCRIPTION`) and then never subscribing again, so one controller keeps rendering the accessory while another has no live subscription to it — the same tile, dead on the phone and alive on the Mac at the same moment. The bridge does the right thing in that situation (it drops the dead subscription and re-announces over mDNS), but no Matter device can force a controller to subscribe, so there is nothing to fix on this side. **The evidence on versions is mixed and is reported here as it stands:** one reporter's tile has stayed up since 26.6.1 ([#7](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/7)), while another reporter on 26.6.1 still sees it, having watched it lapse and return for six months with remissions of up to a week. So treat step 1 as the reliable remedy and an OS update as worth doing but unproven.
   3. **`Add Accessory → More Options → Cancel`** revives the tile for about a minute, because it forces the controller to re-resolve and briefly re-subscribe. A stopgap, not a fix.
+- **"It only happens to my robot vacuum, never to my other Matter accessories" — that is expected, and it is not evidence the plugin is at fault.** Apple Home requires a robot vacuum to be its own Matter node, so Homebridge publishes each one on its own dedicated Matter server with its own port and its own pairing code, while every other accessory you own sits behind the single bridge node. In Homebridge 2.4.x the robot vacuum is the _only_ device type treated that way (`EXTERNAL_DEVICE_TYPES` in `dist/matter/MatterAPIImpl.js` contains `RoboticVacuumCleaner` and nothing else). A controller that loses one subscription therefore loses exactly one tile if that subscription was to a vacuum, whereas losing the bridge's subscription would blank out dozens of accessories at once and be unmistakable. **Your vacuum is not the accessory that breaks most often; it is the only one that can break alone.** So "only the vacuum is affected" is what the controller-side explanation above predicts, rather than something that contradicts it.
 - **Robot shows "Updating…" on every Apple device at once:** _now_ remove the robot from Apple Home and pair it again — a pairing carrying state over from an earlier install is the usual cause (tracked upstream in homebridge/homebridge#3951). What finally worked for the reporter in [#5](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/5) was the full teardown in this exact order: unpair, **uninstall** the plugin, install the current version, pair fresh. A re-pair on top of the existing install did not work for him, so the order is part of the remedy.
 - **Rooms missing for a Q7/B01 robot:** wait for the `B01 rooms for ...` log line, then re-pair once so the Service Area cluster is announced with room data.
 - **Debug logging needs two switches, not one:** the plugin's own **Debug Mode** only decides whether it _calls_ the debug logger — Homebridge decides whether anything is _printed_, and it suppresses plugin debug output unless Homebridge itself runs with `-D`. Turn on **Homebridge Settings → Homebridge Debug Mode** as well, or the log will look exactly the same as before.
@@ -252,7 +253,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 1611 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 1620 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.19.1",
+  "version": "3.19.2",
   "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

@@ -15,17 +15,26 @@ const { describeDevice } = require("./describeDevice");
  * matters: an unclassified refusal is logged as a plugin error with a stack,
  * once per poll, for as long as the robot is away. The reason now travels as
  * a code and the prose is free to change.
- */
-/**
+ *
+ * `code` defaults to the transport code because most refusals ARE transport
+ * conditions — an offline robot, a dead cloud link, a missing local socket —
+ * and those must stay visible as warnings. A refusal that reflects what a
+ * robot family can never do is a capability fact instead, and passing
+ * `B01_METHOD_UNSUPPORTED` puts it on `catchError`'s calm branch by
+ * construction rather than leaving each caller to gate itself. Do not widen
+ * that to the transport cases: it would tell a user nothing is wrong while
+ * their robot is unreachable.
+ *
  * @param {string} kind
  * @param {string} message
+ * @param {string} [code]
  * @returns {Error & { code: string, transientKind: string }}
  */
-function refusal(kind, message) {
+function refusal(kind, message, code = "ROBOROCK_TRANSPORT_REFUSED") {
   const error = /** @type {Error & { code: string, transientKind: string }} */ (
     new Error(message)
   );
-  error.code = "ROBOROCK_TRANSPORT_REFUSED";
+  error.code = code;
   error.transientKind = kind;
   return error;
 }
@@ -327,9 +336,16 @@ class messageQueueHandler {
         const q10 = b01Q10Adapter.translateOutgoing(method, params);
 
         if (!q10) {
+          // A capability fact, not a transport fault: this dialect has no
+          // equivalent for the method and never will. Carrying the unsupported
+          // code keeps `catchError` calm BY CONSTRUCTION, so a caller that
+          // reaches here logs debug instead of "Failed to execute …" on warn.
+          // 3.19.0 and 3.19.1 were each one gate for one loop of exactly this
+          // class; the shape of the error is what kept producing them.
           throw refusal(
             "b01 q10 method unsupported",
-            `${describeDevice(this.adapter, duid)} speaks the B01 Q10 dialect, which has no equivalent for ${method}, so it was not sent. The Q10 dialect (${model || "ss*"}) writes numbered datapoints and sends no reply, so a request that exists to read a value cannot be answered over it; see issue #19.`
+            `${describeDevice(this.adapter, duid)} speaks the B01 Q10 dialect, which has no equivalent for ${method}, so it was not sent. The Q10 dialect (${model || "ss*"}) writes numbered datapoints and sends no reply, so a request that exists to read a value cannot be answered over it; see issue #19.`,
+            "B01_METHOD_UNSUPPORTED"
           );
         }