homebridge-roborock-matter 2.8.1 → 2.9.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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).
+- No functional changes to the plugin itself.
+
 ## 2.8.1
 
 - **Suction modes now render with proper localized names in Apple Home.** Field observation: Apple ignores Matter mode labels and renders its own localized names from the mode TAGS (a variant with only the Vacuum tag displays as plain "Vacuum"). Balanced and Turbo therefore now carry distinct intensity tags (Auto and Quick), matching Quiet and Max — in Apple Home the five levels render as Quiet / Automatic / Quick / Max (+ Deep Clean for Max+ on Q7). Remember: enabling `enableFanPowerCleanModes` requires one remove/re-pair of the robot, since Matter fixes the mode list at commissioning.

package/README.md

@@ -66,6 +66,12 @@ While a robot is actively cleaning, the plugin fetches its live position from th
 
 Enabled by default; opt out with `enableLiveRoomTracking: false`.
 
+## Suction modes (optional)
+
+Enable **Enable Suction-Level Cleaning Modes** (`enableFanPowerCleanModes`) and Apple Home's mode picker gains the suction levels — rendered by Apple with localized names from the Matter mode tags: **Quiet / Automatic / Quick / Max** (+ **Deep Clean** for the Q7's Max+ level). The current mode follows the robot live, so suction changed in the Roborock app shows up in Apple Home too.
+
+> ⚠️ **Re-pairing required:** Matter locks an accessory's mode list at commissioning. After enabling (or disabling) this option, restart Homebridge, then **remove the robot from Apple Home and pair it again** — otherwise the new modes will not appear. The same applies to any option that changes announced capabilities.
+
 ## Supported robots
 
 - **B01/Q7-series (2025):** `roborock.vacuum.sc05` and compatible (Q7 M5 / M5+), including manual-tank mopping with vacuum/mop mode switching.

package/homebridge-ui/public/index.html

@@ -82,39 +82,6 @@
       </label>
     </div>
 
-    <label class="checkbox">
-      <input id="enable-matter-charging-docked" type="checkbox" />
-      <span>
-        Show Charging/Docked on the Apple Home tile
-        <small
-          >Reports real Matter Charging and Docked states instead of Ready while
-          on the dock. Requires a recent iOS/tvOS; turn off and restart the
-          bridge if the tile misbehaves.</small
-        >
-      </span>
-    </label>
-    <label class="field">
-      <span>Charged Battery Threshold (%)</span>
-      <input
-        id="matter-charged-battery-threshold"
-        type="number"
-        min="1"
-        max="100"
-        step="1"
-        placeholder="100"
-      />
-      <small
-        >The tile shows Charging while docked below this battery percentage, and
-        Docked at or above it. Lower it (e.g. 90) if a worn battery makes the
-        robot report fully charged early.</small
-      >
-    </label>
-    <p class="help matter-setup-note">
-      After saving and restarting the Roborock bridge, use the Matter Pairing
-      section below. Apple Home may need both the bridge QR code and the
-      vacuum's 11-digit setup code.
-    </p>
-
     <details id="advanced-settings" class="advanced-settings">
       <summary>Advanced troubleshooting</summary>
       <p class="help">
@@ -164,6 +131,130 @@
     </div>
   </section>
 
+  <section class="panel">
+    <div class="section-header">
+      <div>
+        <h2>Apple Home Features</h2>
+        <p class="help">
+          What each robot exposes through Matter. Options marked
+          <strong>&#9888; re-pair</strong> change the robot's announced
+          capabilities: after toggling them, save, restart Homebridge, then
+          remove the robot from Apple Home and pair it again — Matter locks
+          capabilities at pairing time.
+        </p>
+      </div>
+    </div>
+
+    <label class="checkbox">
+      <input id="enable-matter-service-area" type="checkbox" />
+      <span>
+        Room &amp; map selection <strong>&#9888; re-pair</strong>
+        <small
+          >Pick rooms to clean directly in Apple Home, using your Roborock room
+          names (multi-map homes included).</small
+        >
+      </span>
+    </label>
+
+    <label class="checkbox">
+      <input id="enable-live-room-tracking" type="checkbox" />
+      <span>
+        Live room tracking
+        <small
+          >While cleaning, the robot's map position is resolved to the room it
+          is physically inside and shown as the current room in Apple Home
+          (fetched every ~20 s during active runs only).</small
+        >
+      </span>
+    </label>
+
+    <label class="checkbox">
+      <input id="enable-matter-clean-mode" type="checkbox" />
+      <span>
+        Cleaning mode selection <strong>&#9888; re-pair</strong>
+        <small
+          >Vacuum / Mop / Vacuum + Mop in Apple Home's mode picker,
+          capability-gated per robot.</small
+        >
+      </span>
+    </label>
+
+    <label class="checkbox">
+      <input id="enable-fan-power-clean-modes" type="checkbox" />
+      <span>
+        Suction-level cleaning modes <strong>&#9888; re-pair</strong>
+        <small
+          >Adds Quiet / Balanced / Turbo / Max (and Max+ on Q7) to the mode
+          picker — Apple renders them as Quiet / Automatic / Quick / Max / Deep
+          Clean. Requires cleaning mode selection above.</small
+        >
+      </span>
+    </label>
+
+    <label class="checkbox">
+      <input id="enable-matter-power-source" type="checkbox" />
+      <span>
+        Battery status <strong>&#9888; re-pair</strong>
+        <small
+          >Battery percentage and charging state on the Matter accessory. See
+          the README for a known Apple-side limitation on percentage
+          refresh.</small
+        >
+      </span>
+    </label>
+
+    <label class="checkbox">
+      <input id="enable-matter-extended-states" type="checkbox" />
+      <span>
+        Returning status
+        <small
+          >Shows the extended Matter Returning state while the robot heads back
+          to the dock. Off by default for maximum Apple Home
+          compatibility.</small
+        >
+      </span>
+    </label>
+
+    <label class="checkbox">
+      <input id="enable-matter-charging-docked" type="checkbox" />
+      <span>
+        Show Charging/Docked on the Apple Home tile
+        <small
+          >Reports real Matter Charging and Docked states instead of Ready while
+          on the dock. Requires a recent iOS/tvOS; turn off and restart the
+          bridge if the tile misbehaves.</small
+        >
+      </span>
+    </label>
+    <label class="field">
+      <span>Charged Battery Threshold (%)</span>
+      <input
+        id="matter-charged-battery-threshold"
+        type="number"
+        min="1"
+        max="100"
+        step="1"
+        placeholder="100"
+      />
+      <small
+        >The tile shows Charging while docked below this battery percentage, and
+        Docked at or above it. Lower it (e.g. 90) if a worn battery makes the
+        robot report fully charged early.</small
+      >
+    </label>
+    <p class="help matter-setup-note">
+      After saving and restarting the Roborock bridge, use the Matter Pairing
+      section below. Apple Home may need both the bridge QR code and the
+      vacuum's 11-digit setup code.
+    </p>
+
+    <div class="actions">
+      <button id="save-feature-settings" class="secondary">
+        Save Settings
+      </button>
+    </div>
+  </section>
+
   <section class="panel">
     <div class="section-header">
       <div>

package/homebridge-ui/public/index.js

@@ -8,6 +8,21 @@ const elements = {
   devicesEmpty: document.getElementById("devices-empty"),
   refreshDevices: document.getElementById("refresh-devices"),
   debugMode: document.getElementById("debug-mode"),
+  enableMatterServiceArea: document.getElementById(
+    "enable-matter-service-area"
+  ),
+  enableLiveRoomTracking: document.getElementById("enable-live-room-tracking"),
+  enableMatterCleanMode: document.getElementById("enable-matter-clean-mode"),
+  enableFanPowerCleanModes: document.getElementById(
+    "enable-fan-power-clean-modes"
+  ),
+  enableMatterPowerSource: document.getElementById(
+    "enable-matter-power-source"
+  ),
+  enableMatterExtendedStates: document.getElementById(
+    "enable-matter-extended-states"
+  ),
+  saveFeatureSettings: document.getElementById("save-feature-settings"),
   enableMatterChargingDocked: document.getElementById(
     "enable-matter-charging-docked"
   ),
@@ -124,6 +139,35 @@ async function loadConfig() {
       elements.skipDevices.value = config.skipDevices;
     }
     elements.debugMode.checked = Boolean(config.debugMode);
+    // Apple Home feature toggles. Service Area, clean mode, power source and
+    // live room tracking default ON (config semantics: `!== false`);
+    // suction-level modes and extended states default OFF.
+    if (elements.enableMatterServiceArea) {
+      elements.enableMatterServiceArea.checked =
+        config.enableMatterServiceArea !== false;
+    }
+    if (elements.enableLiveRoomTracking) {
+      elements.enableLiveRoomTracking.checked =
+        config.enableLiveRoomTracking !== false;
+    }
+    if (elements.enableMatterCleanMode) {
+      elements.enableMatterCleanMode.checked =
+        config.enableMatterCleanMode !== false;
+    }
+    if (elements.enableFanPowerCleanModes) {
+      elements.enableFanPowerCleanModes.checked = Boolean(
+        config.enableFanPowerCleanModes
+      );
+    }
+    if (elements.enableMatterPowerSource) {
+      elements.enableMatterPowerSource.checked =
+        config.enableMatterPowerSource !== false;
+    }
+    if (elements.enableMatterExtendedStates) {
+      elements.enableMatterExtendedStates.checked = Boolean(
+        config.enableMatterExtendedOperationalStates
+      );
+    }
     if (elements.enableMatterChargingDocked) {
       elements.enableMatterChargingDocked.checked = Boolean(
         config.enableMatterChargingDockedStates
@@ -213,6 +257,16 @@ function getFormValues() {
     baseURL: getBaseUrl(),
     skipDevices: getSkipDevices(),
     debugMode: getDebugMode(),
+    enableMatterServiceArea: Boolean(elements.enableMatterServiceArea?.checked),
+    enableLiveRoomTracking: Boolean(elements.enableLiveRoomTracking?.checked),
+    enableMatterCleanMode: Boolean(elements.enableMatterCleanMode?.checked),
+    enableFanPowerCleanModes: Boolean(
+      elements.enableFanPowerCleanModes?.checked
+    ),
+    enableMatterPowerSource: Boolean(elements.enableMatterPowerSource?.checked),
+    enableMatterExtendedOperationalStates: Boolean(
+      elements.enableMatterExtendedStates?.checked
+    ),
     enableMatterChargingDockedStates: Boolean(
       elements.enableMatterChargingDocked?.checked
     ),
@@ -1207,6 +1261,11 @@ function init() {
     showToast("error", "Failed to load current config.");
   });
   elements.saveSettings.addEventListener("click", () => saveCredentials(true));
+  if (elements.saveFeatureSettings) {
+    elements.saveFeatureSettings.addEventListener("click", () =>
+      saveCredentials(true)
+    );
+  }
   elements.login.addEventListener("click", login);
   elements.send2fa.addEventListener("click", sendTwoFactorEmail);
   elements.verify2fa.addEventListener("click", verifyTwoFactorCode);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "2.8.1",
+  "version": "2.9.1",
   "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/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

@@ -3467,9 +3467,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 +3756,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 +3953,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) {