homebridge-roborock-matter 2.8.1 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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.0",
   "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": {