homebridge-roborock-matter 3.24.2 → 3.25.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 3.25.1
+
+**The schedule probe kept the status code of a refused route and threw away the server's explanation of it — so the route it was built to measure came back saying nothing.**
+
+3.25.0 shipped a read of the singular cloud scene resource, on the reasoning that a 200 makes it a candidate for a later write and a 404 rules it out for free. Issue #22's reporter ran it, and the answer was neither: `400`.
+
+That is the one outcome the probe had nothing to say about. A 404 means there is no such resource. A 400 means the server routed the request and then rejected it — which is a statement about the request, not about whether the route exists. Whether it means "unknown route", "wrong method" or "that scene is not yours" lives in the body the server sent back, and axios flattens every one of those into the same sentence: `Request failed with status code 400`.
+
+The probe recorded that sentence and dropped the body. So a measurement that took a release to ship, and somebody else's live account to run, produced a number and no reading.
+
+A refused route now keeps what the server actually said, in the log and in the diagnostics record, under the same compaction and redaction a successful answer already gets — an error envelope is no more ours to print blindly than a normal one. This holds for every route the probe reads, not just the one it was found on.
+
+No behaviour outside the diagnostic changes, and the probe is still debug-only, GET-only, once per robot per session, and unable to throw.
+
+## 3.25.0
+
+**The schedule probe now measures whether a cloud schedule is a resource the plugin could ever write to.**
+
+Issue #22's reporter switched two of his three app schedules off, restarted, and sent the reading without saying which two. The log named them, and it named something more useful than that: every scene-level `enabled` stayed `true`, and the flag his app had actually flipped was `enabled` inside each schedule's own TIMER trigger, nested a level deeper. So a HomeKit switch over these schedules would have to rewrite that nested field — not the scene's own.
+
+Knowing what to write is not knowing where to send it. The only write route measured on this client is `user/scene/{id}/execute`, which runs a scene rather than enabling one, and a guessed write endpoint against somebody's live account does not fail politely — it edits or deletes a schedule they rely on.
+
+So this release measures the one remaining thing that costs nothing: whether the singular scene resource answers at all. When the device route reports a timer-driven scene, the probe reads that one scene by id. A resource that answers GET is the only defensible candidate for a later write, and its answer is the payload shape such a write would have to send back; a 404 rules it out for free.
+
+The constraints are unchanged, because they are what make shipping a measurement to thousands of installations defensible: debug logging only, GET only, once per robot per session, cannot throw, credential-shaped fields redacted. Exactly one scene is read rather than all of them — this is a shape measurement, not an inventory, and an account with nine schedules must not become nine requests.
+
+Still a diagnostic, still not a feature. Reading these schedules is solved; switching them is not, and it will not be built on a guess.
+
 ## 3.24.2
 
 **Shutting down while LAN discovery was listening left a UDP socket open and every caller waiting on it hung.**

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. 1831 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. 1847 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 1831 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 1847 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/config.schema.json

@@ -76,7 +76,7 @@
       },
       "enableLiveRoomTracking": {
         "title": "Enable Live Room Tracking",
-        "description": "While a B01/Q7-series robot is actively cleaning, periodically fetch the robot's map position (every ~20 seconds) and report the room it is physically inside as the current Matter Service Area, so controllers like Apple Home can show 'cleaning in <room>'. Requires Matter Room/Map Selection. Disable to avoid the extra map traffic.",
+        "description": "While a robot is actively cleaning, periodically fetch the robot's map position (every ~10 seconds) and report the room it is physically inside as the current Matter Service Area, so controllers like Apple Home can show 'cleaning in <room>'. Both generations are covered: B01/Q7 robots via the SCMap position, classic S/Q-series robots via the RRMap segment grid. Requires Matter Room/Map Selection. Disable to avoid the extra map traffic.",
         "type": "boolean",
         "default": true
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "3.24.2",
+  "version": "3.25.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/parseCloudSceneSchedules.js

@@ -155,11 +155,25 @@ function describeCron(cron) {
  */
 
 /**
+ * Which of the two enable flags the app actually uses is MEASURED, not
+ * assumed, and it matters to anything that would ever write one back.
+ *
+ * The reporter in issue #22 switched two of his three schedules off in the
+ * Roborock app and sent the probe's reading. Every scene-level `enabled`
+ * stayed `true`; the flag that changed was `enabled` inside each TIMER
+ * trigger's own nested `param` string. So the app toggles the TRIGGER, and a
+ * schedule switch would have to rewrite that nested JSON rather than the
+ * scene's own field.
+ *
+ * Both flags are still modelled, because a scene disabled at scene level is a
+ * state the cloud can express and `active` has to account for it.
+ *
  * @typedef {object} CloudSceneSchedule
  * @property {string} id scene id
  * @property {string|null} name scene name as shown in the app
  * @property {string|null} type scene type, e.g. `WORKFLOW`
- * @property {boolean} enabled scene-level enable flag
+ * @property {boolean} enabled scene-level enable flag — measured to stay
+ *   `true` when the app switches a schedule off
  * @property {boolean} active scene enabled AND at least one timer enabled
  * @property {CloudSceneTrigger[]} triggers timer triggers on the scene
  * @property {CloudSceneAction[]} actions device actions the scene performs

package/roborockLib/roborockAPI.js

@@ -23,6 +23,7 @@ const roborockCrypto = require("./lib/roborockCrypto");
 const { METHOD_REFUSED_CODE } = require("./lib/describeReplyRefusal");
 const {
   summariseCloudSceneSchedules,
+  parseCloudSceneSchedules,
 } = require("./lib/parseCloudSceneSchedules");
 const b01Q7Adapter = require("./lib/b01Q7Adapter");
 
@@ -4590,6 +4591,102 @@ class Roborock {
     }
   }
 
+  /**
+   * GET one candidate cloud schedule route, record it, and log what came back.
+   *
+   * Extracted so that every route — the two candidates and the singular scene
+   * resource probed after them — shares one error path. It never throws: this
+   * rides along on a live poll, and a route that does not exist is a
+   * measurement rather than a fault, so a failure is recorded and logged at
+   * debug level instead of surfacing.
+   *
+   * @param {string} duid robot the reading belongs to
+   * @param {{label: string, path: string}} route label to file it under, and
+   *   the path to read
+   * @param {Record<string, unknown>} results accumulator, written in place
+   * @returns {Promise<void>}
+   */
+  async probeOneCloudScheduleRoute(duid, route, results) {
+    try {
+      const response = await this.api.get(route.path);
+      // Roborock wraps most answers in `{api,result,status,success}`. Keep
+      // the envelope only when there is no `result` to unwrap, so the log
+      // shows the payload rather than the wrapper.
+      const payload =
+        response?.data?.result === undefined
+          ? response?.data
+          : response.data.result;
+
+      // Decode BEFORE compacting. `compactDiagnosticPayload` caps strings at
+      // 500 characters and arrays at 8 entries; measured on the real scenes
+      // answer, that cut every schedule mid-task and would drop a ninth
+      // schedule entirely. The raw answer is the only place the measurement
+      // is intact.
+      const decoded = this.describeCloudScheduleAnswer(payload);
+
+      results[route.label] = {
+        path: route.path,
+        ok: true,
+        response: payload,
+        schedules: decoded.length > 0 ? decoded : undefined,
+      };
+
+      this.log.debug(
+        `Roborock cloud schedule probe for ${this.describeDevice(duid)} — GET ${route.path} answered: ${JSON.stringify(
+          this.compactDiagnosticPayload(payload)
+        )}`
+      );
+
+      if (decoded.length > 0) {
+        const [headline, ...entries] = decoded;
+        this.log.debug(
+          `Roborock cloud schedule probe for ${this.describeDevice(duid)} — ${route.path} carries ${headline}:`
+        );
+        for (const entry of entries) {
+          this.log.debug(
+            `Roborock cloud schedule probe for ${this.describeDevice(duid)} —   ${entry}`
+          );
+        }
+      }
+    } catch (error) {
+      const status = error?.response?.status;
+      const message =
+        error instanceof Error ? error.message : String(error ?? "");
+
+      // The status alone does not measure the route, and the reporter's answer
+      // is why: `user/scene/{id}` came back `400`, not `404`. A 404 would have
+      // ruled the resource out; a 400 says the server routed the request and
+      // then rejected it, and only its own body says whether that is "no such
+      // route", "wrong method" or "that scene is not yours". Axios flattens all
+      // of it into `Request failed with status code 400`, which carries nothing.
+      //
+      // So keep the body. It goes through the same compaction and redaction as
+      // a successful answer, because an error envelope is no more ours to print
+      // blindly than a successful one.
+      const body = error?.response?.data;
+      const describedBody =
+        body === undefined ? undefined : this.compactDiagnosticPayload(body);
+
+      results[route.label] = {
+        path: route.path,
+        ok: false,
+        status: status ?? null,
+        error: message,
+        body: describedBody,
+      };
+
+      this.log.debug(
+        `Roborock cloud schedule probe for ${this.describeDevice(duid)} — GET ${route.path} failed${
+          status ? ` with HTTP ${status}` : ""
+        }: ${message}${
+          describedBody === undefined
+            ? ""
+            : ` — the server said: ${JSON.stringify(describedBody)}`
+        }`
+      );
+    }
+  }
+
   async probeCloudScheduleRoutes(duid) {
     if (!duid || !this.config?.debug || !this.api) {
       return undefined;
@@ -4619,65 +4716,35 @@ class Roborock {
     const results = {};
 
     for (const route of routes) {
-      try {
-        const response = await this.api.get(route.path);
-        // Roborock wraps most answers in `{api,result,status,success}`. Keep
-        // the envelope only when there is no `result` to unwrap, so the log
-        // shows the payload rather than the wrapper.
-        const payload =
-          response?.data?.result === undefined
-            ? response?.data
-            : response.data.result;
-
-        // Decode BEFORE compacting. `compactDiagnosticPayload` caps strings at
-        // 500 characters and arrays at 8 entries; measured on the real scenes
-        // answer, that cut every schedule mid-task and would drop a ninth
-        // schedule entirely. The raw answer is the only place the measurement
-        // is intact.
-        const decoded = this.describeCloudScheduleAnswer(payload);
-
-        results[route.label] = {
-          path: route.path,
-          ok: true,
-          response: payload,
-          schedules: decoded.length > 0 ? decoded : undefined,
-        };
-
-        this.log.debug(
-          `Roborock cloud schedule probe for ${this.describeDevice(duid)} — GET ${route.path} answered: ${JSON.stringify(
-            this.compactDiagnosticPayload(payload)
-          )}`
-        );
-
-        if (decoded.length > 0) {
-          const [headline, ...entries] = decoded;
-          this.log.debug(
-            `Roborock cloud schedule probe for ${this.describeDevice(duid)} — ${route.path} carries ${headline}:`
-          );
-          for (const entry of entries) {
-            this.log.debug(
-              `Roborock cloud schedule probe for ${this.describeDevice(duid)} —   ${entry}`
-            );
-          }
-        }
-      } catch (error) {
-        const status = error?.response?.status;
-        const message =
-          error instanceof Error ? error.message : String(error ?? "");
+      await this.probeOneCloudScheduleRoute(duid, route, results);
+    }
 
-        results[route.label] = {
-          path: route.path,
-          ok: false,
-          status: status ?? null,
-          error: message,
-        };
+    // A HomeKit switch over these schedules has to WRITE, and the only write
+    // route measured on this client is `user/scene/{id}/execute`, which RUNS a
+    // scene rather than enabling one. The reporter's off-and-on measurement
+    // narrowed what such a write would have to change — the `enabled` flag
+    // inside the TIMER trigger, not the scene-level one — but not where to
+    // send it, and a guessed write endpoint against a live account does not
+    // fail politely.
+    //
+    // So measure the one thing that costs nothing: whether the singular scene
+    // resource answers at all. A REST resource that answers GET is the only
+    // defensible candidate for a later write, its answer is the payload shape
+    // such a write would have to send back, and a 404 rules it out for free.
+    //
+    // Exactly one scene, deliberately: this is a shape measurement, not an
+    // inventory, and an account with nine schedules must not become nine
+    // requests. It stays inside the once-per-robot-per-session guard above.
+    const [firstSchedule] = parseCloudSceneSchedules(
+      /** @type {{response?: unknown}} */ (results.scenes)?.response
+    );
 
-        this.log.debug(
-          `Roborock cloud schedule probe for ${this.describeDevice(duid)} — GET ${route.path} failed${
-            status ? ` with HTTP ${status}` : ""
-          }: ${message}`
-        );
-      }
+    if (firstSchedule) {
+      await this.probeOneCloudScheduleRoute(
+        duid,
+        { label: "scene", path: `user/scene/${firstSchedule.id}` },
+        results
+      );
     }
 
     await this.updateRoborockDiagnostics(
@@ -5290,7 +5357,7 @@ class Roborock {
    * Fetch the current SCMap and derive which room the robot is physically
    * inside (currentPose ray-cast against the per-room boundary chains).
    * Called from the B01 status loop while the robot is actively cleaning;
-   * throttled on attempts (min 20s gap), single-flight per device, and
+   * throttled on attempts (min 10s gap), single-flight per device, and
    * disabled entirely with the enableLiveRoomTracking=false config option.
    *
    * On a room CHANGE the cached last v1 status is re-broadcast through