homebridge-roborock-vacuum 2.2.7 → 2.2.9

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 2.2.9
+
+- **Fix (Matter)**: Rooms are now published on a map (#60). They used to be published without one, and Apple Home showed no rooms. Room selection works as before
+- **Fix (status)**: Vacuum status (state, battery, charging, error, fan and water settings) now comes from the vacuum itself. The plugin polls `get_status` on every refresh and keeps the real-time status broadcasts, instead of relying on the cloud's home-data snapshot, which can lag behind the device. This fixes Matter vacuums that kept an old state, such as "Return to dock" staying available while the vacuum was already docked (#60). HAP accessories read the same status
+- **Fix (Matter)**: The charging state is reported correctly. "Not charging" was sent as Matter's "fully charged" value, and models that do not report `charge_status` now derive it from the charging and charged states
+- **Fix (Matter)**: The start button no longer fails with `Cannot resume in current state` (#60). A Resume command sent while the vacuum is stopped or docked now starts a clean, and honors the room selection
+- **Change (Matter)**: A vacuum that is returning to or docking at its station now reports "Seeking charger" instead of "Running"
+- **New**: Clear device errors from the settings page. Some errors stay on the vacuum until they are marked as resolved in the Roborock app, even after the cause is fixed, such as the dock's "clean water tank empty" after a refill. When a vacuum reports an error, the settings page now shows it in the device list with a **Clear error** button that resolves it, like **Resolved** in the Roborock app. Homebridge must be running
+- **Fix (login)**: Signing in no longer fails with code 3006 ("user agreement version is not up-to-date"). The login sent a fixed user agreement version, but the current version differs per Roborock server and country; it is now fetched before each login, with the old value as the fallback
+- **Fix (connectivity)**: A cloud connection that stays connected but no longer delivers any messages is restarted. This only happens when the connection reports itself as connected, the Roborock cloud is reachable, and several requests in a row got no answer with no other message in between; restarts back off from 30 minutes up to 6 hours while they do not help. A network or Roborock outage does not trigger restarts
+
+## 2.2.8
+
+- **New**: Project website in English, Traditional Chinese and Japanese: [tasict.github.io/homebridge-roborock-vacuum](https://tasict.github.io/homebridge-roborock-vacuum/). It is now the plugin's homepage in the Homebridge UI
+- **New**: You can now support the plugin by buying me a boba (paid by card, no PayPal account needed) or with PayPal: from the bottom of the plugin settings, the donate link in the Homebridge UI, the README or GitHub's Sponsor button
+- **Change (packaging)**: The npm package no longer contains a development test script, a leftover client ID file or the protocol sniffing helper; it now holds only what the plugin needs to run
+- **Docs**: README rewritten around the current feature set — supported models (with corrected names such as Qrevo Curv), requirements matching the supported Homebridge and Node.js versions, the sign-in flow, and a reference of every config option. The header image is now the plugin's own icon
+- **Change (config UI)**: The settings page describes what it is for, and has a small support footer below the settings
+
 ## 2.2.7
 
 - **Fix (connectivity)**: The plugin no longer fails to start when the Roborock cloud is unreachable. Startup used to abandon everything after the home-data request timed out (`AxiosError: timeout of 20000ms exceeded`, `ECONNRESET`), so no accessories were registered and every command was refused with "Adapter not inited" — even though the vacuum was reachable on the LAN the whole time. The home data (device list and local keys) is now cached on disk, and when the cloud fetch fails the plugin starts in **local-only mode** from that cache: it still runs LAN discovery, connects to each vacuum over the local protocol, publishes the accessories, and accepts start/stop/dock commands. Cloud-only features (scenes, push updates, fresh online flags) resume by themselves once the cloud answers again, without a Homebridge restart. One successful online start is needed to seed the cache; with no cache the plugin stays idle as before, now with a message that says why
@@ -55,7 +74,7 @@ Maintenance release — no functional changes to device control. Reworks the fou
 
 ## 2.2.0
 
-Connectivity and device-support release, porting recent fixes from the python-roborock and ioBroker.roborock upstream projects (see `UpstreamReview-2026-07.md`).
+Connectivity and device-support release, porting recent fixes from the python-roborock and ioBroker.roborock upstream projects.
 
 - **New Feature**: Docks introduced since 2025 (Qrevo Curv, Saros 10, Qrevo S5V, Saros 20, and other new dock type codes 10–40) now get their dust-collection, mop-wash, and drying features — including the dock mop-wash switch. Unknown future dock types default to full-featured instead of featureless
 - **New Feature**: Room names now resolve for vacuums shared from another Roborock account (fetched via the device-share rooms API), so Matter room cleaning and the current-room publisher work on shared devices

package/README.md

@@ -1,82 +1,89 @@
-# homebridge-roborock-vacuum
+<p align="center">
+  <img src="https://raw.githubusercontent.com/tasict/homebridge-roborock-vacuum/master/branding/icon.png" width="96" height="96" alt="">
+</p>
 
-![Roborock Vacuum in Home App](https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/40/21/71/40217177-c879-f670-bd01-c93acfabc31e/AppIcon-0-0-1x_U007emarketing-0-8-0-85-220.png/460x0w.webp)
+# Homebridge Roborock Vacuum
 
-A Homebridge plugin to integrate your Roborock vacuum cleaner with Apple HomeKit, allowing you to control it via the Home app and Siri.
+**Website: [tasict.github.io/homebridge-roborock-vacuum](https://tasict.github.io/homebridge-roborock-vacuum/)** (English, 繁體中文, 日本語)
 
-## Introduction
+[![npm version](https://img.shields.io/npm/v/homebridge-roborock-vacuum?color=%23cb3837&label=npm)](https://www.npmjs.com/package/homebridge-roborock-vacuum)
+[![npm downloads](https://img.shields.io/npm/dm/homebridge-roborock-vacuum)](https://www.npmjs.com/package/homebridge-roborock-vacuum)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-`homebridge-roborock-vacuum` brings your Roborock vacuum cleaner into Apple HomeKit. Using your Roborock app account credentials, this plugin automatically detects your vacuum, enabling you to control it directly from the Home app on your iPhone, iPad, or Mac, or with Siri voice commands.
+`homebridge-roborock-vacuum` is a [Homebridge](https://homebridge.io) plugin that brings Roborock robot vacuums into Apple Home, over HomeKit or Matter. Sign in with your Roborock app account and the plugin finds your vacuums by itself; you can then start and stop them from the Home app, with Siri or from automations. Commands go to the vacuum over your home network, so it stays controllable when the Roborock cloud is down.
+
+Free and open source. If it saves you a few chores, you can [buy me a boba](https://tasict.bobaboba.me) (by card, no PayPal account needed) or [tip with PayPal](https://paypal.me/tasict).
 
 This plugin is inspired by and adapted from the [ioBroker.roborock](https://github.com/copystring/ioBroker.roborock) project by copystring.
 
 ## Features
 
-- **Automatic Device Detection**: No need to manually find or enter your vacuum's device ID.
-- **Start/Stop Cleaning**: Begin or end cleaning sessions.
-- **Device Exclusion**: Skip selected Roborock device IDs so shared or remote vacuums stay out of HomeKit.
-
-## The supported robots are:
-
-Roborock S4
-Roborock S4 Max
-Roborock S5 Max
-Roborock S6
-Roborock S6 Pure
-Roborock S6 MaxV
-Roborock S7
-Roborock S7 MaxV (Ultra)
-Roborock Q5+
-Roborock Q7
-Roborock Q7 Max
-Roborock S7 Pro Ultra
-Roborock S7 Max Ultra
-Roborock S8
-Roborock S8 Pro Ultra
-Roborock Q Revo
-Roborock Q8 Max
-Roborock Q5 Pro
-Roborock Q Revo Pro
-Roborock Qrevo S
-Roborock Qrevo Curve
-Roborock Saros 10
-Roborock (roborock.vacuum.a95)
-Roborock (roborock.vacuum.a159)
-Roborock (roborock.vacuum.ss07)
+- **Automatic device discovery** — no device IDs or IP addresses to look up. The Roborock region is detected from your account.
+- **Start, stop and send home** — over HomeKit the vacuum is a fan-style accessory: turn it on to start cleaning, off to stop and return to the dock.
+- **Battery, charging and status** — battery level, charging state, low-battery warning, and a fault/offline flag when the vacuum reports an error or loses its connection.
+- **Roborock scenes as switches** — every enabled scene from the Roborock app that uses the vacuum can be run from Apple Home.
+- **Dock mop-wash switch** on docks that wash the mop. See [Dock mop-wash switch](#dock-mop-wash-switch).
+- **Consumables** (HomeKit) — remaining life of the filter, main brush and side brush, with a change reminder at 5% or less.
+- **Clear errors from the settings page** — an error the vacuum or dock keeps reporting after you fixed the cause can be cleared without the Roborock app. See [Clearing device errors](#clearing-device-errors).
+- **Matter (Beta)** — publish a vacuum as a native Matter robot vacuum, with room cleaning and clean modes. See [Matter support (Beta)](#matter-support-beta).
+- **Works through cloud outages** — local control over the LAN, and a local-only start when the Roborock cloud is unreachable. See [Cloud outages and local-only mode](#cloud-outages-and-local-only-mode).
+- **Current room → MQTT** (optional) — publish the room being cleaned to your MQTT broker. See [Current Room → MQTT](#current-room--mqtt-optional-telemetry).
+- **Per-device choice** — publish each vacuum over HomeKit or Matter, or skip it (for example a vacuum shared from another home).
 
-## Requirements
+## Supported vacuums
 
-Before installing, ensure you have:
+The plugin works with vacuums that are on your **Roborock app** account. These models are known to work:
 
-- A Roborock vacuum cleaner compatible with the Roborock app.
-- A Roborock app account (email and password).
-- [Homebridge](https://github.com/homebridge/homebridge) installed on a server (e.g., Raspberry Pi).
-- Node.js and npm installed on your Homebridge server.
+S4, S4 Max, S5 Max, S6, S6 Pure, S6 MaxV, S7, S7 MaxV (Ultra), S7 Pro Ultra, S7 Max Ultra, S8, S8 Pro Ultra, Q5+, Q5 Pro, Q7, Q7 Max, Q8 Max, Qrevo, Qrevo Pro, Qrevo S, Qrevo Curv, Saros 10, and the models `roborock.vacuum.a95`, `roborock.vacuum.a159` and `roborock.vacuum.ss07`.
 
-## Installation
+Most other vacuums in the Roborock app work as well; which extras (dock mop wash, consumables, clean modes) appear depends on what the model reports. A vacuum that is set up only in the Xiaomi Home app is not on your Roborock account, so the plugin cannot see it.
+
+## Requirements
 
-Follow these steps to install the plugin:
+- A Roborock vacuum added to the Roborock app, and the email address of that Roborock account.
+- [Homebridge](https://homebridge.io) 1.6 or later, on Node.js 18.20, 20.15, 22 or 24.
+- For Matter: Homebridge 2.x with Matter enabled on the bridge the plugin runs on.
 
-1. **Install Homebridge** (if not already installed):
+## Installation
+
+In the Homebridge UI, open **Plugins**, search for **Roborock Vacuum** and install `homebridge-roborock-vacuum`.
 
-   - Refer to the official [Homebridge installation guide](https://github.com/homebridge/homebridge#installation).
+Without the UI, install it next to Homebridge:
 
-2. **Install the Plugin**:
-   - Open a terminal and run:
-     ```bash
-     npm install -g homebridge-roborock-vacuum
-     ```
+```bash
+npm install -g homebridge-roborock-vacuum
+```
 
 ## Configuration
 
-Use the Homebridge UI settings page to sign in and configure the plugin. Click **Load devices** to list the vacuums on your account, then choose a protocol for each one:
+Configure the plugin from its settings page in the Homebridge UI:
 
-- **HomeKit (HAP)** — the default. The vacuum is bridged to Apple Home as a fan-style accessory, as in previous versions.
-- **Matter (Beta)** — the vacuum is published over Matter as a robotic vacuum cleaner, so it gets the native vacuum icon and controls in Apple Home (and works with Google Home, Alexa and SmartThings). This is an experimental feature — read the [Matter support (Beta)](#matter-support-beta) section below before enabling it.
-- **Skip** — the vacuum is excluded entirely. You can also enter device IDs manually in the list below; manual entries are always skipped.
+1. **Sign in.** Enter your Roborock app email. Either enter your password and press **Password Login**, or press **Send 2FA Email** and enter the code from the email with **Verify Code** (also the way to finish a login that asks for two-factor authentication). Leave **Region** on _Auto detect_ unless detection picks the wrong server. The settings page stores an encrypted session token; you do not need to sign in again after a restart.
+2. **Choose a protocol per vacuum.** Press **Load devices** to list the vacuums on your account and pick one for each:
+   - **HomeKit (HAP)** — the default. The vacuum is bridged to Apple Home as a fan-style accessory, as in previous versions.
+   - **Matter (Beta)** — the vacuum is published over Matter as a robotic vacuum cleaner, so it gets the native vacuum icon and controls in Apple Home (and works with Google Home, Alexa and SmartThings). This is an experimental feature — read the [Matter support (Beta)](#matter-support-beta) section below before enabling it.
+   - **Skip** — the vacuum is excluded entirely. You can also enter device IDs manually in the list below; manual entries are always skipped.
+3. **Restart Homebridge.**
 
 When Homebridge restarts, each device is (re)published according to its selection. A device that was cached under a different protocol (or is now skipped) is removed from the old bridge first. **Changing a device's protocol re-creates the accessory**, so it loses its room and automation assignments in your home app and must be re-organized there.
 
+### Options
+
+The settings page writes these keys to the `RoborockVacuumPlatform` block in `config.json`:
+
+| Key                  | Description                                                                                                                                                                                                |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `email`              | Roborock app account email. Required.                                                                                                                                                                      |
+| `password`           | Roborock account password, saved by **Password Login**. Not needed when you sign in with an email code.                                                                                                    |
+| `encryptedToken`     | Encrypted session data, managed by the settings page.                                                                                                                                                      |
+| `baseURL`            | Roborock API endpoint. Leave empty to auto-detect; otherwise `https://usiot.roborock.com` (US), `https://euiot.roborock.com` (EU), `https://cniot.roborock.com` (CN) or `https://api.roborock.com` (Asia). |
+| `language`           | Language of the names the plugin gives to switches and sensors it adds (`en`, `de`, `es`, `fr`, `it`, `nl`, `pl`, `pt`, `ru`, `uk`, `zh-cn`, `zh-tw`). Default `en`.                                       |
+| `skipDevices`        | Device IDs to leave out, as a list or a comma- or newline-separated string.                                                                                                                                |
+| `matterDevices`      | Device IDs to publish over Matter instead of HomeKit. Ignored without Homebridge 2 and Matter.                                                                                                             |
+| `matterSceneDevices` | Matter device IDs whose Roborock scenes become Matter buttons. When omitted, every Matter device gets them.                                                                                                |
+| `currentRoomMqtt`    | Optional current-room telemetry, see [Current Room → MQTT](#current-room--mqtt-optional-telemetry).                                                                                                        |
+| `debugMode`          | Write debug messages to the Homebridge log. Default `false`.                                                                                                                                               |
+
 ### Matter support (Beta)
 
 > ⚠️ **This is an experimental, lab-grade beta feature.** Matter support for robotic vacuums is still very new on the controller side. In particular, **Apple Home's compatibility is currently poor and not very stable**: the bridge is uncertified (Apple shows an "Uncertified Accessory" warning), the accessory appears as a generic **"Matter Accessory"** during pairing and must be named manually, room selection needs iOS 18.4 or later, and accessories can occasionally show "Not responding" or lose features after iOS updates. If you want the most reliable day-to-day experience, stay on **HomeKit (HAP)**. Choose Matter only if you want the native vacuum UI and room cleaning, and can live with rough edges.
@@ -153,6 +160,14 @@ The switch is **stateful**: it turns on whenever the dock is washing the mop —
 
 The switch's default name comes from the plugin's translation catalog in the language selected by the **Language** option on the settings page (`"language"` in `config.json`; default `en`, 12 languages including `zh-cn` and `zh-tw`). Changing the language only renames accessories on the next restart — accessory identities never change, so **no re-pairing and no room re-selection is needed**. You can also rename the switch freely in your home app.
 
+## Clearing device errors
+
+Some errors stay on the vacuum until they are marked as resolved in the Roborock app, even after the cause is fixed. A typical one is the dock's "clean water tank empty" after you have refilled the tank. While such an error is latched, Apple Home keeps showing the fault.
+
+When a vacuum reports an error, the plugin's settings page shows it next to the vacuum in the device list, with the error code and a short description. Press **Clear error** to resolve it, like tapping **Resolved** in the Roborock app. A dock error is cleared first; press the button again if the vacuum then still reports an error of its own.
+
+The settings page asks the running plugin to send the command, so Homebridge must be running. Fix the cause before clearing the error; an error whose cause is still there comes back.
+
 ## Current Room → MQTT (optional telemetry)
 
 The plugin can publish the room a vacuum is currently cleaning to a local MQTT broker, for use in external automations (e.g. lighting that follows the vacuum room to room). This is **telemetry only** — it is not exposed to HomeKit — and is **off by default**. It reuses the `mqtt` dependency the plugin already ships, so it adds nothing when disabled.
@@ -191,3 +206,14 @@ A retained JSON message is published whenever the room changes:
 - Room names are resolved from the robot's saved map; name your rooms in the Roborock app for them to appear.
 
 > Validated on a Roborock Qrevo (`roborock.vacuum.a185`). On models that don't populate `cleaning_info`, the payload degrades gracefully to `segment_id: -1` / `room: null`.
+
+## Support
+
+If this plugin is useful to you, I'd love it if you bought me a boba:
+
+- **[Buy me a boba](https://tasict.bobaboba.me)**: pay by card, no PayPal account needed
+- **[Tip with PayPal](https://paypal.me/tasict)**
+
+## Trademarks
+
+Roborock is a trademark of Beijing Roborock Technology Co., Ltd. Apple Home and HomeKit are trademarks of Apple Inc. Matter is a trademark of the Connectivity Standards Alliance. This plugin is unofficial and is not affiliated with, endorsed by, or sponsored by any of them.

package/config.schema.json

@@ -17,13 +17,13 @@
         "title": "Email",
         "type": "string",
         "format": "email",
-        "description": "Roborock account email"
+        "description": "Email of your Roborock app account"
       },
       "password": {
         "title": "Password",
         "type": "string",
         "placeholder": "Password",
-        "description": "Roborock account password"
+        "description": "Roborock account password (not needed when signing in with an email code)"
       },
       "encryptedToken": {
         "title": "Encrypted Token",
@@ -34,7 +34,7 @@
       "skipDevices": {
         "title": "Skipped Device IDs",
         "type": "string",
-        "description": "Roborock device IDs to exclude from HomeKit."
+        "description": "Roborock device IDs to leave out of Apple Home (neither HomeKit nor Matter)."
       },
       "matterDevices": {
         "title": "Matter Device IDs",

package/dist/device_error_bridge.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * Device errors shared between the plugin and its settings page.
+ *
+ * The settings page runs in the Homebridge UI's own process and cannot reach
+ * the vacuums itself — a second cloud MQTT session under the account's
+ * client id would disconnect the plugin's. So the files in the Homebridge
+ * storage directory carry the exchange instead:
+ * - the plugin publishes every bridged vacuum's current errors to
+ *   DEVICE_ERRORS_FILE;
+ * - the page asks for an error to be resolved by writing a request file
+ *   into RESOLVE_REQUEST_DIR, which the plugin picks up, runs and answers
+ *   with a result file next to it.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceErrorBridge = exports.RESOLVE_REQUEST_TTL_MS = exports.RESOLVE_REQUEST_DIR = exports.DEVICE_ERRORS_FILE = void 0;
+exports.isValidRequestId = isValidRequestId;
+exports.requestFilePath = requestFilePath;
+exports.resultFilePath = resultFilePath;
+exports.writeJsonAtomic = writeJsonAtomic;
+exports.readJson = readJson;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.DEVICE_ERRORS_FILE = "roborock.deviceErrors.json";
+exports.RESOLVE_REQUEST_DIR = "roborock.resolveError";
+// A request the plugin has not picked up within this window is dropped, and
+// an unread result is removed after the same time.
+exports.RESOLVE_REQUEST_TTL_MS = 60 * 1000;
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9-]{1,64}$/;
+function isValidRequestId(id) {
+    return typeof id === "string" && REQUEST_ID_PATTERN.test(id);
+}
+function requestFilePath(storagePath, id) {
+    return path_1.default.join(storagePath, exports.RESOLVE_REQUEST_DIR, `${id}.request.json`);
+}
+function resultFilePath(storagePath, id) {
+    return path_1.default.join(storagePath, exports.RESOLVE_REQUEST_DIR, `${id}.result.json`);
+}
+/** Write through a temporary file so readers never see a partial file. */
+function writeJsonAtomic(filePath, value) {
+    const tmpPath = `${filePath}.${process.pid}.tmp`;
+    fs_1.default.writeFileSync(tmpPath, JSON.stringify(value, null, 2), "utf8");
+    fs_1.default.renameSync(tmpPath, filePath);
+}
+function readJson(filePath) {
+    try {
+        return JSON.parse(fs_1.default.readFileSync(filePath, "utf8"));
+    }
+    catch (error) {
+        return null;
+    }
+}
+/** Plugin side: publishes device errors and serves resolve requests. */
+class DeviceErrorBridge {
+    constructor(storagePath, 
+    // Resolves the device's current error; true when a resolve was sent,
+    // false when there was nothing to resolve. Throws on failure.
+    resolve, log) {
+        this.storagePath = storagePath;
+        this.resolve = resolve;
+        this.log = log;
+        this.lastPublished = null;
+        this.processing = false;
+    }
+    /** Publish the current errors; a no-op when nothing changed. */
+    publish(devices) {
+        const content = JSON.stringify(devices);
+        if (content === this.lastPublished) {
+            return;
+        }
+        try {
+            const file = { updatedAt: Date.now(), devices };
+            writeJsonAtomic(path_1.default.join(this.storagePath, exports.DEVICE_ERRORS_FILE), file);
+            this.lastPublished = content;
+        }
+        catch (error) {
+            this.log.debug(`Failed to publish device errors: ${error}`);
+        }
+    }
+    /** Poll for resolve requests from the settings page. */
+    start(intervalMs = 2000) {
+        var _a, _b;
+        if (this.timer) {
+            return;
+        }
+        this.timer = setInterval(() => {
+            void this.processRequests();
+        }, intervalMs);
+        (_b = (_a = this.timer).unref) === null || _b === void 0 ? void 0 : _b.call(_a);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    async processRequests() {
+        if (this.processing) {
+            return;
+        }
+        this.processing = true;
+        try {
+            const dir = path_1.default.join(this.storagePath, exports.RESOLVE_REQUEST_DIR);
+            let entries;
+            try {
+                entries = fs_1.default.readdirSync(dir);
+            }
+            catch (error) {
+                return; // No request has been made yet.
+            }
+            const now = Date.now();
+            for (const entry of entries) {
+                const filePath = path_1.default.join(dir, entry);
+                if (entry.endsWith(".result.json")) {
+                    this.removeIfOlderThan(filePath, now - exports.RESOLVE_REQUEST_TTL_MS);
+                    continue;
+                }
+                if (!entry.endsWith(".request.json")) {
+                    continue;
+                }
+                const request = readJson(filePath);
+                // Claim the request before running it so it is never run twice.
+                this.remove(filePath);
+                if (!request ||
+                    !isValidRequestId(request.id) ||
+                    typeof request.duid !== "string" ||
+                    typeof request.requestedAt !== "number" ||
+                    now - request.requestedAt > exports.RESOLVE_REQUEST_TTL_MS) {
+                    continue;
+                }
+                await this.handleRequest(request);
+            }
+        }
+        finally {
+            this.processing = false;
+        }
+    }
+    async handleRequest(request) {
+        let result;
+        try {
+            const sent = await this.resolve(request.duid);
+            result = {
+                id: request.id,
+                ok: true,
+                message: sent ? "Error resolved." : "There is no error to resolve.",
+                finishedAt: Date.now(),
+            };
+        }
+        catch (error) {
+            this.log.warn(`Failed to resolve the error of ${request.duid} requested from the settings page: ${error}`);
+            result = {
+                id: request.id,
+                ok: false,
+                message: `Failed to resolve the error: ${error instanceof Error ? error.message : String(error)}`,
+                finishedAt: Date.now(),
+            };
+        }
+        try {
+            writeJsonAtomic(resultFilePath(this.storagePath, request.id), result);
+        }
+        catch (error) {
+            this.log.debug(`Failed to write the resolve result: ${error}`);
+        }
+    }
+    remove(filePath) {
+        try {
+            fs_1.default.unlinkSync(filePath);
+        }
+        catch (error) {
+            // Already gone.
+        }
+    }
+    removeIfOlderThan(filePath, cutoff) {
+        try {
+            if (fs_1.default.statSync(filePath).mtimeMs < cutoff) {
+                fs_1.default.unlinkSync(filePath);
+            }
+        }
+        catch (error) {
+            // Already gone.
+        }
+    }
+}
+exports.DeviceErrorBridge = DeviceErrorBridge;
+//# sourceMappingURL=device_error_bridge.js.map

package/dist/device_error_bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device_error_bridge.js","sourceRoot":"","sources":["../src/device_error_bridge.ts"],"names":[],"mappings":"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"}

package/dist/error_codes.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Labels for Roborock error codes, shared by the Matter operational-error
+ * reporting and the settings page's device error display.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROBOROCK_DOCK_ERROR_LABELS = exports.ROBOROCK_ERROR_LABELS = void 0;
+// Robot error_code values.
+exports.ROBOROCK_ERROR_LABELS = {
+    1: "Laser sensor fault",
+    2: "Collision sensor fault",
+    3: "Wheel floating",
+    4: "Cliff sensor fault",
+    5: "Main brush blocked",
+    6: "Side brush blocked",
+    7: "Wheel blocked",
+    8: "Device stuck",
+    9: "Dust bin missing",
+    10: "Filter blocked",
+    11: "Magnetic field detected",
+    12: "Low battery",
+    13: "Charging problem",
+    14: "Battery failure",
+    15: "Wall sensor fault",
+    16: "Uneven surface",
+    17: "Side brush failure",
+    18: "Suction fan failure",
+    19: "Unpowered charging station",
+    21: "Laser pressure sensor problem",
+    22: "Charge sensor problem",
+    23: "Dock problem",
+    24: "No-go zone or invisible wall detected",
+    254: "Bin full",
+    255: "Internal error",
+};
+// Dock dock_error_status values (python-roborock RoborockDockErrorCode).
+exports.ROBOROCK_DOCK_ERROR_LABELS = {
+    32: "No dock dustbin or filter",
+    33: "Auto-empty dock fan error",
+    34: "Auto-empty dock jammed",
+    35: "Auto-empty dock voltage error",
+    38: "Clean water tank empty",
+    39: "Dirty water tank full or missing",
+    42: "Maintenance brush jammed",
+    44: "Water filter blocked",
+    46: "Dustbin not installed",
+    53: "Cleaning tank full or blocked",
+};
+//# sourceMappingURL=error_codes.js.map

package/dist/error_codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error_codes.js","sourceRoot":"","sources":["../src/error_codes.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,2BAA2B;AACd,QAAA,qBAAqB,GAA2B;IAC3D,CAAC,EAAE,oBAAoB;IACvB,CAAC,EAAE,wBAAwB;IAC3B,CAAC,EAAE,gBAAgB;IACnB,CAAC,EAAE,oBAAoB;IACvB,CAAC,EAAE,oBAAoB;IACvB,CAAC,EAAE,oBAAoB;IACvB,CAAC,EAAE,eAAe;IAClB,CAAC,EAAE,cAAc;IACjB,CAAC,EAAE,kBAAkB;IACrB,EAAE,EAAE,gBAAgB;IACpB,EAAE,EAAE,yBAAyB;IAC7B,EAAE,EAAE,aAAa;IACjB,EAAE,EAAE,kBAAkB;IACtB,EAAE,EAAE,iBAAiB;IACrB,EAAE,EAAE,mBAAmB;IACvB,EAAE,EAAE,gBAAgB;IACpB,EAAE,EAAE,oBAAoB;IACxB,EAAE,EAAE,qBAAqB;IACzB,EAAE,EAAE,4BAA4B;IAChC,EAAE,EAAE,+BAA+B;IACnC,EAAE,EAAE,uBAAuB;IAC3B,EAAE,EAAE,cAAc;IAClB,EAAE,EAAE,uCAAuC;IAC3C,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,gBAAgB;CACtB,CAAC;AAEF,yEAAyE;AAC5D,QAAA,0BAA0B,GAA2B;IAChE,EAAE,EAAE,2BAA2B;IAC/B,EAAE,EAAE,2BAA2B;IAC/B,EAAE,EAAE,wBAAwB;IAC5B,EAAE,EAAE,+BAA+B;IACnC,EAAE,EAAE,wBAAwB;IAC5B,EAAE,EAAE,kCAAkC;IACtC,EAAE,EAAE,0BAA0B;IAC9B,EAAE,EAAE,sBAAsB;IAC1B,EAAE,EAAE,uBAAuB;IAC3B,EAAE,EAAE,+BAA+B;CACpC,CAAC"}

package/dist/platform.js

@@ -10,6 +10,7 @@ const dock_wash_matter_accessory_1 = require("./dock_wash_matter_accessory");
 const logger_1 = __importDefault(require("./logger"));
 const settings_1 = require("./settings");
 const crypto_1 = require("./crypto");
+const device_error_bridge_1 = require("./device_error_bridge");
 const protocol_1 = require("./protocol");
 const DEP0040_CODE = "DEP0040";
 let dep0040FilterInstalled = false;
@@ -45,6 +46,7 @@ const DPS_STATUS_FIELDS = {
     "122": "battery",
     "123": "fan_power",
     "124": "water_box_mode",
+    "133": "charge_status",
 };
 function translateDpsFields(payload) {
     const dps = payload.dps;
@@ -121,6 +123,11 @@ class RoborockPlatform {
             storagePath: storagePath,
             currentRoomMqtt: this.platformConfig.currentRoomMqtt,
         });
+        this.errorBridge = new device_error_bridge_1.DeviceErrorBridge(storagePath, async (duid) => {
+            const sent = await this.roborockAPI.resolveError(duid);
+            this.publishDeviceErrors();
+            return sent;
+        }, this.log);
         /**
          * When this event is fired it means Homebridge has restored all cached accessories from disk.
          * Dynamic Platform plugins should only register new accessories after this event was fired,
@@ -138,6 +145,7 @@ class RoborockPlatform {
         });
         this.api.on("shutdown" /* APIEvent.SHUTDOWN */, () => {
             this.log.debug("Shutting down...");
+            this.errorBridge.stop();
             if (this.roborockAPI) {
                 this.roborockAPI.stopService();
             }
@@ -232,6 +240,7 @@ class RoborockPlatform {
                         dockWash.updateFromRoborockData(data);
                     }
                 }
+                self.publishDeviceErrors();
                 return;
             }
             for (const vacuum of self.vacuums) {
@@ -241,12 +250,10 @@ class RoborockPlatform {
                 // Scenes load asynchronously; sync the Matter scene buttons once
                 // they are available (or when they change).
                 self.syncMatterScenes();
-                // The HomeData refresh is the only periodic status source — the
-                // roborockLib get_status interval runs but its results never reach
-                // the cache this plugin reads (gated on an unset config field, and
-                // written to a state path getVacuumDeviceStatus does not read).
-                // Mirror it into the Matter vacuums the same way updateDeviceState
-                // does for the HAP accessories.
+                // Periodic status sync. getVacuumDeviceStatus serves the device's
+                // live status (get_status polls and broadcasts) and falls back to
+                // the HomeData snapshot. Mirror it into the Matter vacuums the same
+                // way updateDeviceState does for the HAP accessories.
                 for (const matterVacuum of self.matterVacuums.values()) {
                     matterVacuum.refreshFromDevice();
                 }
@@ -254,12 +261,15 @@ class RoborockPlatform {
                 for (const dockWash of self.matterDockWash.values()) {
                     dockWash.refreshFromDevice();
                 }
+                self.publishDeviceErrors();
             }
         });
         Promise.resolve(self.roborockAPI.startService(function () {
             self.log.info("Service started");
             //call the discoverDevices function
             self.discoverDevices();
+            self.publishDeviceErrors();
+            self.errorBridge.start();
         })).catch((error) => {
             self.log.error(`Failed to start the Roborock service: ${error}. ` +
                 "The plugin will stay idle; fix the configuration or connectivity " +
@@ -309,6 +319,26 @@ class RoborockPlatform {
         // model must start with "roborock.vacuum."
         return typeof model === "string" && model.startsWith("roborock.vacuum.");
     }
+    /**
+     * Publish every bridged vacuum's current robot and dock error for the
+     * settings page. Cheap when nothing changed (the bridge skips the write).
+     */
+    publishDeviceErrors() {
+        if (!this.roborockAPI.isInited()) {
+            return;
+        }
+        const errorCode = (duid, field) => Number(this.roborockAPI.getVacuumDeviceStatus(duid, field)) || 0;
+        const devices = this.roborockAPI
+            .getVacuumList()
+            .filter((device) => !this.isSkippedDeviceId(device.duid))
+            .map((device) => ({
+            duid: device.duid,
+            name: device.name,
+            errorCode: errorCode(device.duid, "error_code"),
+            dockErrorCode: errorCode(device.duid, "dock_error_status"),
+        }));
+        this.errorBridge.publish(devices);
+    }
     isSkippedDeviceId(deviceId) {
         return this.resolveProtocol(deviceId) === "skip";
     }