homebridge-roborock-matter 3.17.3 → 3.17.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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.

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. 1449 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 1449 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.3",
+  "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
             }