homebridge-roborock-matter 3.4.2 → 3.4.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 3.4.3
+
+**A robot with no model profile no longer fills your log with the same request forever.** Models the plugin has no dedicated profile for — the Saros 10 in [#8](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/8), the Qrevo CurvX in [#6](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/6) — run on the capability-derived path, which works, but every status field the profile did not name produced its own `Unsupported attribute … Please contact the dev` warning on every status poll. For the Saros 10 that is eight warnings a minute: about 11,500 requests a day to report the same eight fields. Both issues were promised this would be quietened.
+
+- **Each unmapped field is now reported once per robot, in one line, and then never again.** A firmware's set of unmapped fields is fixed, so a repeat says nothing a user can act on. Repeats go to debug. A time-based throttle was the wrong shape: it would bring the message back forever, which is the complaint rather than the fix.
+- **A field nobody has seen before still gets through.** If a robot starts sending something new after hours of uptime, it is reported on its own — quietening the noise must not also hide the signal, since these lines are the raw material for a model profile.
+- **The line is now usable in a model report.** It names the robot and model, lists every field with its value, and says plainly that control, battery, rooms and state do not depend on them. Object values are serialised instead of arriving as `[object Object]`, which is what `cleaning_info` looked like in #8 — the one field where the shape was the interesting part.
+- **Two startup tests no longer assert on the clock.** Both checked that per-robot probes run concurrently by timing them against a 180 ms budget — and on a quiet machine they finish in ~65 ms, so the assertion could only ever fail for a reason it was not testing. A scheduling hiccup was enough to fail a build with the concurrency perfectly correct. The check was also redundant: serialized probes give a peak concurrency of 1, which the neighbouring assertion already catches exactly. They now assert the property directly — every probe started before the first one finished — which holds on any machine under any load. Same defect 3.4.2 removed from the B01 full-chain simulation.
+- **The log-naming rule from 3.3.2 was itself only half enumerated.** It listed three files by hand, and the files it left out held twelve log lines still printing a bare 22-character duid — including `Device <duid> is offline.`, which is exactly the line someone quotes when asking why a robot dropped out. A hand-written file list is the same mistake as a hand-written line list, one level up. The rule now discovers the file list from the source tree, so a new file is covered the moment it exists, and all twelve lines now name the robot.
+
 ## 3.4.2
 
 **Q7-series robots are no longer asked for things they cannot answer.** Every restart, each Q7-generation robot (`roborock.vacuum.sc05`, `ss07`, and the rest of the B01 family) logged an unsupported-method notice — most visibly for `get_water_box_custom_mode`, and also for `get_timer` and `get_carpet_clean_mode`. The message blamed the robot, and the robot was never involved: the plugin's own send path rejects v1-only requests for B01 devices before anything reaches the network, and the poller then recorded that self-rejection as though the robot had answered it.

package/package.json

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

@@ -0,0 +1,33 @@
+"use strict";
+
+/**
+ * Friendly name for a robot, for use in user-visible log lines.
+ *
+ * `roborockAPI` has had its own `describeDevice` for a while, but the library
+ * modules underneath it only have the adapter reference, so their log lines
+ * kept printing the raw duid — a 22-character opaque string that tells the
+ * reader nothing, in exactly the messages people are asked to paste into an
+ * issue. This is the shared wrapper so the answer to "how is a robot named to
+ * a human" lives in one place rather than being re-decided per module.
+ *
+ * The fallback matters: these lines are reachable before HomeData has been
+ * fetched, and a log line is worth more than a crash, so an adapter without
+ * the helper (or a robot with no cached name) degrades to the duid.
+ *
+ * @param {{ describeDevice?: (duid: string) => string } | null | undefined} adapter
+ * @param {string} duid
+ * @returns {string}
+ */
+function describeDevice(adapter, duid) {
+  if (adapter && typeof adapter.describeDevice === "function") {
+    const name = adapter.describeDevice(duid);
+
+    if (typeof name === "string" && name.length > 0) {
+      return name;
+    }
+  }
+
+  return String(duid);
+}
+
+module.exports = { describeDevice };

package/roborockLib/lib/message.js

@@ -4,6 +4,7 @@ const crypto = require("crypto");
 const CRC32 = require("crc-32");
 const Parser = require("binary-parser").Parser;
 const roborockCrypto = require("./roborockCrypto");
+const { describeDevice } = require("./describeDevice");
 
 let seq = 1;
 let random = 4711; // Should be initialized with a number 0 - 1999?
@@ -243,7 +244,7 @@ class message {
         if (!this.missingLocalKeyWarnings.has(duid)) {
           this.missingLocalKeyWarnings.add(duid);
           this.adapter.log.warn(
-            `Skipping MQTT message for device ${duid}: no localKey available.`
+            `Skipping MQTT message for ${describeDevice(this.adapter, duid)}: no localKey available.`
           );
         }
 
@@ -321,7 +322,7 @@ class message {
         .toString("hex");
       const reason = error && error.message ? error.message : String(error);
       this.adapter.log.error(
-        `failed to _decodeMsg for ${duid}: ${reason} (len=${message.length}, preview=${preview})`
+        `failed to _decodeMsg for ${describeDevice(this.adapter, duid)}: ${reason} (len=${message.length}, preview=${preview})`
       );
       // this.adapter.catchError(error, "_decodeMessage", "none");
       return null;

package/roborockLib/lib/roborock_mqtt_connector.js

@@ -5,6 +5,7 @@ const crypto = require("crypto");
 const Parser = require("binary-parser").Parser;
 const zlib = require("zlib");
 const roborockCrypto = require("./roborockCrypto");
+const { describeDevice } = require("./describeDevice");
 
 const PHOTO_MAGIC = "ROBOROCK";
 const PHOTO_HEADER_MIN_LENGTH = 9;
@@ -499,7 +500,7 @@ class roborock_mqtt_connector {
           } catch (error) {
             // If parsing fails, the data might be corrupted or in an unexpected format
             this.adapter.log.warn(
-              `Unable to parse message for ${duid}. Error: ${error.message}. Data: ${dataString}`
+              `Unable to parse message for ${describeDevice(this.adapter, duid)}. Error: ${error.message}. Data: ${dataString}`
             );
             return;
           }
@@ -507,10 +508,10 @@ class roborock_mqtt_connector {
           // Check if the device is online
           if (parsedData.online == false) {
             this.adapter.log.info(
-              `Couldn't process message. The device ${duid} is offline.`
+              `Couldn't process message. ${describeDevice(this.adapter, duid)} is offline.`
             );
           } else if (parsedData.online == true) {
-            // this.adapter.log.info(`Device ${duid} is online.`);
+            // this.adapter.log.info(`${describeDevice(this.adapter, duid)} is online.`);
           } else if (
             // Check for firmware update information
             parsedData.mqttOtaData
@@ -521,19 +522,19 @@ class roborock_mqtt_connector {
 
             if (otaStatus) {
               this.adapter.log.info(
-                `Device ${duid} firmware update status: ${otaStatus}`
+                `${describeDevice(this.adapter, duid)} firmware update status: ${otaStatus}`
               );
             }
 
             if (otaProgress !== undefined) {
               this.adapter.log.info(
-                `Device ${duid} firmware update progress: ${otaProgress}%`
+                `${describeDevice(this.adapter, duid)} firmware update progress: ${otaProgress}%`
               );
             }
           } else {
             // Received an unrecognized message
             this.adapter.log.warn(
-              `Received an unrecognized message for ${duid}. Data: ${dataString}`
+              `Received an unrecognized message for ${describeDevice(this.adapter, duid)}. Data: ${dataString}`
             );
           }
         } else {

package/roborockLib/lib/vacuum.js

@@ -4,12 +4,45 @@ const rrMessage = require("./message").message;
 const RRMapParser = require("./RRMapParser");
 const fs = require("fs");
 const zlib = require("zlib");
+const { describeDevice } = require("./describeDevice");
 
 // Minimum spacing between periodic (non-forced) get_status polls per robot.
 // MQTT push remains the primary live channel; this is the safety net that
 // catches a dropped push long before the 3-minute full refresh would.
 const STATUS_POLL_MIN_INTERVAL_MS = 60 * 1000;
 
+// Longest rendering of a single unmapped attribute value in the report line
+// below. `cleaning_info` is an object, and one robot's status can carry a
+// nested blob big enough to bury the rest of the message.
+const MAX_REPORTED_STATUS_VALUE_LENGTH = 60;
+
+/**
+ * Render a `get_status` value for a log line. The old per-attribute warning
+ * interpolated the raw value, so an object arrived as the useless
+ * `[object Object]` — visible in skmzwanke's log for `cleaning_info`, which is
+ * the one field where the shape was the interesting part.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describeStatusValue(value) {
+  let text;
+
+  if (value === null || typeof value !== "object") {
+    text = String(value);
+  } else {
+    try {
+      text = JSON.stringify(value);
+    } catch {
+      text = "[unserialisable]";
+    }
+  }
+
+  return text.length > MAX_REPORTED_STATUS_VALUE_LENGTH
+    ? `${text.slice(0, MAX_REPORTED_STATUS_VALUE_LENGTH)}…`
+    : text;
+}
+
 const mappedCleanSummary = {
   0: "clean_time",
   1: "clean_area",
@@ -55,6 +88,41 @@ class vacuum {
 
     /** @type {Map<string, number>} last periodic status poll, per duid */
     this.lastStatusPollAt = new Map();
+
+    /**
+     * `get_status` attributes with no mapping in the robot's feature profile
+     * that have already been reported, per duid. The set of unmapped fields a
+     * given robot sends is fixed by its firmware, so reporting it once says
+     * everything a repeat would; a time-based throttle would still bring the
+     * message back forever, which is the complaint, not the fix.
+     *
+     * @type {Map<string, Set<string>>}
+     */
+    this.reportedUnmappedStatusAttributes = new Map();
+  }
+
+  /**
+   * Record that an unmapped `get_status` attribute is about to be reported for
+   * a robot, and say whether this is the initial sighting.
+   *
+   * @param {string} duid
+   * @param {string} attribute
+   * @returns {boolean} true only the one time the pair has not been seen before
+   */
+  rememberUnmappedStatusAttribute(duid, attribute) {
+    let reported = this.reportedUnmappedStatusAttributes.get(duid);
+
+    if (!reported) {
+      reported = new Set();
+      this.reportedUnmappedStatusAttributes.set(duid, reported);
+    }
+
+    if (reported.has(attribute)) {
+      return false;
+    }
+
+    reported.add(attribute);
+    return true;
   }
 
   /**
@@ -182,7 +250,7 @@ class vacuum {
 
           if (roomList.segments.length === 0) {
             this.adapter.log.warn(
-              `No room segments supplied for app_segment_clean_by_ids on ${duid}.`
+              `No room segments supplied for app_segment_clean_by_ids on ${describeDevice(this.adapter, duid)}.`
             );
             break;
           }
@@ -221,7 +289,7 @@ class vacuum {
           const mapId = Number(value);
           if (!Number.isInteger(mapId) || mapId < 0) {
             this.adapter.log.warn(
-              `Invalid map id '${value}' supplied for load_multi_map on ${duid}.`
+              `Invalid map id '${value}' supplied for load_multi_map on ${describeDevice(this.adapter, duid)}.`
             );
             break;
           }
@@ -391,6 +459,12 @@ class vacuum {
             status: deviceStatus[0] || null,
           });
 
+          // Collected across the whole poll and reported as one line. Eight
+          // separate warnings, once a minute, was ~11,500 identical requests a
+          // day to contact the dev about the same eight fields (#8).
+          /** @type {string[]} */
+          const newlyUnmappedAttributes = [];
+
           for (const attribute in deviceStatus[0]) {
             const isCleaning = this.adapter.isCleaning(
               deviceStatus[0]["state"]
@@ -412,9 +486,15 @@ class vacuum {
                 this.adapter.log.debug(
                   `Skipping known get_status attribute without a Homebridge state object: ${attribute}. Model: ${this.robotModel}`
                 );
+              } else if (
+                this.rememberUnmappedStatusAttribute(duid, attribute)
+              ) {
+                newlyUnmappedAttributes.push(
+                  `${attribute}=${describeStatusValue(deviceStatus[0][attribute])}`
+                );
               } else {
-                this.adapter.log.warn(
-                  `Unsupported attribute: ${attribute} of get_status with value ${deviceStatus[0][attribute]}. Please contact the dev to add the newly found attribute of your robot. Model: ${this.robotModel}`
+                this.adapter.log.debug(
+                  `Unmapped get_status attribute ${attribute}=${describeStatusValue(deviceStatus[0][attribute])} for ${describeDevice(this.adapter, duid)}; already reported, not repeating.`
                 );
               }
               continue; // skip unsupported attributes
@@ -511,6 +591,13 @@ class vacuum {
               { val: deviceStatus[0][attribute], ack: true }
             );
           }
+
+          if (newlyUnmappedAttributes.length > 0) {
+            this.adapter.log.warn(
+              `${describeDevice(this.adapter, duid)} (${this.robotModel}) sends ${newlyUnmappedAttributes.length} get_status field(s) this plugin has no mapping for: ${newlyUnmappedAttributes.join(", ")}. Control, battery, rooms and state come from a model-agnostic path and do not depend on them, so nothing is broken — but a model report issue on GitHub quoting this line is how they get added. Logged once per field per robot, so it will not repeat.`
+            );
+          }
+
           this.adapter.manageDeviceIntervals(duid);
         }
       } else if (parameter == "get_room_mapping") {
@@ -536,7 +623,7 @@ class vacuum {
         // if no rooms have been named, processing them can't work
         if (!Array.isArray(mappedRooms) || mappedRooms.length < 1) {
           this.adapter.log.info(
-            `No room mappings returned for ${duid}. Room-based controls will stay unavailable until the Roborock app exposes named rooms.`
+            `No room mappings returned for ${describeDevice(this.adapter, duid)}. Room-based controls will stay unavailable until the Roborock app exposes named rooms.`
           );
         } else {
           let unnamedRooms = 0;
@@ -566,7 +653,7 @@ class vacuum {
 
           if (unnamedRooms > 0) {
             this.adapter.log.info(
-              `${unnamedRooms} room(s) for ${duid} were missing names from HomeData. Using fallback labels like 'Room <id>' until the Roborock app syncs names.`
+              `${unnamedRooms} room(s) for ${describeDevice(this.adapter, duid)} were missing names from HomeData. Using fallback labels like 'Room <id>' until the Roborock app syncs names.`
             );
           }
         }