homebridge-roborock-matter 2.9.0 → 2.9.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2.9.2
+
+- **Max+ ("Grundig"/"Deep Clean") suction mode now announced on the S8 Pro Ultra.** Field report from a re-paired fleet: the S8 Pro Ultra only showed four suction levels because Max+ was gated to B01/Q7. The classic gate now uses the upstream-vetted per-model feature data (`set_custom_mode_max_plus` in the model's action list) — currently confirming the S8 Pro Ultra (`a70`); further models are added as feature data or field reports with diagnostics exports confirm the level. NOTE: the robot must be re-paired once for the new mode to appear (Matter locks the mode list at commissioning).
+- Battery documentation corrected after upstream verification on homebridge#3958: `batPercentRemaining` is quality **Q (quieter)** as of Matter 1.4 (reports ARE sent via subscription, 10 s throttle) — a spec-compliant controller applies them; Apple Home in steady state does not. No plugin architecture change needed; the bridge already does the right thing.
+
+## 2.9.1
+
+Deep performance pass over the live-room hot paths, with honest before/after measurements.
+
+- **Classic live-room lookup: ~23 ms + ~6.7 MB of allocations -> ~1 microsecond, zero allocations.** The RRMap was previously fully parsed every ~20 s while cleaning: parsedata materializes floor/obstacle/segment pixel arrays (hundreds of thousands of entries on a real 800x800 map) only for the tracker to look up a single pixel. The new `resolveLiveSegmentFromMapBuffer` fast path walks the block table once and reads exactly ONE pixel byte from the raw buffer (~19,000x faster, measured on an 800x800/700 KB map with a 20k-point path block). Equivalence with the full parser is locked by tests probing both paths across room, corridor and out-of-map positions.
+- **B01 room cache is only written to disk on actual change.** The live map fetch refreshed the persisted room-name cache every ~20 s during cleaning even when nothing changed; identical room lists no longer touch the disk.
+- **Hot debug lines no longer pay JSON.stringify when debug is off.** Template arguments are evaluated eagerly in JavaScript; the per-poll B01 status line and the per-message protocol-102 line are now gated behind the debug flag.
+- B01 SCMap parsing consolidated to a single walk (head, pose, rooms, chains in one pass). Measured honestly: no speed win (~0.05 ms either way, the grid field is skipped via its length prefix) — kept for the simpler structure.
+- Full suite: 259 passing (3 new fast-path equivalence/robustness tests).
+
 ## 2.9.0
 
 - **All Apple Home feature toggles are now visible in the plugin settings UI.** The custom settings page previously exposed only a subset of the configuration; options like suction-level cleaning modes, live room tracking, room/map selection, cleaning mode selection, battery and Returning status could only be set by editing the JSON config by hand. They now live in a dedicated **Apple Home Features** section, with a clear "⚠ re-pair" marker on every option that changes the robot's announced Matter capabilities (Matter locks capabilities at commissioning — after toggling those, restart Homebridge, then remove and re-pair the robot).

package/README.md

@@ -96,7 +96,7 @@ Everything is configurable from the Homebridge UI. The essentials:
 
 ## Battery percentage in Apple Home
 
-Apple Home renders the battery percentage from pairing time and never re-reads it — the Matter attribute carries the spec's "changes omitted" reporting quality, so value changes are not pushed to controllers _by design_ (charging state on the very same cluster updates live). This is a controller-side limitation verified end-to-end, not a plugin bug.
+Apple Home renders the battery percentage from pairing time and refreshes it only on a fresh read (commissioning, hub restart) — while charging state on the very same cluster updates live. This is a controller-side limitation, not a plugin bug, and it is being investigated upstream with the Homebridge team ([homebridge#3958](https://github.com/homebridge/homebridge/issues/3958)). Current state of knowledge: as of Matter 1.4 the attribute carries the **"quieter" (Q)** reporting quality — reports ARE sent over the subscription (rate-limited to one per 10 s), a Homebridge maintainer verified that a spec-compliant matter.js controller receives and applies them, yet Apple Home in steady state does not. The likely permanent fix is on Apple's side (Apple Feedback).
 
 <details>
 <summary>The full evidence chain and workarounds</summary>

package/docs/issue-3958-reply.md

@@ -0,0 +1,29 @@
+# Svar til bwp91 på homebridge#3958 — klar til at poste
+
+```markdown
+Thank you — this is exactly the kind of verification I was hoping for, and
+the C → Q correction is a genuinely important update. You're right that my
+analysis was written against the older changes-omitted reading of the
+attribute; I've already corrected the plugin's documentation to reflect the
+Matter 1.4 Q (quieter) quality and your subscription trace
+(mathiashornbek/homebridge-roborock-matter@main, README + docs).
+
+Your controller log also explains two things I had observed but couldn't
+fully reconcile: the resync nudge's null → value transition "working" at the
+wire level while Apple still never converged, and `batChargeState` updating
+live throughout. Both are consistent with the reports leaving the bridge and
+Apple simply not applying Q-quality percentage reports in steady state.
+
+I'll run the verification you suggested on my production setup (three
+robots: one V1, two B01) — Homebridge with matter.js debug logging through a
+full charge cycle, watching for the subscription flushes carrying
+`batPercentRemaining` — and post the log excerpts here. If I can get
+chip-tool set up on the same network I'll add a subscription trace from that
+side too.
+
+Assuming both confirm what your trace already shows, I'll file the Apple
+Feedback report about the controller's handling of Q-quality PowerSource
+attributes and link it here so others can dupe it. Thanks again for digging
+in — happy to test any builds if something changes in the Homebridge Matter
+layer down the road.
+```

package/docs/matter-battery-issue-draft.md

@@ -1,66 +1,57 @@
-# Matter PowerSource `batPercentRemaining` never refreshes in controllers (changes-omitted attribute; device-side store is fresh)
-
-Ready to file against `homebridge/homebridge` (Matter API). Title suggestion:
-
-> Matter bridged accessories: `batPercentRemaining` freezes at pairing-time value in Apple Home (changes-omitted attribute; store verifiably fresh)
-
-## Summary
-
-A Matter Robotic Vacuum Cleaner (device type 0x74) exposed through Homebridge 2's
-Matter API publishes battery updates continuously via `updateAccessoryState`. The
-matter.js store demonstrably carries the live value. Controllers (Apple Home,
-multi-hub) keep rendering the value from pairing time indefinitely — across
-plugin restarts, Homebridge restarts, and days of uptime — while
-`batChargeState` on the very same cluster updates live.
-
-## Environment
-
-- Homebridge 2.1.x (Matter API), plugin `homebridge-roborock-matter` publishing
-  full-state snapshots via `updateAccessoryState`
-- Three robots (one V1-protocol, two B01-protocol) — identical behavior on all
-- Controller: Apple Home (Apple TV + HomePod hubs, current iOS/tvOS)
-
-## Reproduction
-
-1. Pair a bridged Matter accessory that exposes PowerSource with a battery
-   percentage that changes over time (any RVC works).
-2. Let the battery drain or charge by 10+ points.
-3. Compare the Apple Home tile with the matter.js store on disk.
-
-## Evidence chain
-
-1. Plugin log shows continuous publishes with live values (73% → 92% over an
-   hour, all three robots).
-2. `grep -ro "batPercentRemaining[^,}]*" <storage> --include="*.json"` shows the
-   persisted matter.js store matching the vendor app in real time (e.g. 170 =
-   85% while Apple renders 74%).
-3. `batChargeState` (same PowerSource cluster) propagates to Apple Home in
-   near-real-time throughout.
-4. The values Apple renders are exactly each robot's value from its
-   commissioning moment; a re-pair refreshes once, then freezes again.
-5. A device-side "resync nudge" (publishing the attribute as briefly unknown,
-   then real, to force two genuine store changes and a data-version bump) helps
-   only controllers that re-prime their subscription (e.g. after a hub
-   restart); Apple in steady state still never converges.
-
-## Analysis
-
-`batPercentRemaining` (and `batTimeToFullCharge`) carry the Matter spec
-reporting quality **"changes omitted" (C)**. matter.js honors this on the
-device side (changes are not delivered via subscription reports), and the
-matter.js controller compensates on its own side ("Always read attributes that
-do not report changes via subscriptions" — matter.js changelog 0.10). Apple's
-controller evidently performs no such re-reads, so bridged accessories freeze
-on the pairing-time percentage. No plugin-side write can force a
-changes-omitted attribute to report.
-
-## Suggestion
-
-Consider a device-side mitigation in the Homebridge Matter layer for bridged
-accessories — for example bumping the cluster data version or scheduling a
-periodic re-announce for changes-omitted attributes whose value has drifted —
-so controllers that rely purely on subscriptions eventually converge. This
-would fix frozen battery percentages for every bridged plugin at once, in one
-place.
-
-Happy to provide full logs, store dumps, and to test builds.
+# Matter PowerSource `batPercentRemaining` — investigation record
+
+Filed upstream as
+[homebridge/homebridge#3958](https://github.com/homebridge/homebridge/issues/3958)
+on 2026-07-15. This document tracks the current state of knowledge; the
+original report text lives in the issue.
+
+## Symptom
+
+A Matter RVC bridged through Homebridge 2's Matter API publishes battery
+updates continuously; the matter.js store verifiably carries the live value;
+`batChargeState` on the same PowerSource cluster updates live in Apple Home —
+but the rendered battery **percentage** stays at its commissioning-time value
+until a fresh read (re-pair or Matter hub restart).
+
+## Corrected analysis (per Homebridge maintainer verification, 2026-07-15)
+
+The original analysis assumed the attribute carries the Matter reporting
+quality **C (changes omitted)** — never reported via subscription, controllers
+must poll. That was true of older spec revisions, **but as of Matter 1.4 the
+attribute is quality Q (quieter)** , and matter.js 0.17.x (shipped with every
+Homebridge 2.1.x release) models it accordingly:
+
+- **Q (quieter):** reported via subscription, rate-limited to at most one
+  report per 10 seconds, plus an immediate report on any null ↔ value
+  transition.
+
+A Homebridge maintainer (bwp91) commissioned a matter.js controller against a
+bridge exposing `PowerSource(Battery, Rechargeable)` — the same setup
+Homebridge builds — and logged the subscription: percentage changes propagate
+exactly as Q prescribes (immediate first report, deferred follow-up inside the
+10 s window, correct application after an interleaved `batChargeState` bump).
+The "stale cluster data version" theory does not hold on the controller side.
+
+## Where that leaves things
+
+- The bridge **emits** the reports; a spec-compliant controller **applies**
+  them. Apple Home in steady state does not — consistent with Apple's
+  controller still treating the attribute under the older changes-omitted
+  rules and refreshing only on a fresh read.
+- The plugin's boot-time resync nudge (null → value transition) does hit the
+  wire immediately (maintainer-confirmed) and remains useful for controllers
+  that re-prime their subscriptions; Apple still does not converge.
+- **No device-side fix exists**: bumping the data version or re-announcing
+  only produces more of the reports Apple already receives and ignores.
+
+## Next verification steps (requested upstream)
+
+1. Run Homebridge with matter.js debug logging during a battery change and
+   capture the subscription flushes carrying `batPercentRemaining` — proves
+   the reports leave THIS bridge specifically.
+2. Optionally subscribe with `chip-tool` and confirm it sees (and applies)
+   the live values.
+
+If both confirm reports going out, the permanent fix belongs with Apple
+(Apple Feedback report about the controller's handling of Q-quality
+PowerSource attributes). The upstream issue stays open in the meantime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "2.9.0",
+  "version": "2.9.2",
   "description": "Matter-only Homebridge plugin publishing Roborock robot vacuums (including 2025 B01/Q7-series) as native Matter accessories for Apple Home. Fork of homebridge-roborock-vacuum2.",
   "license": "MIT",
   "author": {

package/roborockLib/lib/RRMapParser.js

@@ -516,4 +516,98 @@ RRMapParser.resolveLiveSegmentId = function resolveLiveSegmentId(parsedMap) {
   return null;
 };
 
+/**
+ * Fast path for live-room tracking: resolve the robot's segment DIRECTLY
+ * from the raw RRMap buffer without materializing any pixel arrays.
+ *
+ * parsedata() collects floor/obstacle/segment pixel lists (hundreds of
+ * thousands of array entries on a real map — measured ~23 ms and ~6.7 MB of
+ * allocations per parse on an 800x800 map), which live-room tracking would
+ * pay every ~20 s only to look up a single pixel. This walk touches each
+ * block header once, remembers where the IMAGE pixel data and the robot
+ * position live, and reads exactly ONE pixel byte.
+ *
+ * The SHA1 tail check is intentionally skipped here: the transport layer
+ * already gunzips the payload (gzip's CRC32 validates integrity), and the
+ * header magic + block-structure walk reject malformed buffers.
+ *
+ * @param {Buffer} buf raw RRMap buffer (decrypted and gunzipped)
+ * @returns {number | null} segment id, or null when position/geometry is
+ *   missing, the robot is outside the image, or on an unsegmented pixel.
+ */
+RRMapParser.resolveLiveSegmentFromMapBuffer = function (buf) {
+  if (
+    !Buffer.isBuffer(buf) ||
+    buf.length < 0x18 ||
+    buf[0x00] !== 0x72 ||
+    buf[0x01] !== 0x72
+  ) {
+    return null;
+  }
+
+  const dataLength = buf.readUInt32LE(OFFSETS.LENGTH);
+  const end = Math.min(dataLength, buf.length);
+
+  let image = null;
+  let position = null;
+
+  let dataPosition = 0x14;
+  while (dataPosition + 8 <= end) {
+    const type = buf.readUInt16LE(dataPosition);
+    const hlength = buf.readUInt16LE(dataPosition + OFFSETS.HLENGTH);
+    const length = buf.readUInt32LE(dataPosition + OFFSETS.LENGTH);
+    if (hlength < 8 || dataPosition + hlength + length > buf.length) {
+      return null; // malformed block table
+    }
+
+    if (type === TYPES.IMAGE && hlength > 24) {
+      const offset1 = buf.readUInt8(dataPosition + 2); // == hlength low byte
+      image = {
+        pixelsAt: dataPosition + offset1,
+        top: buf.readInt32LE(dataPosition + offset1 - 0x10),
+        left: buf.readInt32LE(dataPosition + offset1 - 0x0c),
+        height: buf.readInt32LE(dataPosition + offset1 - 0x08),
+        width: buf.readInt32LE(dataPosition + offset1 - 0x04),
+        length,
+      };
+    } else if (type === TYPES.ROBOT_POSITION) {
+      const offset1 = buf.readUInt8(dataPosition + 2);
+      position = [
+        buf.readInt32LE(dataPosition + offset1),
+        buf.readInt32LE(dataPosition + (length >= 12 ? offset1 + 4 : offset1)),
+      ];
+    }
+
+    dataPosition += hlength + length;
+  }
+
+  if (!image || !position || image.width <= 0 || image.height <= 0) {
+    return null;
+  }
+
+  const pixelX = Math.floor(position[0] / 50) - image.left;
+  const pixelY = Math.floor(position[1] / 50) - image.top;
+  if (
+    pixelX < 0 ||
+    pixelY < 0 ||
+    pixelX >= image.width ||
+    pixelY >= image.height
+  ) {
+    return null;
+  }
+
+  const pixelIndex = pixelY * image.width + pixelX;
+  if (pixelIndex >= image.length) {
+    return null;
+  }
+
+  const pixelByte = buf.readUInt8(image.pixelsAt + pixelIndex);
+  const pixelType = pixelByte & 0x07;
+  if (pixelType === 0 || pixelType === 1) {
+    return null; // outside the map or an obstacle pixel
+  }
+  const segmentId = (pixelByte & 248) >> 3;
+  return segmentId !== 0 ? segmentId : null;
+};
+
 module.exports = RRMapParser;

package/roborockLib/lib/b01Q7Adapter.js

@@ -381,6 +381,41 @@ function parseScMapLiveState(buffer) {
     return chain;
   }
 
+  /** @param {Buffer} buf */
+  function parseRoomEntry(buf) {
+    const room = { roomId: -1, roomName: "" };
+    let pos = 0;
+    while (pos < buf.length) {
+      const tag = readVarint(buf, pos);
+      pos = tag.pos;
+      const fieldNumber = Math.floor(tag.value / 8);
+      const wireType = tag.value % 8;
+      if (fieldNumber === 1 && wireType === 0) {
+        const value = readVarint(buf, pos);
+        room.roomId = value.value;
+        pos = value.pos;
+      } else if (fieldNumber === 2 && wireType === 2) {
+        const len = readVarint(buf, pos);
+        room.roomName = buf
+          .subarray(len.pos, len.pos + len.value)
+          .toString("utf8");
+        pos = len.pos + len.value;
+      } else {
+        pos = skipField(buf, pos, wireType);
+      }
+    }
+    return room;
+  }
+
+  /** @type {Array<{roomId: number, roomName: string}>} */
+  const rooms = [];
+
+  // Single pass over the RobotMap wire format: head, pose, rooms and room
+  // chains are all collected in one walk instead of delegating rooms to a
+  // second parseRoomsFromScMap scan. Measured honestly: the win is
+  // negligible (~0.05 ms either way — skipField jumps the large grid field
+  // via its length prefix without touching bytes); this is kept for the
+  // simpler single-walk structure, not for speed.
   let pos = 0;
   while (pos < buffer.length) {
     const tag = readVarint(buffer, pos);
@@ -395,6 +430,11 @@ function parseScMapLiveState(buffer) {
         head = parseMapHead(body);
       } else if (fieldNumber === 8) {
         pose = parseCurrentPose(body);
+      } else if (fieldNumber === 12) {
+        const room = parseRoomEntry(body);
+        if (room.roomId >= 0) {
+          rooms.push(room);
+        }
       } else if (fieldNumber === 14) {
         const chain = parseRoomChain(body);
         if (chain.roomId >= 0 && chain.points.length >= 3) {
@@ -410,7 +450,7 @@ function parseScMapLiveState(buffer) {
   return {
     head,
     pose,
-    rooms: parseRoomsFromScMap(buffer),
+    rooms,
     roomChains:
       /** @type {Array<{roomId: number, points: Array<{x: number, y: number}>}>} */ (
         roomChains

package/roborockLib/lib/deviceFeatures.js

@@ -1345,7 +1345,23 @@ class deviceFeatures {
   }
 }
 
+// Classic v1 models whose upstream-vetted per-model action list includes
+// `set_custom_mode_max_plus` — the verified signal that the robot's firmware
+// accepts the Max+ suction level (v1 fan power 108). Keep this in sync with
+// the modelConfig action lists in processSupportedFeatures above; models are
+// only added here once the upstream feature data (or a field report with a
+// diagnostics export) confirms the level.
+const MAX_PLUS_FAN_POWER_MODELS = new Set([
+  "roborock.vacuum.a70", // S8 Pro Ultra
+]);
+
+/** @param {string} model */
+function supportsMaxPlusFanPower(model) {
+  return MAX_PLUS_FAN_POWER_MODELS.has(model);
+}
+
 module.exports = {
   deviceFeatures,
   stateCodes,
+  supportsMaxPlusFanPower,
 };

package/roborockLib/lib/roborock_mqtt_connector.js

@@ -277,9 +277,13 @@ class roborock_mqtt_connector {
           }
 
           if (dps.id !== undefined) {
-            this.adapter.log.debug(
-              `Cloud message with protocol 102 and id ${dps.id} received. Result: ${JSON.stringify(dps.result)}`
-            );
+            // Runs for every cloud message; only pay the stringify cost
+            // when debug logging is actually enabled.
+            if (this.adapter.config.debug) {
+              this.adapter.log.debug(
+                `Cloud message with protocol 102 and id ${dps.id} received. Result: ${JSON.stringify(dps.result)}`
+              );
+            }
             if (typeof dps.result !== "undefined") {
               this.adapter.setStateAsync("CloudMessage", {
                 duid,

package/roborockLib/roborockAPI.js

@@ -14,6 +14,8 @@ const roborock_mqtt_connector =
 const rrMessage = require("./lib/message").message;
 const vacuum_class = require("./lib/vacuum").vacuum;
 const deviceFeatures = require("./lib/deviceFeatures").deviceFeatures;
+const supportsMaxPlusFanPower =
+  require("./lib/deviceFeatures").supportsMaxPlusFanPower;
 const RRMapParser = require("./lib/RRMapParser");
 const messageQueueHandler =
   require("./lib/messageQueueHandler").messageQueueHandler;
@@ -1944,6 +1946,12 @@ class Roborock {
       canVacuum: true,
       canMop: hasWaterModeSchema || hasMopSchema || hasMopFeature,
       canControlFanPower,
+      // Max+ (fan power 108) only where the upstream-vetted per-model
+      // feature data confirms the level (e.g. S8 Pro Ultra) — field
+      // reports with diagnostics exports extend the list.
+      canMaxPlusFanPower: supportsMaxPlusFanPower(
+        this.getProductAttribute(duid, "model")
+      ),
       canControlWater:
         hasWaterModeSchema ||
         this.hasVacuumFeature(duid, [
@@ -3467,9 +3475,13 @@ class Roborock {
           );
         }
 
-        this.log.debug(
-          `B01 status for ${duid}: ${JSON.stringify(data)} -> ${JSON.stringify(v1Status)}`
-        );
+        // Template args are evaluated even when debug logging is off, and
+        // this line runs on every successful poll — gate the stringify.
+        if (this.config.debug) {
+          this.log.debug(
+            `B01 status for ${duid}: ${JSON.stringify(data)} -> ${JSON.stringify(v1Status)}`
+          );
+        }
 
         if (this.deviceNotify !== undefined) {
           this.deviceNotify("CloudMessage", { duid, payload: [v1Status] });
@@ -3752,13 +3764,18 @@ class Roborock {
 
         // The live fetch already paid for the full map payload; reuse it to
         // keep the room-name cache fresh instead of scheduling another
-        // 6-hour refreshB01Rooms fetch of the same data.
+        // 6-hour refreshB01Rooms fetch of the same data. Written only on
+        // actual change — the cache is persisted to disk, and rewriting an
+        // identical room list every ~20 s during cleaning is pure I/O waste.
         if (parsed.rooms.length > 0) {
           if (!this._b01RoomRefreshAt) {
             this._b01RoomRefreshAt = new Map();
           }
           this._b01RoomRefreshAt.set(duid, Date.now());
-          await this.setB01RoomCache(duid, parsed.rooms);
+          const cachedRooms = JSON.stringify(this.getB01RoomCache(duid));
+          if (cachedRooms !== JSON.stringify(parsed.rooms)) {
+            await this.setB01RoomCache(duid, parsed.rooms);
+          }
         }
 
         const roomId = b01Q7Adapter.resolveLiveRoomId(parsed);
@@ -3944,9 +3961,12 @@ class Roborock {
           return liveState.current;
         }
 
-        const parser = this.vacuums[duid]?.mapParser || new RRMapParser(this);
-        const parsedMap = await parser.parsedata(mapBuffer);
-        const segmentId = RRMapParser.resolveLiveSegmentId(parsedMap);
+        // Fast path: reads the single pixel under the robot directly from
+        // the raw buffer — no pixel arrays are materialized (parsedata costs
+        // ~23 ms + ~6.7 MB of allocations on a real-size map; this is
+        // microseconds).
+        const segmentId =
+          RRMapParser.resolveLiveSegmentFromMapBuffer(mapBuffer);
         liveState.consecutiveFailures = 0;
 
         if (segmentId === null) {