homebridge-roborock-matter 2.9.9 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.0.0
+
+Startup and refresh pass: Homebridge restarts are noticeably faster, and a status refresh that had never actually run now does. Nothing here requires re-pairing — existing setups keep working exactly as they are.
+
+- **Restarts are roughly 5 seconds faster.** LAN discovery listens for robot broadcasts for a fixed 5-second window, and startup used to sit and wait for it with nothing else happening. It now runs alongside the home-data refresh, device setup and network probes, which all fit inside that same window. Measured on a three-robot setup: ~8 s from "Starting adapter" to "Lets go!!!!!!!" before, ~3 s after.
+- **Multi-robot startup no longer costs extra time.** Each robot's first status read and network probe used to run one after another; they now run at once, so three robots start as quickly as one. New tests pin the concurrency down so it cannot silently regress.
+- **A dead status refresh has been repaired.** The periodic `get_status` refresh for classic (S/Q-series) robots was gated on a config key this plugin never sets, which made the condition permanently false — the refresh promised by the code has never run in any released version. It now polls each robot at most once a minute (forced refreshes are unaffected), so a dropped MQTT push self-corrects within a minute instead of waiting up to three for the slow full poll.
+- **~86,000 needless timer wake-ups per robot per day removed.** With the refresh properly throttled, the 1-second scheduler tick that served it is now 15 seconds — same refresh rate, a fraction of the idle CPU on Raspberry Pi class hardware.
+- One request removed from every startup: a scene list was fetched from the Roborock cloud and thrown away.
+- **Security:** a newly published high-severity advisory in a transitive dependency (`ip-address`, reached through the MQTT client) is resolved, and the build toolchain was refreshed. `npm audit` reports zero vulnerabilities for both the shipped package and the development tree.
+- Full suite: 279 passing (7 new startup/refresh tests).
+
 ## 2.9.9
 
 - **Cleans started outside Apple Home now show the right clean mode.** Starting a vacuum+mop (or mop-only) clean from the Roborock app or the robot's buttons left Apple Home claiming plain "Vacuum". The Q7 series reports its active clean type in every status poll (the plugin sent it on start but never read it back); classic S/Q robots are derived from the mop-only suction signature and the active water-flow setting. Apple Home's mode picker now follows the robot live during a run — no re-pairing needed.

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. 263 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. 279 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
 
@@ -92,7 +92,10 @@ The clean mode follows the robot as well: start a vacuum+mop or mop-only clean f
 **The entire Roborock lineup.** If it runs in the Roborock app, this plugin can control it:
 
 - **2025 Q7 series** (`roborock.vacuum.sc05`, Q7 M5 / M5+) — the only Homebridge plugin that supports these at all, including manual-tank mopping with vacuum/mop mode switching.
-- **Classic S-, Q- and Saros-series** — S5 through S8 Pro Ultra, Q5/Q7/Q8/Q Revo families, Saros, and newer.
+- **Classic S-, Q- and Saros-series** — S4 / S5 Max through S8 Pro Ultra, Q5/Q7/Q8/Q Revo families, Saros, and newer.
+
+> **Heads-up for early models:** a few legacy robots — most notably the original S5 — only work with Xiaomi's Mi Home app and can never be added to a Roborock account, so no Roborock-account plugin can reach them. For those, [homebridge-xiaomi-roborock-vacuum](https://github.com/homebridge-xiaomi-roborock-vacuum/homebridge-xiaomi-roborock-vacuum) is the right tool.
+
 - **Future models** are adopted automatically: the plugin reads what each robot says it can do and adapts, so brand-new releases get sensible defaults from day one. If something looks off, [open a model report](https://github.com/mathiashornbek/homebridge-roborock-matter/issues) with a diagnostics export — that's exactly what it's for.
 
 ## Configuration
@@ -113,7 +116,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 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).
+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 not a plugin bug, and the root cause is now **confirmed in the source of matter.js** (the Matter stack Homebridge uses): the percentage attribute carries the spec's "changes omitted" quality, and matter.js currently never emits subscription reports for such attributes — while Apple Home never re-reads them on its own. The fix is tracked upstream in [matter-js/matter.js#4163](https://github.com/matter-js/matter.js/issues/4163) (an opt-in to report them anyway, which the spec permits); once it lands, Homebridge can enable it for bridged accessories and every plugin gets working battery percentages at once. Full investigation: [homebridge#3958](https://github.com/homebridge/homebridge/issues/3958).
 
 <details>
 <summary>The full evidence chain and workarounds</summary>

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

@@ -13,45 +13,40 @@ updates continuously; the matter.js store verifiably carries the live value;
 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.
+## Root cause (confirmed in the matter.js source by the Homebridge maintainer, July 2026)
+
+`ServerBehaviorBacking#configureEventSuppression()` collects every
+changes-omitted property into a suppressed set; only properties that are ALSO
+marked `quieter` get the observer that re-broadcasts them
+(`broadcastChanges([name])`). `batPercentRemaining` is changes-omitted without
+`quieter`, so it hits the `continue` and **no subscription report is ever
+produced** — the store stays fresh and reads serve the live value, which is
+exactly what this investigation's store dumps showed. `batChargeState`
+carries no C quality, which is why it updates live on the same cluster.
+
+Ruled out along the way:
+
+- An intermediate theory (Matter 1.4 Q-quality, reports leaving the bridge)
+  did not survive the maintainer's source check.
+- The freeze reproduces on Homebridge v2.2.2-beta.12 in a **restart-free**
+  window, ruling out the dead-subscription bug fixed by homebridge#3973.
+- matter.js 0.17.7 does not change the behavior (`ServerBehaviorBacking.js`
+  is byte-identical to what Homebridge ships).
+- No viable device-side nudge exists from the Homebridge layer:
+  `broadcastChanges` is `protected`, and private-internals access or patching
+  would break silently on a matter.js update.
+
+## The fix
+
+The Matter spec says a server _may_ omit changes for C attributes — reporting
+them anyway is permitted. The clean solution is an opt-in on the matter.js
+side, raised upstream by the Homebridge maintainer as
+[matter-js/matter.js#4163](https://github.com/matter-js/matter.js/issues/4163)
+with this investigation linked as evidence. Once it lands, Homebridge wires it
+up for bridged accessories and every plugin gets working battery percentages
+at once — no plugin-side change needed.
+
+Until then: homebridge#3958 stays open to track; the plugin keeps its
+boot-time battery resync (useful for controllers that re-prime their
+subscriptions after a hub restart), and the known refresh paths remain
+restarting the Matter hub or re-pairing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "2.9.9",
+  "version": "3.0.0",
   "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": {
@@ -60,16 +60,16 @@
     "qrcode": "^1.5.4"
   },
   "devDependencies": {
-    "@babel/core": "7.24.8",
-    "@babel/preset-env": "7.24.8",
-    "@babel/preset-typescript": "7.24.7",
+    "@babel/core": "7.29.7",
+    "@babel/preset-env": "7.29.7",
+    "@babel/preset-typescript": "7.29.7",
     "@types/jest": "30.0.0",
     "@types/node": "20.14.10",
     "@types/qrcode": "^1.5.6",
     "@types/semver": "7.5.8",
-    "babel-jest": "30.2.0",
+    "babel-jest": "30.4.1",
     "homebridge": "1.8.3",
-    "jest": "30.2.0",
+    "jest": "30.4.2",
     "prettier": "3.3.2",
     "rimraf": "6.0.1",
     "typescript": "5.5.3"

package/roborockLib/lib/vacuum.js

@@ -5,6 +5,11 @@ const RRMapParser = require("./RRMapParser");
 const fs = require("fs");
 const zlib = require("zlib");
 
+// Minimum spacing between periodic (non-forced) get_status polls per robot.
+// MQTT push remains the primary live channel; this is the safety net that
+// catches a dropped push long before the 3-minute full refresh would.
+const STATUS_POLL_MIN_INTERVAL_MS = 60 * 1000;
+
 const mappedCleanSummary = {
   0: "clean_time",
   1: "clean_area",
@@ -47,6 +52,25 @@ class vacuum {
       get_carpet_clean_mode: "deviceStatus",
       get_carpet_cleaning_mode: "deviceStatus",
     };
+
+    /** @type {Map<string, number>} last periodic status poll, per duid */
+    this.lastStatusPollAt = new Map();
+  }
+
+  /**
+   * True when this robot's periodic status poll is due again.
+   * @param {string} duid
+   */
+  shouldPollStatusNow(duid) {
+    const last = this.lastStatusPollAt.get(duid);
+    return (
+      last === undefined || Date.now() - last >= STATUS_POLL_MIN_INTERVAL_MS
+    );
+  }
+
+  /** @param {string} duid */
+  markStatusPolled(duid) {
+    this.lastStatusPollAt.set(duid, Date.now());
   }
 
   async updateDiagnosticSnapshot(duid, key, payload) {
@@ -332,16 +356,21 @@ class vacuum {
           }
         }
       } else if (parameter == "get_status") {
-        const now = new Date();
-        const seconds = now.getSeconds();
         const force = attribute == "force";
 
-        if (
-          force ||
-          this.adapter.socket ||
-          seconds % this.adapter.config.updateInterval == 0
-        ) {
-          // only send status every minute or if websocket is connected
+        // Periodic status refresh, throttled per robot.
+        //
+        // The inherited gate here read `config.updateInterval` (a key this
+        // plugin never sets) and `adapter.socket` (permanently null), so the
+        // expression was `NaN == 0` — always false. The refresh the comment
+        // promised has therefore never run: classic robots relied entirely on
+        // MQTT push plus the slow 3-minute full poll, and a silently dropped
+        // push left Apple Home stale for minutes. An explicit elapsed-time
+        // throttle restores the safety net, and being relative rather than
+        // aligned to wall-clock seconds also stops every robot in a fleet
+        // from polling in the same instant.
+        if (force || this.shouldPollStatusNow(duid)) {
+          this.markStatusPolled(duid);
 
           // const deviceStatus = await this.adapter.messageQueueHandler.sendRequest(duid, "get_status", []);
           const requestOptions = options.preferCloud

package/roborockLib/roborockAPI.js

@@ -42,6 +42,12 @@ const B01_LIVE_ROOM_CLEAR_V1_STATES = new Set([3, 8]);
 // slower cadence than the ~12s active status polls.
 const B01_LIVE_ROOM_MIN_FETCH_GAP_MS = 20000;
 
+// Scheduler granularity for the classic (v1-protocol) status refresh. The
+// refresh itself is throttled per robot inside vacuum.getParameter, so this
+// only decides how promptly that window is noticed — a 1-second tick meant
+// ~86k wake-ups per robot per day to serve at most 1440 polls.
+const CLASSIC_STATUS_TICK_MS = 15000;
+
 // Persisted states whose disk flush is debounced (see setStateAsync): they
 // change on every received robot message, are served from memory, and only
 // need the on-disk copy for restart survival.
@@ -1404,8 +1410,6 @@ class Roborock {
           const homedata = await this.api.get(`v2/user/homes/${homeId}`);
           const homedataResult = homedata.data.result;
 
-          const scene = await this.api.get(`user/scene/home/${homeId}`);
-
           await this.setStateAsync("HomeData", {
             val: JSON.stringify(homedataResult),
             ack: true,
@@ -1482,15 +1486,29 @@ class Roborock {
             this.updateInterval * 1000,
             homeId
           );
-          await this.updateHomeData(homeId);
 
-          const discoveredDevices = this.isCloudOnlyModeEnabled()
-            ? {}
-            : await this.localConnector.getLocalDevices();
+          // LAN discovery listens for UDP broadcasts for a fixed window, so
+          // awaiting it here used to stall startup for the full timeout with
+          // the CPU idle. Its results are only needed at the merge below, and
+          // the local keys it matches against are already loaded, so start it
+          // now and let the home-data refresh, device creation and network
+          // probes run inside that window instead.
+          const localDiscovery = this.isCloudOnlyModeEnabled()
+            ? Promise.resolve({})
+            : this.localConnector.getLocalDevices().catch((error) => {
+                this.log.debug(
+                  `LAN discovery failed; continuing with cloud transport: ${error?.message || error}`
+                );
+                return {};
+              });
+
+          await this.updateHomeData(homeId);
 
           await this.createDevices();
           await this.getNetworkInfo();
 
+          const discoveredDevices = await localDiscovery;
+
           if (!this.isCloudOnlyModeEnabled()) {
             // merge udp discovered devices with local devices found via mqtt
             Object.entries(discoveredDevices).forEach(([duid, ip]) => {
@@ -1763,14 +1781,20 @@ class Roborock {
   }
 
   async getNetworkInfo() {
-    for (const device of this.devices) {
-      const duid = device.duid;
-      if (!this.hasInitializedVacuum(duid)) {
-        continue;
-      }
-
-      await this.vacuums[duid].getParameter(duid, "get_network_info");
-    }
+    // One round-trip per robot, all independent: probing them in parallel
+    // turns N sequential cloud/LAN waits into one at startup. Failures are
+    // already handled inside getParameter, but allSettled keeps a rejection
+    // from one robot from skipping the others.
+    await Promise.allSettled(
+      this.devices
+        .filter((device) => this.hasInitializedVacuum(device.duid))
+        .map((device) =>
+          this.vacuums[device.duid].getParameter(
+            device.duid,
+            "get_network_info"
+          )
+        )
+    );
   }
 
   async createDevices() {
@@ -1830,6 +1854,11 @@ class Roborock {
     this.log.debug(`initializeDeviceUpdates`);
 
     const devices = this.devices;
+    // Each robot's first poll is a chain of round-trips to that robot alone.
+    // Running the chains for different robots concurrently keeps a
+    // multi-robot startup as fast as a single-robot one; the timers below are
+    // still wired up in order, only the initial reads overlap.
+    const initialPolls = [];
 
     for (const device of devices) {
       const duid = device.duid;
@@ -1863,7 +1892,7 @@ class Roborock {
 
       this.vacuums[duid].getStatusIntervall = () => {
         // B01/Q7 status is owned by the dedicated 15s loop; the per-device
-        // 1-second tick would only burn cycles hitting the attempt throttle.
+        // tick would only burn cycles hitting the attempt throttle.
         if (
           this.getVacuumDeviceInfo(duid, "pv") ===
           b01Q7Adapter.B01_PROTOCOL_VERSION
@@ -1873,7 +1902,7 @@ class Roborock {
         this.clearInterval(this.vacuums[duid].getStatusIntervalHandle);
         this.vacuums[duid].getStatusIntervalHandle = this.setInterval(
           this.getStatus.bind(this),
-          1000,
+          CLASSIC_STATUS_TICK_MS,
           duid,
           this.vacuums[duid],
           robotModel
@@ -1886,8 +1915,12 @@ class Roborock {
         this.vacuums[duid].getStatusIntervall(); // actually start getStatusIntervall()
       }
 
-      await this.updateDataMinimumData(duid, this.vacuums[duid], robotModel);
+      initialPolls.push(
+        this.updateDataMinimumData(duid, this.vacuums[duid], robotModel)
+      );
     }
+
+    await Promise.allSettled(initialPolls);
   }
 
   async executeScene(sceneID) {
@@ -1921,17 +1954,6 @@ class Roborock {
     }
   }
 
-  /**
-   * Get scenes from the Roborock API
-   * @returns {Promise<Object>} The scenes data
-   */
-
-  /**
-   * Get scenes for a specific device by duid
-   * @param {string} duid - The device unique identifier
-   * @returns {Array} Array of scenes for the specified device
-   */
-
   getProductAttribute(duid, attribute) {
     const device = this.getVacuumDeviceData(duid);
     const deviceValue = this.getDeviceAttribute(device, attribute);