homebridge-roborock-matter 3.19.8 → 3.20.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 3.20.0
+
+**Two ways the plugin could stop working and never start again. Both silent, both permanent until somebody restarted Homebridge.**
+
+Neither was a crash, which is why neither had been noticed. The plugin stayed up and stopped doing its job.
+
+### A classic robot that flapped offline was never polled again
+
+`manageDeviceIntervals` stops both polling intervals when a robot reads as offline and restarts them when it reads as online. The restart half was unreachable for a classic robot: the only caller sits **inside the `get_status` handler**, so it runs only when a status poll succeeds — and `getStatusIntervalHandle` is the one thing driving those polls. Once they were cleared, nothing was left alive to notice the robot had come back. The one other caller, the home-data supervisor, filtered on B01 and skipped every classic robot deliberately.
+
+`onlineChecker` reads the cached home-data snapshot, which lags by up to one refresh, so the trigger was ordinary rather than exotic: robot drops off wifi, comes back, its LAN socket reconnects first, the next local poll succeeds, the snapshot still says offline, both intervals die. From then on the tile froze on the last known state until the user pressed a button or restarted.
+
+Same dead end at boot, for a different reason: the intervals are only started `if (device.online)`, so a robot that was offline when Homebridge started was **never polled at all** for the life of the process.
+
+The supervisor now covers every robot. It runs on the home-data cadence, which is the same clock that decides `onlineChecker`'s answer, so a robot that comes back is picked up on the tick that notices it.
+
+### A cloud outage during startup wedged the plugin permanently
+
+`getUserData` returns a stored session **without touching the network**, so any install that has logged in once — essentially all of them — never reaches the login retry with backoff. It reaches `getHomeDetail` instead. When that failed, the plugin logged one warning and stopped.
+
+The ordering is what made it terminal: `homedataInterval` and `reconnectIntervall` are created _after_ that call, and `initUser` was never reached, so there was no MQTT client either. **Not one timer existed that would ever try again.** A Pi rebooting after a power cut, with the router still coming up, registered nothing and sat idle until a human intervened. The README's "retries with increasing backoff, up to 10 attempts" described only the login step, which this path skips.
+
+There is now a retry: 1 minute, doubling to a 10-minute ceiling, then holding there. Deliberately with no attempt cap — the failure it recovers from is "the network was not ready yet" and the device is unattended, so giving up means a person has to notice. One timer at a time, unref'd so it can never hold Homebridge open, cleared on shutdown, and reset by a success so a later outage starts from 1 minute again.
+
+9 new tests, and the supervisor's own test previously asserted the skip that caused the first bug.
+
 ## 3.19.8
 
 **A recovery line now names only a failure the log actually announced — and the test that says so had been failing on disk, uncommitted, for 3 days.**

package/README.md

@@ -37,7 +37,7 @@ This is the most feature-packed, most thoroughly engineered Roborock plugin for
 - 📍 **See where it's cleaning — live.** Apple Home shows _"Cleaning — Kitchen"_ with the room the robot is actually inside, updating as it moves from room to room. Works even for cleans started from the robot's button or the Roborock app. No other Homebridge plugin does this.
 - 🧭 **One robot, one tile — and as many robots as you own.** Sign in once and your whole fleet comes along: every vacuum on your account appears as its own clean, native accessory in Apple Home. No clutter of fake fans and helper switches, and rooms appear with the names you gave them in the Roborock app.
 - ⚡ **Fast and reliable.** Commands go directly to the robot over your own network whenever possible, with the Roborock cloud as automatic backup — and built-in diagnostics in the settings if you ever want to look under the hood.
-- 🛡️ **Verified by Homebridge.** Reviewed and endorsed by the Homebridge team. 1655 automated tests, zero known vulnerabilities, no analytics, and a startup designed to never crash your Homebridge — even when your Wi-Fi or the Roborock cloud has a bad day.
+- 🛡️ **Verified by Homebridge.** Reviewed and endorsed by the Homebridge team. 1663 automated tests, zero known vulnerabilities, no analytics, and a startup designed to never crash your Homebridge — even when your Wi-Fi or the Roborock cloud has a bad day.
 
 ## Features
 
@@ -255,7 +255,7 @@ The complete path — robot → plugin → Homebridge → matter.js store — wa
 
 ## Contributing
 
-Model reports, diagnostics exports, and pull requests are very welcome. The codebase ships with 1655 tests (protocol fixtures verified against the [python-roborock](https://github.com/Python-roborock/python-roborock) reference), strict TypeScript checking, and CI across Node 22/24 × Homebridge 1.11/2.x — `npm test` before you push and you're set.
+Model reports, diagnostics exports, and pull requests are very welcome. The codebase ships with 1663 tests (protocol fixtures verified against the [python-roborock](https://github.com/Python-roborock/python-roborock) reference), strict TypeScript checking, and CI across Node 22/24 × Homebridge 1.11/2.x — `npm test` before you push and you're set.
 
 ## Support the project
 

package/package.json

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

@@ -1968,6 +1968,13 @@ class Roborock {
           await this.initializeDeviceUpdates();
 
           this.bInited = true;
+          // A success ends the retry chain and forgets the backoff, so a
+          // later outage starts from one minute again rather than ten.
+          if (this.startServiceRetryTimer) {
+            this.clearTimeout(this.startServiceRetryTimer);
+            this.startServiceRetryTimer = null;
+          }
+          this.startServiceRetryAttempts = 0;
           this.log.info(
             `Roborock connection ready; ${this.getVacuumList().length} robot(s) available.`
           );
@@ -1989,10 +1996,19 @@ class Roborock {
       // maintenance, a rate-limited response and plain DNS failure. The stack
       // tells the user nothing and the line used to end without saying what
       // now happens.
-      this.log.warn(
-        `Could not fetch your Roborock home details: ${error?.message || error}. This is almost always a temporary Roborock cloud or network problem; no robots will load until the next successful start.`
-      );
       this.log.debug(error?.stack || String(error));
+      // A CACHED SESSION MEANS THIS PATH IS THE COMMON ONE, AND IT USED TO BE
+      // TERMINAL.
+      //
+      // `getUserData` returns a stored session without touching the network,
+      // so an install that has logged in once never reaches the login retry
+      // above. It reaches `getHomeDetail` instead — and both `homedataInterval`
+      // and `reconnectIntervall` are created AFTER that call, so a failure here
+      // left the plugin with no MQTT client and not one timer that would ever
+      // try again. A Pi that reboots after a power cut while the router is
+      // still coming up registered nothing and sat idle until a human
+      // restarted Homebridge.
+      this.scheduleStartServiceRetry(error);
     }
 
     if (callback) {
@@ -3576,7 +3592,62 @@ class Roborock {
     return `${duid}:${mapId}`;
   }
 
+  /**
+   * Try `startService` again after a failure that left nothing running.
+   *
+   * Backoff doubles from 1 minute to a 10-minute ceiling and then keeps
+   * going, deliberately without an attempt cap: the failure this recovers
+   * from is "the network was not ready yet", and the device it runs on is
+   * unattended. Giving up would mean a human has to notice. One timer at a
+   * time, unref'd so it can never hold Homebridge open, and cleared on
+   * shutdown.
+   *
+   * @param {unknown} [error]
+   */
+  scheduleStartServiceRetry(error) {
+    if (this.startServiceRetryTimer || this.bInited) {
+      return;
+    }
+    this.startServiceRetryAttempts = (this.startServiceRetryAttempts || 0) + 1;
+    const delay = Math.min(
+      60000 * Math.pow(2, this.startServiceRetryAttempts - 1),
+      600000
+    );
+    this.log.warn(
+      `Could not fetch your Roborock home details: ${
+        /** @type {any} */ (error)?.message || error
+      }. This is almost always a temporary Roborock cloud or network problem. Retrying in ${Math.round(
+        delay / 60000
+      )} minute(s); no robots will load until it succeeds.`
+    );
+    const timer = setTimeout(() => {
+      this.startServiceRetryTimer = null;
+      if (this.bInited) {
+        return;
+      }
+      this.log.info(
+        `Retrying the Roborock connection (attempt ${this.startServiceRetryAttempts + 1}).`
+      );
+      void Promise.resolve(this.startService()).catch((retryError) => {
+        this.log.debug(
+          `Roborock connection retry failed: ${
+            /** @type {any} */ (retryError)?.message || retryError
+          }`
+        );
+        this.scheduleStartServiceRetry(retryError);
+      });
+    }, delay);
+    if (typeof timer?.unref === "function") {
+      timer.unref();
+    }
+    this.startServiceRetryTimer = timer;
+  }
+
   clearTimersAndIntervals() {
+    if (this.startServiceRetryTimer) {
+      this.clearTimeout(this.startServiceRetryTimer);
+      this.startServiceRetryTimer = null;
+    }
     if (this.reconnectIntervall) {
       this.clearInterval(this.reconnectIntervall);
     }
@@ -3641,7 +3712,7 @@ class Roborock {
         const homedata = home.data.result;
 
         if (homedata) {
-          this.superviseB01DeviceIntervals();
+          this.superviseDeviceIntervals();
           await this.refreshLocalKeysFromHomeData(homedata);
           await this.setStateAsync("HomeData", {
             val: JSON.stringify(homedata),
@@ -4554,19 +4625,45 @@ class Roborock {
    * their status polling forever. Called from the periodic HomeData refresh
    * as a supervisor: restarts intervals when a B01 robot is back online.
    */
-  superviseB01DeviceIntervals() {
+  /**
+   * Re-check every robot's polling intervals, from the home-data refresh.
+   *
+   * THIS USED TO SKIP EVERY CLASSIC ROBOT, AND THAT WAS A DEAD END IT COULD
+   * NOT COME BACK FROM.
+   *
+   * `manageDeviceIntervals` stops both intervals when the robot reads as
+   * offline and restarts them when it reads as online. The restart half was
+   * unreachable for a classic robot, because the only other caller sits
+   * inside the `get_status` handler — i.e. it only runs when a status poll
+   * SUCCEEDS, and `getStatusIntervalHandle` is the one thing that drives
+   * those polls. Once the intervals were cleared, nothing was left alive to
+   * notice the robot had come back.
+   *
+   * `onlineChecker` reads the cached home-data snapshot, which lags by up to
+   * one refresh, so the trigger was ordinary: robot drops off wifi, comes
+   * back, its LAN socket reconnects first, the next local poll succeeds, the
+   * stale snapshot still says offline, both intervals die. From then on the
+   * Apple Home tile froze on the last known state until the user pressed a
+   * button or restarted Homebridge.
+   *
+   * This runs on the home-data cadence, which is exactly the clock that
+   * decides `onlineChecker`'s answer, so a robot that comes back is picked up
+   * on the same tick that notices it. The B01 status loop stays B01-only —
+   * that is a different mechanism and it is started unconditionally below.
+   */
+  superviseDeviceIntervals() {
     this.startB01StatusLoop();
 
     for (const duid of this.initializedVacuumDuids) {
-      if (
-        this.getVacuumDeviceInfo(duid, "pv") ===
-        b01Q7Adapter.B01_PROTOCOL_VERSION
-      ) {
-        void this.manageDeviceIntervals(duid).catch(() => undefined);
-      }
+      void this.manageDeviceIntervals(duid).catch(() => undefined);
     }
   }
 
+  /** @deprecated Kept so existing callers and tests keep working. */
+  superviseB01DeviceIntervals() {
+    this.superviseDeviceIntervals();
+  }
+
   /**
    * Dedicated status loop for B01/Q7 robots, independent of the fragile
    * per-device v1 interval machinery. Ticks every 15 seconds and asks