homebridge-roborock-matter 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -1,10 +1,20 @@
 # 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.
 
-- **Restarts are roughly 5 seconds faster.** LAN discovery listens for robot broadcasts for a fixed 5-second window, and startup used to sit and wait for it with nothing else happening. It now runs alongside the home-data refresh, device setup and network probes, which all fit inside that same window. Measured on a three-robot setup: ~8 s from "Starting adapter" to "Lets go!!!!!!!" before, ~3 s after.
+- **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.

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": "3.0.0",
+  "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": {

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/roborockAPI.js

@@ -1505,52 +1505,26 @@ class Roborock {
           await this.updateHomeData(homeId);
 
           await this.createDevices();
-          await this.getNetworkInfo();
-
-          const discoveredDevices = await localDiscovery;
-
-          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)}`
-            );
-
-            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",
-                });
-              }
-            }
-
-            for (const device in this.localDevices) {
-              const duid = device;
-              const ip = this.localDevices[device];
 
-              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!`
@@ -1567,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();

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,
+};