homebridge-roborock-matter 3.4.5 → 3.4.6

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 3.4.6
+
+**Trying cloud-only mode once marked a robot "Cloud only" forever.** jawnlydon reported in [#7](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/7) that a "Cloud Only" instance of his robot "seems to have stuck around through several re-pairs" — surviving a bridge restart, repeated Apple Home re-pairings, and a complete uninstall and reinstall of the plugin. It was not a leftover accessory. It was one stale field.
+
+- **The markers cloud-only mode writes are now retracted when it is switched off.** Enabling the mode stamps a robot's transport diagnostics to say local transport is disabled, and those diagnostics are persisted. `tcpConnectionState` is only ever rewritten when a LAN connection is actually attempted — and none is attempted for a robot no local IP was discovered for — so for such a robot the marker stayed on disk permanently, outliving the setting that wrote it. Startup now reconciles the markers in both directions, clearing only the fields that still hold the marker value so a live LAN connection is never stomped.
+- **The report stopped contradicting itself.** Reading that stale marker back, the device card said `connectionStatus: Cloud only` with the hint "Cloud-only mode is enabled, so local LAN discovery and local TCP control are disabled" — two lines under the same report's `cloudOnlyMode: disabled`. The report was pointing at a setting that was off, and it cost its reader an evening.
+- **Setting and clearing derive from one table**, so a marker added later is retracted later. A hand-written list of fields to put back is the same mistake as a hand-written list of files or log lines, one level down — the lesson 3.4.3 and 3.4.5 each learned in their own layer.
+- **`cloudOnlyMode` in the diagnostic report now quotes the saved config, not the checkbox.** The `matterFeatures` line was fixed for exactly this reason and the fix stopped at that line, leaving the line directly above it still reading its form control — so a report could state a setting the running plugin did not have. A test now enumerates the rule over the source: nothing the report builder reaches may read the settings form, except the helpers whose whole job is to warn that the form and the saved config disagree. Unsaved edits to cloud-only mode now raise that warning too.
+
 ## 3.4.5
 
 **The one log line that exists to diagnose Apple Home display problems was hiding the transitions.** `Matter publish for <robot>: battery=…, operationalState=…, runMode=…, cleanMode=…` was added so an Apple Home display issue could be settled from a single log excerpt — and it was only ever emitted when the **battery** value changed. skmzwanke reported in [#8](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/8) that his Apple Home tile sat on "Traveling to Room"/"Preparing" for an entire cleaning run, and sent a log covering that whole run: every operational-state transition in it was invisible, because the line only appeared on the four polls where the battery happened to tick down. The log contained the answer and could not show it.

package/homebridge-ui/public/index.js

@@ -252,21 +252,64 @@ function getCloudOnlyMode() {
  *
  * @returns {Promise<string>}
  */
-async function describeEnabledMatterFeatures() {
-  let config = null;
+/**
+ * The plugin config as SAVED, or null when it cannot be read.
+ *
+ * Every settings-derived line in the diagnostic report goes through here. The
+ * form is only ever consulted afterwards, to warn that it disagrees.
+ *
+ * @returns {Promise<Record<string, any> | null>}
+ */
+async function readSavedPluginConfig() {
   try {
     const configs =
       window.homebridge &&
       typeof window.homebridge.getPluginConfig === "function"
         ? await window.homebridge.getPluginConfig()
         : null;
-    config = configs
-      ? configs.find((entry) => entry.platform === "RoborockVacuumPlatform")
+    return configs
+      ? configs.find((entry) => entry.platform === "RoborockVacuumPlatform") ||
+          null
       : null;
   } catch {
+    return null;
+  }
+}
+
+/**
+ * Cloud-only mode as the RUNNING plugin has it.
+ *
+ * This read the checkbox until 3.4.6, which is the same trap the matterFeatures
+ * line was fixed for one line below — fixing the line in front of me instead of
+ * the rule. A user who had tried cloud-only mode and switched it off again got
+ * a report whose settings line said `disabled` while the device below it said
+ * "Cloud only", and spent an evening hunting a ghost setting.
+ *
+ * @returns {Promise<string>}
+ */
+async function describeSavedCloudOnlyMode() {
+  const config = await readSavedPluginConfig();
+  if (!config) {
     return "unavailable";
   }
 
+  const label = config.cloudOnlyMode === true ? "enabled" : "disabled";
+  return hasUnsavedCloudOnlyEdit(config)
+    ? `${label} (WARNING: the settings form has unsaved changes; this is the value the plugin is running)`
+    : label;
+}
+
+/** True when the cloud-only checkbox differs from what is saved in the config. */
+function hasUnsavedCloudOnlyEdit(config) {
+  return (
+    Boolean(elements.cloudOnlyMode && elements.cloudOnlyMode.checked) !==
+    (config.cloudOnlyMode === true)
+  );
+}
+
+async function describeEnabledMatterFeatures() {
+  const config = await readSavedPluginConfig();
+
   if (!config) {
     return "unavailable";
   }
@@ -1114,7 +1157,7 @@ async function buildDiagnosticsReport(result) {
     `nodeVersion: ${result.nodeVersion || "unknown"}`,
     `token: ${hasToken ? "present" : "missing"}`,
     `homeData: ${result.hasHomeData ? "present" : "missing"}`,
-    `cloudOnlyMode: ${getCloudOnlyMode() ? "enabled" : "disabled"}`,
+    `cloudOnlyMode: ${await describeSavedCloudOnlyMode()}`,
     // Which Apple Home features are switched on decides what the plugin is
     // even allowed to publish, so a report that omits them cannot answer
     // "why doesn't Apple Home show X?" — the first question every one of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "3.4.5",
+  "version": "3.4.6",
   "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/roborockAPI.js

@@ -38,6 +38,27 @@ const B01_LIVE_ROOM_FETCH_V1_STATES = new Set([5, 11, 16, 17, 18]);
 // cached live room is cleared so a later run starts fresh.
 const B01_LIVE_ROOM_CLEAR_V1_STATES = new Set([3, 8]);
 
+// The transport-diagnostics fields cloud-only mode owns, and the marker value
+// it writes into each.
+//
+// These diagnostics are persisted, so the markers outlive the setting unless
+// something puts them back. `tcpConnectionState` is the one that stuck: it is
+// only rewritten when a LAN connection is actually attempted, and none is
+// attempted for a robot no local IP was ever discovered for. A user who tried
+// cloud-only mode once and switched it off again kept "Cloud only" on the
+// device card through restarts, re-pairs and a full plugin reinstall, and the
+// diagnostic report told them cloud-only mode was enabled two lines under its
+// own `cloudOnlyMode: disabled`.
+//
+// Setting and clearing both derive from this table on purpose. A hand-written
+// list of fields to clear is the same mistake as a hand-written list of files
+// or log lines one level up: it is correct until someone adds a fourth marker.
+const CLOUD_ONLY_TRANSPORT_MARKERS = Object.freeze({
+  lastTransportReason: "cloud-only-mode",
+  localDiscoveryState: "disabled",
+  tcpConnectionState: "disabled",
+});
+
 // Minimum gap between live-room map fetch attempts while cleaning. The map
 // payload is an order of magnitude heavier than get_status, so it rides a
 // slower cadence than the active status polls — but 20s meant a robot could
@@ -896,6 +917,49 @@ class Roborock {
     });
   }
 
+  /**
+   * Reconcile one robot's cloud-only transport markers with the mode as it is
+   * configured right now.
+   *
+   * Enabling stamps every marker in CLOUD_ONLY_TRANSPORT_MARKERS. Disabling
+   * clears exactly those fields that still hold the marker value, so a LAN
+   * connection that came up in the meantime is never stomped, and a robot that
+   * has no diagnostics yet is not given any.
+   *
+   * @param {string} duid
+   * @param {boolean} cloudOnly
+   */
+  async syncCloudOnlyTransportMarkers(duid, cloudOnly) {
+    if (!duid) {
+      return;
+    }
+
+    if (cloudOnly) {
+      await this.updateTransportDiagnostics(duid, {
+        ...CLOUD_ONLY_TRANSPORT_MARKERS,
+      });
+      return;
+    }
+
+    const entry = this.getTransportDiagnostics()[duid];
+    if (!entry || typeof entry != "object") {
+      return;
+    }
+
+    const cleared = {};
+    for (const [field, marker] of Object.entries(
+      CLOUD_ONLY_TRANSPORT_MARKERS
+    )) {
+      if (entry[field] === marker) {
+        cleared[field] = null;
+      }
+    }
+
+    if (Object.keys(cleared).length) {
+      await this.updateTransportDiagnostics(duid, cleared);
+    }
+  }
+
   getTransportDiagnostics() {
     const diagnostics = this.getStateAsync("TransportDiagnostics");
     if (diagnostics && typeof diagnostics.val == "string") {
@@ -1518,29 +1582,30 @@ class Roborock {
             ignoredSet
           );
 
-          if (this.isCloudOnlyModeEnabled()) {
+          const cloudOnly = this.isCloudOnlyModeEnabled();
+          if (cloudOnly) {
             this.log.info(
               "Roborock cloud-only mode is enabled; local LAN discovery and TCP connections will be skipped."
             );
+          }
 
-            for (const device of managedDevicesForDiagnostics) {
+          for (const device of managedDevicesForDiagnostics) {
+            if (cloudOnly) {
               await this.updateTransportDiagnostics(device.duid, {
                 lastTransport: "cloud",
-                lastTransportReason: "cloud-only-mode",
                 localIp: null,
-                localDiscoveryState: "disabled",
-                tcpConnectionState: "disabled",
+              });
+            } else if (!device.localKey) {
+              await this.updateTransportDiagnostics(device.duid, {
+                lastTransport: "cloud",
+                lastTransportReason: "missing-local-key",
               });
             }
-          } else {
-            for (const device of managedDevicesForDiagnostics) {
-              if (!device.localKey) {
-                await this.updateTransportDiagnostics(device.duid, {
-                  lastTransport: "cloud",
-                  lastTransportReason: "missing-local-key",
-                });
-              }
-            }
+
+            // Runs in BOTH directions: switching the mode off has to retract
+            // the markers it wrote, or they stay on disk for good and the
+            // device keeps reporting itself as cloud-only.
+            await this.syncCloudOnlyTransportMarkers(device.duid, cloudOnly);
           }
 
           // this.adapter.log.debug(`initUser test: ${JSON.stringify(Array.from(this.adapter.localKeys.entries()))}`);
@@ -4505,6 +4570,6 @@ class Roborock {
   }
 }
 
-module.exports = { Roborock };
+module.exports = { Roborock, CLOUD_ONLY_TRANSPORT_MARKERS };
 
 ////////////////////////////////////////////////////////////////////////////////////////////////////