homebridge-roborock-matter 3.21.2 → 3.21.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 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. 1707 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 1707 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.3",
   "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,66 @@
+"use strict";
+
+/**
+ * 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);
+  }
+}
+
+module.exports = { describeReplyRefusal };

package/roborockLib/lib/localConnector.js

@@ -5,6 +5,7 @@ const Parser = require("binary-parser").Parser;
 const net = require("net");
 const dgram = require("dgram");
 const { describeDevice } = require("./describeDevice");
+const { describeReplyRefusal } = require("./describeReplyRefusal");
 
 const PORT = 58866;
 const TIMEOUT = 5000; // 5 Sekunden Timeout
@@ -584,17 +585,30 @@ 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(
+          new Error(
+            `The robot refused ${method || "the request"} (local id ${id}): ${refusal}`
+          )
+        );
+        return;
+      }
       resolve(result);
 
       if (this.adapter.deviceNotify !== undefined) {

package/roborockLib/lib/roborock_mqtt_connector.js

@@ -6,6 +6,7 @@ const Parser = require("binary-parser").Parser;
 const zlib = require("zlib");
 const roborockCrypto = require("./roborockCrypto");
 const { describeDevice } = require("./describeDevice");
+const { describeReplyRefusal } = require("./describeReplyRefusal");
 
 const PHOTO_MAGIC = "ROBOROCK";
 const PHOTO_HEADER_MIN_LENGTH = 9;
@@ -364,8 +365,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 +411,19 @@ 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(
+                new Error(
+                  `The robot refused ${pending.method || "the request"} (cloud id ${dps.id}): ${refusal}`
+                )
+              );
+            } 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) {