homebridge-roborock-matter 3.22.0 → 3.23.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 3.23.1
+
+**A Q7 that finished cleaning normally asked its owner to report a fault.**
+
+The maintainer's own `roborock.vacuum.sc05` logged six distinct unexplained `error_code`s in a single day — 2110, 2108, 501, 2102, 2103 and the long-familiar 2105 — every one of them while it was running. It then finished its run and docked at 100%. Nothing was wrong with it at any point.
+
+Read against python-roborock's own per-family fault tables, two of those six are not faults at all:
+
+- **2102** — "Cleaning completed. Returning to the dock." It fires after **every** task.
+- **2100** — "Low battery. Resume cleaning after recharging." The robot announcing normal auto-recharge-and-resume.
+
+The plugin already treats the Q10 family's equivalents this way: upstream marks that family's 501 as hardware-confirmed and firing per completed task, and its 502 as a low-battery resume, and both have been informational here since the families were split. The Q7 family was simply never given its own two. The asymmetry ran the other way too — the Q7 has always silenced 407 ("cleaning in progress, scheduled clean ignored") while the Q10 did not, though upstream marks it hardware-confirmed and "lifecycle, not an error" on that family as well. All three are informational now.
+
+Apple Home was never affected: no B01 fault number appears in the plugin's v1 error table, so an unrecognised one has always published nothing rather than drawing a fault on a healthy tile. What it reached was the log, which named the code once per run and asked the owner to report the number "if the robot really is in trouble right now" — asked, in these two cases, after a clean that had just completed successfully.
+
+**Restraint is the other half of this.** Only a healthy robot's lifecycle notifications are silenced. A scheduled clean that did not run (2003, "Battery level below 20%. Scheduled task canceled") and a clean that ended without reaching its target (2007, 2012) are outcomes an owner may want to know about, so they still surface. And the codes upstream itself cannot explain — 2103, 2105, 2108 and 2110 are bare `fault_NNNN` entries there too — stay exactly as they were. Silencing a number nobody has explained would be a guess, not a translation.
+
+## 3.23.0
+
+**Where a newer robot actually keeps its schedules: a read-only measurement, on request.**
+
+Some newer robots decline the device-side schedule method outright. A Saros 10R (`roborock.vacuum.a144`) answers `-10007 "Not FCC robot"` to every `get_server_timer`, while the legacy `get_timer` honestly answers `[]`. Both answers are true — that robot holds no _device-side_ timers — and yet its owner has three daily schedules, which he showed running under the robot's own Schedule screen in the Roborock app. They are held server-side, on cloud routes the device protocol never touches, and this plugin has only ever asked the robot.
+
+Rather than map a payload nobody here has seen, this release measures it. With debug logging on, the plugin now asks the two candidate cloud routes for each robot once and prints what came back:
+
+- `user/devices/{duid}/jobs` — schedules
+- `user/scene/device/{duid}` — the app's Routines
+
+The answer is also filed under `lastCloudScheduleProbe` in the plugin's diagnostics.
+
+**This is a diagnostic, not a feature, and it is built to stay that way.** It is silent unless debug logging is on, so no installation pays for it uninvited. It only ever issues GETs, so it cannot alter a schedule. It runs once per robot per session, so no poll cadence can turn it into traffic. It cannot throw, because it rides along on a live poll. And credential-shaped fields in the answer are redacted before anything is logged.
+
+It does not yet expose these schedules in HomeKit. It establishes their shape, which is what the next step needs.
+
 ## 3.22.0
 
 **Schedule reads cost far fewer cloud calls, and the queue that makes that possible could deadlock itself.**

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. 1760 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. 1787 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
 
@@ -257,7 +257,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 1760 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 1787 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.22.0",
+  "version": "3.23.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/b01Q7Adapter.js

@@ -197,13 +197,40 @@ function v1FanPowerToWind(family) {
 // Fault codes that are informational rather than active errors — per family,
 // because the 2 families reuse the same numbers for different things.
 //
-// Q7: 407 = "Cleaning in progress. Scheduled cleanup ignored".
-// Q10: 400 = scheduled clean starting, 501 = cleaning completed and returning
+// Q7: 407 = "Cleaning in progress. Scheduled cleanup ignored", 2100 = "Low
+// battery. Resume cleaning after recharging", 2102 = "Cleaning completed.
+// Returning to the dock".
+// Q10: 400 = scheduled clean starting, 407 = cleaning in progress and a due
+// scheduled clean ignored, 501 = cleaning completed and returning
 // (hardware-confirmed upstream, and it fires after EVERY task, so treating it
 // as a fault would leave a Q10 permanently in error), 502 = low-battery
 // resume.
-const INFORMATIONAL_Q7_FAULTS = new Set([0, 407]);
-const INFORMATIONAL_Q10_FAULTS = new Set([0, 400, 501, 502]);
+//
+// EACH FAMILY NEEDS ITS OWN PER-TASK COMPLETION CODE, AND THE Q7 WAS MISSING
+// ITS ONE UNTIL 3.23.1. The 2 sets started from the codes each family had
+// actually been measured emitting, which left them asymmetric in both
+// directions: the Q10 had its after-every-task code (501) while the Q7 did
+// not, and the Q7 had 407 while the Q10 did not — even though upstream marks
+// `YXFault` 407 hardware-confirmed on a physical ss07 and "lifecycle, not an
+// error".
+//
+// The Q7 gap surfaced on the maintainer's own `sc05`, which logged 6 distinct
+// unmapped codes in a single day (2110, 2108, 501, 2102, 2103, 2105), every
+// one of them mid-run, and then finished and docked at 100 % with nothing
+// wrong. Read against python-roborock's `B01Fault`, 2 of the 6 are not faults:
+// 2102 fires after every task, and 2100 is the robot announcing normal
+// auto-recharge-and-resume — the Q7 analogue of the Q10's 502.
+//
+// WHAT IS DELIBERATELY LEFT SURFACING, BECAUSE SILENCE IS NOT FREE. Only a
+// healthy robot's lifecycle notifications belong here. Q7's 2003 ("Battery
+// level below 20%. Scheduled task canceled") and 2007/2012 ("Unable to reach
+// the target. Cleaning ended") are outcomes a user may want to know about — a
+// scheduled clean that did not run is not noise. And the codes upstream has no
+// description for at all (2103, 2105, 2108, 2110 are bare `fault_NNNN` there)
+// stay put: silencing a number nobody has explained would be a guess, not a
+// translation.
+const INFORMATIONAL_Q7_FAULTS = new Set([0, 407, 2100, 2102]);
+const INFORMATIONAL_Q10_FAULTS = new Set([0, 400, 407, 501, 502]);
 
 /** @param {string} family */
 function informationalFaults(family) {

package/roborockLib/lib/vacuum.js

@@ -980,6 +980,19 @@ class vacuum {
           this.adapter.log.debug(
             `Roborock ${parameter} diagnostic for ${duid}: ${JSON.stringify(this.adapter.compactDiagnosticPayload(timers))}`
           );
+
+          // Both device-side timer methods have now answered for this robot,
+          // so this is the one moment where their answers can be compared with
+          // what the cloud holds (#22). The probe is read-only, debug-only and
+          // runs once per robot per session; it must not be able to fail the
+          // poll it is riding along on.
+          try {
+            await this.adapter.probeCloudScheduleRoutes?.(duid);
+          } catch (error) {
+            this.adapter.log.debug(
+              `Roborock cloud schedule probe for ${duid} could not run: ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
         }
       } else if (parameter == "get_photo") {
         const photoresponse = await sendParameterRequest(

package/roborockLib/roborockAPI.js

@@ -4540,6 +4540,113 @@ class Roborock {
     return await this.vacuums[duid].getServerTimers(duid, options);
   }
 
+  /**
+   * Ask the Roborock CLOUD where a robot's schedules live (#22).
+   *
+   * Some newer robots decline the device-side `get_server_timer` outright —
+   * a Saros 10R (`roborock.vacuum.a144`) answers `-10007 "Not FCC robot"` on
+   * every attempt, while the legacy `get_timer` honestly answers `[]`. Both
+   * answers are true: that robot has no DEVICE-side timers. Its owner
+   * demonstrably has three daily schedules in the app, under the robot's own
+   * Schedule screen, so they are held server-side on routes the device
+   * protocol knows nothing about.
+   *
+   * This is a MEASUREMENT, not a feature. It reads the two candidate routes
+   * and prints what came back, so the next release can map a real payload
+   * instead of a guess. Deliberately constrained:
+   *
+   * - **Debug only.** Silent for every installation that has not asked for it.
+   * - **GET only.** Nothing here can change a schedule. The Hawk interceptor
+   *   signs an empty body (`roborockAPI.js` request interceptor), so a
+   *   body-bearing write would not authenticate anyway — a read does.
+   * - **Once per robot per session,** so a poll cadence cannot turn it into
+   *   traffic.
+   * - **Never throws.** A probe that breaks startup would be worse than the
+   *   missing feature it investigates.
+   *
+   * @param {string} duid Robot to probe.
+   * @returns {Promise<Record<string, unknown> | undefined>} Per-route outcome,
+   *   or `undefined` when the probe did not run.
+   */
+  async probeCloudScheduleRoutes(duid) {
+    if (!duid || !this.config?.debug || !this.api) {
+      return undefined;
+    }
+
+    if (!this._probedCloudScheduleRoutes) {
+      this._probedCloudScheduleRoutes = new Set();
+    }
+
+    if (this._probedCloudScheduleRoutes.has(duid)) {
+      return undefined;
+    }
+
+    this._probedCloudScheduleRoutes.add(duid);
+
+    // Route names and shapes cross-checked against python-roborock's
+    // `get_schedules` and `get_scenes`. Our own `executeScene` already talks to
+    // `user/scene/{id}/execute` on this same client, which is what makes the
+    // base URL and the leading-slash convention here a measured fact rather
+    // than a hope.
+    const routes = [
+      { label: "schedules", path: `user/devices/${duid}/jobs` },
+      { label: "scenes", path: `user/scene/device/${duid}` },
+    ];
+
+    /** @type {Record<string, unknown>} */
+    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;
+
+        results[route.label] = {
+          path: route.path,
+          ok: true,
+          response: payload,
+        };
+
+        this.log.debug(
+          `Roborock cloud schedule probe for ${this.describeDevice(duid)} — GET ${route.path} answered: ${JSON.stringify(
+            this.compactDiagnosticPayload(payload)
+          )}`
+        );
+      } 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}`
+        );
+      }
+    }
+
+    await this.updateRoborockDiagnostics(
+      String(duid),
+      "lastCloudScheduleProbe",
+      results
+    );
+
+    return results;
+  }
+
   async updateServerTimer(duid, timerId, enabled, options = {}) {
     if (!this.vacuums[duid]) {
       throw new Error(