homebridge-roborock-matter 3.20.0 → 3.21.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 3.21.0
+
+**You can now change the clean mode while the robot is already cleaning. This needed a change in Homebridge itself, and that change has now shipped.**
+
+Until now a mode picked mid-run only moved the picker. The prep sequence that sends the mode to the robot runs before a start and nowhere else, so the robot carried on with the settings it began with, and the tile quietly disagreed with the floor. That was not an oversight in this plugin: Matter's RvcCleanMode cluster forbids a mode change outside idle unless the device advertises the `DirectModeChange` feature, and Homebridge had no way for a plugin to advertise it. [homebridge/homebridge#4001](https://github.com/homebridge/homebridge/pull/4001) added one, and it is merged and released in `2.4.1-beta.11`.
+
+**What happens now.** A mode change while the robot is running or paused is sent to the robot immediately, and the picker holds your choice until the robot's own status agrees with it — up to 150 seconds, after which the picker gives up and follows the robot again with a warning line naming what it asked for. If the command fails outright, every piece of selection state rolls back to what it was and the controller is told the change failed, so a rejected change cannot leave the picker showing a mode the robot never took.
+
+**On the empty-tank warning, which had to move with it.** The tank check deliberately read the robot's live water level rather than the picker, on the reasoning that a mid-run selection was never applied and so could not be trusted. That reasoning no longer holds, and left alone it would have raised a tank warning for water the robot had already acknowledged turning off. The applied-type pin is now the authority during the confirmation window.
+
+**What you need to run it.** Homebridge `2.4.1-beta.11` or newer. On `2.4.0` the feature declaration is inert — that version has no concept of plugin-advertised Matter features, so nothing changes and nothing breaks. It follows the existing `enableMatterCleanMode` setting: leave it on and live changes are advertised, turn it off and neither the declaration nor the handler exists.
+
+6 new tests.
+
+## 3.20.1
+
+**The resource half of the same review: seven things that leaked, hung on, or would have taken the bridge down given the right unlucky moment.**
+
+**Every timer this library creates is now unref'd, and cannot become an unhandled rejection.** `src/timers.ts` has stated the policy since it was written — "a pending timer must never be why Homebridge cannot shut down" — and `src/` honours it at every one of its own call sites. `roborockLib` never imported that module, so all ~20 of its timers were ref'd, including each in-flight request timeout of up to 30 seconds, none of which were cleared on shutdown. Both fixes live in the 2 wrapper methods every timer in the library already goes through, so they cover all of them at once. The rejection guard matters more than it looks: Homebridge's `uncaughtException` handler is `process.kill(SIGTERM)` and node routes unhandled rejections into it, so one rejecting poll callback takes the whole bridge down. None can reject today — but `updateDataMinimumData` has no `try` in its 114 lines and survives only because each of its callees happens to catch, which is a contract nobody had written down.
+
+**Shutdown now actually stops things.** `stopService()` cleared timers and nothing else. `client.end()` existed in exactly 1 place in the codebase, inside `reconnectClient`, and never on the shutdown path — so in the seconds between Homebridge's SIGTERM and its forced exit, robot frames kept arriving and being dispatched into disposed accessories, and a local socket closing in that window scheduled a _new_ reconnect and wrote diagnostics files into a bridge being dismantled. Both transports are closed now, and every pending request is rejected rather than left hanging.
+
+**One throwing `dispose()` no longer skips the rest of shutdown.** The SHUTDOWN handler was a straight-line sequence, so a throw anywhere in it skipped `stopService()` — the step that stops the polling and closes the transports. A shutdown that half-runs is worse than one that fails loudly.
+
+**A list that grew by 2 entries a minute, forever.** `processDockType()` runs on every status poll carrying `dock_type`, and the poll site's comment says that is safe because the function is idempotent. It is — for `commands`, `deviceStates` and `consumablesString`, which all use keyed assignment. `resetConsumables` was the one member using `.push`. Measured: 6 entries became 2016 after 1005 polls, about 86,400 a month per robot.
+
+**A transient network failure no longer deletes your saved session.** The login error path made no distinction between "Roborock rejected your password" and "DNS was not up yet", and deleted both the stored session and the cached device list for either. On a boot where the router is still coming up that destroyed the only offline snapshot the plugin has. Only an actual refusal clears it now, and an unrecognised failure is treated as transport — deleting a good session costs a re-login, keeping a dead one costs one failed request.
+
+**Two smaller ones.** A guard reading `photoGzipChunks != []` compared against a fresh array literal and was therefore always true, so it never guarded anything. And two concurrent `createClient` calls could each build a socket, with the later assignment orphaning the first — its handlers correctly declined to reconnect, so there was no storm, but the file descriptor stayed open for the life of the process. The new claim is released in a `finally`, because a leaked claim would be worse than the leak it prevents: that robot could never reconnect again.
+
+17 new tests.
+
 ## 3.20.0
 
 **Two ways the plugin could stop working and never start again. Both silent, both permanent until somebody restarted Homebridge.**

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. 1663 automated tests, zero known vulnerabilities, no analytics, and a startup designed to never crash your Homebridge — even when your Wi-Fi or the Roborock cloud has a bad day.
+- 🛡️ **Verified by Homebridge.** Reviewed and endorsed by the Homebridge team. 1686 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
 
@@ -90,6 +90,8 @@ Enable **Enable Suction-Level Cleaning Modes** (`enableFanPowerCleanModes`) and
 
 The clean mode follows the robot as well: start a vacuum+mop or mop-only clean from the Roborock app (or the robot's buttons) and Apple Home switches to the matching mode during the run — no setup needed.
 
+**Changing the mode mid-run needs Homebridge `2.4.1-beta.11` or newer.** Matter forbids a clean-mode change outside idle unless the device advertises the `DirectModeChange` feature, and a plugin could not advertise it until [homebridge/homebridge#4001](https://github.com/homebridge/homebridge/pull/4001). With a version that has it, a mode picked while the robot is running or paused is sent to the robot straight away and the picker holds your choice until the robot's status agrees. On `2.4.0` the declaration is inert: the picker still only takes effect on the next start, exactly as before.
+
 > ⚠️ **Re-pairing required:** Matter locks an accessory's mode list at commissioning. After enabling (or disabling) this option, restart Homebridge, then **remove the robot from Apple Home and pair it again** — otherwise the new modes will not appear. The same applies to any option that changes announced capabilities.
 
 > 🛑 **Turn a suction level off in Apple Home _before_ you disable this option.** Matter stores the selected clean mode on disk and restores it on every start, but it does not store the list of modes it is allowed to come from. So if a suction level (mode 3–7) is the one selected when you disable the option, the restored value is no longer in the announced list, and Matter refuses to bring the accessory up at all:
@@ -255,7 +257,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 1663 tests (protocol fixtures verified against the [python-roborock](https://github.com/Python-roborock/python-roborock) reference), strict TypeScript checking, and CI across Node 22/24 × Homebridge 1.11/2.x — `npm test` before you push and you're set.
+Model reports, diagnostics exports, and pull requests are very welcome. The codebase ships with 1686 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/dist/matter_vacuum_accessory.js

@@ -6,6 +6,7 @@ const timers_1 = require("./timers");
 const { getModelNameWithoutBrand } = require("../roborockLib/lib/deviceFeatures");
 const MATTER_CLEAN_MODE_COMMAND_TIMEOUT_MS = 2000;
 const MATTER_CLEAN_MODE_PREP_TIMEOUT_MS = 2500;
+const MATTER_CLEAN_MODE_LIVE_CONFIRMATION_TIMEOUT_MS = 150 * 1000;
 // Commands reach this class from two places now: the Matter clusters, and the
 // optional HAP action switches. The surface is threaded through the command
 // path rather than inferred, because the only way a user can tell a dropped
@@ -617,6 +618,7 @@ class RoborockMatterVacuumAccessory {
         this.serviceAreaProgress = [];
         this.selectedCleanMode = CLEAN_MODE_VACUUM;
         this.selectedCleanModeNeedsApply = false;
+        this.selectedCleanModeLiveConfirmationExpiresAt = 0;
         /**
          * Whether `selectedCleanMode` holds a choice or merely its initial value.
          *
@@ -709,6 +711,12 @@ class RoborockMatterVacuumAccessory {
             prepWindowMs: MATTER_CLEAN_MODE_PREP_TIMEOUT_MS,
         };
     }
+    getMatterCleanModeLiveCommandOptions() {
+        return {
+            ...this.getMatterCleanModePrepCommandOptions(),
+            context: "during cleaning",
+        };
+    }
     /** The robot's name exactly as the log lines and Apple Home spell it. */
     getDisplayName() {
         return this.getVacuumName();
@@ -954,14 +962,11 @@ class RoborockMatterVacuumAccessory {
      * the sort.
      *
      * WHERE THIS DELIBERATELY DIFFERS FROM getCurrentCleanMode(), because the
-     * difference looks like an oversight and is not: there, a Matter selection
-     * that has not been applied yet outranks the robot's live report, so the
-     * mode picker keeps showing what the user just asked for instead of
-     * flickering back. Here it does not. A selection made mid-run is not applied
-     * mid-run — the prep only runs before a start — so the robot carries on with
-     * the water it already had, and a robot physically mopping with an empty
-     * tank is blocked no matter what the picker shows. The picker reports
-     * intent; this reports what is happening to the floor.
+     * difference looks like an oversight and is not: there, an acknowledged
+     * Matter selection stays visible while the robot's status catches up. Here
+     * the applied-type pin below is the authority during that same window, so a
+     * stale water report cannot invent a tank warning for water the robot has
+     * already acknowledged turning off.
      *
      * The derived type goes through acceptLiveCleanType() like every other
      * consumer of it, and that gate is right here for the same reason it is
@@ -1489,25 +1494,52 @@ class RoborockMatterVacuumAccessory {
     async changeCleanMode(newMode) {
         const name = this.getVacuumName();
         this.platform.log.info(`Matter clean mode request for ${name}: ${newMode !== null && newMode !== void 0 ? newMode : "unknown"}.`);
-        if (this.isSupportedCleanMode(newMode)) {
-            this.rememberCurrentRoborockCleanModeSettings();
-            this.selectedCleanMode = newMode;
-            this.selectedCleanModeNeedsApply = true;
-            this.userSelectedCleanMode = true;
-            // Discard the level remembered from the robot: from here on the user
-            // has said what they want, and an unreadable fan power must fall back
-            // to their choice rather than to what the robot said before it. The
-            // applied-type pin goes for the same reason — it records an older
-            // intent, and this selection supersedes it.
-            this.lastResolvedFanPowerCleanMode = null;
-            this.appliedCleanTypePin = null;
-            const state = {
-                rvcCleanMode: { currentMode: newMode },
-            };
-            this.setAndScheduleOptimisticState(state, "clean mode change");
+        if (!this.isSupportedCleanMode(newMode)) {
+            this.platform.log.warn(`Ignoring unsupported Matter clean mode '${newMode}' for ${name}.`);
             return;
         }
-        this.platform.log.warn(`Ignoring unsupported Matter clean mode '${newMode}' for ${name}.`);
+        const previousSelection = {
+            selectedCleanMode: this.selectedCleanMode,
+            selectedCleanModeNeedsApply: this.selectedCleanModeNeedsApply,
+            selectedCleanModeLiveConfirmationExpiresAt: this.selectedCleanModeLiveConfirmationExpiresAt,
+            userSelectedCleanMode: this.userSelectedCleanMode,
+            lastResolvedFanPowerCleanMode: this.lastResolvedFanPowerCleanMode,
+            appliedCleanTypePin: this.appliedCleanTypePin,
+        };
+        // These are robot-reported preferences, not speculative selection
+        // bookkeeping. If the command fails they remain valid pre-command truth,
+        // so the rollback below intentionally does not restore them.
+        this.rememberCurrentRoborockCleanModeSettings();
+        this.selectedCleanMode = newMode;
+        this.selectedCleanModeNeedsApply = true;
+        this.selectedCleanModeLiveConfirmationExpiresAt = 0;
+        this.userSelectedCleanMode = true;
+        // Discard the level remembered from the robot: from here on the user has
+        // said what they want, and an unreadable fan power must fall back to their
+        // choice rather than to what the robot said before it.
+        this.lastResolvedFanPowerCleanMode = null;
+        this.appliedCleanTypePin = null;
+        const operationalState = this.getOperationalState();
+        const canApplyLive = operationalState === RVC_OPERATIONAL_STATE.RUNNING ||
+            operationalState === RVC_OPERATIONAL_STATE.PAUSED;
+        try {
+            if (canApplyLive) {
+                await this.applyCleanModeDuringRun(newMode);
+            }
+        }
+        catch (error) {
+            this.selectedCleanMode = previousSelection.selectedCleanMode;
+            this.selectedCleanModeNeedsApply =
+                previousSelection.selectedCleanModeNeedsApply;
+            this.selectedCleanModeLiveConfirmationExpiresAt =
+                previousSelection.selectedCleanModeLiveConfirmationExpiresAt;
+            this.userSelectedCleanMode = previousSelection.userSelectedCleanMode;
+            this.lastResolvedFanPowerCleanMode =
+                previousSelection.lastResolvedFanPowerCleanMode;
+            this.appliedCleanTypePin = previousSelection.appliedCleanTypePin;
+            throw error;
+        }
+        this.setAndScheduleOptimisticState({ rvcCleanMode: { currentMode: newMode } }, "clean mode change");
     }
     async pauseCleaning(surface = exports.MATTER_SURFACE) {
         const roborockState = this.getNumberStatus("state");
@@ -2097,6 +2129,25 @@ class RoborockMatterVacuumAccessory {
         }
         return ((_a = FAN_POWER_CLEAN_MODES.find((powerMode) => powerMode.mode === cleanMode)) !== null && _a !== void 0 ? _a : null);
     }
+    doesLiveCleanModeMatch(cleanMode) {
+        const expectedBaseType = this.getBaseCleanType(cleanMode);
+        const liveType = this.getLiveCleanType();
+        if (liveType !== null && !this.acceptLiveCleanType(liveType)) {
+            return false;
+        }
+        if (liveType !== null &&
+            this.getBaseCleanType(liveType) !== expectedBaseType) {
+            return false;
+        }
+        const fanPowerMode = this.getFanPowerCleanMode(cleanMode);
+        if (fanPowerMode) {
+            // Some robots omit a live clean type, but fan power independently
+            // confirms a suction variant. Base clean-type changes have no equivalent
+            // independent signal and still require the robot to report a live type.
+            return this.getNumberStatus("fan_power") === fanPowerMode.fanPower;
+        }
+        return liveType !== null;
+    }
     getCurrentCleanMode() {
         let selected = this.isSupportedCleanMode(this.selectedCleanMode)
             ? this.selectedCleanMode
@@ -2110,6 +2161,24 @@ class RoborockMatterVacuumAccessory {
         // selection wins until it has been applied, and outside an active run
         // the (sticky) robot-side setting must not shadow the user's selection.
         const inCleaningRun = this.isInCleaningRunMode(this.getOperationalState());
+        if (this.selectedCleanModeLiveConfirmationExpiresAt > 0) {
+            if (!inCleaningRun) {
+                this.selectedCleanModeLiveConfirmationExpiresAt = 0;
+            }
+            else if (this.doesLiveCleanModeMatch(this.selectedCleanMode)) {
+                this.selectedCleanModeLiveConfirmationExpiresAt = 0;
+                this.appliedCleanTypePin = null;
+                this.clearOptimisticCluster("rvcCleanMode");
+            }
+            else if (Date.now() < this.selectedCleanModeLiveConfirmationExpiresAt) {
+                return selected;
+            }
+            else {
+                this.selectedCleanModeLiveConfirmationExpiresAt = 0;
+                this.appliedCleanTypePin = null;
+                this.platform.log.warn(`Roborock acknowledged the live ${this.getCleanModeLabel(this.selectedCleanMode)} change for ${this.getVacuumName()}, but its status did not converge within ${MATTER_CLEAN_MODE_LIVE_CONFIRMATION_TIMEOUT_MS / 1000} seconds; Apple Home will now follow the robot's live report.`);
+            }
+        }
         this.trackAppliedCleanTypeRun(inCleaningRun);
         // The wind-down is not a mode change, and on a classic robot it looks
         // exactly like one.
@@ -2337,6 +2406,30 @@ class RoborockMatterVacuumAccessory {
      * vacuum-family mode keeps the robot's current suction, a mop-family mode
      * its current water level), so applying pins the clean TYPE and nothing else.
      */
+    async applyCleanModeDuringRun(cleanMode) {
+        var _a;
+        const applySettings = this.api.applyMatterCleanModeSettings;
+        if (typeof applySettings !== "function") {
+            throw new Error("Roborock clean-mode control is unavailable.");
+        }
+        const settings = this.getRoborockCleanModeSettings(cleanMode);
+        if (!settings) {
+            throw new Error(`No Roborock settings exist for ${this.getCleanModeLabel(cleanMode)}.`);
+        }
+        this.platform.log.info(`Applying ${this.getCleanModeLabel(cleanMode)} mode to ${this.getVacuumName()} during cleaning.`);
+        const result = await this.withCleanModePrepTimeout(applySettings.call(this.api, this.getDuid(), settings, this.getMatterCleanModeLiveCommandOptions()));
+        if ((_a = result === null || result === void 0 ? void 0 : result.unconfirmedSettings) === null || _a === void 0 ? void 0 : _a.length) {
+            throw new Error(`Roborock did not confirm the ${result.unconfirmedSettings.join(" and ")} during the live clean-mode change.`);
+        }
+        this.selectedCleanModeNeedsApply = false;
+        this.selectedCleanModeLiveConfirmationExpiresAt =
+            Date.now() + MATTER_CLEAN_MODE_LIVE_CONFIRMATION_TIMEOUT_MS;
+        this.appliedCleanTypePin = {
+            cleanType: this.getBaseCleanType(cleanMode),
+            runObserved: true,
+            reported: false,
+        };
+    }
     async applyCleanModeBeforeStarting() {
         const applySettings = this.api.applyMatterCleanModeSettings;
         if (typeof applySettings !== "function") {
@@ -3699,6 +3792,20 @@ class RoborockMatterVacuumAccessory {
         }
         return this.optimisticClusters;
     }
+    clearOptimisticCluster(cluster) {
+        const optimistic = this.getActiveOptimisticState();
+        if (!optimistic || !(cluster in optimistic)) {
+            return;
+        }
+        const remaining = { ...optimistic };
+        delete remaining[cluster];
+        if (Object.keys(remaining).length === 0) {
+            this.clearOptimisticState();
+            return;
+        }
+        this.optimisticClusters = remaining;
+        this.optimisticGeneration += 1;
+    }
     clearOptimisticState() {
         this.optimisticClusters = null;
         this.optimisticExpiresAt = 0;