homebridge-roborock-matter 2.9.1 → 2.9.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.9.3
+
+**The plugin is now Verified by Homebridge!** 🎉 Reviewed and endorsed by the Homebridge team (homebridge/plugins#1124), with specific praise for the encrypted at-rest session storage, the preserved fork attribution, and the per-release notes.
+
+- Verified badge added to the README.
+- **Donate button enabled** on the plugin's Homebridge UI tile via the standard `funding` field (PayPal), plus a Support section in the README.
+- Verified plugins are bumped in Homebridge UI search results and distributed via the pre-bundled tarball pipeline for faster, more reliable installs on low-power devices.
+
+## 2.9.2
+
+- **Max+ ("Grundig"/"Deep Clean") suction mode now announced on the S8 Pro Ultra.** Field report from a re-paired fleet: the S8 Pro Ultra only showed four suction levels because Max+ was gated to B01/Q7. The classic gate now uses the upstream-vetted per-model feature data (`set_custom_mode_max_plus` in the model's action list) — currently confirming the S8 Pro Ultra (`a70`); further models are added as feature data or field reports with diagnostics exports confirm the level. NOTE: the robot must be re-paired once for the new mode to appear (Matter locks the mode list at commissioning).
+- Battery documentation corrected after upstream verification on homebridge#3958: `batPercentRemaining` is quality **Q (quieter)** as of Matter 1.4 (reports ARE sent via subscription, 10 s throttle) — a spec-compliant controller applies them; Apple Home in steady state does not. No plugin architecture change needed; the bridge already does the right thing.
+
 ## 2.9.1
 
 Deep performance pass over the live-room hot paths, with honest before/after measurements.

package/README.md

@@ -9,6 +9,7 @@
 </p>
 
 <p align="center">
+  <a href="https://github.com/homebridge/homebridge/wiki/Verified-Plugins"><img src="https://img.shields.io/badge/homebridge-verified-blueviolet?color=%23491F59&style=flat" alt="verified-by-homebridge"></a>
   <a href="https://www.npmjs.com/package/homebridge-roborock-matter"><img src="https://img.shields.io/npm/v/homebridge-roborock-matter?label=npm&color=cb3837" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/homebridge-roborock-matter"><img src="https://img.shields.io/npm/dt/homebridge-roborock-matter?label=downloads&color=8a5cf5" alt="npm downloads"></a>
   <a href="https://github.com/mathiashornbek/homebridge-roborock-matter/actions"><img src="https://img.shields.io/github/actions/workflow/status/mathiashornbek/homebridge-roborock-matter/nodejs.yml?label=CI" alt="CI status"></a>
@@ -27,7 +28,7 @@ Log in with your **Roborock app account** — no token extraction, no rooted app
 - 📍 **Live room tracking — on every robot.** While the robot works, its position is read from the map channel (encrypted SCMap on B01/Q7, classic RRMap on S/Q-series), matched against your room geometry, and published as the current Matter Service Area. Apple Home shows _"Cleaning — Kitchen"_ — including runs started from the robot's button or the Roborock app. No other Homebridge plugin does this.
 - 🧭 **Matter-only, by design.** No legacy fan tiles, no helper-switch clutter. One robot, one native accessory, on Homebridge 2's built-in Matter bridge — including room/map selection sourced from your Roborock account's named rooms.
 - 🔌 **Cloud + local, automatically.** Commands prefer a direct local TCP connection to the robot and fall back to the Roborock cloud transparently, with per-device connection diagnostics in the settings UI when you want to see exactly what happened.
-- 🛡️ **Hardened and boring where it counts.** 256 automated tests, CI on Node 22/24 against Homebridge 1.11 and 2.x, zero known vulnerabilities, no analytics, no post-install scripts, and a startup that retries with backoff instead of ever crash-looping Homebridge — verified against the Homebridge plugin-verification harness.
+- 🛡️ **Hardened and boring where it counts.** 260 automated tests, CI on Node 22/24 against Homebridge 1.11 and 2.x, zero known vulnerabilities, no analytics, no post-install scripts, and a startup that retries with backoff instead of ever crash-looping Homebridge. **Verified by Homebridge** after review by the Homebridge team.
 
 ## Features
 
@@ -96,7 +97,7 @@ Everything is configurable from the Homebridge UI. The essentials:
 
 ## Battery percentage in Apple Home
 
-Apple Home renders the battery percentage from pairing time and never re-reads it — the Matter attribute carries the spec's "changes omitted" reporting quality, so value changes are not pushed to controllers _by design_ (charging state on the very same cluster updates live). This is a controller-side limitation verified end-to-end, not a plugin bug.
+Apple Home renders the battery percentage from pairing time and refreshes it only on a fresh read (commissioning, hub restart) — while charging state on the very same cluster updates live. This is a controller-side limitation, not a plugin bug, and it is being investigated upstream with the Homebridge team ([homebridge#3958](https://github.com/homebridge/homebridge/issues/3958)). Current state of knowledge: as of Matter 1.4 the attribute carries the **"quieter" (Q)** reporting quality — reports ARE sent over the subscription (rate-limited to one per 10 s), a Homebridge maintainer verified that a spec-compliant matter.js controller receives and applies them, yet Apple Home in steady state does not. The likely permanent fix is on Apple's side (Apple Feedback).
 
 <details>
 <summary>The full evidence chain and workarounds</summary>
@@ -116,6 +117,10 @@ The complete path — robot → plugin → Homebridge → matter.js store — wa
 
 Model reports, diagnostics exports, and pull requests are very welcome. The codebase ships with 256 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
+
+If this plugin makes your home a little smarter, you can support its development via [PayPal](https://paypal.me/MathiasHornbek) — or through the ❤️ **Donate** button on the plugin's tile in the Homebridge UI. Model reports and diagnostics exports are just as valuable!
+
 ## Attribution
 
 A Matter-only fork of [`homebridge-roborock-vacuum2`](https://github.com/applemanj/homebridge-roborock-vacuum2) by **Joshua Appleman**, itself adapted from [ioBroker.roborock](https://github.com/copystring/ioBroker.roborock) by **copystring**, with original work by **Nico Hartung**. B01/Q7 protocol work is implemented against the [python-roborock](https://github.com/Python-roborock/python-roborock) reference. All original copyright is preserved under the [MIT license](./LICENSE).

package/docs/issue-3958-reply.md

@@ -0,0 +1,29 @@
+# Svar til bwp91 på homebridge#3958 — klar til at poste
+
+```markdown
+Thank you — this is exactly the kind of verification I was hoping for, and
+the C → Q correction is a genuinely important update. You're right that my
+analysis was written against the older changes-omitted reading of the
+attribute; I've already corrected the plugin's documentation to reflect the
+Matter 1.4 Q (quieter) quality and your subscription trace
+(mathiashornbek/homebridge-roborock-matter@main, README + docs).
+
+Your controller log also explains two things I had observed but couldn't
+fully reconcile: the resync nudge's null → value transition "working" at the
+wire level while Apple still never converged, and `batChargeState` updating
+live throughout. Both are consistent with the reports leaving the bridge and
+Apple simply not applying Q-quality percentage reports in steady state.
+
+I'll run the verification you suggested on my production setup (three
+robots: one V1, two B01) — Homebridge with matter.js debug logging through a
+full charge cycle, watching for the subscription flushes carrying
+`batPercentRemaining` — and post the log excerpts here. If I can get
+chip-tool set up on the same network I'll add a subscription trace from that
+side too.
+
+Assuming both confirm what your trace already shows, I'll file the Apple
+Feedback report about the controller's handling of Q-quality PowerSource
+attributes and link it here so others can dupe it. Thanks again for digging
+in — happy to test any builds if something changes in the Homebridge Matter
+layer down the road.
+```

package/docs/matter-battery-issue-draft.md

@@ -1,66 +1,57 @@
-# Matter PowerSource `batPercentRemaining` never refreshes in controllers (changes-omitted attribute; device-side store is fresh)
-
-Ready to file against `homebridge/homebridge` (Matter API). Title suggestion:
-
-> Matter bridged accessories: `batPercentRemaining` freezes at pairing-time value in Apple Home (changes-omitted attribute; store verifiably fresh)
-
-## Summary
-
-A Matter Robotic Vacuum Cleaner (device type 0x74) exposed through Homebridge 2's
-Matter API publishes battery updates continuously via `updateAccessoryState`. The
-matter.js store demonstrably carries the live value. Controllers (Apple Home,
-multi-hub) keep rendering the value from pairing time indefinitely — across
-plugin restarts, Homebridge restarts, and days of uptime — while
-`batChargeState` on the very same cluster updates live.
-
-## Environment
-
-- Homebridge 2.1.x (Matter API), plugin `homebridge-roborock-matter` publishing
-  full-state snapshots via `updateAccessoryState`
-- Three robots (one V1-protocol, two B01-protocol) — identical behavior on all
-- Controller: Apple Home (Apple TV + HomePod hubs, current iOS/tvOS)
-
-## Reproduction
-
-1. Pair a bridged Matter accessory that exposes PowerSource with a battery
-   percentage that changes over time (any RVC works).
-2. Let the battery drain or charge by 10+ points.
-3. Compare the Apple Home tile with the matter.js store on disk.
-
-## Evidence chain
-
-1. Plugin log shows continuous publishes with live values (73% → 92% over an
-   hour, all three robots).
-2. `grep -ro "batPercentRemaining[^,}]*" <storage> --include="*.json"` shows the
-   persisted matter.js store matching the vendor app in real time (e.g. 170 =
-   85% while Apple renders 74%).
-3. `batChargeState` (same PowerSource cluster) propagates to Apple Home in
-   near-real-time throughout.
-4. The values Apple renders are exactly each robot's value from its
-   commissioning moment; a re-pair refreshes once, then freezes again.
-5. A device-side "resync nudge" (publishing the attribute as briefly unknown,
-   then real, to force two genuine store changes and a data-version bump) helps
-   only controllers that re-prime their subscription (e.g. after a hub
-   restart); Apple in steady state still never converges.
-
-## Analysis
-
-`batPercentRemaining` (and `batTimeToFullCharge`) carry the Matter spec
-reporting quality **"changes omitted" (C)**. matter.js honors this on the
-device side (changes are not delivered via subscription reports), and the
-matter.js controller compensates on its own side ("Always read attributes that
-do not report changes via subscriptions" — matter.js changelog 0.10). Apple's
-controller evidently performs no such re-reads, so bridged accessories freeze
-on the pairing-time percentage. No plugin-side write can force a
-changes-omitted attribute to report.
-
-## Suggestion
-
-Consider a device-side mitigation in the Homebridge Matter layer for bridged
-accessories — for example bumping the cluster data version or scheduling a
-periodic re-announce for changes-omitted attributes whose value has drifted —
-so controllers that rely purely on subscriptions eventually converge. This
-would fix frozen battery percentages for every bridged plugin at once, in one
-place.
-
-Happy to provide full logs, store dumps, and to test builds.
+# Matter PowerSource `batPercentRemaining` — investigation record
+
+Filed upstream as
+[homebridge/homebridge#3958](https://github.com/homebridge/homebridge/issues/3958)
+on 2026-07-15. This document tracks the current state of knowledge; the
+original report text lives in the issue.
+
+## Symptom
+
+A Matter RVC bridged through Homebridge 2's Matter API publishes battery
+updates continuously; the matter.js store verifiably carries the live value;
+`batChargeState` on the same PowerSource cluster updates live in Apple Home —
+but the rendered battery **percentage** stays at its commissioning-time value
+until a fresh read (re-pair or Matter hub restart).
+
+## Corrected analysis (per Homebridge maintainer verification, 2026-07-15)
+
+The original analysis assumed the attribute carries the Matter reporting
+quality **C (changes omitted)** — never reported via subscription, controllers
+must poll. That was true of older spec revisions, **but as of Matter 1.4 the
+attribute is quality Q (quieter)** , and matter.js 0.17.x (shipped with every
+Homebridge 2.1.x release) models it accordingly:
+
+- **Q (quieter):** reported via subscription, rate-limited to at most one
+  report per 10 seconds, plus an immediate report on any null ↔ value
+  transition.
+
+A Homebridge maintainer (bwp91) commissioned a matter.js controller against a
+bridge exposing `PowerSource(Battery, Rechargeable)` — the same setup
+Homebridge builds — and logged the subscription: percentage changes propagate
+exactly as Q prescribes (immediate first report, deferred follow-up inside the
+10 s window, correct application after an interleaved `batChargeState` bump).
+The "stale cluster data version" theory does not hold on the controller side.
+
+## Where that leaves things
+
+- The bridge **emits** the reports; a spec-compliant controller **applies**
+  them. Apple Home in steady state does not — consistent with Apple's
+  controller still treating the attribute under the older changes-omitted
+  rules and refreshing only on a fresh read.
+- The plugin's boot-time resync nudge (null → value transition) does hit the
+  wire immediately (maintainer-confirmed) and remains useful for controllers
+  that re-prime their subscriptions; Apple still does not converge.
+- **No device-side fix exists**: bumping the data version or re-announcing
+  only produces more of the reports Apple already receives and ignores.
+
+## Next verification steps (requested upstream)
+
+1. Run Homebridge with matter.js debug logging during a battery change and
+   capture the subscription flushes carrying `batPercentRemaining` — proves
+   the reports leave THIS bridge specifically.
+2. Optionally subscribe with `chip-tool` and confirm it sees (and applies)
+   the live values.
+
+If both confirm reports going out, the permanent fix belongs with Apple
+(Apple Feedback report about the controller's handling of Q-quality
+PowerSource attributes). The upstream issue stays open in the meantime.

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "2.9.1",
+  "version": "2.9.3",
   "description": "Matter-only Homebridge plugin publishing Roborock robot vacuums (including 2025 B01/Q7-series) as native Matter accessories for Apple Home. Fork of homebridge-roborock-vacuum2.",
   "license": "MIT",
   "author": {
     "name": "Mathias Hornbek"
   },
+  "funding": {
+    "type": "paypal",
+    "url": "https://paypal.me/MathiasHornbek"
+  },
   "keywords": [
     "apple-home",
     "homebridge-plugin",

package/roborockLib/lib/deviceFeatures.js

@@ -1345,7 +1345,23 @@ class deviceFeatures {
   }
 }
 
+// Classic v1 models whose upstream-vetted per-model action list includes
+// `set_custom_mode_max_plus` — the verified signal that the robot's firmware
+// accepts the Max+ suction level (v1 fan power 108). Keep this in sync with
+// the modelConfig action lists in processSupportedFeatures above; models are
+// only added here once the upstream feature data (or a field report with a
+// diagnostics export) confirms the level.
+const MAX_PLUS_FAN_POWER_MODELS = new Set([
+  "roborock.vacuum.a70", // S8 Pro Ultra
+]);
+
+/** @param {string} model */
+function supportsMaxPlusFanPower(model) {
+  return MAX_PLUS_FAN_POWER_MODELS.has(model);
+}
+
 module.exports = {
   deviceFeatures,
   stateCodes,
+  supportsMaxPlusFanPower,
 };

package/roborockLib/roborockAPI.js

@@ -14,6 +14,8 @@ const roborock_mqtt_connector =
 const rrMessage = require("./lib/message").message;
 const vacuum_class = require("./lib/vacuum").vacuum;
 const deviceFeatures = require("./lib/deviceFeatures").deviceFeatures;
+const supportsMaxPlusFanPower =
+  require("./lib/deviceFeatures").supportsMaxPlusFanPower;
 const RRMapParser = require("./lib/RRMapParser");
 const messageQueueHandler =
   require("./lib/messageQueueHandler").messageQueueHandler;
@@ -1944,6 +1946,12 @@ class Roborock {
       canVacuum: true,
       canMop: hasWaterModeSchema || hasMopSchema || hasMopFeature,
       canControlFanPower,
+      // Max+ (fan power 108) only where the upstream-vetted per-model
+      // feature data confirms the level (e.g. S8 Pro Ultra) — field
+      // reports with diagnostics exports extend the list.
+      canMaxPlusFanPower: supportsMaxPlusFanPower(
+        this.getProductAttribute(duid, "model")
+      ),
       canControlWater:
         hasWaterModeSchema ||
         this.hasVacuumFeature(duid, [