homebridge-roborock-matter 3.23.0 → 3.23.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 3.23.1
+
+**A Q7 that finished cleaning normally asked its owner to report a fault.**
+
+The maintainer's own `roborock.vacuum.sc05` logged six distinct unexplained `error_code`s in a single day — 2110, 2108, 501, 2102, 2103 and the long-familiar 2105 — every one of them while it was running. It then finished its run and docked at 100%. Nothing was wrong with it at any point.
+
+Read against python-roborock's own per-family fault tables, two of those six are not faults at all:
+
+- **2102** — "Cleaning completed. Returning to the dock." It fires after **every** task.
+- **2100** — "Low battery. Resume cleaning after recharging." The robot announcing normal auto-recharge-and-resume.
+
+The plugin already treats the Q10 family's equivalents this way: upstream marks that family's 501 as hardware-confirmed and firing per completed task, and its 502 as a low-battery resume, and both have been informational here since the families were split. The Q7 family was simply never given its own two. The asymmetry ran the other way too — the Q7 has always silenced 407 ("cleaning in progress, scheduled clean ignored") while the Q10 did not, though upstream marks it hardware-confirmed and "lifecycle, not an error" on that family as well. All three are informational now.
+
+Apple Home was never affected: no B01 fault number appears in the plugin's v1 error table, so an unrecognised one has always published nothing rather than drawing a fault on a healthy tile. What it reached was the log, which named the code once per run and asked the owner to report the number "if the robot really is in trouble right now" — asked, in these two cases, after a clean that had just completed successfully.
+
+**Restraint is the other half of this.** Only a healthy robot's lifecycle notifications are silenced. A scheduled clean that did not run (2003, "Battery level below 20%. Scheduled task canceled") and a clean that ended without reaching its target (2007, 2012) are outcomes an owner may want to know about, so they still surface. And the codes upstream itself cannot explain — 2103, 2105, 2108 and 2110 are bare `fault_NNNN` entries there too — stay exactly as they were. Silencing a number nobody has explained would be a guess, not a translation.
+
 ## 3.23.0
 
 **Where a newer robot actually keeps its schedules: a read-only measurement, on request.**

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. 1778 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. 1787 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
 
@@ -257,7 +257,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 1778 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 1787 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.23.0",
+  "version": "3.23.1",
   "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/b01Q7Adapter.js

@@ -197,13 +197,40 @@ function v1FanPowerToWind(family) {
 // Fault codes that are informational rather than active errors — per family,
 // because the 2 families reuse the same numbers for different things.
 //
-// Q7: 407 = "Cleaning in progress. Scheduled cleanup ignored".
-// Q10: 400 = scheduled clean starting, 501 = cleaning completed and returning
+// Q7: 407 = "Cleaning in progress. Scheduled cleanup ignored", 2100 = "Low
+// battery. Resume cleaning after recharging", 2102 = "Cleaning completed.
+// Returning to the dock".
+// Q10: 400 = scheduled clean starting, 407 = cleaning in progress and a due
+// scheduled clean ignored, 501 = cleaning completed and returning
 // (hardware-confirmed upstream, and it fires after EVERY task, so treating it
 // as a fault would leave a Q10 permanently in error), 502 = low-battery
 // resume.
-const INFORMATIONAL_Q7_FAULTS = new Set([0, 407]);
-const INFORMATIONAL_Q10_FAULTS = new Set([0, 400, 501, 502]);
+//
+// EACH FAMILY NEEDS ITS OWN PER-TASK COMPLETION CODE, AND THE Q7 WAS MISSING
+// ITS ONE UNTIL 3.23.1. The 2 sets started from the codes each family had
+// actually been measured emitting, which left them asymmetric in both
+// directions: the Q10 had its after-every-task code (501) while the Q7 did
+// not, and the Q7 had 407 while the Q10 did not — even though upstream marks
+// `YXFault` 407 hardware-confirmed on a physical ss07 and "lifecycle, not an
+// error".
+//
+// The Q7 gap surfaced on the maintainer's own `sc05`, which logged 6 distinct
+// unmapped codes in a single day (2110, 2108, 501, 2102, 2103, 2105), every
+// one of them mid-run, and then finished and docked at 100 % with nothing
+// wrong. Read against python-roborock's `B01Fault`, 2 of the 6 are not faults:
+// 2102 fires after every task, and 2100 is the robot announcing normal
+// auto-recharge-and-resume — the Q7 analogue of the Q10's 502.
+//
+// WHAT IS DELIBERATELY LEFT SURFACING, BECAUSE SILENCE IS NOT FREE. Only a
+// healthy robot's lifecycle notifications belong here. Q7's 2003 ("Battery
+// level below 20%. Scheduled task canceled") and 2007/2012 ("Unable to reach
+// the target. Cleaning ended") are outcomes a user may want to know about — a
+// scheduled clean that did not run is not noise. And the codes upstream has no
+// description for at all (2103, 2105, 2108, 2110 are bare `fault_NNNN` there)
+// stay put: silencing a number nobody has explained would be a guess, not a
+// translation.
+const INFORMATIONAL_Q7_FAULTS = new Set([0, 407, 2100, 2102]);
+const INFORMATIONAL_Q10_FAULTS = new Set([0, 400, 407, 501, 502]);
 
 /** @param {string} family */
 function informationalFaults(family) {