homebridge-roborock-matter 2.9.9 → 3.0.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 3.0.1
+
+Follow-up to 3.0.0 after measuring a real restart instead of trusting the reasoning. Two things needed fixing, one of them mine.
+
+- **Startup now genuinely finishes in ~2 seconds instead of ~7.** 3.0.0 moved LAN discovery off the critical path but still waited for its full 5-second broadcast window before declaring startup finished, so the total barely moved — the claim in the 3.0.0 notes ("~8 s before, ~3 s after") was wrong, and the corrected numbers are below. Local transport is an optimisation over the cloud path, not a prerequisite for it, so it now attaches in the background after the robots are already live in Apple Home.
+- **Fixed: the first cloud request could fail on a cold start.** `get_network_info` was issued about a second after the MQTT handshake began and failed with "Cloud connection not available" — visible in real logs for a cloud-transported robot. Startup now waits for the broker session to actually come up (up to 10 s, then continues regardless) before the first requests, instead of relying on an unrelated delay to cover the gap.
+- The diagnostics export is no longer headed `homebridge-roborock-vacuum2 diagnostic report` — a leftover from the fork that made reports confusing to read.
+
+Measured on a three-robot fleet (two Q7, one S8 Pro Ultra), "Starting adapter" to "Lets go!!!!!!!": 6–7 s on 2.9.x and 3.0.0, ~2 s on 3.0.1.
+
+## 3.0.0
+
+Startup and refresh pass: Homebridge restarts are noticeably faster, and a status refresh that had never actually run now does. Nothing here requires re-pairing — existing setups keep working exactly as they are.
+
+- **LAN discovery moved off the critical path.** It listens for robot broadcasts for a fixed 5-second window, and startup used to sit and wait for it before even creating the devices. Device setup and network probes now run inside that window instead. (The wall-clock win landed in 3.0.1 — see above; this release only reordered the work.)
+- **Multi-robot startup no longer costs extra time.** Each robot's first status read and network probe used to run one after another; they now run at once, so three robots start as quickly as one. New tests pin the concurrency down so it cannot silently regress.
+- **A dead status refresh has been repaired.** The periodic `get_status` refresh for classic (S/Q-series) robots was gated on a config key this plugin never sets, which made the condition permanently false — the refresh promised by the code has never run in any released version. It now polls each robot at most once a minute (forced refreshes are unaffected), so a dropped MQTT push self-corrects within a minute instead of waiting up to three for the slow full poll.
+- **~86,000 needless timer wake-ups per robot per day removed.** With the refresh properly throttled, the 1-second scheduler tick that served it is now 15 seconds — same refresh rate, a fraction of the idle CPU on Raspberry Pi class hardware.
+- One request removed from every startup: a scene list was fetched from the Roborock cloud and thrown away.
+- **Security:** a newly published high-severity advisory in a transitive dependency (`ip-address`, reached through the MQTT client) is resolved, and the build toolchain was refreshed. `npm audit` reports zero vulnerabilities for both the shipped package and the development tree.
+- Full suite: 279 passing (7 new startup/refresh tests).
+
 ## 2.9.9
 
 - **Cleans started outside Apple Home now show the right clean mode.** Starting a vacuum+mop (or mop-only) clean from the Roborock app or the robot's buttons left Apple Home claiming plain "Vacuum". The Q7 series reports its active clean type in every status poll (the plugin sent it on start but never read it back); classic S/Q robots are derived from the mop-only suction signature and the active water-flow setting. Apple Home's mode picker now follows the robot live during a run — no re-pairing needed.

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. 263 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. 279 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
 
@@ -92,7 +92,10 @@ The clean mode follows the robot as well: start a vacuum+mop or mop-only clean f
 **The entire Roborock lineup.** If it runs in the Roborock app, this plugin can control it:
 
 - **2025 Q7 series** (`roborock.vacuum.sc05`, Q7 M5 / M5+) — the only Homebridge plugin that supports these at all, including manual-tank mopping with vacuum/mop mode switching.
-- **Classic S-, Q- and Saros-series** — S5 through S8 Pro Ultra, Q5/Q7/Q8/Q Revo families, Saros, and newer.
+- **Classic S-, Q- and Saros-series** — S4 / S5 Max through S8 Pro Ultra, Q5/Q7/Q8/Q Revo families, Saros, and newer.
+
+> **Heads-up for early models:** a few legacy robots — most notably the original S5 — only work with Xiaomi's Mi Home app and can never be added to a Roborock account, so no Roborock-account plugin can reach them. For those, [homebridge-xiaomi-roborock-vacuum](https://github.com/homebridge-xiaomi-roborock-vacuum/homebridge-xiaomi-roborock-vacuum) is the right tool.
+
 - **Future models** are adopted automatically: the plugin reads what each robot says it can do and adapts, so brand-new releases get sensible defaults from day one. If something looks off, [open a model report](https://github.com/mathiashornbek/homebridge-roborock-matter/issues) with a diagnostics export — that's exactly what it's for.
 
 ## Configuration
@@ -113,7 +116,7 @@ Everything is configurable from the Homebridge UI. The essentials:
 
 ## Battery percentage in Apple Home
 
-Apple Home renders the battery percentage from pairing time and refreshes it only on a fresh read (commissioning, hub restart) — while charging state on the very same cluster updates live. This is a controller-side limitation, not a plugin bug, and it is being investigated upstream with the Homebridge team ([homebridge#3958](https://github.com/homebridge/homebridge/issues/3958)). Current state of knowledge: as of Matter 1.4 the attribute carries the **"quieter" (Q)** reporting quality — reports ARE sent over the subscription (rate-limited to one per 10 s), a Homebridge maintainer verified that a spec-compliant matter.js controller receives and applies them, yet Apple Home in steady state does not. The likely permanent fix is on Apple's side (Apple Feedback).
+Apple Home renders the battery percentage from pairing time and refreshes it only on a fresh read (commissioning, hub restart) — while charging state on the very same cluster updates live. This is not a plugin bug, and the root cause is now **confirmed in the source of matter.js** (the Matter stack Homebridge uses): the percentage attribute carries the spec's "changes omitted" quality, and matter.js currently never emits subscription reports for such attributes — while Apple Home never re-reads them on its own. The fix is tracked upstream in [matter-js/matter.js#4163](https://github.com/matter-js/matter.js/issues/4163) (an opt-in to report them anyway, which the spec permits); once it lands, Homebridge can enable it for bridged accessories and every plugin gets working battery percentages at once. Full investigation: [homebridge#3958](https://github.com/homebridge/homebridge/issues/3958).
 
 <details>
 <summary>The full evidence chain and workarounds</summary>

package/docs/matter-battery-issue-draft.md

@@ -13,45 +13,40 @@ updates continuously; the matter.js store verifiably carries the live value;
 but the rendered battery **percentage** stays at its commissioning-time value
 until a fresh read (re-pair or Matter hub restart).
 
-## Corrected analysis (per Homebridge maintainer verification, 2026-07-15)
-
-The original analysis assumed the attribute carries the Matter reporting
-quality **C (changes omitted)** — never reported via subscription, controllers
-must poll. That was true of older spec revisions, **but as of Matter 1.4 the
-attribute is quality Q (quieter)** , and matter.js 0.17.x (shipped with every
-Homebridge 2.1.x release) models it accordingly:
-
-- **Q (quieter):** reported via subscription, rate-limited to at most one
-  report per 10 seconds, plus an immediate report on any null ↔ value
-  transition.
-
-A Homebridge maintainer (bwp91) commissioned a matter.js controller against a
-bridge exposing `PowerSource(Battery, Rechargeable)` — the same setup
-Homebridge builds — and logged the subscription: percentage changes propagate
-exactly as Q prescribes (immediate first report, deferred follow-up inside the
-10 s window, correct application after an interleaved `batChargeState` bump).
-The "stale cluster data version" theory does not hold on the controller side.
-
-## Where that leaves things
-
-- The bridge **emits** the reports; a spec-compliant controller **applies**
-  them. Apple Home in steady state does not — consistent with Apple's
-  controller still treating the attribute under the older changes-omitted
-  rules and refreshing only on a fresh read.
-- The plugin's boot-time resync nudge (null → value transition) does hit the
-  wire immediately (maintainer-confirmed) and remains useful for controllers
-  that re-prime their subscriptions; Apple still does not converge.
-- **No device-side fix exists**: bumping the data version or re-announcing
-  only produces more of the reports Apple already receives and ignores.
-
-## Next verification steps (requested upstream)
-
-1. Run Homebridge with matter.js debug logging during a battery change and
-   capture the subscription flushes carrying `batPercentRemaining` — proves
-   the reports leave THIS bridge specifically.
-2. Optionally subscribe with `chip-tool` and confirm it sees (and applies)
-   the live values.
-
-If both confirm reports going out, the permanent fix belongs with Apple
-(Apple Feedback report about the controller's handling of Q-quality
-PowerSource attributes). The upstream issue stays open in the meantime.
+## Root cause (confirmed in the matter.js source by the Homebridge maintainer, July 2026)
+
+`ServerBehaviorBacking#configureEventSuppression()` collects every
+changes-omitted property into a suppressed set; only properties that are ALSO
+marked `quieter` get the observer that re-broadcasts them
+(`broadcastChanges([name])`). `batPercentRemaining` is changes-omitted without
+`quieter`, so it hits the `continue` and **no subscription report is ever
+produced** — the store stays fresh and reads serve the live value, which is
+exactly what this investigation's store dumps showed. `batChargeState`
+carries no C quality, which is why it updates live on the same cluster.
+
+Ruled out along the way:
+
+- An intermediate theory (Matter 1.4 Q-quality, reports leaving the bridge)
+  did not survive the maintainer's source check.
+- The freeze reproduces on Homebridge v2.2.2-beta.12 in a **restart-free**
+  window, ruling out the dead-subscription bug fixed by homebridge#3973.
+- matter.js 0.17.7 does not change the behavior (`ServerBehaviorBacking.js`
+  is byte-identical to what Homebridge ships).
+- No viable device-side nudge exists from the Homebridge layer:
+  `broadcastChanges` is `protected`, and private-internals access or patching
+  would break silently on a matter.js update.
+
+## The fix
+
+The Matter spec says a server _may_ omit changes for C attributes — reporting
+them anyway is permitted. The clean solution is an opt-in on the matter.js
+side, raised upstream by the Homebridge maintainer as
+[matter-js/matter.js#4163](https://github.com/matter-js/matter.js/issues/4163)
+with this investigation linked as evidence. Once it lands, Homebridge wires it
+up for bridged accessories and every plugin gets working battery percentages
+at once — no plugin-side change needed.
+
+Until then: homebridge#3958 stays open to track; the plugin keeps its
+boot-time battery resync (useful for controllers that re-prime their
+subscriptions after a hub restart), and the known refresh paths remain
+restarting the Matter hub or re-pairing.

package/homebridge-ui/public/index.js

@@ -982,7 +982,7 @@ async function copyDiagnosticsReport() {
 function buildDiagnosticsReport(result) {
   const hasToken = Boolean(result.hasEncryptedToken || state.hasEncryptedToken);
   const lines = [
-    "homebridge-roborock-vacuum2 diagnostic report",
+    "homebridge-roborock-matter diagnostic report",
     `generatedAt: ${result.generatedAt || "unknown"}`,
     `pluginVersion: ${result.pluginVersion || "unknown"}`,
     `nodeVersion: ${result.nodeVersion || "unknown"}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-matter",
-  "version": "2.9.9",
+  "version": "3.0.1",
   "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": {
@@ -60,16 +60,16 @@
     "qrcode": "^1.5.4"
   },
   "devDependencies": {
-    "@babel/core": "7.24.8",
-    "@babel/preset-env": "7.24.8",
-    "@babel/preset-typescript": "7.24.7",
+    "@babel/core": "7.29.7",
+    "@babel/preset-env": "7.29.7",
+    "@babel/preset-typescript": "7.29.7",
     "@types/jest": "30.0.0",
     "@types/node": "20.14.10",
     "@types/qrcode": "^1.5.6",
     "@types/semver": "7.5.8",
-    "babel-jest": "30.2.0",
+    "babel-jest": "30.4.1",
     "homebridge": "1.8.3",
-    "jest": "30.2.0",
+    "jest": "30.4.2",
     "prettier": "3.3.2",
     "rimraf": "6.0.1",
     "typescript": "5.5.3"

package/roborockLib/lib/roborock_mqtt_connector.js

@@ -493,6 +493,38 @@ class roborock_mqtt_connector {
     return this.connected;
   }
 
+  /**
+   * Resolve once the MQTT session is usable, or after `timeoutMs` regardless.
+   *
+   * The broker handshake takes a few seconds, and cloud requests issued
+   * before it completes fail outright with "Cloud connection not available".
+   * Startup used to get away with this because an unrelated fixed delay
+   * happened to sit in front of the first requests; waiting on the real
+   * signal makes that timing explicit rather than accidental. Resolving on
+   * timeout (instead of rejecting) keeps a slow or offline broker from
+   * blocking startup — callers fall back to their own error handling.
+   *
+   * @param {number} [timeoutMs=10000]
+   * @returns {Promise<boolean>} whether the connection came up in time
+   */
+  async waitUntilConnected(timeoutMs = 10000) {
+    if (this.connected) {
+      return true;
+    }
+
+    const deadline = Date.now() + timeoutMs;
+    while (!this.connected && Date.now() < deadline) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, 100);
+        if (typeof timer?.unref === "function") {
+          timer.unref();
+        }
+      });
+    }
+
+    return this.connected;
+  }
+
   async ensureConnected() {
     if (client && this.connected) {
       this.adapter.log.debug("MQTT health check passed. Reconnect skipped.");

package/roborockLib/lib/vacuum.js

@@ -5,6 +5,11 @@ const RRMapParser = require("./RRMapParser");
 const fs = require("fs");
 const zlib = require("zlib");
 
+// Minimum spacing between periodic (non-forced) get_status polls per robot.
+// MQTT push remains the primary live channel; this is the safety net that
+// catches a dropped push long before the 3-minute full refresh would.
+const STATUS_POLL_MIN_INTERVAL_MS = 60 * 1000;
+
 const mappedCleanSummary = {
   0: "clean_time",
   1: "clean_area",
@@ -47,6 +52,25 @@ class vacuum {
       get_carpet_clean_mode: "deviceStatus",
       get_carpet_cleaning_mode: "deviceStatus",
     };
+
+    /** @type {Map<string, number>} last periodic status poll, per duid */
+    this.lastStatusPollAt = new Map();
+  }
+
+  /**
+   * True when this robot's periodic status poll is due again.
+   * @param {string} duid
+   */
+  shouldPollStatusNow(duid) {
+    const last = this.lastStatusPollAt.get(duid);
+    return (
+      last === undefined || Date.now() - last >= STATUS_POLL_MIN_INTERVAL_MS
+    );
+  }
+
+  /** @param {string} duid */
+  markStatusPolled(duid) {
+    this.lastStatusPollAt.set(duid, Date.now());
   }
 
   async updateDiagnosticSnapshot(duid, key, payload) {
@@ -332,16 +356,21 @@ class vacuum {
           }
         }
       } else if (parameter == "get_status") {
-        const now = new Date();
-        const seconds = now.getSeconds();
         const force = attribute == "force";
 
-        if (
-          force ||
-          this.adapter.socket ||
-          seconds % this.adapter.config.updateInterval == 0
-        ) {
-          // only send status every minute or if websocket is connected
+        // Periodic status refresh, throttled per robot.
+        //
+        // The inherited gate here read `config.updateInterval` (a key this
+        // plugin never sets) and `adapter.socket` (permanently null), so the
+        // expression was `NaN == 0` — always false. The refresh the comment
+        // promised has therefore never run: classic robots relied entirely on
+        // MQTT push plus the slow 3-minute full poll, and a silently dropped
+        // push left Apple Home stale for minutes. An explicit elapsed-time
+        // throttle restores the safety net, and being relative rather than
+        // aligned to wall-clock seconds also stops every robot in a fleet
+        // from polling in the same instant.
+        if (force || this.shouldPollStatusNow(duid)) {
+          this.markStatusPolled(duid);
 
           // const deviceStatus = await this.adapter.messageQueueHandler.sendRequest(duid, "get_status", []);
           const requestOptions = options.preferCloud

package/roborockLib/roborockAPI.js

@@ -42,6 +42,12 @@ const B01_LIVE_ROOM_CLEAR_V1_STATES = new Set([3, 8]);
 // slower cadence than the ~12s active status polls.
 const B01_LIVE_ROOM_MIN_FETCH_GAP_MS = 20000;
 
+// Scheduler granularity for the classic (v1-protocol) status refresh. The
+// refresh itself is throttled per robot inside vacuum.getParameter, so this
+// only decides how promptly that window is noticed — a 1-second tick meant
+// ~86k wake-ups per robot per day to serve at most 1440 polls.
+const CLASSIC_STATUS_TICK_MS = 15000;
+
 // Persisted states whose disk flush is debounced (see setStateAsync): they
 // change on every received robot message, are served from memory, and only
 // need the on-disk copy for restart survival.
@@ -1404,8 +1410,6 @@ class Roborock {
           const homedata = await this.api.get(`v2/user/homes/${homeId}`);
           const homedataResult = homedata.data.result;
 
-          const scene = await this.api.get(`user/scene/home/${homeId}`);
-
           await this.setStateAsync("HomeData", {
             val: JSON.stringify(homedataResult),
             ack: true,
@@ -1482,57 +1486,45 @@ class Roborock {
             this.updateInterval * 1000,
             homeId
           );
-          await this.updateHomeData(homeId);
 
-          const discoveredDevices = this.isCloudOnlyModeEnabled()
-            ? {}
-            : await this.localConnector.getLocalDevices();
-
-          await this.createDevices();
-          await this.getNetworkInfo();
-
-          if (!this.isCloudOnlyModeEnabled()) {
-            // 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)}`
-            );
+          // LAN discovery listens for UDP broadcasts for a fixed window, so
+          // awaiting it here used to stall startup for the full timeout with
+          // the CPU idle. Its results are only needed at the merge below, and
+          // the local keys it matches against are already loaded, so start it
+          // now and let the home-data refresh, device creation and network
+          // probes run inside that window instead.
+          const localDiscovery = this.isCloudOnlyModeEnabled()
+            ? Promise.resolve({})
+            : this.localConnector.getLocalDevices().catch((error) => {
+                this.log.debug(
+                  `LAN discovery failed; continuing with cloud transport: ${error?.message || error}`
+                );
+                return {};
+              });
 
-            for (const device of localKeyDevices) {
-              if (
-                !Object.prototype.hasOwnProperty.call(
-                  this.localDevices,
-                  device.duid
-                )
-              ) {
-                await this.updateTransportDiagnostics(device.duid, {
-                  localDiscoveryState: "not-discovered",
-                  lastTransportReason: "missing-local-ip",
-                });
-              }
-            }
+          await this.updateHomeData(homeId);
 
-            for (const device in this.localDevices) {
-              const duid = device;
-              const ip = this.localDevices[device];
+          await this.createDevices();
 
-              await this.updateTransportDiagnostics(duid, {
-                localIp: ip,
-                localDiscoveryState: "discovered",
-              });
-              await this.localConnector.createClient(duid, ip);
-            }
-          }
+          // Cloud requests fail outright until the MQTT session is up, and
+          // the very first ones (the per-robot network probe, then each
+          // robot's initial poll) used to be issued a second after the
+          // broker handshake started. Wait for the real signal instead of
+          // hoping an unrelated delay covers it; a broker that never comes
+          // up releases the wait and the requests fail as they would have.
+          await this.rr_mqtt_connector.waitUntilConnected();
 
+          await this.getNetworkInfo();
           await this.initializeDeviceUpdates();
+
           this.bInited = true;
           this.log.info(`Starting adapter finished. Lets go!!!!!!!`);
+
+          // LAN attach runs to completion in the background. Everything above
+          // works over the cloud, and the transport layer already falls back
+          // to it, so holding accessory registration hostage to a fixed-length
+          // broadcast listen only delayed the Apple Home tiles.
+          void this.attachLocalTransports(localDiscovery, localKeyDevices);
         } else {
           this.log.info(
             `Most likely failed to login. Deleting UserData to force new login!`
@@ -1549,6 +1541,59 @@ class Roborock {
     }
   }
 
+  /**
+   * Merge LAN-discovered robots and open their local TCP connections.
+   *
+   * Deliberately runs after startup has completed: local transport is an
+   * optimisation over the cloud path, not a prerequisite for it.
+   *
+   * @param {Promise<Record<string, string>>} localDiscovery
+   * @param {Array<{duid: string}>} localKeyDevices
+   */
+  async attachLocalTransports(localDiscovery, localKeyDevices) {
+    if (this.isCloudOnlyModeEnabled()) {
+      return;
+    }
+
+    try {
+      const discoveredDevices = await localDiscovery;
+
+      // 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)}`);
+
+      for (const device of this.normalizeArray(localKeyDevices)) {
+        if (
+          !Object.prototype.hasOwnProperty.call(this.localDevices, device.duid)
+        ) {
+          await this.updateTransportDiagnostics(device.duid, {
+            localDiscoveryState: "not-discovered",
+            lastTransportReason: "missing-local-ip",
+          });
+        }
+      }
+
+      for (const duid in this.localDevices) {
+        const ip = this.localDevices[duid];
+
+        await this.updateTransportDiagnostics(duid, {
+          localIp: ip,
+          localDiscoveryState: "discovered",
+        });
+        await this.localConnector.createClient(duid, ip);
+      }
+    } catch (error) {
+      // Local transport is best-effort; the cloud path stays available.
+      this.log.debug(
+        `Local transport attach failed; continuing on cloud transport: ${error?.message || error}`
+      );
+    }
+  }
+
   async stopService() {
     try {
       this.flushPendingPersistedStates();
@@ -1763,14 +1808,20 @@ class Roborock {
   }
 
   async getNetworkInfo() {
-    for (const device of this.devices) {
-      const duid = device.duid;
-      if (!this.hasInitializedVacuum(duid)) {
-        continue;
-      }
-
-      await this.vacuums[duid].getParameter(duid, "get_network_info");
-    }
+    // One round-trip per robot, all independent: probing them in parallel
+    // turns N sequential cloud/LAN waits into one at startup. Failures are
+    // already handled inside getParameter, but allSettled keeps a rejection
+    // from one robot from skipping the others.
+    await Promise.allSettled(
+      this.devices
+        .filter((device) => this.hasInitializedVacuum(device.duid))
+        .map((device) =>
+          this.vacuums[device.duid].getParameter(
+            device.duid,
+            "get_network_info"
+          )
+        )
+    );
   }
 
   async createDevices() {
@@ -1830,6 +1881,11 @@ class Roborock {
     this.log.debug(`initializeDeviceUpdates`);
 
     const devices = this.devices;
+    // Each robot's first poll is a chain of round-trips to that robot alone.
+    // Running the chains for different robots concurrently keeps a
+    // multi-robot startup as fast as a single-robot one; the timers below are
+    // still wired up in order, only the initial reads overlap.
+    const initialPolls = [];
 
     for (const device of devices) {
       const duid = device.duid;
@@ -1863,7 +1919,7 @@ class Roborock {
 
       this.vacuums[duid].getStatusIntervall = () => {
         // B01/Q7 status is owned by the dedicated 15s loop; the per-device
-        // 1-second tick would only burn cycles hitting the attempt throttle.
+        // tick would only burn cycles hitting the attempt throttle.
         if (
           this.getVacuumDeviceInfo(duid, "pv") ===
           b01Q7Adapter.B01_PROTOCOL_VERSION
@@ -1873,7 +1929,7 @@ class Roborock {
         this.clearInterval(this.vacuums[duid].getStatusIntervalHandle);
         this.vacuums[duid].getStatusIntervalHandle = this.setInterval(
           this.getStatus.bind(this),
-          1000,
+          CLASSIC_STATUS_TICK_MS,
           duid,
           this.vacuums[duid],
           robotModel
@@ -1886,8 +1942,12 @@ class Roborock {
         this.vacuums[duid].getStatusIntervall(); // actually start getStatusIntervall()
       }
 
-      await this.updateDataMinimumData(duid, this.vacuums[duid], robotModel);
+      initialPolls.push(
+        this.updateDataMinimumData(duid, this.vacuums[duid], robotModel)
+      );
     }
+
+    await Promise.allSettled(initialPolls);
   }
 
   async executeScene(sceneID) {
@@ -1921,17 +1981,6 @@ class Roborock {
     }
   }
 
-  /**
-   * Get scenes from the Roborock API
-   * @returns {Promise<Object>} The scenes data
-   */
-
-  /**
-   * Get scenes for a specific device by duid
-   * @param {string} duid - The device unique identifier
-   * @returns {Array} Array of scenes for the specified device
-   */
-
   getProductAttribute(duid, attribute) {
     const device = this.getVacuumDeviceData(duid);
     const deviceValue = this.getDeviceAttribute(device, attribute);

package/roborockLib/roborock_mqtt_connector.js

@@ -0,0 +1,609 @@
+"use strict";
+
+const mqtt = require("mqtt");
+const crypto = require("crypto");
+const Parser = require("binary-parser").Parser;
+const zlib = require("zlib");
+const roborockCrypto = require("./roborockCrypto");
+
+const PHOTO_MAGIC = "ROBOROCK";
+const PHOTO_HEADER_MIN_LENGTH = 9;
+const PROTOCOL_301_HEADER_LENGTH = 24;
+
+const protocol301Parser = new Parser()
+  .endianess("little")
+  .string("endpoint", {
+    length: 15,
+    stripNull: true,
+  })
+  .uint8("unknown1")
+  .uint16("id")
+  .buffer("unknown2", {
+    length: 6,
+  });
+
+const photoParser = new Parser()
+  .endianess("little")
+  .string("roborock", {
+    length: 8,
+    stripNull: true,
+  })
+  .uint8("id");
+
+let mqttUser;
+let mqttPassword;
+let client;
+let endpoint;
+let rriot;
+
+let photoGzipChunks = [];
+let photoChunkID = 0;
+
+function payloadStartsWith(payload, value) {
+  return (
+    Buffer.isBuffer(payload) &&
+    payload.length >= value.length &&
+    payload.subarray(0, value.length).toString("utf8") === value
+  );
+}
+
+function parsePhotoPayload(payload) {
+  if (
+    !payloadStartsWith(payload, PHOTO_MAGIC) ||
+    payload.length < PHOTO_HEADER_MIN_LENGTH
+  ) {
+    return null;
+  }
+
+  return photoParser.parse(payload);
+}
+
+function parseProtocol301Header(payload) {
+  if (
+    !Buffer.isBuffer(payload) ||
+    payload.length < PROTOCOL_301_HEADER_LENGTH
+  ) {
+    return null;
+  }
+
+  return protocol301Parser.parse(
+    payload.subarray(0, PROTOCOL_301_HEADER_LENGTH)
+  );
+}
+
+class roborock_mqtt_connector {
+  constructor(adapter) {
+    this.adapter = adapter;
+
+    this.connected = false;
+
+    // NOTE: this class previously generated its own RSA-2048 keypair here,
+    // but nothing ever read it — the protocol keypair lives in message.js
+    // (lazily created for the rare photo path). Removed: one full RSA
+    // keygen less at every startup.
+  }
+
+  async initUser(userdata) {
+    rriot = userdata.rriot;
+
+    endpoint = roborockCrypto
+      .md5bin(rriot.k)
+      .subarray(8, 14)
+      .toString("base64"); // Could be a random but rather static string. The app generates it on first run.
+    mqttUser = roborockCrypto.md5hex(rriot.u + ":" + rriot.k).substring(2, 10);
+    mqttPassword = roborockCrypto.md5hex(rriot.s + ":" + rriot.k).substring(16);
+    client = mqtt.connect(rriot.r.m, {
+      clientId: mqttUser,
+      username: mqttUser,
+      password: mqttPassword,
+      keepalive: 30,
+    });
+  }
+
+  async initMQTT_Subscribe() {
+    const timeout = setTimeout(async () => {
+      this.adapter.restart();
+    }, 30000);
+
+    await client.on("connect", (result) => {
+      if (typeof result != "undefined") {
+        client.subscribe(`rr/m/o/${rriot.u}/${mqttUser}/#`, (err, granted) => {
+          if (err) {
+            this.logConnectionIssue(
+              `Failed to subscribe to the Roborock MQTT server: ${err} (granted: ${JSON.stringify(granted)}).`
+            );
+          }
+        });
+        clearTimeout(timeout);
+
+        this.connected = true;
+        if (this._connectionIssueActive) {
+          this._connectionIssueActive = false;
+          this._connectionIssueLog?.clear();
+          this.adapter.log.info(
+            `Roborock MQTT connection recovered after the reported outage.`
+          );
+        }
+      }
+      this.adapter.log.debug(
+        `MQTT connection connected ${JSON.stringify(result)}.`
+      );
+    });
+
+    // Connection-state events are account-level transport telemetry, not
+    // per-robot command failures: log them as clear, throttled warnings
+    // instead of routing them through catchError (which used to produce the
+    // misleading `Failed to execute client.on("error") on robot undefined`
+    // spam twice per reconnect attempt during network outages).
+    await client.on("error", (error) => {
+      this.connected = false;
+      this.logConnectionIssue(
+        `Roborock MQTT connection error: ${error?.message || error}. The client keeps reconnecting automatically.`
+      );
+    });
+
+    await client.on("close", () => {
+      if (this.connected) {
+        this.adapter.log.info(`MQTT connection closed; reconnecting.`);
+      }
+      this.connected = false;
+    });
+
+    await client.on("reconnect", () => {
+      client.subscribe(`rr/m/o/${rriot.u}/${mqttUser}/#`, (err, granted) => {
+        if (err) {
+          this.logConnectionIssue(
+            `Failed to subscribe to the Roborock MQTT server after reconnect: ${err} (granted: ${JSON.stringify(granted)}).`
+          );
+        }
+      });
+      clearTimeout(timeout);
+      this.adapter.log.debug(`MQTT connection reconnect attempt.`);
+    });
+
+    await client.on("offline", () => {
+      this.connected = false;
+      this.logConnectionIssue(
+        `Roborock MQTT connection is offline. The client keeps reconnecting automatically.`
+      );
+    });
+  }
+
+  /**
+   * Warn about a connection problem at most once per 5 minutes per message,
+   * and remember that an outage is in progress so the next successful
+   * connect logs a single recovery line instead of silence.
+   * @param {string} message
+   */
+  logConnectionIssue(message) {
+    if (!this._connectionIssueLog) {
+      this._connectionIssueLog = new Map();
+    }
+    this._connectionIssueActive = true;
+    const now = Date.now();
+    const lastAt = this._connectionIssueLog.get(message) || 0;
+    if (now - lastAt >= 5 * 60 * 1000) {
+      this._connectionIssueLog.set(message, now);
+      this.adapter.log.warn(message);
+    } else {
+      this.adapter.log.debug(message);
+    }
+  }
+
+  getKnownDeviceDuids() {
+    const knownDuids = new Set();
+
+    if (this.adapter.localKeys instanceof Map) {
+      for (const duid of this.adapter.localKeys.keys()) {
+        knownDuids.add(duid);
+      }
+    }
+
+    if (this.adapter.devices && Array.isArray(this.adapter.devices)) {
+      for (const device of this.adapter.devices) {
+        if (device && device.duid) {
+          knownDuids.add(device.duid);
+        }
+      }
+    }
+
+    return knownDuids;
+  }
+
+  resolveDuidFromTopic(topic) {
+    const topicSegments = topic
+      .split("/")
+      .filter((segment) => segment && segment.length > 0);
+    if (topicSegments.length === 0) {
+      return null;
+    }
+
+    const knownDuids = this.getKnownDeviceDuids();
+    const topicTail = topicSegments[topicSegments.length - 1];
+
+    if (knownDuids.has(topicTail)) {
+      return topicTail;
+    }
+
+    for (let index = topicSegments.length - 2; index >= 0; index--) {
+      if (knownDuids.has(topicSegments[index])) {
+        return topicSegments[index];
+      }
+    }
+
+    if (knownDuids.size === 0) {
+      return topicTail;
+    }
+
+    return null;
+  }
+
+  async initMQTT_Message() {
+    this.adapter.log.info(`MQTT initialized`);
+
+    client.on("message", (topic, message) => {
+      try {
+        const duid = this.resolveDuidFromTopic(topic);
+        if (!duid) {
+          this.adapter.log.debug(
+            `Skipping MQTT message with unmatched topic '${topic}'.`
+          );
+          return;
+        }
+
+        const data = this.adapter.message._decodeMsg(message, duid);
+        if (!data) {
+          return;
+        }
+        // this.adapter.log.debug(`MESSAGE RECEIVED for duid ${duid} with key: ${this.adapter.localKeys.get(duid)} data: ${JSON.stringify(data)} raw: ${JSON.stringify(mqttMessageParser.parse(message))} message: ${message}`);
+        // this.adapter.log.debug(`MESSAGE RECEIVED for duid ${duid} with key: ${this.adapter.localKeys.get(duid)} data: ${JSON.stringify(data.toString("hex"))} message: ${message}`);
+        // this.adapter.log.debug(`MESSAGE RECEIVED for duid ${duid} with key: ${this.adapter.localKeys.get(duid)} data: ${JSON.stringify(data)}`);
+
+        // this.adapter.log.debug("Protocol: " + data.protocol);
+        if (data.protocol == 102) {
+          const parsedPayload = JSON.parse(data.payload);
+          let dps;
+          if (typeof parsedPayload.dps["102"] != "undefined") {
+            dps = JSON.parse(parsedPayload.dps["102"]);
+          } else if (typeof parsedPayload.dps["10001"] != "undefined") {
+            if (typeof parsedPayload.dps["10001"] == "string") {
+              dps = JSON.parse(parsedPayload.dps["10001"]);
+            } else {
+              dps = parsedPayload.dps["10001"];
+            }
+          } else {
+            dps = parsedPayload.dps;
+          }
+
+          if (resolveB01PendingResponse(this.adapter, duid, dps)) {
+            return;
+          }
+
+          if (dps.id !== undefined) {
+            // 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,
+                payload: dps.result,
+              });
+            }
+          } else {
+            this.adapter.log.debug(
+              `Cloud message with protocol 102 received. Result: ${data.payload}`
+            );
+
+            if (this.adapter.deviceNotify !== undefined) {
+              this.adapter.deviceNotify("CloudMessage", {
+                duid,
+                payload: JSON.parse(data.payload),
+              });
+            }
+          }
+
+          // special check for secure request like get_map_v1 etc. Don't process if result is OK. Instead wait for the actual response for protocol 301
+          if (dps.result != "ok") {
+            if (this.adapter.pendingRequests.has(dps.id)) {
+              const { resolve, timeout } = this.adapter.pendingRequests.get(
+                dps.id
+              );
+              this.adapter.clearTimeout(timeout);
+              this.adapter.pendingRequests.delete(dps.id);
+              resolve(dps.result);
+            }
+          }
+          // protocol 300 seems to be for get_photo 0 only. get_photo 0 is for large images. 1 is for small images.
+        } else if (data.protocol == 300) {
+          const photoData = parsePhotoPayload(data.payload);
+          if (photoData) {
+            if (this.adapter.pendingRequests.has(photoData.id)) {
+              this.adapter.log.debug(`First photo gzip chunk detected!`);
+
+              photoGzipChunks.push(data.payload.slice(56));
+              photoChunkID = photoData.id;
+            }
+          } else {
+            this.adapter.log.debug(
+              `Skipping protocol 300 MQTT message for ${duid} because the payload is not a complete Roborock photo header.`
+            );
+          }
+        } else if (data.protocol == 301) {
+          // B01/Q7 map upload responses arrive on protocol 301 as an opaque
+          // base64 blob. Resolve the per-device pending map request first;
+          // classic v1 photo/map chunk handling continues below otherwise.
+          const pendingMap = this.adapter.pendingB01MapRequests?.get(duid);
+          if (pendingMap) {
+            this.adapter.clearTimeout(pendingMap.timeout);
+            this.adapter.pendingB01MapRequests.delete(duid);
+            pendingMap.resolve(data.payload);
+            return;
+          }
+
+          if (data.seq == 2 && photoGzipChunks != [] && photoChunkID != 0) {
+            this.adapter.log.debug(`Second photo gzip chunk detected!`);
+            photoGzipChunks.push(data.payload);
+
+            if (this.adapter.pendingRequests.has(photoChunkID)) {
+              const { resolve, timeout } =
+                this.adapter.pendingRequests.get(photoChunkID);
+              this.adapter.clearTimeout(timeout);
+              this.adapter.pendingRequests.delete(photoChunkID);
+
+              const finalPhotoGzip = Buffer.concat(photoGzipChunks);
+
+              photoGzipChunks = [];
+              photoChunkID = 0;
+
+              resolve(finalPhotoGzip);
+            }
+          } else {
+            const photoData = parsePhotoPayload(data.payload);
+            if (photoData) {
+              this.adapter.log.debug(
+                `Cloud message with protocol 301 and photo id ${photoData.id} received.`
+              );
+
+              if (this.adapter.pendingRequests.has(photoData.id)) {
+                const { resolve, timeout } = this.adapter.pendingRequests.get(
+                  photoData.id
+                );
+                this.adapter.clearTimeout(timeout);
+                this.adapter.pendingRequests.delete(photoData.id);
+                this.adapter.log.debug(
+                  `Cloud message with protocol 301 and photo id ${photoData.id} received.`
+                );
+                resolve(data.payload.slice(56));
+              }
+            } else {
+              const data2 = parseProtocol301Header(data.payload);
+              if (!data2) {
+                this.adapter.log.debug(
+                  `Skipping protocol 301 MQTT message for ${duid} because the payload is shorter than ${PROTOCOL_301_HEADER_LENGTH} bytes.`
+                );
+                return;
+              }
+
+              if (!endpoint.startsWith(data2.endpoint)) {
+                return;
+              }
+
+              const iv = Buffer.alloc(16, 0);
+              const decipher = crypto.createDecipheriv(
+                "aes-128-cbc",
+                this.adapter.nonce,
+                iv
+              );
+              let decrypted = Buffer.concat([
+                decipher.update(data.payload.subarray(24)),
+                decipher.final(),
+              ]);
+              decrypted = zlib.gunzipSync(decrypted);
+              // this.adapter.log.debug("raw 301: " + decrypted);
+
+              if (this.adapter.pendingRequests.has(data2.id)) {
+                const { resolve, timeout } = this.adapter.pendingRequests.get(
+                  data2.id
+                );
+                this.adapter.clearTimeout(timeout);
+                this.adapter.pendingRequests.delete(data2.id);
+                // this.adapter.log.debug("protocol 301 OK check: " + JSON.stringify(decrypted));
+                this.adapter.log.debug(
+                  `Cloud message with protocol 301 and id ${data2.id} received.`
+                );
+                resolve(decrypted);
+              }
+            }
+          }
+        } else if (data.protocol == 500) {
+          // 500 is for general information
+          const dataString = data.payload.toString("utf8");
+          let parsedData;
+
+          try {
+            parsedData = JSON.parse(dataString);
+          } catch (error) {
+            // If parsing fails, the data might be corrupted or in an unexpected format
+            this.adapter.log.warn(
+              `Unable to parse message for ${duid}. Error: ${error.message}. Data: ${dataString}`
+            );
+            return;
+          }
+
+          // Check if the device is online
+          if (parsedData.online == false) {
+            this.adapter.log.info(
+              `Couldn't process message. The device ${duid} is offline.`
+            );
+          } else if (parsedData.online == true) {
+            // this.adapter.log.info(`Device ${duid} is online.`);
+          } else if (
+            // Check for firmware update information
+            parsedData.mqttOtaData
+          ) {
+            const otaStatus = parsedData.mqttOtaData.mqttOtaStatus?.status;
+            const otaProgress =
+              parsedData.mqttOtaData.mqttOtaProgress?.progress;
+
+            if (otaStatus) {
+              this.adapter.log.info(
+                `Device ${duid} firmware update status: ${otaStatus}`
+              );
+            }
+
+            if (otaProgress !== undefined) {
+              this.adapter.log.info(
+                `Device ${duid} firmware update progress: ${otaProgress}%`
+              );
+            }
+          } else {
+            // Received an unrecognized message
+            this.adapter.log.warn(
+              `Received an unrecognized message for ${duid}. Data: ${dataString}`
+            );
+          }
+        } else {
+          this.adapter.log.debug(
+            `Received message with unknown protocol ${data.protocol} data: ${JSON.stringify(data)}.`
+          );
+        }
+      } catch (error) {
+        this.adapter.log.error(
+          `client.on message failed for topic '${topic}': ${error.stack || error}`
+        );
+      }
+    });
+  }
+
+  getEndpoint() {
+    return endpoint;
+  }
+
+  sendMessage(duid, roborockMessage) {
+    client.publish(`rr/m/i/${rriot.u}/${mqttUser}/${duid}`, roborockMessage, {
+      qos: 1,
+    });
+  }
+
+  isConnected() {
+    return this.connected;
+  }
+
+  /**
+   * Resolve once the MQTT session is usable, or after `timeoutMs` regardless.
+   *
+   * The broker handshake takes a few seconds, and cloud requests issued
+   * before it completes fail outright with "Cloud connection not available".
+   * Startup used to get away with this because an unrelated fixed delay
+   * happened to sit in front of the first requests; waiting on the real
+   * signal makes that timing explicit rather than accidental. Resolving on
+   * timeout (instead of rejecting) keeps a slow or offline broker from
+   * blocking startup — callers fall back to their own error handling.
+   *
+   * @param {number} [timeoutMs=10000]
+   * @returns {Promise<boolean>} whether the connection came up in time
+   */
+  async waitUntilConnected(timeoutMs = 10000) {
+    if (this.connected) {
+      return true;
+    }
+
+    const deadline = Date.now() + timeoutMs;
+    while (!this.connected && Date.now() < deadline) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, 100);
+        if (typeof timer?.unref === "function") {
+          timer.unref();
+        }
+      });
+    }
+
+    return this.connected;
+  }
+
+  async ensureConnected() {
+    if (client && this.connected) {
+      this.adapter.log.debug("MQTT health check passed. Reconnect skipped.");
+      return false;
+    }
+
+    await this.reconnectClient(true);
+    return true;
+  }
+
+  async reconnectClient(force = false) {
+    if (client) {
+      try {
+        if (!force && this.connected) {
+          this.adapter.log.debug(
+            "MQTT reconnect skipped because client is already connected."
+          );
+          return false;
+        }
+
+        this.adapter.log.info("Reconnecting mqtt client!");
+        await client.end();
+        client.reconnect();
+        return true;
+      } catch (error) {
+        this.adapter.catchError(
+          `Failed to reconnect with error: ${error}`,
+          `reconnectClient`
+        );
+      }
+    }
+
+    return false;
+  }
+}
+
+/**
+ * Correlate a Q7/B01 RPC response (dps 10001 payload) to its pending request
+ * by msgId. Returns true when the dps object was a B01 message and has been
+ * fully handled; false when the caller should continue v1 processing.
+ * Robot-initiated B01 pushes (no matching request) trigger a status refresh
+ * instead of guessing at undocumented event payload formats.
+ */
+function resolveB01PendingResponse(adapter, duid, dps) {
+  if (!dps || dps.msgId === undefined || dps.id !== undefined) {
+    return false;
+  }
+
+  const b01Key = String(dps.msgId);
+  const pendingB01 = adapter.pendingRequests.get(b01Key);
+
+  if (pendingB01) {
+    adapter.clearTimeout(pendingB01.timeout);
+    adapter.pendingRequests.delete(b01Key);
+    if (dps.code !== undefined && dps.code !== 0) {
+      pendingB01.reject(
+        new Error(
+          `B01 command ${dps.method || "(unknown method)"} failed with code ${dps.code} for ${duid}.`
+        )
+      );
+    } else {
+      pendingB01.resolve(dps.data !== undefined ? dps.data : null);
+    }
+  } else {
+    adapter.log.debug(
+      `Unsolicited B01 message for ${duid} (${dps.method || "no method"}); scheduling a status refresh.`
+    );
+    if (typeof adapter.getStatus === "function") {
+      void adapter.getStatus(duid, { force: true }).catch(() => undefined);
+    }
+  }
+
+  return true;
+}
+
+module.exports = {
+  resolveB01PendingResponse,
+  roborock_mqtt_connector,
+  parseProtocol301Header,
+  parsePhotoPayload,
+  payloadStartsWith,
+};