homebridge-roborock-matter 3.2.0 → 3.3.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 3.3.1
+
+Two field reports arrived within an hour of 3.3.0 and both came down to the same thing: the log and the diagnostics report were answering questions nobody had asked while staying silent on the one that mattered. This release is almost entirely about making the plugin legible.
+
+- **The live-room log said "the robot may be between rooms" for four different problems.** The resolver returns nothing when the map payload has no header, when it carries no robot position, when it carries no room outlines, or when the position genuinely falls outside every outline — and only the last of those is "between rooms". A day of field logs produced 51 of these messages, every one of them asserting a cause that may not have been the cause. Each case is now named, with the number of outlines in the map and the computed position cell, so a coordinate problem is visible in the log instead of needing a debug build.
+- **The message identifying a misbehaving robot was the one you could not read.** The failure line printed a raw 22-character duid while the success line beside it printed the robot's name. In a three-robot house that is the difference between a usable log and a wall of identifiers. The live-room, B01 status and B01 room lines all use the name now.
+- **The attempt counter appeared to reset at random.** A robot resolving back into the room it was already in silently zeroed the miss counter without logging anything, so "attempt 15" was followed by "attempt 5" with nothing in between. Re-entering a known room after a run of misses now says so.
+- **The startup line announced a cadence the code stopped using.** 3.2.0 changed the at-rest B01 poll from 45 s to 25 s and left the message advertising 45 s — misleading in exactly the area it was meant to explain. The cadence values are named constants now and the message is derived from them, so they cannot drift apart again.
+- **The diagnostics report now lists which Apple Home features are switched on.** A report that omits them cannot answer "why doesn't Apple Home show this?", which is the first question most of them are sent to answer — and it cost a full round-trip with a user who had run the test correctly.
+- **The Matter publish line names the robot, and reports a fault when one is being published.** Previously it printed a duid and said nothing about faults, so there was no way to tell whether Apple Home was showing nothing because the plugin sent nothing.
+- **`operationalError` is no longer part of the accessory's registration snapshot.** It is published on the first runtime update instead, seconds later. Matter commissions the endpoint from that snapshot, and 1.4.61 removed the plugin's fault write precisely because Apple Home reacted badly to it there — so a robot that happens to be faulted when Homebridge starts can no longer change what gets commissioned. The mandatory Matter default covers the gap.
+
+## 3.3.0
+
+A robot that has stopped because it is wedged under the sofa has always looked exactly like a robot that finished the job: **Ready**. This release lets the plugin say what is actually wrong — asked for by Wazza151 in [#5](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/5), whose previous Matter bridge showed him when the clean-water tank ran empty.
+
+- **New setting: Report faults in Apple Home** (off by default). The robot's own faults — stuck, blocked brush or wheel, missing dust bin, flat battery, unreachable dock — are published as the Matter Error state with the Roborock description attached, instead of being flattened to Ready. Dock and tank conditions — clean-water tank empty, waste-water tank full, dust bag missing, air duct blocked, mop-wash tank full — are published as a Matter fault too, but deliberately do **not** force the Error state: a robot whose waste-water tank is full can still vacuum, and an accessory in Error may be refused a Start command by the controller.
+- **The Error state was never gated for a reason.** `ERROR` (3) is a member of even the basic advertised operational state list, so publishing it was always legal — it was being rewritten to `STOPPED` alongside the states that genuinely did need a gate. That is why no released version has ever shown a Roborock fault in Apple Home.
+- **A detached water tank or mop pad is not a fault.** Both are the normal, correct configuration for a vacuum-only run, so reporting them would leave a permanent warning on every dry robot's tile. They are read, and deliberately ignored.
+- **The fault detail can never cost you the tile.** `operationalError` travels in the same cluster payload as the operational state, so a Matter build that refuses the attribute would otherwise freeze Cleaning/Docked along with it — the reason the explicit write was removed back in 1.4.61. If the write is rejected, the plugin immediately re-publishes without it, logs a warning naming the reason, and stops sending it for the rest of the session. An endpoint that is merely still starting up keeps its normal retry and does not disable the feature.
+- **Diagnostics no longer truncate away the answer.** A Roborock status payload runs to about fifty fields and the export kept the first thirty — which are largely housekeeping, while the twenty it dropped included `dock_error_status`, the single field a question about the dock's water tanks turns on. The fields that matter for a fault report are now always kept, however far down the payload they sit, with the size cap otherwise unchanged and secret redaction untouched.
+
 ## 3.2.0
 
 Field feedback on the Q7 series: the live room in Apple Home lagged badly behind the robot. One run took 90 seconds to name the first room; another took seven minutes.

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. 279 automated tests, zero known vulnerabilities, no analytics, and a startup designed to never crash your Homebridge — even when your Wi-Fi or the Roborock cloud has a bad day.
+- 🛡️ **Verified by Homebridge.** Reviewed and endorsed by the Homebridge team. 380 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
 
@@ -75,7 +75,7 @@ Progress stays honest: a room is only shown as _completed_ once the robot was ac
 <details>
 <summary>How it works under the hood</summary>
 
-While a robot is actively cleaning, the plugin fetches its live position from the map channel (throttled to ~20 s, active runs only, nothing while docked or paused) and publishes the room it is inside as the Matter Service Area `currentArea`. Both robot generations are covered: **B01/Q7** robots via the encrypted SCMap protobuf (position ray-cast against per-room boundary outlines), **classic S/Q-series** robots via the RRMap segment grid (position resolved against per-pixel room segments — a single-byte lookup on the raw map buffer, ~1 µs per check).
+While a robot is actively cleaning, the plugin fetches its live position from the map channel (the first room of a run goes out immediately, then ~10 s apart, active runs only, nothing while docked or paused) and publishes the room it is inside as the Matter Service Area `currentArea`. Both robot generations are covered: **B01/Q7** robots via the encrypted SCMap protobuf (position ray-cast against per-room boundary outlines), **classic S/Q-series** robots via the RRMap segment grid (position resolved against per-pixel room segments — a single-byte lookup on the raw map buffer, ~1 µs per check).
 
 </details>
 
@@ -102,17 +102,31 @@ The clean mode follows the robot as well: start a vacuum+mop or mop-only clean f
 
 Everything is configurable from the Homebridge UI. The essentials:
 
-| Option                          | Default | What it does                                                                                                                                                                  |
-| ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `email` / password              | —       | Your Roborock app account (2FA handled in the UI; the session token is stored encrypted)                                                                                      |
-| `skipDevices`                   | —       | Comma-separated device IDs the plugin should ignore                                                                                                                           |
-| `enableMatterServiceArea`       | `true`  | Room/map selection in Apple Home                                                                                                                                              |
-| `enableLiveRoomTracking`        | `true`  | Live current-room from the robot's map position while cleaning                                                                                                                |
-| `enableMatterCleanMode`         | `true`  | Vacuum / Mop / Vacuum + Mop mode selection                                                                                                                                    |
-| `enableFanPowerCleanModes`      | `false` | Adds Quiet / Balanced / Turbo / Max (and Max+ on Q7) suction modes to the Matter mode list. **Re-pair the robot once after toggling** — Matter locks the mode list at pairing |
-| `enableMatterPowerSource`       | `true`  | Battery cluster                                                                                                                                                               |
-| `cloudOnlyMode`                 | `false` | Skip local TCP entirely and use the cloud for everything                                                                                                                      |
-| `transientWarningThrottleHours` | `6`     | How often recurring transient-timeout warnings may repeat (0 = only in debug)                                                                                                 |
+| Option                          | Default | What it does                                                                                                                                                                    |
+| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `email` / password              | —       | Your Roborock app account (2FA handled in the UI; the session token is stored encrypted)                                                                                        |
+| `skipDevices`                   | —       | Comma-separated device IDs the plugin should ignore                                                                                                                             |
+| `enableMatterServiceArea`       | `true`  | Room/map selection in Apple Home                                                                                                                                                |
+| `enableLiveRoomTracking`        | `true`  | Live current-room from the robot's map position while cleaning                                                                                                                  |
+| `enableMatterCleanMode`         | `true`  | Vacuum / Mop / Vacuum + Mop mode selection                                                                                                                                      |
+| `enableFanPowerCleanModes`      | `false` | Adds Quiet / Balanced / Turbo / Max (and Max+ on Q7) suction modes to the Matter mode list. **Re-pair the robot once after toggling** — Matter locks the mode list at pairing   |
+| `enableMatterPowerSource`       | `true`  | Battery cluster                                                                                                                                                                 |
+| `enableMatterFaultReporting`    | `false` | Say why the robot needs attention instead of showing Ready — stuck, empty clean-water tank, full waste-water tank, missing dust bag ([details](#why-the-robot-needs-attention)) |
+| `cloudOnlyMode`                 | `false` | Skip local TCP entirely and use the cloud for everything                                                                                                                        |
+| `transientWarningThrottleHours` | `6`     | How often recurring transient-timeout warnings may repeat (0 = only in debug)                                                                                                   |
+
+## Why the robot needs attention
+
+By default a robot that has stopped for any reason shows as **Ready** in Apple Home — whether it finished the job or is wedged under the sofa. Turning on **Report faults in Apple Home** changes that: the robot's own faults are published as the Matter Error state, and the condition behind them is published as a Matter fault so the Home app can say what is wrong rather than just that something is.
+
+What gets reported:
+
+- **The robot's own faults** — stuck, a blocked brush or wheel, a missing dust bin, a flat battery, a dock it cannot reach. These put the tile into Error, because the robot genuinely cannot work.
+- **Dock and tank conditions** — an empty clean-water tank, a full waste-water tank, a missing dust bag, a blocked air duct, a mop-wash tank that needs emptying. These are reported as a fault but deliberately **do not** put the tile into Error: a robot whose waste-water tank is full can still vacuum, and an accessory in Error may be refused a Start command by the controller.
+
+What is deliberately **not** reported: a detached water tank or mop pad. That is the normal, correct configuration for a vacuum-only run, so treating it as a fault would leave a permanent warning on every dry robot's tile.
+
+It is off by default for two reasons: a robot reporting Error may be refused a Start command from Apple Home, and the fault attribute has a history with Apple Home commissioning. If Matter ever refuses the attribute, the plugin drops it by itself and logs a warning rather than letting it freeze the tile. How much of this Apple Home actually draws, and in what words, is Apple's decision.
 
 ## Battery percentage in Apple Home
 

package/config.schema.json

@@ -110,6 +110,12 @@
         "type": "boolean",
         "default": false
       },
+      "enableMatterFaultReporting": {
+        "title": "Report Faults in Apple Home",
+        "description": "Show why the robot needs attention instead of leaving it as Ready: a stuck robot reports Error, and conditions such as an empty clean-water tank, a full waste-water tank, a missing dust bag or a blocked brush are published as a Matter fault. Which of them Apple Home renders, and how, is Apple's decision. Off by default because a robot reporting Error may refuse a Start command from Apple Home. Dock conditions never force the Error state, so a robot that can still vacuum stays startable. If Matter refuses the fault attribute, the plugin drops it automatically and logs a warning rather than freezing the tile.",
+        "type": "boolean",
+        "default": false
+      },
       "matterChargedBatteryThreshold": {
         "title": "Charged Battery Threshold (%)",
         "description": "Battery percentage at which a docked robot switches from Charging to Docked on the Apple Home tile. Default 100. Lower it (e.g. 90) if a worn battery makes the robot report fully charged early.",

package/dist/matter_vacuum_accessory.js

@@ -145,6 +145,102 @@ const RVC_CHARGING_DOCKED_STATE_LIST = [
     RVC_OPERATIONAL_STATE.CHARGING,
     RVC_OPERATIONAL_STATE.DOCKED,
 ];
+// RVC Operational State ErrorStateEnum, from the Matter cluster definition
+// (src/app/zap-templates/zcl/data-model/chip/operational-state-rvc-cluster.xml).
+// Only the values that shipped with the original RVC device type are used:
+// they are the ones controllers have understood the longest, and a fault the
+// controller cannot name is worse than a generic one it can.
+const RVC_ERROR_STATE = {
+    NO_ERROR: 0x00,
+    UNABLE_TO_START_OR_RESUME: 0x01,
+    UNABLE_TO_COMPLETE_OPERATION: 0x02,
+    FAILED_TO_FIND_CHARGING_DOCK: 0x40,
+    STUCK: 0x41,
+    DUST_BIN_MISSING: 0x42,
+    DUST_BIN_FULL: 0x43,
+    WATER_TANK_EMPTY: 0x44,
+    WATER_TANK_MISSING: 0x45,
+    MOP_CLEANING_PAD_MISSING: 0x47,
+    LOW_BATTERY: 0x48,
+};
+/**
+ * Roborock `error_code` to Matter ErrorStateEnum. The Roborock names are the
+ * ones this plugin already shows in `deviceFeatures.js`; several distinct
+ * mechanical faults collapse onto STUCK because Matter has no finer-grained
+ * standard code for them, which is fine — the human-readable Roborock text
+ * rides along in `errorStateDetails`.
+ *
+ * Codes deliberately absent map to UNABLE_TO_COMPLETE_OPERATION via the
+ * fallback: inventing a wrong specific code is worse than a correct vague one.
+ */
+const ROBOROCK_ERROR_TO_MATTER = new Map([
+    [3, RVC_ERROR_STATE.STUCK], // Wheel floating
+    [5, RVC_ERROR_STATE.STUCK], // Main brush blocked
+    [6, RVC_ERROR_STATE.STUCK], // Side brush blocked
+    [7, RVC_ERROR_STATE.STUCK], // Wheel blocked
+    [8, RVC_ERROR_STATE.STUCK], // Device stuck
+    [9, RVC_ERROR_STATE.DUST_BIN_MISSING], // Dust bin missing
+    [12, RVC_ERROR_STATE.LOW_BATTERY], // Low battery
+    [16, RVC_ERROR_STATE.STUCK], // Uneven surface
+    [19, RVC_ERROR_STATE.FAILED_TO_FIND_CHARGING_DOCK], // Unpowered charging station
+    [22, RVC_ERROR_STATE.FAILED_TO_FIND_CHARGING_DOCK], // Charge sensor problem
+    [23, RVC_ERROR_STATE.FAILED_TO_FIND_CHARGING_DOCK], // Dock problem
+    [24, RVC_ERROR_STATE.STUCK], // No-go zone or invisible wall detected
+    [254, RVC_ERROR_STATE.DUST_BIN_FULL], // Bin full
+]);
+/**
+ * Roborock `dock_error_status` to Matter ErrorStateEnum, with the label the
+ * Roborock app uses. Values are the ones the reference implementations agree
+ * on; `0` means the dock is healthy.
+ *
+ * The dirty-water tank has no pre-1.4 standard code, so "waste water tank
+ * full" reports as DUST_BIN_FULL — the closest "a container needs emptying"
+ * signal every controller understands — with the true wording in the details.
+ */
+const ROBOROCK_DOCK_ERROR_TO_MATTER = new Map([
+    [
+        34,
+        {
+            errorStateId: RVC_ERROR_STATE.UNABLE_TO_COMPLETE_OPERATION,
+            details: "Dock air duct blocked",
+        },
+    ],
+    [
+        38,
+        {
+            errorStateId: RVC_ERROR_STATE.WATER_TANK_EMPTY,
+            details: "Clean water tank empty",
+        },
+    ],
+    [
+        39,
+        {
+            errorStateId: RVC_ERROR_STATE.DUST_BIN_FULL,
+            details: "Waste water tank full",
+        },
+    ],
+    [
+        44,
+        {
+            errorStateId: RVC_ERROR_STATE.WATER_TANK_MISSING,
+            details: "Dirty water tank latch open",
+        },
+    ],
+    [
+        46,
+        {
+            errorStateId: RVC_ERROR_STATE.DUST_BIN_MISSING,
+            details: "Dock dust bag missing",
+        },
+    ],
+    [
+        53,
+        {
+            errorStateId: RVC_ERROR_STATE.UNABLE_TO_COMPLETE_OPERATION,
+            details: "Mop cleaning tank full or blocked",
+        },
+    ],
+]);
 const POWER_SOURCE_STATUS = {
     ACTIVE: 1,
     UNAVAILABLE: 3,
@@ -252,6 +348,13 @@ class RoborockMatterVacuumAccessory {
         this.lastWaterBoxMode = null;
         this.matterInitializationRetryAttempt = 0;
         this.matterInitializationRetryPending = false;
+        // Latched when a Matter write carrying `operationalError` is rejected.
+        // `operationalError` travels in the same cluster payload as
+        // `operationalState`, so a controller or matter.js build that refuses the
+        // attribute would otherwise freeze the whole tile — Cleaning/Docked
+        // included — for as long as the setting stays on. One rejection is enough
+        // to drop the attribute for the rest of this run.
+        this.faultReportingRejected = false;
         this.returnToDockRetryPending = false;
         this.matterStateHeartbeatTimer = null;
         // Serializes every Matter publish so concurrent publishers (live messages,
@@ -359,7 +462,15 @@ class RoborockMatterVacuumAccessory {
             this.accessory.context = {};
         }
         this.accessory.context.duid = duid;
-        this.accessory.clusters = this.buildClusters();
+        // The registration snapshot is the payload Matter commissions the
+        // endpoint from, and 1.4.61 removed the plugin's `operationalError` write
+        // precisely because Apple Home reacted badly to it there. Keep the
+        // declaration byte-identical to a build without fault reporting and let
+        // the attribute arrive on the first runtime publish a few seconds later
+        // — matter.js supplies the mandatory NoError default in the meantime, so
+        // nothing is missing, and a robot that happens to be faulted at
+        // Homebridge start can no longer change what gets commissioned.
+        this.accessory.clusters = this.stripOperationalError(this.buildClusters());
         this.accessory.handlers = this.buildHandlers();
         this.accessory.getState = async (cluster, attribute) => {
             const clusterState = this.buildCluster(cluster);
@@ -383,7 +494,7 @@ class RoborockMatterVacuumAccessory {
         }
     }
     async updateMatterStateFromRoborock() {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c;
         if (!this.registered) {
             return;
         }
@@ -406,7 +517,15 @@ class RoborockMatterVacuumAccessory {
                 const opState = clusters.rvcOperationalState;
                 const runMode = clusters.rvcRunMode;
                 const cleanMode = clusters.rvcCleanMode;
-                this.platform.log.info(`Matter publish for ${(_b = (_a = this.accessory.context) === null || _a === void 0 ? void 0 : _a.duid) !== null && _b !== void 0 ? _b : this.accessory.UUID}: battery=${typeof halfPercent === "number" ? halfPercent / 2 + "%" : "n/a"}, operationalState=${(_c = opState === null || opState === void 0 ? void 0 : opState.operationalState) !== null && _c !== void 0 ? _c : "n/a"}, runMode=${(_d = runMode === null || runMode === void 0 ? void 0 : runMode.currentMode) !== null && _d !== void 0 ? _d : "n/a"}, cleanMode=${(_e = cleanMode === null || cleanMode === void 0 ? void 0 : cleanMode.currentMode) !== null && _e !== void 0 ? _e : "n/a"}.`);
+                // A fault only appears here when one is actually being published, so
+                // an unremarkable line stays unremarkable — but when a user reports
+                // "Apple Home shows nothing", this is what says whether the plugin
+                // sent anything to show.
+                const fault = opState === null || opState === void 0 ? void 0 : opState.operationalError;
+                const faultSummary = fault && fault.errorStateId
+                    ? `, fault=${fault.errorStateId}${fault.errorStateDetails ? ` (${fault.errorStateDetails})` : ""}`
+                    : "";
+                this.platform.log.info(`Matter publish for ${this.getVacuumName()}: battery=${typeof halfPercent === "number" ? halfPercent / 2 + "%" : "n/a"}, operationalState=${(_a = opState === null || opState === void 0 ? void 0 : opState.operationalState) !== null && _a !== void 0 ? _a : "n/a"}, runMode=${(_b = runMode === null || runMode === void 0 ? void 0 : runMode.currentMode) !== null && _b !== void 0 ? _b : "n/a"}, cleanMode=${(_c = cleanMode === null || cleanMode === void 0 ? void 0 : cleanMode.currentMode) !== null && _c !== void 0 ? _c : "n/a"}${faultSummary}.`);
             }
             this.ensureMatterStateHeartbeat();
         }
@@ -690,6 +809,14 @@ class RoborockMatterVacuumAccessory {
                     // Drop the record so the cluster is retried on the next snapshot
                     // even if its payload is unchanged.
                     this.lastPublishedClusterJson.delete(cluster);
+                    // Opt-in fault reporting must never cost the user their tile. If
+                    // the payload carried `operationalError` and the write was
+                    // refused for any reason other than an endpoint that is still
+                    // coming up, retry immediately without it and stop sending it.
+                    // The operational state itself then still lands.
+                    if (await this.retryWithoutOperationalError(matter, cluster, attributes, error)) {
+                        return;
+                    }
                     failures.push(error);
                     this.platform.log.debug(`Matter publish for cluster ${cluster} on ${this.accessory.UUID} failed: ${error instanceof Error ? error.message : String(error)}`);
                 }
@@ -722,6 +849,38 @@ class RoborockMatterVacuumAccessory {
             throw error;
         }
     }
+    /**
+     * Recovery for a rejected `operationalError` write.
+     *
+     * Returns true when the cluster was successfully re-published without the
+     * attribute, in which case the caller must treat the write as a success —
+     * the operational state landed, only the optional fault detail was dropped.
+     * Returns false for payloads that never carried the attribute, for an
+     * endpoint that is merely still initializing (that has its own retry, and
+     * disabling a feature over a transient startup race would be wrong), and
+     * when the retry fails too.
+     */
+    async retryWithoutOperationalError(matter, cluster, attributes, error) {
+        if (!("operationalError" in attributes) ||
+            this.isMatterInitializingError(error)) {
+            return false;
+        }
+        const { operationalError: _rejected, ...withoutError } = attributes;
+        try {
+            await matter.updateAccessoryState(this.accessory.UUID, cluster, withoutError);
+        }
+        catch (_a) {
+            // The write was failing for some other reason. Leave the feature alone
+            // and let the caller record a normal failure.
+            return false;
+        }
+        if (!this.faultReportingRejected) {
+            this.faultReportingRejected = true;
+            this.platform.log.warn(`Matter rejected the fault detail (operationalError) for ${this.getVacuumName()}, so fault reporting has been switched off for this session; the operational state itself is unaffected. Turn off "Report Faults in Apple Home" to silence this. Reason: ${this.getErrorMessage(error)}`);
+        }
+        this.lastPublishedClusterJson.set(cluster, JSON.stringify(withoutError));
+        return true;
+    }
     /**
      * Publish a full Roborock cluster snapshot, performing a one-time battery
      * resync per boot first. Matter controllers filter attribute reports by
@@ -869,6 +1028,19 @@ class RoborockMatterVacuumAccessory {
         }
         return this.applyOptimisticState(clusters);
     }
+    /**
+     * A copy of a cluster snapshot with the optional fault attribute removed,
+     * for the one payload where its presence is a commissioning risk rather
+     * than useful information.
+     */
+    stripOperationalError(clusters) {
+        const operationalState = clusters.rvcOperationalState;
+        if (!operationalState || !("operationalError" in operationalState)) {
+            return clusters;
+        }
+        const { operationalError: _omitted, ...rest } = operationalState;
+        return { ...clusters, rvcOperationalState: rest };
+    }
     buildCluster(cluster) {
         var _a;
         let clusterState;
@@ -1194,7 +1366,7 @@ class RoborockMatterVacuumAccessory {
     }
     buildOperationalStateCluster() {
         const operationalState = this.getOperationalState();
-        return {
+        const cluster = {
             // RVC Operational State requires PhaseList and CurrentPhase to be null.
             phaseList: null,
             currentPhase: null,
@@ -1204,6 +1376,20 @@ class RoborockMatterVacuumAccessory {
             operationalStateList: this.getOperationalStateList().map((operationalStateId) => ({ operationalStateId })),
             operationalState,
         };
+        if (this.isFaultReportingEnabled()) {
+            // Always write the attribute while the feature is on, never just when
+            // something is wrong: an error that is published but never cleared
+            // leaves the tile complaining about a tank the user refilled an hour
+            // ago. NO_ERROR is the "all clear".
+            const operationalError = this.buildOperationalError();
+            cluster.operationalError =
+                operationalError !== null && operationalError !== void 0 ? operationalError : (operationalState === RVC_OPERATIONAL_STATE.ERROR
+                    ? // The robot says it has halted but named no code. Saying
+                        // "error, but no error" is worse than a truthful vague answer.
+                        { errorStateId: RVC_ERROR_STATE.UNABLE_TO_COMPLETE_OPERATION }
+                    : { errorStateId: RVC_ERROR_STATE.NO_ERROR });
+        }
+        return cluster;
     }
     buildPowerSourceCluster(batteryValue, chargeStatusValue, stateValue) {
         const battery = batteryValue === undefined
@@ -1776,6 +1962,68 @@ class RoborockMatterVacuumAccessory {
     isChargingDockedStateEnabled() {
         return (this.platform.platformConfig.enableMatterChargingDockedStates === true);
     }
+    /**
+     * Opt-in fault reporting. Off by default: publishing `operationalError` is
+     * the one thing 1.4.61 removed for Apple Home commissioning safety, and a
+     * robot that reports ERROR may be refused a Start command by the
+     * controller — so a spurious fault would cost the user their tile. The
+     * write also self-disables at runtime if Matter rejects it
+     * (`faultReportingRejected`), which keeps a bad payload from taking the
+     * rest of the operational-state cluster down with it.
+     */
+    isFaultReportingEnabled() {
+        return (this.platform.platformConfig.enableMatterFaultReporting === true &&
+            !this.faultReportingRejected);
+    }
+    /**
+     * Map the robot's current condition onto a Matter ErrorStateStruct, or null
+     * when nothing is wrong.
+     *
+     * `errorStateLabel` is deliberately never set. The Matter spec only allows
+     * it for manufacturer-range IDs, and labels on standard IDs are exactly
+     * what wedged Apple Home at "Connecting" in 1.4.40 — `errorStateDetails` is
+     * the field that may carry free text alongside a standard ID.
+     */
+    buildOperationalError() {
+        var _a, _b, _c;
+        // The robot's own fault takes precedence over a dock consumable: if it is
+        // stuck under the sofa, that is what the user needs to be told.
+        const errorCode = this.getNumberStatus("error_code");
+        if (errorCode !== null && errorCode !== 0) {
+            return {
+                errorStateId: (_a = ROBOROCK_ERROR_TO_MATTER.get(errorCode)) !== null && _a !== void 0 ? _a : RVC_ERROR_STATE.UNABLE_TO_COMPLETE_OPERATION,
+                errorStateDetails: this.describeRoborockError(errorCode),
+            };
+        }
+        const dockErrorStatus = this.getNumberStatus("dock_error_status");
+        if (dockErrorStatus !== null && dockErrorStatus !== 0) {
+            const mapped = ROBOROCK_DOCK_ERROR_TO_MATTER.get(dockErrorStatus);
+            return {
+                errorStateId: (_b = mapped === null || mapped === void 0 ? void 0 : mapped.errorStateId) !== null && _b !== void 0 ? _b : RVC_ERROR_STATE.UNABLE_TO_COMPLETE_OPERATION,
+                errorStateDetails: (_c = mapped === null || mapped === void 0 ? void 0 : mapped.details) !== null && _c !== void 0 ? _c : `Dock error ${dockErrorStatus}`,
+            };
+        }
+        // Onboard tank ran dry mid-mop. This flag is set by the robot only when
+        // water is actually wanted, so it does not fire on a vacuum-only run.
+        if (this.getNumberStatus("water_shortage_status") === 1) {
+            return {
+                errorStateId: RVC_ERROR_STATE.WATER_TANK_EMPTY,
+                errorStateDetails: "Water tank empty",
+            };
+        }
+        // Deliberately NOT reported as faults: `water_box_status` and
+        // `water_box_carriage_status` being 0. A detached tank or mop pad is the
+        // normal, correct configuration for a vacuum-only run, so treating them
+        // as errors would put a permanent warning on every dry robot's tile.
+        return null;
+    }
+    describeRoborockError(errorCode) {
+        var _a, _b;
+        const description = (_b = (_a = this.api).getErrorCodeDescription) === null || _b === void 0 ? void 0 : _b.call(_a, errorCode);
+        return typeof description === "string" && description.length > 0
+            ? description
+            : `Roborock error ${errorCode}`;
+    }
     /**
      * Battery percentage at which a docked robot switches from Charging to
      * Docked on the Matter tile. Defaults to 100 (charging until full); users
@@ -1913,7 +2161,20 @@ class RoborockMatterVacuumAccessory {
         }
         switch (operationalState) {
             case RVC_OPERATIONAL_STATE.ERROR:
-                return RVC_OPERATIONAL_STATE.STOPPED;
+                // ERROR (3) is a member of even the basic advertised list, so
+                // publishing it was always legal — it was downgraded to STOPPED
+                // alongside the states that genuinely needed a gate, which is why a
+                // robot stuck under the sofa has always read as "Ready" in Apple
+                // Home. Report it for real once the user has opted in.
+                //
+                // Only Roborock states 9 (Charging Error) and 12 (In Error) reach
+                // here, i.e. the robot's own claim that it has halted. Dock
+                // consumables arrive through `dock_error_status` instead and never
+                // touch the state, so a full waste-water tank does not make a robot
+                // that can still vacuum look unstartable in Apple Home.
+                return this.isFaultReportingEnabled()
+                    ? RVC_OPERATIONAL_STATE.ERROR
+                    : RVC_OPERATIONAL_STATE.STOPPED;
             case RVC_OPERATIONAL_STATE.SEEKING_CHARGER:
                 return RVC_OPERATIONAL_STATE.STOPPED;
             case RVC_OPERATIONAL_STATE.EMPTYING_DUST_BIN: