homebridge-roborock-matter 3.26.0 → 3.28.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 3.28.0
+
+**Startup and network traffic, measured rather than felt.**
+
+### The tiles no longer wait for readings no tile displays
+
+`initializeDeviceUpdates` awaited the whole first parameter cycle for every robot — 8 serial round-trips per classic robot — and only then did startup set `bInited`, fire the Homebridge callback and register the Matter accessories. Those 8 requests read consumable hours, timers, carpet mode and water-box mode. Not one of them reaches the tile; the tile displays `get_status`, which was not among them.
+
+Counted on the critical path between "Homebridge started the plugin" and "the vacuum exists in Apple Home": **up to 12 serial network waits before, 3 after.** The home snapshot was also fetched twice back to back — `v2/user/homes` to build the device list, then `user/homes` again inside `updateHomeData` — and the second one is now handed the first one's payload. The network probe and the first status run concurrently instead of one after the other.
+
+On my own network this was a few seconds. On a robot that does not answer locally — the case in [#22](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/22), where every local request runs its full 10-second timeout before falling back to the cloud — it kept the vacuum out of Apple Home for over a minute after every restart.
+
+### The first status is immediate, not 15 seconds away
+
+The classic poller is a plain interval, so its first tick landed 15 seconds after start and the tile showed the cloud snapshot until then. The B01 loop already fired its first read immediately for exactly this reason; the classic path now does too. Each robot's first status is awaited before registration, in parallel across robots and capped at 4 seconds, so the tile registers with fresh state but never waits on a robot that will not answer.
+
+### 160 requests an hour became 52
+
+Measured per classic robot: the periodic cycle issued 8 requests every 180 seconds — `get_multi_maps_list`, `get_room_mapping`, `get_consumable`, `get_server_timer`, `get_timer`, `get_carpet_mode`, `get_carpet_clean_mode`, `get_water_box_custom_mode` — for values that change roughly once a week. 3 robots in one house: about 280 requests an hour, 6,700 a day, at the Roborock cloud and the robots' local ports.
+
+The 6 slow-changing readings now move to a **30-minute lane**. Room mappings deliberately stay on every cycle: a room renamed in the Roborock app should reach Apple Home within minutes, and that refresh now serves from the persisted cache first — the same shape the B01 branch already had — so its 2 round-trips run behind the tile rather than in front of it.
+
+|               | before     | after      |
+| ------------- | ---------- | ---------- |
+| classic robot | 160 / hour | ~52 / hour |
+| Q7 (B01)      | 60 / hour  | ~6 / hour  |
+
+`get_status` is untouched — still every 15 seconds for a classic robot, still the dedicated B01 loop — because that is the one reading the tile lives on. A schedule written from Apple Home or a diagnostics export that wants fresh numbers can bring the slow lane forward with `requestSlowParameterPoll`.
+
+8 new tests, 6 of which fail against 3.27.0.
+
+## 3.27.0
+
+**The scene resource named its one write verb, and it is the one that deletes. So the search moves off that resource and onto its siblings — asked safely, and this time with controls, so the round either finds the route or proves there is nothing left to find.**
+
+3.26.0 asked `user/scene/<id>` which methods it accepts. Issue #22's reporter ran it and the answer came back on the first try:
+
+```
+OPTIONS user/scene/<id> → "" — the resource allows: DELETE,OPTIONS
+```
+
+That is an answer, and not one of the two the thread had planned for. The plan said an `Allow` naming a write verb means the next step is a promised no-op, and a missing `Allow` means we are near the end of what can be measured from outside. What arrived names exactly one method that changes anything, and it removes a schedule rather than toggling one. There is no write there to put behind a HomeKit switch, and a destructive verb is not something to try against someone's live account to see what happens.
+
+**What that rules out is the resource, not the feature.** The plugin's own scene-run path reaches `user/scene/<id>/execute`, so sub-resources under a scene id exist and carry verbs the scene itself does not. This release asks the same safe question of the routes that are left:
+
+- `user/scene` — the collection, where a REST API most often keeps an update
+- `user/scene/<id>/enable` — the literal candidate for the nested `TIMER` flag the reporter's app flips
+
+**And of two controls, which is the part that makes the answers mean anything.** An `Allow` header on its own is not evidence:
+
+- `user/scene/device/<duid>` — a **positive** control. This same probe run already read it successfully, so it is mapped beyond doubt. If `OPTIONS` cannot describe even that, the instrument does not see routes and no other answer in the set is worth reading. It is also why the control is this route and not `/execute`: a control must not be a path whose real verb starts a robot.
+- `user/scene/<id>/no-such-subresource-control` — a **negative** control. If a path with nothing behind it also answers with an `Allow` header, the server answers everything and every positive here is an artefact.
+
+Together they bound the search instead of extending it: this round either names a route or shows that no later round would.
+
+Everything that made the probe safe to ship is unchanged and still bound by tests — silent unless debug logging is on, safe methods only, once per robot per session, cannot throw into the poll it rides on, and only the `Allow` header is taken from a response rather than the header block, which carries session material. A source guard now also pins the two properties that would otherwise fail invisibly: every candidate is narrowed to a safe method at one point, and the negative control cannot be dropped.
+
 ## 3.26.0
 
 **The refused route answered, and what it said was that the route exists — just not for the verb we asked with. So this release asks it which verb it does take, without attempting one.**

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. 1854 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. 1870 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
 
@@ -258,7 +258,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 1854 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 1870 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.26.0",
+  "version": "3.28.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": {

package/roborockLib/roborockAPI.js

@@ -299,6 +299,15 @@ const B01_STATUS_FORCED_GAP_MS = 1500;
 const B01_STATUS_ACTIVE_GAP_MS = 12000;
 const B01_STATUS_IDLE_GAP_MS = 25000;
 
+// The last path segment of the cloud schedule probe's negative control.
+//
+// The probe asks candidate routes which methods they take. An `Allow` header
+// coming back is only evidence if a route that CANNOT exist stays silent, so
+// one deliberately unmappable path is asked the same question. It is a fixed
+// literal rather than a random string so that the same reading is reproducible
+// across restarts and legible in a log a user pastes into an issue.
+const ABSENT_ROUTE_PROBE_SEGMENT = "no-such-subresource-control";
+
 // How many keys of an arbitrary diagnostic object survive compaction.
 const DIAGNOSTIC_KEY_LIMIT = 30;
 
@@ -331,6 +340,32 @@ const DIAGNOSTIC_PRIORITY_KEYS = new Set([
 // ~86k wake-ups per robot per day to serve at most 1440 polls.
 const CLASSIC_STATUS_TICK_MS = 15000;
 
+// HOW OFTEN THE SLOW-CHANGING PARAMETERS ARE RE-READ.
+//
+// Measured before this existed: a classic robot's periodic cycle issued 8
+// requests every 180 seconds - `get_multi_maps_list`, `get_room_mapping`,
+// `get_consumable`, `get_server_timer`, `get_timer`, `get_carpet_mode`,
+// `get_carpet_clean_mode`, `get_water_box_custom_mode` - 160 an hour, all
+// serial, for values that change roughly once a week. Consumable hours tick
+// over during a clean and nowhere else; timers change when the user edits a
+// schedule; carpet and water-box modes change when the user changes a setting.
+// None of them drives the Apple Home tile - that is `get_status`, on its own
+// 15-second tick and untouched by this.
+//
+// Room mappings are deliberately NOT in the slow lane: a room the user renames
+// or splits in the Roborock app should show up in Apple Home within minutes,
+// and the refresh already serves from cache first. Everything else waits.
+//
+// 30 minutes cuts a classic robot from 160 to about 52 requests an hour and a
+// Q7 from 60 to about 46. A diagnostics export still sees the last reading;
+// anything that needs a fresh one can ask for it.
+const SLOW_PARAMETER_POLL_INTERVAL_MS = 30 * 60 * 1000;
+
+// The longest startup will wait for a classic robot's first status before the
+// Matter accessories register. A robot that answers does so in well under a
+// second; one that does not must not hold the others' tiles hostage.
+const INITIAL_STATUS_WAIT_CAP_MS = 4000;
+
 // 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.
@@ -465,6 +500,8 @@ class Roborock {
     this.unsupportedPollCommands = new Set();
     this.loggedPollProfiles = new Set();
     this.skippedDialectPolls = new Set();
+    /** @type {Map<string, number>} duid -> when its slow lane last ran */
+    this.lastSlowParameterPollAt = new Map();
     this.baseURL = options.baseURL || "usiot.roborock.com";
 
     this.userData = options.userData || null;
@@ -2042,7 +2079,7 @@ class Roborock {
                 return {};
               });
 
-          await this.updateHomeData(homeId);
+          await this.updateHomeData(homeId, homedataResult);
 
           await this.createDevices();
 
@@ -2061,8 +2098,14 @@ class Roborock {
           // createDevices() so the boot poll cannot precede the wait above.
           this.startB01StatusLoop();
 
-          await this.getNetworkInfo();
-          await this.initializeDeviceUpdates();
+          // Independent, so concurrent: the network probe feeds the LAN
+          // attach that runs later in the background, and the first status
+          // feeds the tile. Neither needs the other, and serially they were
+          // two full round-trip waits where one is enough.
+          await Promise.allSettled([
+            this.getNetworkInfo(),
+            this.initializeDeviceUpdates(),
+          ]);
 
           this.bInited = true;
           // A success ends the retry chain and forgets the backoff, so a
@@ -2604,9 +2647,51 @@ class Roborock {
         this.vacuums[duid].getStatusIntervall(); // actually start getStatusIntervall()
       }
 
-      initialPolls.push(
-        this.updateDataMinimumData(duid, this.vacuums[duid], robotModel)
-      );
+      // THE TILE WAITS FOR NONE OF THIS, SO IT MUST NOT WAIT FOR ANY OF IT.
+      //
+      // `initializeDeviceUpdates` used to await the whole first parameter
+      // cycle for every robot - 8 serial round-trips per classic robot, each
+      // able to spend its full 10-second timeout on a robot that does not
+      // answer locally - and only then did the caller set `bInited`, fire the
+      // Homebridge callback, and register the Matter accessories. On a home
+      // network that added a few seconds to startup. On a robot with a dead
+      // local link it kept the vacuum out of Apple Home for over a minute
+      // after every restart, for readings of consumable hours and carpet
+      // mode that no tile displays.
+      //
+      // The cycle still runs once at start; it just runs behind the tiles.
+      void this.updateDataMinimumData(
+        duid,
+        this.vacuums[duid],
+        robotModel
+      ).catch((error) => {
+        this.log.debug(
+          `Initial parameter cycle failed for ${this.describeDevice(duid)}: ${
+            /** @type {any} */ (error)?.message || error
+          }`
+        );
+      });
+
+      // What the tile IS waiting for is one real status. The classic poller
+      // is a plain interval, so its first tick used to land 15 seconds after
+      // start and the tile showed the cloud snapshot until then; the B01 loop
+      // already fires its first read immediately for exactly this reason.
+      // Each robot's first status is awaited, in parallel across robots and
+      // capped, so registration waits for fresh state but never for a robot
+      // that will not answer.
+      if (!this.isB01Device(duid)) {
+        initialPolls.push(
+          Promise.race([
+            this.getStatus(duid),
+            new Promise((resolve) => {
+              const timer = setTimeout(resolve, INITIAL_STATUS_WAIT_CAP_MS);
+              if (typeof timer?.unref === "function") {
+                timer.unref();
+              }
+            }),
+          ])
+        );
+      }
     }
 
     await Promise.allSettled(initialPolls);
@@ -3229,6 +3314,37 @@ class Roborock {
    * @param {boolean} isB01
    * @returns {Promise<any>}
    */
+  /**
+   * Is it time to re-read a robot's slow-changing parameters?
+   *
+   * The first cycle after start always qualifies (nothing recorded yet), so a
+   * fresh process still reads everything once - in the background, off the
+   * startup critical path.
+   *
+   * @param {string} duid
+   */
+  isSlowParameterPollDue(duid) {
+    const last = this.lastSlowParameterPollAt.get(duid) ?? 0;
+    return Date.now() - last >= SLOW_PARAMETER_POLL_INTERVAL_MS;
+  }
+
+  /** @param {string} duid */
+  markSlowParameterPoll(duid) {
+    this.lastSlowParameterPollAt.set(duid, Date.now());
+  }
+
+  /**
+   * Forget a robot's slow-lane stamp so the next cycle re-reads everything.
+   * Used when something the slow lane owns is known to have changed - a
+   * schedule written from Apple Home, a diagnostics export asking for fresh
+   * numbers.
+   *
+   * @param {string} duid
+   */
+  requestSlowParameterPoll(duid) {
+    this.lastSlowParameterPollAt.delete(duid);
+  }
+
   async pollParameter(duid, vacuum, method, isB01) {
     if (isB01 && !b01Q7Adapter.canAnswerV1Method(method)) {
       const key = `${duid}:${method}`;
@@ -3491,6 +3607,13 @@ class Roborock {
         await this.pollParameter(duid, vacuum, "get_room_mapping", isB01);
       }
 
+      // Everything below this line is the slow lane. See
+      // SLOW_PARAMETER_POLL_INTERVAL_MS for the measurement behind it.
+      if (!this.isSlowParameterPollDue(duid)) {
+        return;
+      }
+      this.markSlowParameterPoll(duid);
+
       await this.pollParameter(duid, vacuum, "get_consumable", isB01);
 
       await this.pollParameter(duid, vacuum, "get_server_timer", isB01);
@@ -3622,10 +3745,28 @@ class Roborock {
       }
     }
 
-    try {
+    // Same shape as the B01 branch above, for the same reason: with a room
+    // list already persisted from an earlier run, Service Area can expose it
+    // the moment the accessory registers, and the 2 round-trips that refresh
+    // it run behind the tile instead of in front of it. Only a robot the
+    // plugin has never seen rooms for is worth waiting on.
+    const refresh = async () => {
       await vacuum.getParameter(duid, "get_multi_maps_list");
       await vacuum.getParameter(duid, "get_room_mapping");
       await this.cacheMissingMatterServiceAreaRoomMappings(duid, vacuum);
+    };
+
+    if (this.getRoomMappingsForDevice(duid).length > 0) {
+      void refresh().catch((error) => {
+        this.log.debug(
+          `Background room refresh failed for ${duid}: ${error.message || error}`
+        );
+      });
+      return true;
+    }
+
+    try {
+      await refresh();
       return true;
     } catch (error) {
       this.log.debug(
@@ -3882,12 +4023,26 @@ class Roborock {
     this.log.debug(`Length of message queue: ${this.messageQueue.size}`);
   }
 
-  async updateHomeData(homeId) {
+  /**
+   * Refresh the home snapshot - devices, products, local keys - and let every
+   * robot's polling intervals re-check themselves against it.
+   *
+   * @param {string | number} homeId
+   * @param {Record<string, any>} [prefetched] a home payload already fetched
+   *   by the caller. Startup fetched `v2/user/homes/{id}` seconds earlier,
+   *   built the device list from it, and then called this, which fetched
+   *   `user/homes/{id}` again before the Matter accessories could register:
+   *   2 cloud round-trips for one snapshot, back to back, on the critical
+   *   path. With the payload handed in, this consumes it. The periodic
+   *   caller passes nothing and fetches fresh, as before.
+   */
+  async updateHomeData(homeId, prefetched) {
     this.log.debug(`Updating HomeData with homeId: ${homeId}`);
     if (this.api) {
       try {
-        const home = await this.api.get(`user/homes/${homeId}`);
-        const homedata = home.data.result;
+        const homedata = prefetched
+          ? prefetched
+          : (await this.api.get(`user/homes/${homeId}`)).data.result;
 
         if (homedata) {
           this.superviseDeviceIntervals();
@@ -4845,6 +5000,62 @@ class Roborock {
         { label: "sceneMethods", path: scenePath, method: "options" },
         results
       );
+
+      // And that question was answered: the resource allows DELETE and
+      // OPTIONS. It is an answer, and not one of the two the thread's own
+      // decision rule anticipated. The singular scene resource takes exactly
+      // one method that changes anything, and it destroys a schedule rather
+      // than toggling one — so there is no write here to put behind a HomeKit
+      // switch, and a destructive verb aimed at a stranger's live account to
+      // see what happens is not a measurement this project will take.
+      //
+      // That rules out the resource, not the feature. Our own `executeScene`
+      // reaches `user/scene/{id}/execute`, so sub-resources under a scene id
+      // demonstrably exist and carry verbs the scene itself does not. Whether
+      // one of them is the toggle is the last question this instrument can
+      // ask, and it is asked WITH CONTROLS, because on its own an `Allow`
+      // header proves nothing:
+      //
+      //   - `user/scene` — the collection, where a REST API most often keeps
+      //     an update;
+      //   - `user/scene/{id}/enable` — the literal candidate for the nested
+      //     flag the reporter's app flips;
+      //   - `user/scene/device/{duid}` — the POSITIVE control. This run has
+      //     ALREADY read it successfully, so it is mapped beyond doubt. If
+      //     OPTIONS cannot describe even that, the instrument does not see
+      //     routes and every other answer in this set is noise. It is also
+      //     why the control is this route and not `/execute`: a control must
+      //     not be a path whose real verb runs a robot.
+      //   - a path that cannot exist — the NEGATIVE control. If THAT comes
+      //     back with an Allow header, the server answers everything and no
+      //     positive here means anything.
+      //
+      // Together they bound the search rather than extend it: this round
+      // either names a route or shows that no later round would.
+      //
+      // Asking costs nothing that could alter a schedule, and that is
+      // measured rather than assumed: the OPTIONS of the scene resource came
+      // back with an EMPTY body and an Allow header, which is a servlet
+      // container answering the request itself instead of handing it to the
+      // handler behind the path.
+      for (const candidate of [
+        { label: "sceneCollectionMethods", path: "user/scene" },
+        { label: "sceneEnableMethods", path: `${scenePath}/enable` },
+        {
+          label: "mappedRouteControl",
+          path: `user/scene/device/${duid}`,
+        },
+        {
+          label: "absentRouteControl",
+          path: `${scenePath}/${ABSENT_ROUTE_PROBE_SEGMENT}`,
+        },
+      ]) {
+        await this.probeOneCloudScheduleRoute(
+          duid,
+          { ...candidate, method: "options" },
+          results
+        );
+      }
     }
 
     await this.updateRoborockDiagnostics(