homebridge-roborock-matter 3.17.2 → 3.17.4

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 3.17.4
+
+**The "no mapping for these fields" warning no longer asks you to report fields this plugin already maps.** Raised by the log [@jcoz00](https://github.com/jcoz00) posted in [#6](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/6), whose Qrevo CurvX was told the plugin has no mapping for **eighteen** `get_status` fields and that a GitHub model report quoting the line is how they get added. Fifteen of those eighteen are named in `deviceFeatures.js` already. There was nothing for a report to add, and the three fields that genuinely were news sat buried in a list of fifteen that were not.
+
+The message was asking the wrong question. A robot's status table starts as a copy of the plugin's baseline and capability detection adds to it, so "this field is not switched on for **this robot**" and "this plugin has never heard of this field" are different questions — and only the second one is worth a user's time. The warning asked the first and reported the answer as the second.
+
+Each case now says what it means. A field no table anywhere names is still warned about once, by name and value, and still worth a model report; for the CurvX that is three fields rather than eighteen. A field the plugin maps but this robot's capability gate did not switch on is a debug line that says so, once per field per robot, and does not point anyone at GitHub. The repeat line that followed it on every subsequent poll is gone for that case — fifteen lines a minute saying nothing the first one did not.
+
+**This quietens [#8](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/8) entirely as a side effect.** All nine fields [@skmzwanke](https://github.com/skmzwanke)'s Saros 10 was warned about have since been added, so that warning had been asking for work that was already done. It now says nothing at all.
+
+Nothing about which fields are read, published or acted on changed — this release changes only what the log claims. The declared set of capability-installable fields is derived from the source by a test that scans for every writer, so a new capability cannot reintroduce the wrong warning without the suite failing.
+
+## 3.17.3
+
+**Q7- and Q10-series robots no longer spend a cloud request per poll on an answer the plugin cannot read.** Reported with a diagnostics export by [@niclasreich](https://github.com/niclasreich) in [#14](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/14), whose Q10 S5 (`roborock.vacuum.ss07`) logged `Failed to execute get_room_mapping … method prop.get timed out after 10 seconds` while the MQTT connection was reported as up.
+
+The two method names in that line disagree, and that was the clue. `get_room_mapping` is the caller's label; `prop.get` is what actually went on the wire. The classic room-mapping routine opens by fetching `get_status` in order to read `map_status` and derive a floor number — and on these robots `get_status` translates to a real `prop.get`. `map_status` is a v1-only field that a Q7/Q10 status dictionary has never carried, so the reply could not have been used whatever it said. The request itself was already answered locally from the dialect's neutral table without touching the network, which is exactly why the existing skip did not catch this: the harmless call was making a second, expensive one.
+
+The classic flow is now skipped outright for these robots, which is where their room data was never coming from in the first place — it arrives over the protobuf map channel. That removes one cloud round-trip per poll cycle per robot, along with the `No room mappings returned` notice and the empty room-list announcement that repeated at the same rate. Robots on the classic protocol are unaffected and still read `map_status` exactly as before.
+
+**This does not by itself explain a robot that ignores commands from Apple Home**, which is the other half of that report; it removes a wasted request and the misleading error line it produced.
+
 ## 3.17.2
 
 **The Qrevo CurvX's dock can now offer the Empty Bin switch.** Reported with a diagnostics export, and then settled by hand, by [@jcoz00](https://github.com/jcoz00) in [#6](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/6). His a185 reports `dock_type: 20`, and the dock table this plugin inherited stops at 9 — so the CurvX fell through to "unknown dock" and was treated as having no auto-empty capability, which kept the optional Empty Bin switch added in 3.17.0 from ever being offered for it. Dock type 20 is now a named, recognised auto-empty dock.

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. 1438 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. 1506 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
 
@@ -252,7 +252,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 1438 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 1506 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.17.2",
+  "version": "3.17.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/deviceFeatures.js

@@ -182,6 +182,80 @@ const deviceStates = {
   cleaning_info: "string",
 };
 
+// Every `get_status` field name a capability path can install into a robot's
+// own `deviceStates`. A per-model table starts as a copy of the pristine
+// baseline above and capability detection adds to it, so "absent from this
+// robot's table" and "unknown to this plugin" are two different questions.
+// `hasDeviceStatusAttribute()` only ever answered the first, and the unmapped-
+// field warning in vacuum.js asked it the second: jcoz00's Qrevo CurvX (#6)
+// was told the plugin has no mapping for eighteen fields and that a model
+// report is how they get added, when fifteen of the eighteen are named right
+// here and there was nothing for a report to add.
+//
+// This is a hand-written list, which is the defect shape the note at
+// matter_vacuum_accessory.ts:185 warns about. It is held shut from outside:
+// __tests__/a-known-field-is-not-called-unmapped.test.js scans this file for
+// `deviceStates.<field> =` writers and fails if one of them is missing below,
+// so a new capability cannot quietly reintroduce the wrong warning.
+const CAPABILITY_STATUS_ATTRIBUTES = new Set([
+  "avoid_count",
+  "back_type",
+  "camera_status",
+  "carpet_clean_mode",
+  "carpet_mode",
+  "charge_status",
+  "clean_fluid",
+  "clean_percent",
+  "collision_avoid_status",
+  "common_status",
+  "corner_clean_mode",
+  "distance_off",
+  "dry_status",
+  "dss",
+  "home_sec_enable_password",
+  "home_sec_status",
+  "in_warmup",
+  "kct",
+  "last_clean_t",
+  "map_flag",
+  "monitor_status",
+  "mop_forbidden_enable",
+  "mop_mode",
+  "rdt",
+  "repeat",
+  "replenish_mode",
+  "rss",
+  "switch_map_mode",
+  "switch_status",
+  "voice_chat_status",
+  "wash_phase",
+  "wash_ready",
+  "wash_status",
+  "water_box_carriage_status",
+  "water_box_custom_mode",
+  "water_box_mode",
+  "water_box_status",
+  "water_shortage_status",
+]);
+
+/**
+ * Whether this plugin knows the named `get_status` field at all — in the
+ * pristine baseline table or behind any capability gate.
+ *
+ * Deliberately not a method on `deviceFeatures`: the question is about the
+ * plugin, not about one robot's instance, and asking an instance is what
+ * produced the wrong warning in the first place.
+ *
+ * @param {string} attribute
+ * @returns {boolean}
+ */
+function isKnownStatusAttribute(attribute) {
+  return (
+    Object.prototype.hasOwnProperty.call(deviceStates, attribute) ||
+    CAPABILITY_STATUS_ATTRIBUTES.has(attribute)
+  );
+}
+
 // Shared shape for the work-time consumables that both consumablesInt and
 // consumablesString track identically.
 const workTimeConsumable = {
@@ -1583,6 +1657,7 @@ function getModelNameWithoutBrand(model) {
 module.exports = {
   deviceFeatures,
   errorCodes,
+  isKnownStatusAttribute,
   supportsMaxPlusFanPower,
   getModelMarketingName,
   getModelNameWithoutBrand,

package/roborockLib/lib/vacuum.js

@@ -5,6 +5,7 @@ const RRMapParser = require("./RRMapParser");
 const fs = require("fs");
 const zlib = require("zlib");
 const { describeDevice } = require("./describeDevice");
+const { isKnownStatusAttribute } = require("./deviceFeatures");
 
 // Minimum spacing between periodic (non-forced) get_status polls per robot.
 // MQTT push remains the primary live channel; this is the safety net that
@@ -620,7 +621,12 @@ class vacuum {
                 `Devices.${duid}.deviceStatus.${attribute}`
               ))
             ) {
-              const isKnownStatusAttribute =
+              // Renamed from `isKnownStatusAttribute` on purpose: it is not
+              // what it used to be called. The feature profile answers "is
+              // this field switched on for THIS robot", which is a narrower
+              // question than "does this plugin know the field", and the old
+              // name invited the loop below to confuse the two.
+              const isEnabledForThisRobot =
                 typeof this.adapter.vacuums[duid].features
                   .hasDeviceStatusAttribute === "function" &&
                 this.adapter.vacuums[duid].features.hasDeviceStatusAttribute(
@@ -636,20 +642,45 @@ class vacuum {
               // on: fifty lines a minute, and the log ring — the thing you
               // need when something real goes wrong — held ninety minutes.
               //
-              // The distinction below is the part that carries information
-              // and it is untouched: an attribute nobody has mapped yet is
-              // still reported once, by name and value.
-              if (
-                !isKnownStatusAttribute &&
-                this.rememberUnmappedStatusAttribute(duid, attribute)
-              ) {
-                newlyUnmappedAttributes.push(
-                  `${attribute}=${describeStatusValue(deviceStatus[0][attribute])}`
-                );
-              } else if (!isKnownStatusAttribute) {
-                this.adapter.log.debug(
-                  `Unmapped get_status attribute ${attribute}=${describeStatusValue(deviceStatus[0][attribute])} for ${describeDevice(this.adapter, duid)}; already reported, not repeating.`
+              // The distinction below is the part that carries information,
+              // and it now has three cases rather than two. Asking only the
+              // per-robot question is what sent jcoz00 (#6) after a model
+              // report for fifteen fields that were already mapped: his Qrevo
+              // CurvX sends them, his robot's capability detection never
+              // switched them on, and the warning read that as "this plugin
+              // has no mapping for them". A warning that says "no mapping"
+              // and points at GitHub is only true of a field no table
+              // anywhere names — which for his robot was three of eighteen.
+              const isKnownToPlugin = isKnownStatusAttribute(attribute);
+
+              if (!isEnabledForThisRobot) {
+                const isFirstSighting = this.rememberUnmappedStatusAttribute(
+                  duid,
+                  attribute
                 );
+
+                if (isKnownToPlugin) {
+                  // Worth seeing once when we go looking — a gate that did not
+                  // fire for a field the robot demonstrably sends is a lead —
+                  // but not worth waking a user for, and nothing they can act
+                  // on. Repeats are silent rather than a debug line: the field
+                  // is mapped and the gate is not going to change mid-run, so
+                  // a per-poll line would be fifteen of them a minute on a
+                  // Qrevo CurvX saying nothing the first one did not.
+                  if (isFirstSighting) {
+                    this.adapter.log.debug(
+                      `get_status attribute ${attribute}=${describeStatusValue(deviceStatus[0][attribute])} arrived from ${describeDevice(this.adapter, duid)}, but this robot's capability detection did not switch it on. This plugin maps the field, so there is nothing to report.`
+                    );
+                  }
+                } else if (isFirstSighting) {
+                  newlyUnmappedAttributes.push(
+                    `${attribute}=${describeStatusValue(deviceStatus[0][attribute])}`
+                  );
+                } else {
+                  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
             }
@@ -765,6 +796,19 @@ class vacuum {
           this.adapter.manageDeviceIntervals(duid);
         }
       } else if (parameter == "get_room_mapping") {
+        // Room data on B01/Q7 robots travels over the protobuf map channel,
+        // and `get_room_mapping` itself is answered from the dialect's neutral
+        // table without touching the network — so this branch looked free.
+        // It is not: it opens by fetching `get_status` to read `map_status`,
+        // a v1-only field that Q7 status dictionaries have never carried, and
+        // on B01 `get_status` translates to a real `prop.get`. That is one
+        // cloud round-trip per poll cycle per robot spent on an answer this
+        // code cannot read — reported under the caller's label, which is why
+        // #14's log line names `get_room_mapping` but times out on `prop.get`.
+        if (this.adapter.isB01Device?.(duid)) {
+          return;
+        }
+
         const deviceStatus = await sendParameterRequest("get_status", []);
         const mapStatus = Array.isArray(deviceStatus)
           ? deviceStatus[0]?.["map_status"]

package/roborockLib/roborockAPI.js

@@ -982,9 +982,7 @@ class Roborock {
   }
 
   getRoomMappingsForDevice(duid) {
-    if (
-      this.getVacuumDeviceInfo(duid, "pv") === b01Q7Adapter.B01_PROTOCOL_VERSION
-    ) {
+    if (this.isB01Device(duid)) {
       return this.getB01RoomCache(duid).map((room) => ({
         segmentId: room.roomId,
         mapId: 0,
@@ -1025,9 +1023,7 @@ class Roborock {
     // the canonical mapId 0. Reporting 0 here keeps the Matter room-clean
     // flow from attempting a map switch (load_multi_map has no Q7
     // equivalent) before sending the segment command.
-    if (
-      this.getVacuumDeviceInfo(duid, "pv") === b01Q7Adapter.B01_PROTOCOL_VERSION
-    ) {
+    if (this.isB01Device(duid)) {
       return 0;
     }
 
@@ -2308,10 +2304,7 @@ class Roborock {
       this.vacuums[duid].getStatusIntervall = () => {
         // B01/Q7 status is owned by the dedicated 15s loop; the per-device
         // tick would only burn cycles hitting the attempt throttle.
-        if (
-          this.getVacuumDeviceInfo(duid, "pv") ===
-          b01Q7Adapter.B01_PROTOCOL_VERSION
-        ) {
+        if (this.isB01Device(duid)) {
           return null;
         }
         this.clearInterval(this.vacuums[duid].getStatusIntervalHandle);
@@ -2396,9 +2389,7 @@ class Roborock {
     // with no electronic mop/water control, so Matter must never expose mop
     // modes for them regardless of what the generic cloud schema claims.
     // Suction (Q7 "wind") is controllable via the B01 adapter.
-    if (
-      this.getVacuumDeviceInfo(duid, "pv") === b01Q7Adapter.B01_PROTOCOL_VERSION
-    ) {
+    if (this.isB01Device(duid)) {
       return {
         // Q7 robots mop with a manually filled tank: expose the mop/vacuum
         // mode switch, but never water-level status or control.
@@ -5070,6 +5061,22 @@ class Roborock {
     }
   }
 
+  /**
+   * True when this robot speaks the B01/Q7 dialect rather than classic v1.
+   *
+   * Four places wrote this comparison out by hand before it had a name, and
+   * `vacuum.js` was about to need a fifth. It decides which wire protocol a
+   * robot speaks, so it gets one spelling.
+   *
+   * @param {string} duid
+   * @returns {boolean}
+   */
+  isB01Device(duid) {
+    return (
+      this.getVacuumDeviceInfo(duid, "pv") === b01Q7Adapter.B01_PROTOCOL_VERSION
+    );
+  }
+
   /**
    * A device's name for log messages, falling back to the duid.
    *