homebridge-roborock-matter 3.21.2 → 3.21.4

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 3.21.4
+
+**The refusal 3.21.3 made visible was then reported as a plugin crash, twice per poll cycle, forever.**
+
+DSimeone1989 ran 3.21.3 and sent the line it was written to produce. His Saros 10R answers:
+
+```
+Cloud message with protocol 102 and id 5 received. No result; reply was {"id":5,"error":{"code":-10007,"message":"Not FCC robot"}}
+```
+
+That is the answer: the robot's firmware declines `get_server_timer` outright. The fix worked. What it also produced was this, every poll cycle, for a robot behaving exactly as intended:
+
+```
+Failed to execute get_server_timer on robot Rocky (roborock.vacuum.a144): Error: The robot refused get_server_timer (cloud id 5): Not FCC robot (code -10007)
+    at MqttClient.<anonymous> (…/roborock_mqtt_connector.js:420:17)
+    at MqttClient.emit (node:events:514:28)
+    … eight more frames
+```
+
+**A stated refusal was thrown as a bare `Error`.** It carried no code, so it matched none of `catchError`'s calm branches and fell through to the final `else`, which logs `error.stack`. The stack names our own MQTT handler and describes nothing that went wrong. Because the schedule coordinator and the generic poll both ask, it was emitted twice per cycle, indefinitely.
+
+**A refusal the robot spelled out is now a capability fact, not a failure.** It is tagged where it is constructed, carries the robot's own error code, is reported once per robot per method so the owner learns why a feature is missing, and then drops to debug. It never carries a stack trace and never escalates to `log.error`.
+
+Deliberately narrow: transport failures are untouched. A robot that is unreachable, a dead cloud link and a missing local socket all keep their existing loud paths — quieting those would tell an owner nothing is wrong while their robot is offline.
+
+## 3.21.3
+
+**A robot that refuses a request was reported as a robot that answered nothing.**
+
+DSimeone1989 reported in #22 that his Roborock app schedules never appear. His Saros 10R (`roborock.vacuum.a144`) answers `get_status`, `get_timer`, `get_carpet_mode` and `get_water_box_custom_mode` over the cloud in the same second, and refuses `get_server_timer`. All the plugin could say about it was:
+
+```
+Cloud message with protocol 102 and id 10 received. Result: undefined
+Schedule discovery for 1MDui…: type=undefined, value=undefined
+Unable to reliably read Roborock schedules …: get_server_timer returned undefined
+```
+
+**The reason was decoded and then dropped.** A Roborock reply carries its payload in `result`. Both connectors handed `result` straight to the waiting promise without asking whether the reply had one, so a refusal resolved as a success whose value happened to be `undefined` — the same value a caller sees for a reply the parser could not read, and indistinguishable from a genuine empty answer. Whatever the robot said about why now never reached a log line, an error, or the user.
+
+**A reply with no `result` is no longer treated as an empty answer.** When the robot spells out a refusal, the waiting caller gets it as an error naming the method and the robot's own words, over both the cloud and the LAN socket. When there is no result and no stated reason, the debug log prints the reply itself instead of the word `undefined`.
+
+Deliberately narrow: a reply that carries a `result` is untouched, and an empty array stays an authoritative "you have no timers" rather than becoming an error. Only a refusal the robot actually stated changes behaviour.
+
+11 new tests, red against the old code on both halves.
+
 ## 3.21.2
 
 **Driving through a room still marked it cleaned. 3.19.7 was meant to fix that and did not.**

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. 1695 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. 1720 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 1695 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 1720 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.21.2",
+  "version": "3.21.4",
   "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/describeReplyRefusal.js

@@ -0,0 +1,120 @@
+"use strict";
+
+/**
+ * Marks an error as "the robot answered and declined", as opposed to anything
+ * that went wrong on our side or on the wire. `catchError` keys its calm
+ * branch on this.
+ */
+const METHOD_REFUSED_CODE = "ROBOROCK_METHOD_REFUSED";
+
+/**
+ * A Roborock reply carries its payload in `result`. A reply that has an `id`
+ * but no `result` at all is not an empty success — the robot took the request
+ * and declined it, and when it says why, it says so in `error`.
+ *
+ * Both connectors used to hand `result` straight to the waiting promise, so
+ * such a reply resolved with `undefined` and the refusal was dropped one line
+ * before anyone could read it. Issue #22 is what that costs: a Saros 10R
+ * (`roborock.vacuum.a144`) answers every other method and refuses
+ * `get_server_timer`, and the only thing the plugin could tell its owner was
+ * `get_server_timer returned undefined` — the same sentence it would print for
+ * a timeout, a parser gap or a firmware that has no such method.
+ *
+ * Kept deliberately narrow: a reply that carries a `result` is never touched,
+ * and a resultless reply with no error field still resolves as before. Only a
+ * refusal the robot spelled out is turned into a rejection.
+ *
+ * @param {unknown} reply decoded reply body (protocol 102 over cloud, 4 over LAN)
+ * @returns {string|null} the robot's own words, or null when there is no refusal to report
+ */
+function describeReplyRefusal(reply) {
+  if (!reply || typeof reply !== "object") {
+    return null;
+  }
+
+  if (typeof reply.result !== "undefined") {
+    return null;
+  }
+
+  const error = reply.error;
+
+  if (error === undefined || error === null || error === "") {
+    return null;
+  }
+
+  if (typeof error !== "object") {
+    return String(error);
+  }
+
+  const code = error.code;
+  const message = error.message;
+  const hasCode = code !== undefined && code !== null;
+  const hasMessage = typeof message === "string" && message.length > 0;
+
+  if (hasCode && hasMessage) {
+    return `${message} (code ${code})`;
+  }
+  if (hasMessage) {
+    return message;
+  }
+  if (hasCode) {
+    return `code ${code}`;
+  }
+
+  // An error object in a shape nobody here has seen yet is still worth more
+  // to the reader than `undefined`.
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+/**
+ * A robot that answers a request and declines it has told us a fact about
+ * itself. It is not a plugin failure, and it must not be rendered as one.
+ *
+ * 3.21.3 made the refusal visible but threw it as a bare `Error`, so it
+ * carried no code and matched none of `catchError`'s calm branches. It landed
+ * on the final `else` and was logged with `error.stack` — an ERROR line plus a
+ * ten-frame JavaScript stack trace pointing at our own MQTT handler, twice per
+ * poll cycle, for as long as the robot is on the account. Issue #22's Saros 10R
+ * refuses `get_server_timer` with `Not FCC robot (code -10007)` on every poll:
+ * the stack trace describes nothing that went wrong, and the repetition buries
+ * real errors.
+ *
+ * Tagging the error at the point of construction is what puts it on a calm
+ * branch by construction, rather than leaving every caller to recognise a
+ * refusal from its prose — the failure mode `getTransientErrorKind` already
+ * documents.
+ *
+ * @param {string} message human-readable refusal, already naming method and id
+ * @param {unknown} reply the decoded reply the refusal came from
+ * @returns {Error & { code: string, robotErrorCode?: unknown }}
+ */
+function createRefusalError(message, reply) {
+  const error =
+    /** @type {Error & { code: string, robotErrorCode?: unknown }} */ (
+      new Error(message)
+    );
+  error.code = METHOD_REFUSED_CODE;
+
+  const replyError =
+    reply && typeof reply === "object"
+      ? /** @type {any} */ (reply).error
+      : null;
+  if (replyError && typeof replyError === "object") {
+    const code = /** @type {any} */ (replyError).code;
+    if (code !== undefined && code !== null) {
+      error.robotErrorCode = code;
+    }
+  }
+
+  return error;
+}
+
+module.exports = {
+  describeReplyRefusal,
+  createRefusalError,
+  METHOD_REFUSED_CODE,
+};

package/roborockLib/lib/localConnector.js

@@ -5,6 +5,10 @@ const Parser = require("binary-parser").Parser;
 const net = require("net");
 const dgram = require("dgram");
 const { describeDevice } = require("./describeDevice");
+const {
+  describeReplyRefusal,
+  createRefusalError,
+} = require("./describeReplyRefusal");
 
 const PORT = 58866;
 const TIMEOUT = 5000; // 5 Sekunden Timeout
@@ -584,17 +588,31 @@ class localConnector {
     const result = parsed_102.result;
 
     if (this.adapter.pendingRequests.has(id)) {
+      const refusal = describeReplyRefusal(parsed_102);
       this.adapter.log.debug(
-        `Local message with protocol 4 and id ${id} received. Result: ${JSON.stringify(result)}`
+        typeof result === "undefined"
+          ? `Local message with protocol 4 and id ${id} received. No result; reply was ${JSON.stringify(parsed_102)}`
+          : `Local message with protocol 4 and id ${id} received. Result: ${JSON.stringify(result)}`
       );
-      const { resolve, timeout } = this.adapter.pendingRequests.get(id);
+      const { resolve, reject, timeout, method } =
+        this.adapter.pendingRequests.get(id);
       this.adapter.clearTimeout(timeout);
       this.adapter.pendingRequests.delete(id);
       // Proof that this socket is not mute, so any run of timeouts counted
-      // against it starts over.
+      // against it starts over. A refusal still proves the socket answers —
+      // it is the request that failed, not the transport.
       if (this.adapter.noteLocalRequestSucceeded) {
         this.adapter.noteLocalRequestSucceeded(duid);
       }
+      if (refusal && typeof reject === "function") {
+        reject(
+          createRefusalError(
+            `The robot refused ${method || "the request"} (local id ${id}): ${refusal}`,
+            parsed_102
+          )
+        );
+        return;
+      }
       resolve(result);
 
       if (this.adapter.deviceNotify !== undefined) {

package/roborockLib/lib/roborock_mqtt_connector.js

@@ -6,6 +6,10 @@ const Parser = require("binary-parser").Parser;
 const zlib = require("zlib");
 const roborockCrypto = require("./roborockCrypto");
 const { describeDevice } = require("./describeDevice");
+const {
+  describeReplyRefusal,
+  createRefusalError,
+} = require("./describeReplyRefusal");
 
 const PHOTO_MAGIC = "ROBOROCK";
 const PHOTO_HEADER_MIN_LENGTH = 9;
@@ -364,8 +368,15 @@ class roborock_mqtt_connector {
             // Runs for every cloud message; only pay the stringify cost
             // when debug logging is actually enabled.
             if (this.adapter.config.debug) {
+              // A reply with no `result` used to print "Result: undefined",
+              // which reads like a robot that said nothing. It said something;
+              // it just did not say it in `result`. Print the reply itself so
+              // the refusal is on the record even when nobody is waiting for
+              // this id any more.
               this.adapter.log.debug(
-                `Cloud message with protocol 102 and id ${dps.id} received. Result: ${JSON.stringify(dps.result)}`
+                typeof dps.result === "undefined"
+                  ? `Cloud message with protocol 102 and id ${dps.id} received. No result; reply was ${JSON.stringify(dps)}`
+                  : `Cloud message with protocol 102 and id ${dps.id} received. Result: ${JSON.stringify(dps.result)}`
               );
             }
             if (typeof dps.result !== "undefined") {
@@ -403,7 +414,20 @@ class roborock_mqtt_connector {
           if (shouldResolveOn102(pending, dps.result)) {
             this.adapter.clearTimeout(pending.timeout);
             this.adapter.pendingRequests.delete(dps.id);
-            pending.resolve(dps.result);
+            // A refusal is a failed request, not an empty one. Resolving it
+            // with `undefined` is indistinguishable from a real empty answer
+            // to every caller upstream — see describeReplyRefusal.
+            const refusal = describeReplyRefusal(dps);
+            if (refusal) {
+              pending.reject(
+                createRefusalError(
+                  `The robot refused ${pending.method || "the request"} (cloud id ${dps.id}): ${refusal}`,
+                  dps
+                )
+              );
+            } else {
+              pending.resolve(dps.result);
+            }
           }
           // protocol 300 seems to be for get_photo 0 only. get_photo 0 is for large images. 1 is for small images.
         } else if (data.protocol == 300) {

package/roborockLib/roborockAPI.js

@@ -20,6 +20,7 @@ const RRMapParser = require("./lib/RRMapParser");
 const messageQueueHandler =
   require("./lib/messageQueueHandler").messageQueueHandler;
 const roborockCrypto = require("./lib/roborockCrypto");
+const { METHOD_REFUSED_CODE } = require("./lib/describeReplyRefusal");
 const b01Q7Adapter = require("./lib/b01Q7Adapter");
 
 // v1 states in which the robot is actively doing something and state
@@ -4316,6 +4317,33 @@ class Roborock {
         return;
       }
 
+      // A refusal the robot spelled out is a fact about that robot, not a
+      // plugin failure: nothing on our side went wrong, so there is no stack
+      // worth printing, and the same robot will keep saying the same thing on
+      // every poll. Say it once so the owner learns why a feature is missing,
+      // then keep quiet. (Issue #22: a Saros 10R refuses `get_server_timer`
+      // with "Not FCC robot", which 3.21.3 rendered as an ERROR plus a
+      // ten-frame stack trace twice per poll cycle, indefinitely.)
+      if (
+        error &&
+        typeof error === "object" &&
+        error.code === METHOD_REFUSED_CODE
+      ) {
+        if (!this._reportedMethodRefusals) {
+          this._reportedMethodRefusals = new Set();
+        }
+        const seenKey = `${duid || "unknown"}:${attribute || "unknown"}`;
+        if (this._reportedMethodRefusals.has(seenKey)) {
+          this.log.debug(errorText);
+        } else {
+          this._reportedMethodRefusals.add(seenKey);
+          this.log.warn(
+            `${this.describeDevice(duid)} (${model || "unknown model"}) refuses ${attribute}: ${error.message}. This is the robot's own answer, not a plugin failure; it will not be reported again this session.`
+          );
+        }
+        return;
+      }
+
       const transientErrorKind =
         (typeof error === "object" && error?.transientKind) ||
         this.getTransientErrorKind(errorText);