homebridge-roborock-matter 3.35.0 → 3.36.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 3.36.0
+
+**The LAN connection now asks the robot which protocol it speaks, the way python-roborock always has, and a cloud session that has gone quiet is restarted.**
+
+### "Connected but answered nothing" (#24, #28)
+
+[@Marrand](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/24) and [@CooperCGN](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/28) both have an S8 (`a51`) that accepts the LAN connection and then answers nothing, while python-roborock — the library Home Assistant uses — gets answers from the same robots. Comparing the 2 side by side, this plugin differed in 4 places, and every one of them can produce exactly that symptom:
+
+- **No hello.** python-roborock opens every local connection with a hello, first in `1.0` and then in `L01`, and encrypts by whichever the robot answers. This plugin sent none for a `1.0` robot, and took the LAN protocol from the account's `pv`, which python-roborock says outright is a different thing. A robot whose firmware has moved to `L01` on the LAN ignores every `1.0` frame.
+- **The wrong L01 handshake.** Where it did try `L01`, it sent a protocol-1 frame. Protocol 1 is the robot's answer, not the question, so nothing answered it.
+- **Datapoint 4.** A local request went out on datapoint 4, the protocol number. python-roborock sends datapoint 101 on both transports.
+- **Protocol 4 only.** A local reply was accepted only on protocol 4; one on 5 or 102 was dropped without a word.
+
+All 4 now follow python-roborock. Against a fake robot built from python-roborock's own codec in 5 firmware variants, 3.35.0 got an answer from 1 and 3.36.0 from all 5.
+
+- The hello result is logged once: `answered the local hello in 1.0`, or that the robot speaks `L01` on the LAN, or that it answered no hello. That line is what I need from #24 and #28.
+- A robot that answers no hello keeps 3.35.0's behaviour exactly. Its first request after a connect waits up to 10 seconds for the hellos; after that, not again. A robot listed as `L01` always waits, because no local frame can be built without the hello's nonces.
+
+I ran it as 3.36.0-beta.1 on my own server first. My S8 Pro Ultra answered the hello in 1.0 in 4-18 ms on 4 restarts, and its local requests kept being answered for the 10 minutes I watched. Nobody here has a robot that needs `L01`, so that part is tested against python-roborock's codec, not against hardware.
+
+### A cloud session that says it is up and delivers nothing
+
+python-roborock restarts its MQTT session after 3 cloud timeouts in a row, at most once every 30 minutes, because "the MQTT connection appears to be alive but no messages are being received". This plugin only reconnected when the link reported itself down. CooperCGN's log counts 574 cloud messages by 08:54 and 576 by 12:11, while his robot started, paused and docked in between, and [@pponce](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/27) measured a recreated session answering within 369 ms. Same rule now, with one addition from review: a timeout only counts when nothing at all arrived from that robot while the request waited, so a map request whose acknowledgement arrives and whose map does not is not mistaken for a dead session.
+
+A cloud reply on protocol 4 or 5 that carries datapoint 102 is now read as a reply, as python-roborock reads it.
+
+### Found in review
+
+- A hello still in flight when the socket closed carried on into the dead socket, and a reconnect made in that window could inherit the old socket's hello and never get one of its own. Each hello now belongs to its socket, and a request that waited on a hello re-checks the socket before it is sent.
+- The session restart now never runs while Homebridge is stopping.
+- A socket that closed during its hello while the cloud was also down got the request written into it anyway, and counted it as a mute socket. It is now refused at once.
+
+### Tests
+
+2,153 tests, 22 more than 3.35.0. Measured against the 3.35.0 sources, file by file: 12 of 13 fail for the hello and the reply rules, 3 of 5 for the session restart, 4 of 4 for the socket each hello belongs to. The 2 that pass there guard against a restart 3.35.0 could not make.
+
 ## 3.35.0
 
 **3.34.0 broke the half of the play button it was meant to leave alone, and an empty water tank could hide a running clean in Apple Home. Both are fixed, with 8 more found by reading this plugin against matter.js 0.17.9 and python-roborock 7.12.0 instead of against its own comments.**

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. 2131 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. 2153 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
 
@@ -264,7 +264,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 2131 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 2153 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.35.0",
+  "version": "3.36.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/lib/localConnector.js

@@ -4,6 +4,7 @@ const crypto = require("crypto");
 const Parser = require("binary-parser").Parser;
 const net = require("net");
 const dgram = require("dgram");
+const CRC32 = require("crc-32");
 const { describeDevice } = require("./describeDevice");
 const { noteLateReply } = require("./lateReplies");
 const {
@@ -100,6 +101,44 @@ const shortMessageParser = new Parser()
   .uint32("timestamp")
   .uint16("protocol");
 
+/**
+ * The local hello, as python-roborock does it (devices/transport/
+ * local_channel.py). Protocol numbers from `RoborockMessageProtocol`.
+ */
+const HELLO_REQUEST = 0;
+const HELLO_RESPONSE = 1;
+const PING_RESPONSE = 3;
+/** python-roborock's `_TIMEOUT` for each hello attempt. */
+const HELLO_TIMEOUT_MS = 5000;
+/** The local protocols a hello can negotiate, in python-roborock's order. */
+const NEGOTIABLE_LOCAL_VERSIONS = ["1.0", "L01"];
+/** Local reply frames: GENERAL_REQUEST, GENERAL_RESPONSE, RPC_RESPONSE. */
+const LOCAL_REPLY_PROTOCOLS = new Set([4, 5, 102]);
+
+/**
+ * A hello request frame, byte for byte as python-roborock builds one:
+ * version, seq 1, random = our connect nonce, timestamp, protocol 0, no
+ * payload (so no length field), CRC32 over all of that. 21 bytes, behind the
+ * usual 4-byte length prefix.
+ *
+ * @param {string} version "1.0" or "L01"
+ * @param {number} connectNonce
+ * @param {number} timestamp seconds
+ * @returns {Buffer}
+ */
+function buildHelloFrame(version, connectNonce, timestamp) {
+  const body = Buffer.alloc(21);
+  body.write(version, 0, "latin1");
+  body.writeUInt32BE(1, 3);
+  body.writeUInt32BE(connectNonce >>> 0, 7);
+  body.writeUInt32BE(timestamp >>> 0, 11);
+  body.writeUInt16BE(HELLO_REQUEST, 15);
+  body.writeUInt32BE(CRC32.buf(body.subarray(0, 17)) >>> 0, 17);
+  const prefix = Buffer.alloc(4);
+  prefix.writeUInt32BE(body.length, 0);
+  return Buffer.concat([prefix, body]);
+}
+
 class localConnector {
   constructor(adapter) {
     this.adapter = adapter;
@@ -112,7 +151,31 @@ class localConnector {
      * @type {Set<string>}
      */
     this.pendingClientConnects = new Set();
-    this.l01HandshakeWaiters = new Map();
+    /**
+     * The hello in flight per robot: which version was asked, and how to
+     * settle it. See negotiateLocalProtocol().
+     * @type {Map<string, {version: string, timeout: any, settle: (ackNonce: number | null) => void}>}
+     */
+    this.helloWaiters = new Map();
+    /**
+     * The hello in flight per robot, and the socket it belongs to — a
+     * reconnect must not inherit the previous socket's hello.
+     * @type {Map<string, {client: any, promise: Promise<string | null>}>}
+     */
+    this.negotiations = new Map();
+    /**
+     * The local protocol the robot answered a hello in, for the CURRENT
+     * connection. Cleared when the socket goes; message.js reads it.
+     * @type {Map<string, string>}
+     */
+    this.negotiatedVersions = new Map();
+    /**
+     * The last version that worked, kept across reconnects so the next hello
+     * asks it first. @type {Map<string, string>}
+     */
+    this.preferredVersions = new Map();
+    /** @type {Map<string, string>} the last negotiation outcome logged */
+    this.reportedNegotiations = new Map();
     this.reconnectTimers = new Map();
     this.connectPromises = new Map();
     // Consecutive failed local connects per duid, used to back the retry delay
@@ -337,18 +400,7 @@ class localConnector {
       delete this.localClients[duid];
     }
 
-    const waiter = this.l01HandshakeWaiters.get(duid);
-    if (waiter) {
-      this.adapter.clearTimeout(waiter.timeout);
-      this.l01HandshakeWaiters.delete(duid);
-      waiter.reject(
-        new Error(
-          `TCP client reset during L01 handshake for ${describeDevice(this.adapter, duid)}`
-        )
-      );
-    }
-
-    this.adapter.localL01Nonces.delete(duid);
+    this.forgetNegotiation(duid);
     client.destroy();
     await this.adapter.updateTransportDiagnostics(duid, {
       tcpConnectionState: "disconnected",
@@ -453,11 +505,6 @@ class localConnector {
         .connect(58867, ip, async () => {
           this.adapter.log.debug(`tcp client for ${duid} connected`);
           await this.markLocalConnected(duid);
-          this.ensureL01Handshake(duid).catch((error) => {
-            this.adapter.log.debug(
-              `L01 handshake on connect failed for ${duid}: ${error.message}`
-            );
-          });
           finish(resolve);
         })
         .on("error", (error) => {
@@ -505,17 +552,7 @@ class localConnector {
         lastTransport: "cloud",
         lastTransportReason: "tcp-disconnected",
       });
-      const waiter = this.l01HandshakeWaiters.get(duid);
-      if (waiter) {
-        this.adapter.clearTimeout(waiter.timeout);
-        this.l01HandshakeWaiters.delete(duid);
-        waiter.reject(
-          new Error(
-            `TCP client closed during L01 handshake for ${describeDevice(this.adapter, duid)}`
-          )
-        );
-      }
-      this.adapter.localL01Nonces.delete(duid);
+      this.forgetNegotiation(duid);
       this.scheduleReconnect(duid, ip, this.nextReconnectDelay(duid));
       client.connected = false;
     });
@@ -532,6 +569,18 @@ class localConnector {
 
     this.localClients[duid] = client;
 
+    if (!connectFailed) {
+      // Started only now, with the socket current and its `data` listener
+      // attached — the answer has to land somewhere. Every local request
+      // awaits it (awaitLocalNegotiation), so nothing goes out on the socket
+      // before the robot has said which protocol it speaks.
+      this.negotiateLocalProtocol(duid).catch((error) => {
+        this.adapter.log.debug(
+          `Local hello on connect failed for ${duid}: ${error?.message || error}`
+        );
+      });
+    }
+
     if (connectFailed) {
       // The close/error listeners above are attached only now, after the
       // connect promise settled. On a FAILED connect both events already fired
@@ -658,35 +707,42 @@ class localConnector {
    * @param {Buffer} currentBuffer
    */
   processLocalSegment(duid, segmentLength, currentBuffer) {
-    // length of 17 does not contain any useful data.
-    // It seems to be protocol handshake metadata.
-    if (segmentLength == 17) {
+    // A hello or ping answer: a bare header (17 bytes), or a header with a
+    // CRC (21). It carries no payload, so it is settled here and never
+    // decoded. Until 3.36.0 only an L01 hello answer was recognised, and only
+    // at exactly 17 bytes.
+    if (segmentLength === 17 || segmentLength === 21) {
       try {
         const shortMessage = shortMessageParser.parse(currentBuffer);
-        if (shortMessage.version == "L01" && shortMessage.protocol == 1) {
-          const currentNonces = this.adapter.localL01Nonces.get(duid) || {};
-          this.adapter.localL01Nonces.set(duid, {
-            connectNonce: currentNonces.connectNonce,
-            ackNonce: shortMessage.random,
-          });
-
-          const waiter = this.l01HandshakeWaiters.get(duid);
-          if (waiter) {
-            this.adapter.clearTimeout(waiter.timeout);
-            this.l01HandshakeWaiters.delete(duid);
-            waiter.resolve(true);
-          }
+        if (shortMessage.protocol === HELLO_RESPONSE) {
+          this.settleHello(duid, shortMessage.version, shortMessage.random);
+          return;
+        }
+        if (shortMessage.protocol === PING_RESPONSE) {
+          return;
         }
       } catch (error) {
         this.adapter.log.debug(
           `Failed parsing short local message for ${duid}: ${error.message}`
         );
       }
-      return;
+      if (segmentLength === 17) {
+        return;
+      }
     }
 
     const data = this.adapter.message._decodeMsg(currentBuffer, duid);
-    if (!data || data.protocol != 4) {
+    if (!data) {
+      return;
+    }
+    // python-roborock matches a reply by the `102` datapoint on ANY protocol.
+    // This plugin accepted protocol 4 only, so a robot that answers on 5
+    // (GENERAL_RESPONSE) or 102 had every reply dropped here in silence — on
+    // the wire, exactly a socket that "connected but answered nothing".
+    if (!LOCAL_REPLY_PROTOCOLS.has(Number(data.protocol))) {
+      this.adapter.log.debug(
+        `Ignored a local frame with protocol ${data.protocol} from ${describeDevice(this.adapter, duid)}.`
+      );
       return;
     }
 
@@ -712,8 +768,8 @@ class localConnector {
       const refusal = describeReplyRefusal(parsed_102);
       this.adapter.log.debug(
         typeof result === "undefined"
-          ? `Local message with protocol 4 and id ${id} received. No result; reply was ${JSON.stringify(parsed_102)}`
-          : `Local message with protocol 4 and id ${id} received. Result: ${JSON.stringify(result)}`
+          ? `Local message with protocol ${data.protocol} and id ${id} received. No result; reply was ${JSON.stringify(parsed_102)}`
+          : `Local message with protocol ${data.protocol} and id ${id} received. Result: ${JSON.stringify(result)}`
       );
       const { resolve, reject, timeout, method } =
         this.adapter.pendingRequests.get(id);
@@ -817,70 +873,247 @@ class localConnector {
     }
   }
 
-  async ensureL01Handshake(duid) {
-    const version = await this.adapter.getRobotVersion(duid);
-    if (version != "L01") {
-      return;
-    }
-
+  /**
+   * Ask the robot which local protocol it speaks, the way python-roborock
+   * does on every connect: a hello in "1.0", and if that goes unanswered for
+   * 5 seconds, a hello in "L01". The answer decides how local frames are
+   * encrypted (message.js reads getNegotiatedVersion) and, for L01, carries
+   * the nonce the session key is built from.
+   *
+   * WHY 3.36.0 ADDED IT. This plugin sent no hello for a "1.0" robot at all
+   * and trusted home data's `pv` for the local protocol, which python-roborock
+   * says outright is "different from vacuum protocol versions". A robot whose
+   * firmware has moved to L01 on the LAN, or that wants a hello before it
+   * answers, accepts the TCP connection and then ignores every frame — the
+   * "connected but answered nothing" two S8 owners reported (#24, #28) while
+   * python-roborock answered them. Its own L01 handshake was a protocol-1
+   * frame (the robot's ANSWER type) with a running sequence number, which
+   * nothing answers.
+   *
+   * If neither hello is answered, nothing else changes: local requests go out
+   * exactly as before, so a robot that never needed a hello keeps working.
+   *
+   * @param {string} duid
+   * @returns {Promise<string | null>} the version, or null when not negotiated
+   */
+  negotiateLocalProtocol(duid) {
     const client = this.localClients[duid];
-    if (!client || !client.connected) {
-      return;
+    const inFlight = this.negotiations.get(duid);
+    if (inFlight && inFlight.client === client) {
+      return inFlight.promise;
     }
+    const entry = {
+      client,
+      promise: Promise.resolve(/** @type {string | null} */ (null)),
+    };
+    entry.promise = this.runNegotiation(duid).finally(() => {
+      if (this.negotiations.get(duid) === entry) {
+        this.negotiations.delete(duid);
+      }
+    });
+    this.negotiations.set(duid, entry);
+    return entry.promise;
+  }
 
-    const existingNonces = this.adapter.localL01Nonces.get(duid);
+  /**
+   * What a local request waits for before it is built: an in-flight hello.
+   * Resolves at once when none is running.
+   *
+   * @param {string} duid
+   * @returns {Promise<void>}
+   */
+  async awaitLocalNegotiation(duid) {
+    // A robot that answered no hello last time is not made to wait 10 s on
+    // every reconnect for the same answer; its requests go out as they always
+    // did while the hello is retried alongside them.
+    // Not for a robot listed as L01: without the hello's nonces no local
+    // frame can be built at all, so it always waits (found in final
+    // verification).
     if (
-      existingNonces &&
-      typeof existingNonces.connectNonce == "number" &&
-      typeof existingNonces.ackNonce == "number"
+      this.reportedNegotiations.get(duid) === "none" &&
+      (await this.adapter.getRobotVersion(duid)) !== "L01"
     ) {
       return;
     }
+    const inFlight = this.negotiations.get(duid);
+    if (inFlight && inFlight.client === this.localClients[duid]) {
+      await inFlight.promise.catch(() => null);
+    }
+  }
 
-    const timestamp = Math.floor(Date.now() / 1000);
-    const handshakeMessage = await this.adapter.message.buildRoborockMessage(
-      duid,
-      1,
-      timestamp,
-      Buffer.alloc(0)
-    );
-    if (!handshakeMessage) {
-      throw new Error(
-        `Failed to build protocol 1 handshake message for ${describeDevice(this.adapter, duid)}`
-      );
+  /**
+   * @param {string} duid
+   * @returns {string | undefined} the local protocol this connection agreed
+   */
+  getNegotiatedVersion(duid) {
+    return this.negotiatedVersions.get(duid);
+  }
+
+  /**
+   * @param {string} duid
+   * @returns {Promise<string | null>}
+   */
+  async runNegotiation(duid) {
+    const robotVersion = await this.adapter.getRobotVersion(duid);
+    if (!NEGOTIABLE_LOCAL_VERSIONS.includes(robotVersion)) {
+      return null;
+    }
+    const client = this.localClients[duid];
+    if (!client || !client.connected) {
+      return null;
     }
 
-    const connectNonce = handshakeMessage.readUInt32BE(7);
-    this.adapter.localL01Nonces.set(duid, {
-      connectNonce,
-      ackNonce: undefined,
-    });
+    const preferred = this.preferredVersions.get(duid) || robotVersion;
+    const order =
+      preferred === "L01" ? ["L01", "1.0"] : [...NEGOTIABLE_LOCAL_VERSIONS];
+    const startedAt = Date.now();
+
+    const socketIsCurrent = () =>
+      this.localClients[duid] === client && Boolean(client.connected);
 
-    if (this.l01HandshakeWaiters.has(duid)) {
-      const waiter = this.l01HandshakeWaiters.get(duid);
-      this.adapter.clearTimeout(waiter.timeout);
-      this.l01HandshakeWaiters.delete(duid);
+    for (const version of order) {
+      if (!socketIsCurrent()) {
+        return null;
+      }
+      const answer = await this.sendHello(duid, client, version);
+      // A socket that closed mid-hello answers nothing, and that says
+      // nothing about the robot: no next attempt, no "answered no hello".
+      if (!socketIsCurrent()) {
+        return null;
+      }
+      if (answer) {
+        this.negotiatedVersions.set(duid, version);
+        this.preferredVersions.set(duid, version);
+        if (version === "L01") {
+          this.adapter.localL01Nonces.set(duid, answer);
+        }
+        this.reportNegotiation(duid, version, robotVersion, startedAt);
+        return version;
+      }
     }
 
-    const handshakePromise = new Promise((resolve, reject) => {
-      const timeout = this.adapter.setTimeout(() => {
-        this.l01HandshakeWaiters.delete(duid);
-        reject(
-          new Error(
-            `Timed out waiting for L01 handshake response for ${describeDevice(this.adapter, duid)}`
-          )
-        );
-      }, 3000);
+    this.negotiatedVersions.delete(duid);
+    this.reportNegotiation(duid, null, robotVersion, startedAt);
+    return null;
+  }
 
-      this.l01HandshakeWaiters.set(duid, { resolve, reject, timeout });
+  /**
+   * One hello, settled by the robot's answer or after HELLO_TIMEOUT_MS.
+   *
+   * @param {string} duid
+   * @param {any} client
+   * @param {string} version
+   * @returns {Promise<{connectNonce: number, ackNonce: number} | null>}
+   */
+  sendHello(duid, client, version) {
+    return new Promise((resolve) => {
+      // python-roborock: get_next_int(10000, 32767).
+      const connectNonce = crypto.randomInt(10000, 32768);
+      let settled = false;
+      const settle = (/** @type {number | null} */ ackNonce) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        this.adapter.clearTimeout(timeout);
+        if (this.helloWaiters.get(duid)?.settle === settle) {
+          this.helloWaiters.delete(duid);
+        }
+        resolve(ackNonce === null ? null : { connectNonce, ackNonce });
+      };
+      const timeout = this.adapter.setTimeout(
+        () => settle(null),
+        HELLO_TIMEOUT_MS
+      );
+      this.helloWaiters.set(duid, { version, timeout, settle });
+      try {
+        client.write(
+          buildHelloFrame(version, connectNonce, Math.floor(Date.now() / 1000))
+        );
+      } catch (error) {
+        this.adapter.log.debug(
+          `Could not send the local hello to ${duid}: ${error?.message || error}`
+        );
+        settle(null);
+      }
     });
+  }
+
+  /**
+   * A hello answer arrived. It settles the waiting hello only when it is in
+   * the version that was asked; an answer in another version is said and
+   * ignored, and the next attempt follows.
+   *
+   * @param {string} duid
+   * @param {string} version
+   * @param {number} random the robot's nonce
+   * @returns {void}
+   */
+  settleHello(duid, version, random) {
+    const waiter = this.helloWaiters.get(duid);
+    if (!waiter) {
+      return;
+    }
+    if (waiter.version !== version) {
+      this.adapter.log.debug(
+        `${describeDevice(this.adapter, duid)} answered a ${waiter.version} hello in ${version}; trying the next protocol.`
+      );
+      return;
+    }
+    waiter.settle(random);
+  }
 
-    const lengthBuffer = Buffer.alloc(4);
-    lengthBuffer.writeUInt32BE(handshakeMessage.length, 0);
-    const fullMessage = Buffer.concat([lengthBuffer, handshakeMessage]);
-    client.write(fullMessage);
+  /**
+   * Say what the hello found, once per change. A robot answering in its
+   * home-data protocol is the normal case: said at info once, then debug.
+   * Anything else is the evidence #24 and #28 needed, so it is said at info
+   * whenever it changes.
+   *
+   * @param {string} duid
+   * @param {string | null} version
+   * @param {string} robotVersion
+   * @param {number} startedAt
+   * @returns {void}
+   */
+  reportNegotiation(duid, version, robotVersion, startedAt) {
+    const outcome = version ?? "none";
+    const first = !this.reportedNegotiations.has(duid);
+    const changed = this.reportedNegotiations.get(duid) !== outcome;
+    this.reportedNegotiations.set(duid, outcome);
+    const elapsed = Date.now() - startedAt;
+    if (version === robotVersion) {
+      // Once at info per start, so a support log shows the hello worked;
+      // every reconnect after that at debug.
+      (first ? this.adapter.log.info : this.adapter.log.debug).call(
+        this.adapter.log,
+        `${describeDevice(this.adapter, duid)} answered the local hello in ${version} (${elapsed} ms).`
+      );
+      return;
+    }
+    if (!changed) {
+      return;
+    }
+    this.adapter.log.info(
+      version
+        ? `${describeDevice(this.adapter, duid)} speaks the ${version} protocol on the LAN, not the ${robotVersion} its Roborock account lists; local requests now use ${version}.`
+        : `${describeDevice(this.adapter, duid)} accepted the local connection but answered no hello, in 1.0 or L01 (5 seconds each). Local requests go out as before; if they go unanswered too, the plugin moves this robot to the Roborock cloud by itself.`
+    );
+  }
 
-    await handshakePromise;
+  /**
+   * The socket is gone: settle any hello waiting on it and drop what this
+   * connection agreed. The preferred version is kept for the next hello.
+   *
+   * @param {string} duid
+   * @returns {void}
+   */
+  forgetNegotiation(duid) {
+    const waiter = this.helloWaiters.get(duid);
+    if (waiter) {
+      waiter.settle(null);
+    }
+    this.negotiatedVersions.delete(duid);
+    this.adapter.localL01Nonces?.delete?.(duid);
   }
 
   /**
@@ -1131,11 +1364,7 @@ class localConnector {
     for (const duid of Object.keys(this.localClients)) {
       const client = this.localClients[duid];
       delete this.localClients[duid];
-      const waiter = this.l01HandshakeWaiters.get(duid);
-      if (waiter) {
-        this.adapter.clearTimeout(waiter.timeout);
-        this.l01HandshakeWaiters.delete(duid);
-      }
+      this.forgetNegotiation(duid);
       try {
         client?.removeAllListeners?.();
         client?.destroy?.();
@@ -1147,11 +1376,12 @@ class localConnector {
         );
       }
     }
-    this.l01HandshakeWaiters.clear();
+    this.helloWaiters.clear();
     this.pendingClientConnects.clear();
   }
 }
 
 module.exports = {
   localConnector,
+  buildHelloFrame,
 };

package/roborockLib/lib/message.js

@@ -120,9 +120,13 @@ class message {
         },
       });
     } else {
+      // Datapoint 101 on BOTH transports, as python-roborock sends it
+      // (`RequestMessage._as_payload`). Until 3.36.0 a local request went on
+      // datapoint 4 — the protocol number, not the RPC datapoint — which some
+      // robots accept and nothing guarantees.
       payload = JSON.stringify({
         dps: {
-          [protocol]: JSON.stringify(inner),
+          101: JSON.stringify(inner),
         },
         t: timestamp,
       });
@@ -132,7 +136,14 @@ class message {
   }
 
   async buildRoborockMessage(duid, protocol, timestamp, payload) {
-    const version = await this.adapter.getRobotVersion(duid);
+    // A LOCAL frame (protocol 4) is encrypted in the protocol the robot
+    // answered the local hello in, which need not be the one its account
+    // lists (localConnector.negotiateLocalProtocol). Cloud frames keep `pv`.
+    const negotiated =
+      protocol == 4
+        ? this.adapter.localConnector?.getNegotiatedVersion?.(duid)
+        : undefined;
+    const version = negotiated || (await this.adapter.getRobotVersion(duid));
 
     let encrypted;
 

package/roborockLib/lib/messageQueueHandler.js

@@ -175,7 +175,8 @@ function describeCloudSilence(adapter, duid, receiptsAtSend) {
  * @property {(duid: string) => boolean} isConnected
  * @property {(duid: string, message: Buffer) => void} sendMessage
  * @property {(duid: string) => void} clearChunkBuffer
- * @property {(duid: string) => Promise<void>} [ensureL01Handshake]
+ * @property {(duid: string) => Promise<void>} [awaitLocalNegotiation]
+ * @property {(duid: string) => string | undefined} [getNegotiatedVersion]
  */
 
 /**
@@ -230,6 +231,9 @@ function unansweredRequestError(message, transportWasUp) {
  * @property {(duid: string) => Promise<boolean>} [ensureLocalConnection]
  * @property {(duid: string, method?: string) => Promise<void>} [noteLocalRequestTimedOut]
  * @property {(duid: string, method: string) => void} [noteRequestAnswered]
+ * @property {() => void} [noteCloudReply] Any reply over the cloud.
+ * @property {() => boolean} [noteCloudSilence] A cloud request timed out
+ *   while MQTT reported itself connected.
  * @property {(duid: string, method: string, error: unknown) => void} [noteRequestUnanswered]
  * @property {import("./lateReplies").LateReplyTracker} [lateReplies] Remembers
  *   timed-out request ids so a reply that turns up after its timeout can be
@@ -429,16 +433,31 @@ class messageQueueHandler {
       );
     }
 
-    if (!useCloudConnection && version == "L01") {
+    if (!useCloudConnection) {
+      // Never put a request on a socket whose hello is still in the air: the
+      // answer decides how the frame is encrypted. Bounded by the hello's own
+      // timeouts (2 x 5 s), and instant once negotiated.
       try {
-        if (this.adapter.localConnector.ensureL01Handshake) {
-          await this.adapter.localConnector.ensureL01Handshake(duid);
-        }
+        await this.adapter.localConnector.awaitLocalNegotiation?.(duid);
       } catch (error) {
         const errorMessage =
           error instanceof Error ? error.message : String(error);
         this.adapter.log.debug(
-          `L01 handshake before request failed for ${duid}: ${errorMessage}`
+          `Local hello before request failed for ${duid}: ${errorMessage}`
+        );
+      }
+      // The socket may have closed during the wait. The state read before it
+      // is stale, so read it again — for the cloud fallback here AND for the
+      // "no local connection" refusal further down, which reads the same
+      // variable (found in final verification).
+      localConnectionState = this.adapter.localConnector.isConnected(duid);
+      if (
+        !localConnectionState &&
+        this.adapter.rr_mqtt_connector.isConnected()
+      ) {
+        useCloudConnection = true;
+        this.adapter.log.debug(
+          `The local socket for ${duid} closed during its hello. Falling back to cloud connection for method ${method}.`
         );
       }
     }
@@ -581,6 +600,25 @@ class messageQueueHandler {
               );
               this.adapter.noteRequestUnanswered?.(duid, method, error);
               this.adapter.lateReplies?.noteTimedOut(messageID, duid, method);
+              // A link that says it is up and delivers NOTHING from this
+              // robot while the request waits is the stale session
+              // python-roborock restarts. A frame that did arrive — a
+              // get_map_v1 acknowledgement whose map never follows, a status
+              // push — means the session delivers, so it is not counted
+              // (found in review). B01 is left out: a Q10 command is
+              // fire-and-forget by design.
+              const deliveredMeanwhile =
+                receiptsAtSend !== null &&
+                typeof this.adapter.getCloudMessageReceiptCount ===
+                  "function" &&
+                this.adapter.getCloudMessageReceiptCount(duid) > receiptsAtSend;
+              if (
+                transportWasUp &&
+                !deliveredMeanwhile &&
+                !b01Q7Adapter.isB01Protocol(version)
+              ) {
+                this.adapter.noteCloudSilence?.();
+              }
               reject(error);
             } else {
               // A socket that keeps reporting itself connected while every
@@ -622,6 +660,9 @@ class messageQueueHandler {
             // seven methods in #22/#24 that it was built for.
             resolve: (value) => {
               this.adapter.noteRequestAnswered?.(duid, method);
+              if (useCloudConnection) {
+                this.adapter.noteCloudReply?.();
+              }
               resolve(value);
             },
             // A refusal is an answer too. The reply handlers (cloud 102,
@@ -633,6 +674,9 @@ class messageQueueHandler {
             // the method was given up on although the robot had just replied.
             reject: (error) => {
               this.adapter.noteRequestAnswered?.(duid, method);
+              if (useCloudConnection) {
+                this.adapter.noteCloudReply?.();
+              }
               reject(error);
             },
             abandon: reject,

package/roborockLib/lib/roborock_mqtt_connector.js

@@ -66,6 +66,36 @@ const photoBuffers = new Map();
 // already paste.
 const droppedFrames = new Map();
 
+/**
+ * Whether a decoded cloud frame is an RPC reply. Protocol 102 always was;
+ * python-roborock also takes a frame on 4 or 5 whose payload carries the
+ * `102` datapoint, and until 3.36.0 such a reply was dropped here unread.
+ *
+ * @param {{protocol?: unknown, payload?: unknown}} data
+ * @returns {boolean}
+ */
+function isRpcReplyFrame(data) {
+  const protocol = Number(data?.protocol);
+  if (protocol === 102) {
+    return true;
+  }
+  if (protocol !== 4 && protocol !== 5) {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(String(data.payload));
+    return (
+      parsed !== null &&
+      typeof parsed === "object" &&
+      parsed.dps !== null &&
+      typeof parsed.dps === "object" &&
+      Object.prototype.hasOwnProperty.call(parsed.dps, "102")
+    );
+  } catch {
+    return false;
+  }
+}
+
 function noteDroppedFrame(duid, reason) {
   let entry = droppedFrames.get(duid);
   if (!entry) {
@@ -398,7 +428,7 @@ class roborock_mqtt_connector {
         // 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) {
+        if (isRpcReplyFrame(data)) {
           const parsedPayload = JSON.parse(data.payload);
           let dps;
           if (typeof parsedPayload.dps["102"] != "undefined") {
@@ -895,6 +925,7 @@ function resolveB01PendingResponse(adapter, duid, dps) {
 
 module.exports = {
   describeDroppedFrames,
+  isRpcReplyFrame,
   resolveB01PendingResponse,
   roborock_mqtt_connector,
   parseProtocol301Header,

package/roborockLib/roborockAPI.js

@@ -439,6 +439,9 @@ const SIMPLE_VACUUM_COMMANDS = new Set([
 ]);
 
 const TRANSIENT_ERROR_LOG_THROTTLE_MS = 6 * 60 * 60 * 1000;
+// python-roborock mqtt/health_manager.py: TIMEOUT_THRESHOLD, RESTART_COOLDOWN.
+const CLOUD_SILENCES_BEFORE_SESSION_RESTART = 3;
+const CLOUD_SESSION_RESTART_COOLDOWN_MS = 30 * 60 * 1000;
 const MATTER_CLEAN_MODE_COMMAND_TIMEOUT_MS = 2000;
 // Reserved out of the caller's prep window so the sequence ends by itself and
 // reports what it could not confirm, rather than being cut off mid-command with
@@ -537,6 +540,9 @@ class Roborock {
     // Replies that came after their request had timed out. See
     // lib/lateReplies.js; the give-up line reads it.
     this.lateReplies = new LateReplyTracker();
+    // Consecutive unanswered cloud requests while MQTT says it is connected.
+    // See noteCloudSilence().
+    this.cloudSessionHealth = { consecutiveSilences: 0, lastRestartAt: 0 };
     this.baseURL = options.baseURL || "usiot.roborock.com";
 
     this.userData = options.userData || null;
@@ -3400,6 +3406,61 @@ class Roborock {
     return vacuum.getParameter(duid, method);
   }
 
+  /**
+   * Any reply came back over the cloud: the session delivers.
+   *
+   * @returns {void}
+   */
+  noteCloudReply() {
+    this.cloudSessionHealth.consecutiveSilences = 0;
+  }
+
+  /**
+   * A cloud request timed out while MQTT reported itself connected.
+   *
+   * python-roborock's HealthManager exists for exactly this — "the MQTT
+   * connection appears to be alive but no messages are being received" — and
+   * restarts the session after 3 timeouts in a row, at most once every 30
+   * minutes. This plugin only ever reconnected when mqtt.js said the link was
+   * DOWN, so a session that stayed up and went quiet stayed quiet: CooperCGN's
+   * log in #28 counts 574 cloud messages by 08:54 and 576 by 12:11, while his
+   * robot started, paused and docked in between, and @pponce measured a
+   * recreated session answering again within 369 ms (#27). Same rule here.
+   *
+   * @returns {boolean} whether a restart was started
+   */
+  noteCloudSilence() {
+    if (this.stopped) {
+      return false;
+    }
+    const health = this.cloudSessionHealth;
+    health.consecutiveSilences += 1;
+    if (health.consecutiveSilences < CLOUD_SILENCES_BEFORE_SESSION_RESTART) {
+      return false;
+    }
+    const now = Date.now();
+    if (
+      health.lastRestartAt !== 0 &&
+      now - health.lastRestartAt < CLOUD_SESSION_RESTART_COOLDOWN_MS
+    ) {
+      return false;
+    }
+    const silences = health.consecutiveSilences;
+    health.lastRestartAt = now;
+    health.consecutiveSilences = 0;
+    this.log.info(
+      `${silences} cloud requests in a row went unanswered while the MQTT connection reported itself up, so the plugin is starting a fresh MQTT session — the same rule python-roborock applies (3 in a row, at most once every 30 minutes). A request in flight at this moment may fail once.`
+    );
+    void Promise.resolve()
+      .then(() => this.rr_mqtt_connector?.reconnectClient?.(true))
+      .catch((error) => {
+        this.log.debug(
+          `Restarting the MQTT session failed: ${error?.message || error}`
+        );
+      });
+    return true;
+  }
+
   /**
    * The message layer saw a reply. Called for EVERY request, including
    * `get_status` and every command — the register ignores any pair no