homebridge-roborock-vacuum 2.2.6 → 2.2.7

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.2.7
+
+- **Fix (connectivity)**: The plugin no longer fails to start when the Roborock cloud is unreachable. Startup used to abandon everything after the home-data request timed out (`AxiosError: timeout of 20000ms exceeded`, `ECONNRESET`), so no accessories were registered and every command was refused with "Adapter not inited" — even though the vacuum was reachable on the LAN the whole time. The home data (device list and local keys) is now cached on disk, and when the cloud fetch fails the plugin starts in **local-only mode** from that cache: it still runs LAN discovery, connects to each vacuum over the local protocol, publishes the accessories, and accepts start/stop/dock commands. Cloud-only features (scenes, push updates, fresh online flags) resume by themselves once the cloud answers again, without a Homebridge restart. One successful online start is needed to seed the cache; with no cache the plugin stays idle as before, now with a message that says why
+- **Fix (connectivity)**: A vacuum the plugin is locally connected to is treated as online even when the cached cloud status says otherwise, so commands and polling are not blocked by a stale offline flag during a cloud outage
+- **Fix (connectivity)**: Local-only mode no longer depends on UDP discovery finding the vacuums. Each device's last known LAN address is cached next to the device list, so vacuums on another VLAN (or when port 58866 is taken by another integration on the same host) are still dialed directly while the cloud is down
+- **Fix (connectivity)**: Local-only mode also works without a cloud session. When the login itself fails while the cloud is down (or the cached session was cleared), the plugin still starts from the cache and logs in again on the periodic refresh once the cloud answers. Only network-level login failures are retried; a rejected login or a pending two-factor prompt is left to the Config UI
+- **Fix (connectivity)**: A degraded cloud no longer costs you the session. The cached session is cleared only when the login API explicitly rejects it with an API error code. An empty or malformed answer, and a `401` from the device API that the login API does not confirm, are treated as transient and retried
+- **Fix (connectivity)**: The cached device list is tagged with the account it was fetched for and ignored after switching accounts, so a local-only start never controls another account's vacuums
+- **Fix (logging)**: During an outage the periodic home-data refresh logs its failure once at error level and then at debug level until the cloud answers again, instead of an error every interval. The signed device API now times out after 20 s instead of hanging on a black-holed connection
+
 ## 2.2.6
 
 - **New Feature**: The Roborock region is now detected automatically from the account email when no endpoint is configured — the config UI's Region selector gains an "Auto detect (recommended)" option and new installs no longer need to know which server their account lives on. An explicitly chosen region keeps working exactly as before, and if detection fails the plugin falls back to the previous US default with a hint to pin the region manually. Two-factor login also benefits: it now sends the account's real registered country from the detection response instead of guessing it from the endpoint host (which mapped every EU account to Germany)

package/README.md

@@ -115,6 +115,33 @@ Pairing is one-time per node — switching a device between HAP and Matter later
 - Scene buttons require the **separate bridge pairing** (step 5) and appear as plain on/off switches in the controller.
 - Multi-floor maps are not exposed (rooms come from the currently active map), and zone cleaning, consumables and dock controls other than the mop-wash switch are not available over Matter yet.
 
+## Cloud outages and local-only mode
+
+Roborock's cloud is required to log in and to read your device list, but it is
+not required to _control_ a vacuum: once the plugin knows a device's local key,
+it talks to the robot directly over your LAN.
+
+The plugin caches the device list, the local keys and each vacuum's last known
+LAN address on disk (owner-readable only) after every successful cloud
+refresh. If the Roborock cloud is unreachable when Homebridge starts, the
+plugin falls back to that cache and starts in **local-only mode**:
+
+- your vacuums still appear in HomeKit, and start/stop/dock commands work over the LAN;
+- vacuums are found by UDP discovery, or dialed at their cached address when
+  discovery finds nothing (another VLAN, or port 58866 in use);
+- cloud-only features are unavailable until the cloud returns — scenes, push
+  status updates, and the cloud online flag;
+- the plugin keeps retrying in the background, so cloud features come back on
+  their own without a Homebridge restart. If the login itself failed during
+  the outage, the plugin logs in again by itself once the cloud answers (a
+  pending two-factor prompt still needs the Config UI).
+
+The log says which mode you are in (`Starting adapter finished in local-only
+mode (cloud unreachable).`). Two caveats: the plugin needs **one successful
+online start** to create the cache, so a brand-new install cannot start offline,
+and a vacuum that is shared from another Roborock account can only be controlled
+through the cloud.
+
 ## Dock mop-wash switch
 
 On vacuums whose dock can wash the mop (G10, S7 Pro/MaxV Ultra, S7 Max Ultra, S8 Pro Ultra, Q Revo family, …) the plugin adds a switch that starts and stops a dock mop wash:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-vacuum",
-  "version": "2.2.6",
+  "version": "2.2.7",
   "description": "Roborock Vacuum Cleaner - plugin for Homebridge.",
   "license": "MIT",
   "keywords": [

package/roborockLib/lib/vacuum.js

@@ -141,6 +141,9 @@ class vacuum {
             // another account can never be local.
             if (attribute == "ip" && !this.adapter.isSharedDevice(duid)) {
               this.adapter.localDevices[duid] = networkInfo[attribute];
+              if (typeof this.adapter.persistLocalDevices === "function") {
+                this.adapter.persistLocalDevices();
+              }
             }
             this.adapter.setStateAsync(
               `Devices.${duid}.networkInfo.${attribute}`,

package/roborockLib/roborockAPI.js

@@ -126,6 +126,10 @@ class Roborock {
 
     this.scenesData = null; // Store scenes data locally
 
+    // Resolved Roborock home id. May start null on a cloud-failed (local-only)
+    // startup; updateHomeData learns it once the cloud is reachable.
+    this.homeId = null;
+
     this.name = "roborock";
     this.deviceNotify = null;
     this.baseURL = options.baseURL || "usiot.roborock.com";
@@ -162,9 +166,23 @@ class Roborock {
     clearTimeout(timeout);
   }
 
+  // State ids that are mirrored to disk so they survive a restart: the cloud
+  // session/client id, and the home data (device list + local keys), its
+  // home id and the devices' last LAN addresses, which let the plugin start
+  // over the LAN when the cloud is down.
+  isPersistedStateId(id) {
+    return (
+      id == "UserData" ||
+      id == "clientID" ||
+      id == "HomeData" ||
+      id == "HomeId" ||
+      id == "LocalDevices"
+    );
+  }
+
   getStateAsync(id) {
     try {
-      if (id == "UserData" || id == "clientID") {
+      if (this.isPersistedStateId(id)) {
         const persistPath = this.getPersistPath(id);
         if (fs.existsSync(persistPath)) {
           return JSON.parse(fs.readFileSync(persistPath, "utf8"));
@@ -182,7 +200,8 @@ class Roborock {
           return legacyState;
         }
 
-        return null;
+        // Fall back to the in-memory copy when nothing is on disk yet.
+        return this.states[id] !== undefined ? this.states[id] : null;
       }
 
       return this.states[id];
@@ -198,10 +217,11 @@ class Roborock {
 
   async setStateAsync(id, state) {
     try {
-      if (id == "UserData" || id == "clientID") {
+      if (this.isPersistedStateId(id)) {
         const persistPath = this.getPersistPath(id);
         fs.mkdirSync(path.dirname(persistPath), { recursive: true });
-        // 0600: UserData contains the cloud token and rriot secrets.
+        // 0600: UserData holds the cloud token/rriot secrets and HomeData
+        // holds per-device localKey secrets.
         fs.writeFileSync(persistPath, JSON.stringify(state, null, 2), {
           encoding: "utf8",
           mode: 0o600,
@@ -221,11 +241,7 @@ class Roborock {
         this.deviceNotify(id, state);
       }
     } catch (error) {
-      if (
-        (id == "UserData" || id == "clientID") &&
-        error &&
-        error.code == "EACCES"
-      ) {
+      if (this.isPersistedStateId(id) && error && error.code == "EACCES") {
         try {
           const fallbackPath = path.join(
             this.forceTemporaryPersistPath(),
@@ -250,6 +266,9 @@ class Roborock {
 
   async deleteStateAsync(id) {
     try {
+      // Only the session files are removed from disk. HomeData, HomeId and
+      // LocalDevices are the offline cache and deliberately survive a failed
+      // login; loadCachedHomeData rejects a cache from another account.
       if (id == "UserData" || id == "clientID") {
         const persistPath = this.getPersistPath(id);
         if (fs.existsSync(persistPath)) {
@@ -461,30 +480,119 @@ class Roborock {
     // api/v1/getUrlByEmail(email = ...)
 
     const userdata = await this.getUserData(this.loginApi);
-    if (!userdata) {
+    if (userdata) {
+      this.setupCloudApi(userdata);
+    } else {
+      // No session (cloud unreachable, or 2FA pending): local control only
+      // needs the cached local keys and IPs, so try the local-only start.
+      // updateHomeData logs in again once the cloud answers.
       this.log.error(
-        "Login failed or requires 2FA. Please complete authentication in the Config UI."
+        "Login failed or requires 2FA. Please complete authentication in the " +
+          "Config UI. Trying to start in local-only mode from the cached " +
+          "device list."
       );
       await this.setStateAsync("info.connection", { val: false, ack: true });
-      return;
+    }
+
+    // Fetch home data (device list + local keys). The cloud is tried first; on
+    // failure we fall back to the last cached copy so the plugin can still
+    // control the vacuums over the LAN while the cloud is unreachable.
+    let homeId = null;
+    let homedataResult = null;
+    let fromCache = false;
+
+    if (userdata) {
+      try {
+        const fetched = await this.fetchHomeDataFromCloud();
+        homeId = fetched.homeId;
+        homedataResult = fetched.homedataResult;
+
+        await this.setStateAsync(
+          "HomeData",
+          this.homeDataState(homedataResult)
+        );
+        if (homeId != null) {
+          await this.setStateAsync("HomeId", { val: homeId, ack: true });
+        }
+      } catch (error) {
+        this.log.error(
+          "Failed to fetch home data from the Roborock cloud: " +
+            (error && error.message ? error.message : error)
+        );
+      }
+    }
+
+    if (!homedataResult) {
+      const cached = this.loadCachedHomeData();
+      if (!cached) {
+        this.log.error(
+          "No cached device data is available, so the plugin cannot start " +
+            "offline. It needs at least one successful online startup to cache " +
+            "the device list and local keys. Staying idle until the Roborock " +
+            "cloud is reachable."
+        );
+        await this.setStateAsync("info.connection", { val: false, ack: true });
+        if (callback) {
+          callback();
+        }
+        return;
+      }
+
+      homedataResult = cached.homedataResult;
+      homeId = cached.homeId;
+      fromCache = true;
+      // The startup error above already said why; keep the periodic refresh
+      // quiet until the cloud answers again.
+      this.cloudUnreachable = true;
+
+      // Publish the cached copy as the live home data. Everything
+      // downstream - the device list, the protocol version used to frame
+      // local messages, and every status read - goes through
+      // getParsedHomeData, which reads this.states. Without this the plugin
+      // would look like it owns no devices and would unregister every
+      // cached accessory.
+      await this.setStateAsync("HomeData", this.homeDataState(homedataResult));
+
+      this.log.warn(
+        "Roborock cloud is unreachable - starting in LOCAL-ONLY mode using " +
+          "the last cached device list. Commands are sent over the LAN; " +
+          "cloud features (scenes, push updates) resume automatically once " +
+          "the cloud is reachable again."
+      );
     }
 
     try {
-      this.loginApi.defaults.headers.common["Authorization"] = userdata.token;
+      await this.initializeFromHomeData(
+        userdata,
+        homedataResult,
+        homeId,
+        fromCache
+      );
     } catch (error) {
       this.log.error(
-        "Failed to login. Most likely wrong token! Deleting HomeData and UserData. Try again! " +
-          error
+        "Failed to initialize devices from home data: " +
+          (error && error.stack ? error.stack : error)
       );
+    }
 
-      this.deleteStateAsync("HomeData");
-      this.deleteStateAsync("UserData");
+    if (callback) {
+      callback();
     }
+  }
+
+  // Authorize the login API with the session token and build the Hawk-signed
+  // device API. Runs at startup and again from updateHomeData when a
+  // session-less (local-only) start logs in once the cloud is back.
+  setupCloudApi(userdata) {
+    this.userData = userdata;
+    this.loginApi.defaults.headers.common["Authorization"] = userdata.token;
     const rriot = userdata.rriot;
 
-    // Initialize the real API.
     this.api = axios.create({
       baseURL: rriot.r.a,
+      // Fail instead of hanging when the cloud black-holes connections;
+      // otherwise the periodic refresh piles up requests every interval.
+      timeout: 20000,
     });
     this.api.interceptors.request.use((config) => {
       try {
@@ -520,147 +628,320 @@ class Roborock {
       }
       return config;
     });
+  }
+
+  // Start (or restart) the cloud MQTT client for a session. Any previous
+  // client is closed first so a re-login never leaves a second one
+  // reconnecting in the background.
+  async initCloudMqtt(userdata) {
+    this.rr_mqtt_connector.disconnectClient();
+    await this.rr_mqtt_connector.initUser(userdata);
+    await this.rr_mqtt_connector.initMQTT_Subscribe();
+    await this.rr_mqtt_connector.initMQTT_Message();
+  }
+
+  // Log in again after a session-less (local-only) start. Only network-level
+  // login failures are retried; a rejected login or a pending 2FA is left for
+  // the user. Returns true once the signed API and MQTT client are up.
+  async reconnectCloud() {
+    if (this.loginRetryable === false || !this.config.password) {
+      return false;
+    }
 
-    // Get home details.
     try {
-      const homeDetail = await this.loginApi.get("api/v1/getHomeDetail");
-      if (homeDetail && homeDetail.data && homeDetail.data.data) {
-        const homeId = homeDetail.data.data.rrHomeId;
+      const userdata = await this.getUserData(this.loginApi);
+      if (!userdata) {
+        return false;
+      }
 
-        if (this.api) {
-          const homedata = await this.api.get(`v2/user/homes/${homeId}`);
-          const homedataResult = homedata.data.result;
+      this.setupCloudApi(userdata);
+      await this.initCloudMqtt(userdata);
+      this.log.info("Logged in to the Roborock cloud again.");
+      return true;
+    } catch (error) {
+      this.log.debug(`Cloud re-login failed: ${error && error.message}`);
+      return false;
+    }
+  }
 
-          await this.setStateAsync("HomeData", {
-            val: JSON.stringify(homedataResult),
-            ack: true,
-          });
+  // Cloud failures repeat every refresh interval during an outage: log the
+  // first at error level, the rest at debug, and announce the recovery once.
+  logCloudFailure(message) {
+    if (this.cloudUnreachable) {
+      this.log.debug(message);
+      return;
+    }
 
-          // skip devices whose serial number or device ID is in ignoredDevices or skipDevices
-          const ignoredDevices = this.config.ignoredDevices || [];
-          const skipDevices = this.parseSkipDevices(this.config.skipDevices);
-          const ignoredSet = new Set([...ignoredDevices, ...skipDevices]);
-          // create devices and set states
-          this.products = homedataResult.products;
-          this.devices = homedataResult.devices || [];
-          this.devices = this.devices.filter(
-            (device) =>
-              !ignoredSet.has(device.sn) && !ignoredSet.has(device.duid)
-          );
-          this.receivedDevices = (homedataResult.receivedDevices || []).filter(
-            (device) =>
-              !ignoredSet.has(device.sn) && !ignoredSet.has(device.duid)
-          );
+    this.cloudUnreachable = true;
+    this.log.error(
+      `${message} Further failures are logged at debug level until the cloud answers again.`
+    );
+  }
 
-          const allManagedDevices = (homedataResult.devices || []).concat(
-            homedataResult.receivedDevices || []
-          );
-          const localKeyDevices = [];
-          for (const device of allManagedDevices) {
-            if (!device || !device.duid) {
-              continue;
-            }
+  noteCloudReachable() {
+    if (this.cloudUnreachable) {
+      this.cloudUnreachable = false;
+      this.log.info(
+        "Roborock cloud is reachable again; resuming cloud features."
+      );
+    }
+  }
 
-            if (
-              (device.sn && ignoredSet.has(device.sn)) ||
-              (device.duid && ignoredSet.has(device.duid))
-            ) {
-              continue;
-            }
+  // True when the login API explicitly rejected the session. A degraded cloud
+  // can answer 200 with an empty or non-JSON body; that is not a rejection,
+  // and wiping the session on it would force a password login (possibly with
+  // 2FA) on the next start.
+  isSessionRejection(body) {
+    return !!(body && typeof body.code === "number" && body.code !== 200);
+  }
 
-            if (!device.localKey) {
-              this.log.warn(
-                `Device ${device.duid} (product ${device.productId || "unknown"}) has no localKey in home data and cannot be controlled. Fields returned by the API: ${Object.keys(device).join(", ")}`
-              );
-              continue;
-            }
+  // Ask the login API whether the current session is still accepted. Returns
+  // true only on an explicit rejection; an unreachable cloud cannot tell.
+  async isSessionRejected() {
+    try {
+      const homeDetail = await this.loginApi.get("api/v1/getHomeDetail");
+      return this.isSessionRejection(homeDetail && homeDetail.data);
+    } catch (error) {
+      return false;
+    }
+  }
 
-            localKeyDevices.push(device);
-          }
+  // Fetch the account's home data from the cloud. Throws on any failure
+  // (network, timeout, or an unusable response) so the caller can fall back to
+  // the cached copy. Only an explicit rejection clears the cached session so
+  // the next startup re-logs in.
+  async fetchHomeDataFromCloud() {
+    const homeDetail = await this.loginApi.get("api/v1/getHomeDetail");
+    const body = homeDetail && homeDetail.data;
+    if (!(body && body.data)) {
+      if (this.isSessionRejection(body)) {
+        this.log.warn(
+          `The stored Roborock session was rejected (code ${body.code}: ${body.msg || "no message"}). ` +
+            "Clearing it so the next startup re-authenticates."
+        );
+        this.userData = null;
+        await this.deleteStateAsync("UserData");
+        throw new Error(
+          `getHomeDetail rejected the session (code ${body.code})`
+        );
+      }
+      throw new Error("getHomeDetail returned no usable data");
+    }
 
-          this.localKeys = new Map(
-            localKeyDevices.map((device) => [device.duid, device.localKey])
-          );
+    const homeId = body.data.rrHomeId;
 
-          // this.adapter.log.debug(`initUser test: ${JSON.stringify(Array.from(this.adapter.localKeys.entries()))}`);
+    if (!this.api) {
+      throw new Error("Signed cloud API is not initialized");
+    }
 
-          await this.rr_mqtt_connector.initUser(userdata);
-          await this.rr_mqtt_connector.initMQTT_Subscribe();
-          await this.rr_mqtt_connector.initMQTT_Message();
+    const homedata = await this.api.get(`v2/user/homes/${homeId}`);
+    const homedataResult = homedata && homedata.data && homedata.data.result;
+    if (!homedataResult) {
+      throw new Error("home data response was empty");
+    }
 
-          // store name of each room via ID
-          const rooms = homedataResult.rooms;
-          for (const room in rooms) {
-            const roomID = rooms[room].id;
-            const roomName = rooms[room].name;
+    return { homeId, homedataResult };
+  }
 
-            this.roomIDs[roomID] = roomName;
-          }
+  // HomeData state as stored: tagged with the account it belongs to, so a
+  // cache left behind by a previous account is never used for a local-only
+  // start.
+  homeDataState(homedataResult) {
+    return {
+      val: JSON.stringify(homedataResult),
+      ack: true,
+      account: this.config.username,
+    };
+  }
 
-          await this.loadSharedDeviceRooms();
-          this.log.debug(`RoomIDs debug: ${JSON.stringify(this.roomIDs)}`);
+  // Load the last home data cached on disk (written on every successful cloud
+  // fetch). Returns { homeId, homedataResult } or null when nothing is cached.
+  loadCachedHomeData() {
+    try {
+      const cached = this.getStateAsync("HomeData");
+      const raw = cached && typeof cached.val === "string" ? cached.val : null;
+      if (!raw) {
+        return null;
+      }
 
-          // reconnect every 3 hours (10800 seconds)
-          this.reconnectIntervall = this.setInterval(async () => {
-            this.log.debug(`Reconnecting after 3 hours!`);
+      if (cached.account && cached.account !== this.config.username) {
+        this.log.warn(
+          `Ignoring cached device data: it belongs to ${cached.account}, not ${this.config.username}.`
+        );
+        return null;
+      }
 
-            await this.rr_mqtt_connector.reconnectClient();
-          }, 10800 * 1000);
+      const homedataResult = JSON.parse(raw);
+      if (!homedataResult) {
+        return null;
+      }
 
-          this.homedataInterval = this.setInterval(
-            this.updateHomeData.bind(this),
-            this.updateInterval * 1000,
-            homeId
-          );
-          await this.updateHomeData(homeId);
+      const cachedHomeId = this.getStateAsync("HomeId");
+      const homeId =
+        cachedHomeId && cachedHomeId.val != null ? cachedHomeId.val : null;
 
-          const discoveredDevices = await this.localConnector.getLocalDevices();
+      return { homeId, homedataResult };
+    } catch (error) {
+      this.log.debug(
+        `Failed to read cached home data: ${error && error.message}`
+      );
+      return null;
+    }
+  }
 
-          await this.createDevices();
-          await this.getNetworkInfo();
+  // Last known LAN address per device, so a local-only start can dial the
+  // vacuums even when UDP discovery finds nothing (other VLAN, port 58866
+  // taken by another integration) and get_network_info needs the cloud.
+  loadCachedLocalDevices() {
+    const cached = this.getStateAsync("LocalDevices");
+    return cached && cached.val && typeof cached.val === "object"
+      ? cached.val
+      : {};
+  }
 
-          // merge udp discovered devices with local devices found via mqtt
-          Object.entries(discoveredDevices).forEach(([duid, ip]) => {
-            if (
-              !Object.prototype.hasOwnProperty.call(this.localDevices, duid)
-            ) {
-              this.localDevices[duid] = ip;
-            }
-          });
-          this.log.debug(`localDevices: ${JSON.stringify(this.localDevices)}`);
+  persistLocalDevices() {
+    if (Object.keys(this.localDevices).length === 0) {
+      return; // never replace a useful cache with nothing
+    }
 
-          for (const device in this.localDevices) {
-            const duid = device;
-            const ip = this.localDevices[device];
+    return this.setStateAsync("LocalDevices", {
+      val: this.localDevices,
+      ack: true,
+    });
+  }
 
-            await this.localConnector.createClient(duid, ip);
-          }
+  // Build the device list, local keys, MQTT/local connections and polling from
+  // home data - shared by the online path (fresh cloud data) and the
+  // local-only path (cached data). The cloud MQTT client and the home-data
+  // refresh interval are set up in both cases so cloud features recover on
+  // their own once the cloud is reachable again.
+  async initializeFromHomeData(userdata, homedataResult, homeId, fromCache) {
+    if (homeId != null) {
+      this.homeId = homeId;
+    }
+
+    // skip devices whose serial number or device ID is in ignoredDevices or skipDevices
+    const ignoredDevices = this.config.ignoredDevices || [];
+    const skipDevices = this.parseSkipDevices(this.config.skipDevices);
+    const ignoredSet = new Set([...ignoredDevices, ...skipDevices]);
+    // create devices and set states
+    this.products = homedataResult.products;
+    this.devices = homedataResult.devices || [];
+    this.devices = this.devices.filter(
+      (device) => !ignoredSet.has(device.sn) && !ignoredSet.has(device.duid)
+    );
+    this.receivedDevices = (homedataResult.receivedDevices || []).filter(
+      (device) => !ignoredSet.has(device.sn) && !ignoredSet.has(device.duid)
+    );
 
-          await this.initializeDeviceUpdates();
-          this.bInited = true;
-          this.log.info(`Starting adapter finished. Lets go!!!!!!!`);
-        } else {
-          this.log.info(
-            `Most likely failed to login. Deleting UserData to force new login!`
-          );
-          await this.deleteStateAsync(`UserData`);
-        }
-      } else {
+    const allManagedDevices = (homedataResult.devices || []).concat(
+      homedataResult.receivedDevices || []
+    );
+    const localKeyDevices = [];
+    for (const device of allManagedDevices) {
+      if (!device || !device.duid) {
+        continue;
+      }
+
+      if (
+        (device.sn && ignoredSet.has(device.sn)) ||
+        (device.duid && ignoredSet.has(device.duid))
+      ) {
+        continue;
+      }
+
+      if (!device.localKey) {
         this.log.warn(
-          "The stored Roborock session is invalid or expired. " +
-            "Deleting cached UserData to force a new login. " +
-            "Please re-authenticate in the plugin settings if this persists."
+          `Device ${device.duid} (product ${device.productId || "unknown"}) has no localKey in home data and cannot be controlled. Fields returned by the API: ${Object.keys(device).join(", ")}`
         );
-        this.userData = null;
-        await this.deleteStateAsync(`UserData`);
+        continue;
       }
-    } catch (error) {
-      this.log.error("Failed to get home details: " + error.stack);
+
+      localKeyDevices.push(device);
     }
 
-    if (callback) {
-      callback();
+    this.localKeys = new Map(
+      localKeyDevices.map((device) => [device.duid, device.localKey])
+    );
+
+    // The cloud MQTT client is initialised from the (cached) session even in
+    // local-only mode: it keeps retrying in the background, so the cloud path
+    // and push updates recover on their own once the broker is reachable.
+    // Without a session, reconnectCloud brings it up after the re-login.
+    if (userdata) {
+      await this.initCloudMqtt(userdata);
+    }
+
+    // store name of each room via ID
+    const rooms = homedataResult.rooms;
+    for (const room in rooms) {
+      const roomID = rooms[room].id;
+      const roomName = rooms[room].name;
+
+      this.roomIDs[roomID] = roomName;
     }
+
+    await this.loadSharedDeviceRooms();
+    this.log.debug(`RoomIDs debug: ${JSON.stringify(this.roomIDs)}`);
+
+    // reconnect every 3 hours (10800 seconds)
+    this.reconnectIntervall = this.setInterval(async () => {
+      this.log.debug(`Reconnecting after 3 hours!`);
+
+      await this.rr_mqtt_connector.reconnectClient();
+    }, 10800 * 1000);
+
+    // Periodic home-data refresh. It also drives cloud recovery: on a
+    // local-only start (no homeId yet) updateHomeData learns it via
+    // getHomeDetail before refreshing.
+    this.homedataInterval = this.setInterval(
+      () => this.updateHomeData(this.homeId),
+      this.updateInterval * 1000
+    );
+    // A fresh online start pulls once more to load scenes and reconcile
+    // intervals. In local-only mode the cloud is down, so defer to the interval
+    // instead of blocking startup on a call that will fail.
+    if (!fromCache) {
+      await this.updateHomeData(this.homeId);
+    }
+
+    const discoveredDevices = await this.localConnector.getLocalDevices();
+
+    await this.createDevices();
+    await this.getNetworkInfo();
+
+    // merge udp discovered devices with local devices found via mqtt
+    Object.entries(discoveredDevices).forEach(([duid, ip]) => {
+      if (!Object.prototype.hasOwnProperty.call(this.localDevices, duid)) {
+        this.localDevices[duid] = ip;
+      }
+    });
+
+    // Devices that answered neither the UDP broadcast nor (cloud down) the
+    // get_network_info request: dial the address they had last time. A stale
+    // one just fails to connect and goes through the usual reconnect loop.
+    for (const [duid, ip] of Object.entries(this.loadCachedLocalDevices())) {
+      if (!this.localDevices[duid] && this.localKeys.has(duid)) {
+        this.localDevices[duid] = ip;
+      }
+    }
+    await this.persistLocalDevices();
+    this.log.debug(`localDevices: ${JSON.stringify(this.localDevices)}`);
+
+    for (const device in this.localDevices) {
+      const duid = device;
+      const ip = this.localDevices[device];
+
+      await this.localConnector.createClient(duid, ip);
+    }
+
+    await this.initializeDeviceUpdates();
+    this.bInited = true;
+    this.log.info(
+      fromCache
+        ? "Starting adapter finished in local-only mode (cloud unreachable)."
+        : "Starting adapter finished. Lets go!!!!!!!"
+    );
   }
 
   async stopService() {
@@ -695,6 +976,7 @@ class Roborock {
 
       if (!this.config.password) {
         this.log.error("Password is missing and no valid token is available.");
+        this.loginRetryable = false;
         return null;
       }
 
@@ -725,6 +1007,7 @@ class Roborock {
       if (loginResult && loginResult.code === 2031) {
         this.authState.twoFactorRequired = true;
         this.authState.statusMessage = "Two-factor authentication required.";
+        this.loginRetryable = false;
         this.log.error(
           "Two-factor authentication required. Use the Config UI to continue."
         );
@@ -736,8 +1019,20 @@ class Roborock {
       // Failed logins (bad credentials, unreachable cloud) are expected
       // runtime conditions — report "no user data" so startService aborts
       // gracefully instead of crashing Homebridge with an unhandled
-      // rejection.
-      this.log.error(`Error in getUserData: ${error.message}`);
+      // rejection. Only a network-level failure (no HTTP answer, or a server
+      // error) may be retried automatically by reconnectCloud; a rejected
+      // login must never be repeated every interval.
+      this.loginRetryable = !!(
+        error &&
+        error.isAxiosError &&
+        (!error.response || error.response.status >= 500)
+      );
+      if (this.loginRetryable) {
+        // Repeats every refresh interval while the cloud is down.
+        this.logCloudFailure(`Error in getUserData: ${error.message}.`);
+      } else {
+        this.log.error(`Error in getUserData: ${error.message}`);
+      }
       await this.deleteStateAsync("HomeData");
       await this.deleteStateAsync("UserData");
       return null;
@@ -894,8 +1189,10 @@ class Roborock {
 
       const robotModel = this.getProductAttribute(duid, "model");
 
-      if (device.online) {
-        this.log.debug(`${duid} online. Starting update intervals.`);
+      // onlineChecker also reports a locally connected device as reachable, so
+      // polling still runs for LAN-reachable devices during a cloud outage.
+      if (await this.onlineChecker(duid)) {
+        this.log.debug(`${duid} reachable. Starting update intervals.`);
         this.startDeviceIntervals(duid);
       }
 
@@ -965,7 +1262,7 @@ class Roborock {
       try {
         await this.api.post(`user/scene/${sceneID.val}/execute`);
       } catch (error) {
-        if (!this.handleApiUnauthorized(error, "executeScene")) {
+        if (!(await this.handleApiUnauthorized(error, "executeScene"))) {
           this.catchError(error.stack, "executeScene");
         }
       }
@@ -981,6 +1278,10 @@ class Roborock {
       throw new Error("loginApi is not initialized. Call init() first.");
     }
 
+    if (this.homeId != null) {
+      return this.homeId; // resolved at startup; no cloud round trip needed
+    }
+
     try {
       const homeDetail = await this.loginApi.get("api/v1/getHomeDetail");
       if (homeDetail && homeDetail.data && homeDetail.data.data) {
@@ -1014,7 +1315,7 @@ class Roborock {
 
       return response.data;
     } catch (error) {
-      if (!this.handleApiUnauthorized(error, "getScenes")) {
+      if (!(await this.handleApiUnauthorized(error, "getScenes"))) {
         this.log.error(`Failed to get scenes: ${error.message}`);
       }
       throw error;
@@ -1096,7 +1397,28 @@ class Roborock {
     return product ? product[attribute] : null;
   }
 
+  // Whether the per-device local TCP client is currently connected.
+  isLocallyConnected(duid) {
+    try {
+      return !!(
+        this.localConnector &&
+        typeof this.localConnector.isConnected === "function" &&
+        this.localConnector.isConnected(duid)
+      );
+    } catch (error) {
+      return false;
+    }
+  }
+
   async onlineChecker(duid) {
+    // A device we hold a live local connection to is reachable regardless of
+    // the cached cloud online flag, which is stale (and may be false) while the
+    // cloud is unreachable. Trusting the live socket is what keeps local
+    // commands from being rejected during a cloud outage.
+    if (this.isLocallyConnected(duid)) {
+      return true;
+    }
+
     const homedata = this.getParsedHomeData();
     if (!homedata) {
       return false;
@@ -1135,6 +1457,10 @@ class Roborock {
   // Query them per shared device and merge into roomIDs. Room entries carry
   // their id as either `id` or `roomId` depending on the backend.
   async loadSharedDeviceRooms() {
+    if (!this.api) {
+      return; // session-less local-only start: shared devices are cloud-only
+    }
+
     for (const device of this.receivedDevices || []) {
       try {
         const response = await this.api.get(
@@ -1287,35 +1613,67 @@ class Roborock {
   }
 
   async updateHomeData(homeId) {
-    this.log.debug(`Updating HomeData with homeId: ${homeId}`);
-    if (this.api) {
+    // Cloud recovery for a session-less (local-only) start: nothing
+    // cloud-side works until a login succeeds, so retry that first.
+    if (!this.api && !(await this.reconnectCloud())) {
+      return;
+    }
+
+    if (homeId == null) {
+      homeId = this.homeId;
+    }
+
+    // Cloud recovery: a local-only start may have no home id yet. Learn it
+    // from getHomeDetail before refreshing, so cloud features resume without
+    // a Homebridge restart. While the cloud is still down this just retries
+    // on the next tick.
+    if (homeId == null) {
       try {
-        const home = await this.api.get(`user/homes/${homeId}`);
-        const homedata = home.data.result;
+        const homeDetail = await this.loginApi.get("api/v1/getHomeDetail");
+        homeId =
+          homeDetail && homeDetail.data && homeDetail.data.data
+            ? homeDetail.data.data.rrHomeId
+            : null;
+      } catch (error) {
+        this.log.debug(
+          `Home id still unavailable (cloud likely still down): ${error && error.message}`
+        );
+        return;
+      }
 
-        if (homedata) {
-          await this.setStateAsync("HomeData", {
-            val: JSON.stringify(homedata),
-            ack: true,
-          });
-          this.log.debug(`homedata successfully updated`);
+      if (homeId == null) {
+        return;
+      }
 
-          await this.getScenes();
+      this.homeId = homeId;
+      await this.setStateAsync("HomeId", { val: homeId, ack: true });
+    }
 
-          // Fresh online flags just arrived: stop polling devices that went
-          // offline and resume devices that came back (both idempotent).
-          for (const duid of this.initializedVacuumDuids) {
-            await this.manageDeviceIntervals(duid);
-          }
-        } else {
-          this.log.warn("homedata failed to download");
-        }
-      } catch (error) {
-        if (!this.handleApiUnauthorized(error, "updateHomeData")) {
-          this.log.error(
-            `Failed to update updateHomeData with error: ${error}`
-          );
+    this.log.debug(`Updating HomeData with homeId: ${homeId}`);
+    try {
+      const home = await this.api.get(`user/homes/${homeId}`);
+      const homedata = home.data.result;
+
+      if (homedata) {
+        await this.setStateAsync("HomeData", this.homeDataState(homedata));
+        this.log.debug(`homedata successfully updated`);
+        this.noteCloudReachable();
+
+        await this.getScenes();
+
+        // Fresh online flags just arrived: stop polling devices that went
+        // offline and resume devices that came back (both idempotent).
+        for (const duid of this.initializedVacuumDuids) {
+          await this.manageDeviceIntervals(duid);
         }
+      } else {
+        this.log.warn("homedata failed to download");
+      }
+    } catch (error) {
+      if (!(await this.handleApiUnauthorized(error, "updateHomeData"))) {
+        this.logCloudFailure(
+          `Failed to update updateHomeData with error: ${error}.`
+        );
       }
     }
   }
@@ -1331,7 +1689,7 @@ class Roborock {
    *   HomeData polling stops until the user re-authenticates.
    * Returns true when the error was a 401 and has been handled here.
    */
-  handleApiUnauthorized(error, context) {
+  async handleApiUnauthorized(error, context) {
     if (!error || !error.response || error.response.status !== 401) {
       return false;
     }
@@ -1361,6 +1719,17 @@ class Roborock {
     if (this.sessionInvalidated) {
       return true;
     }
+
+    // A 401 from the signed API normally means a revoked session, but a
+    // degraded cloud can produce one too. Ask the login API before throwing
+    // the session away; while it still accepts the token (or cannot be
+    // reached) the request simply retries on the next interval.
+    if (!(await this.isSessionRejected())) {
+      this.logCloudFailure(
+        `Roborock API rejected the request (401) in ${context}, but the login API still accepts the session. Keeping it and retrying later.`
+      );
+      return true;
+    }
     this.sessionInvalidated = true;
 
     this.log.warn(