homebridge-roborock-matter 3.24.2 → 3.25.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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. 1838 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 1838 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.24.2",
+  "version": "3.25.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/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,83 @@ 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 ?? "");
+
+      results[route.label] = {
+        path: route.path,
+        ok: false,
+        status: status ?? null,
+        error: message,
+      };
+
+      this.log.debug(
+        `Roborock cloud schedule probe for ${this.describeDevice(duid)} — GET ${route.path} failed${
+          status ? ` with HTTP ${status}` : ""
+        }: ${message}`
+      );
+    }
+  }
+
   async probeCloudScheduleRoutes(duid) {
     if (!duid || !this.config?.debug || !this.api) {
       return undefined;
@@ -4619,65 +4697,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(