homebridge-roborock-matter 3.34.0 → 3.35.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 3.35.0
+
+**3.34.0 broke the half of the play button it was meant to leave alone, and an empty water tank could hide a running clean in Apple Home. Both are fixed, with 8 more found by reading this plugin against matter.js 0.17.9 and python-roborock 7.12.0 instead of against its own comments.**
+
+### My regression first: resume on a paused full clean
+
+3.34.0 sent `resume_segment_clean` whenever `in_cleaning` was non-zero, on the assumption that 0 meant whole-home and anything else meant rooms. Roborock's numbering (python-roborock `RoborockInCleaning`) is 0 complete, 1 whole-home not complete, 2 zone not complete, 3 room not complete. A paused full clean reads 1, so the case [@CooperCGN](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/28) had confirmed working got the room verb. Each value now gets its own: 3 → `resume_segment_clean`, 2 → `resume_zoned_clean`, 0/1 → `app_start`. That is the same choice Home Assistant makes. B01 is unchanged.
+
+### An empty tank no longer hides a running clean (#35)
+
+[@pponce](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/35) decoded an outgoing Matter report: the plugin logged `operationalState=1 … fault=68`, and the wire carried `operationalState=3`. In matter.js 0.17.9, writing any `operationalError` other than NoError sets the state to Error, and clearing it does not give the old state back. "Running with a warning" does not exist on the version Homebridge ships. So Apple Home showed "Refill the water tank" while his robot mopped 2 rooms.
+
+- A fault is now only published for a robot at rest (Stopped, Charging, Docked) or one really in Error. A robot that is cleaning, paused, driving home or busy at the dock gets NoError, and the publish line says `fault=68 held back while the robot works`.
+- That check is made after a Matter command's optimistic state as well, and on the robot's own state as well as the one Apple Home is sent. Mid-run states this plugin has no name for (33 attaching the mop, 6301-6310 the mopping states and a few more) count as working, not at rest: DSimeone's a144 reports 33 in the middle of a room clean.
+- When a fault clears, the robot's real state is written back in the same publish. Before, the tile stayed on Error until the robot changed state or the 10th heartbeat.
+- While a fault stands, the state is never re-written. 3.31.0's every-10th-heartbeat resync was wiping and re-raising it: one "Refill the water tank" notification about every 10 minutes for as long as the tank was empty. The resync now re-asserts the fault itself, which is a no-op when it landed.
+
+The comments that said the state is "deliberately NOT forced to Error" were wrong on 0.17.9 and are corrected. The tests now run against a replay of the real 0.17.9 reactors (`test-support/matter-0.17.9-store.js`). The old stand-in modelled the wipe but not the forcing, which is how 4 tests came to assert stores 0.17.9 can never hold.
+
+### The dock's own tank word, and 2 new sensors (#22, #26)
+
+[@DSimeone1989](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/22)'s Saros 10R let the water-empty automation fire in 1 run and not the other, and the cloud settings had nothing to do with it. `dock_error_status` holds 1 code at a time. In run 1 both tanks needed attention and the code was 39 (dirty tank full), so the empty clean tank never showed. The dock reports each tank separately in `dss`, which this plugin had never read.
+
+- Water Tank Empty now reads the clean-water field of `dss` where the dock sends one. When it says the tank is fine, a lingering `water_shortage_status` no longer overrules it, which may be what [@n0rt0nthec4t](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/26) is seeing after a refill. A 38 still wins, and docks without `dss` work exactly as before.
+- 2 new optional sensors: **Dirty Water Tank Full** and **Cleaning Fluid Empty**. The second is the detergent warning DSimeone asked for; only docks with automatic dosing report it.
+- `dss` is ignored on plain chargers and auto-empty-only docks, which have no tanks for it to describe.
+- The robot's own `error_code` 38 and 39 ("check the clean/dirty water tank") are known now, so nobody is asked to report them.
+- Diagnostic reports keep `dss`, `rss` and `wash_status`. All 3 were cut at the key limit, including in #26.
+
+### Q10 state was read with the Q7 table (#33)
+
+[@yquirion](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/33)'s Q10 S5 flapped between Stopped and Docked. Home data was translated with the Q7 work-status table for every B01 robot, while a pushed datapoint was read as v1, and the 2 disagree: a charging Q10 (8) became Stopped. The Q10 numbers its states the v1 way plus a few of its own (python-roborock `YXDeviceState`), so it now gets its own table, on both paths. The Q7 L5 half of #33 ("Updating…") is not explained by anything here yet.
+
+### The give-up register
+
+- A robot that answers with an error has answered. A refusal did not reset the count, so 5 silences, 1 refusal and 1 silence gave the method up.
+- One silent `get_map_v1` counted twice: once in the message layer, once in the live-room fetch. Live-room tracking was paused after 3 silent fetches instead of 6. CooperCGN's log shows both lines in the same second.
+- Shutting Homebridge down no longer counts as an answer.
+
+### A reply that comes too late is called late
+
+A reply that arrives after its 10-second timeout was dropped without a word on the local socket, and a late map frame was counted as "discarded by the plugin — a bug here". The give-up line also told #24 and #28 that `get_server_timer` replies were "not arriving at all", on a counter that only ever looks at map frames. Timed-out requests are now remembered for 10 minutes. A reply that matches one is logged and counted, and the give-up line says "did arrive, but only after the plugin had stopped waiting" when that is what happened. The map-frame claim is made only about `get_map_v1`.
+
+### Service Area writes matter.js refused
+
+matter.js refuses a whole Service Area write when 1 progress entry names a room that no longer exists, and refuses to register the endpoint when 2 rooms or 2 maps share a name. Progress is persisted across restarts, so a room merged away in the Roborock app froze the cluster until the next run. Progress and current area are now filtered against the published rooms, and a second "Bedroom" is "Bedroom 2".
+
+### Left as it is, on purpose
+
+3.33.0 and 3.34.0 said the room poll "normally" reads the floor from the status the plugin already polled. That cache is never written under Homebridge, so every room poll has asked `get_status` after `get_room_mapping` all along. I made the cache real during this release, and review showed why it should stay empty: a status up to 1 minute old files a map switched in the Roborock app under the wrong map, in the room cache that is persisted. 1 extra request every few minutes is cheaper. The comment now says so.
+
+### Tests
+
+2,131 tests, 65 more than 3.34.0. How many of the new ones fail on the 3.34.0 sources, measured file by file: 5 of 5 for the #35 fault, 3 of 3 for the gate after review, 11 of 12 for the Q10 table, 9 of 13 for the dock tanks, 2 of 7 for resume, 2 of 2 for the register, 5 of 10 for late replies, 4 of 4 for Service Area.
+
 ## 3.34.0
 
 **3.33.0 fixed the room poll for the robots that did not need it. Both reporters ran it and measured the same failure again.**

package/README.md

@@ -37,25 +37,25 @@ 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. 2066 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. 2131 automated tests, zero known vulnerabilities, no analytics, and a startup designed to never crash your Homebridge — even when your Wi-Fi or the Roborock cloud has a bad day.
 
 ## Features
 
-|                                       |                                                                                                                                                                                                            |
-| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🤖 **Full control from Apple Home**   | Start, stop, pause and send the robot home to its dock — from the Home app or Siri                                                                                                                         |
-| 🕹️ **Switches for automations**       | Optional per-robot Start Cleaning, Return to Dock, Pause and Find switches — Apple Home does not offer a dock action for a Matter vacuum ([details](#automations-in-apple-home))                           |
-| 🎯 **Sensors as automation triggers** | Optional per-robot Docked, Cleaning and Water Tank Empty contact sensors — a Matter vacuum is not offered as an automation trigger at all, and a contact sensor is ([details](#automations-in-apple-home)) |
-| 🗓️ **Roborock schedules as switches** | Optional per-robot switches that turn the schedules you made in the Roborock app on and off — device-side ones and the timers on your Routines ([details](#automations-in-apple-home))                     |
-| ▶️ **Routines as switches**           | Optional per-robot momentary switches that run a Routine from the Roborock app, so Siri and Home automations can start one by name ([details](#automations-in-apple-home))                                 |
-| 🚪 **Clean specific rooms**           | Pick rooms right in Apple Home, with the names you gave them in the Roborock app — multi-floor homes included                                                                                              |
-| 📍 **Live room tracking**             | See which room the robot is cleaning right now, updated as it moves ([details](#live-room-tracking))                                                                                                       |
-| 📊 **Honest cleaning progress**       | Each room goes pending → cleaning → done — and a room only counts as done when the robot was actually there                                                                                                |
-| 🌀 **Cleaning & suction modes**       | Vacuum / Mop / Vacuum + Mop on models that support it — plus optional Quiet / Balanced / Turbo / Max suction levels (Max+ on Q7)                                                                           |
-| 🔋 **Battery & charging**             | Battery level and charging state on the accessory ([one Apple-side caveat](#battery-percentage-in-apple-home))                                                                                             |
-| 🧠 **New models just work**           | Brand-new Roborock models get sensible defaults automatically, and the plugin adapts to what each robot actually supports                                                                                  |
-| 🩺 **Built-in diagnostics**           | Connection status, a one-click connection test, and a ready-to-share report if you ever need help                                                                                                          |
-| 🔐 **Easy, safe login**               | Sign in with your Roborock account right in the settings — two-factor supported, session stored encrypted                                                                                                  |
+|                                       |                                                                                                                                                                                                                                                         |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🤖 **Full control from Apple Home**   | Start, stop, pause and send the robot home to its dock — from the Home app or Siri                                                                                                                                                                      |
+| 🕹️ **Switches for automations**       | Optional per-robot Start Cleaning, Return to Dock, Pause and Find switches — Apple Home does not offer a dock action for a Matter vacuum ([details](#automations-in-apple-home))                                                                        |
+| 🎯 **Sensors as automation triggers** | Optional per-robot Docked, Cleaning, Water Tank Empty, Dirty Water Tank Full and Cleaning Fluid Empty contact sensors — a Matter vacuum is not offered as an automation trigger at all, and a contact sensor is ([details](#automations-in-apple-home)) |
+| 🗓️ **Roborock schedules as switches** | Optional per-robot switches that turn the schedules you made in the Roborock app on and off — device-side ones and the timers on your Routines ([details](#automations-in-apple-home))                                                                  |
+| ▶️ **Routines as switches**           | Optional per-robot momentary switches that run a Routine from the Roborock app, so Siri and Home automations can start one by name ([details](#automations-in-apple-home))                                                                              |
+| 🚪 **Clean specific rooms**           | Pick rooms right in Apple Home, with the names you gave them in the Roborock app — multi-floor homes included                                                                                                                                           |
+| 📍 **Live room tracking**             | See which room the robot is cleaning right now, updated as it moves ([details](#live-room-tracking))                                                                                                                                                    |
+| 📊 **Honest cleaning progress**       | Each room goes pending → cleaning → done — and a room only counts as done when the robot was actually there                                                                                                                                             |
+| 🌀 **Cleaning & suction modes**       | Vacuum / Mop / Vacuum + Mop on models that support it — plus optional Quiet / Balanced / Turbo / Max suction levels (Max+ on Q7)                                                                                                                        |
+| 🔋 **Battery & charging**             | Battery level and charging state on the accessory ([one Apple-side caveat](#battery-percentage-in-apple-home))                                                                                                                                          |
+| 🧠 **New models just work**           | Brand-new Roborock models get sensible defaults automatically, and the plugin adapts to what each robot actually supports                                                                                                                               |
+| 🩺 **Built-in diagnostics**           | Connection status, a one-click connection test, and a ready-to-share report if you ever need help                                                                                                                                                       |
+| 🔐 **Easy, safe login**               | Sign in with your Roborock account right in the settings — two-factor supported, session stored encrypted                                                                                                                                               |
 
 ## Quick start
 
@@ -136,7 +136,7 @@ Everything is configurable from the Homebridge UI. The essentials:
 | `enableHomeKitActionSwitches`           | `false`      | Adds a plain Home app switch per robot for Start Cleaning / Return to Dock / Empty Bin / Pause / Find, so automations can reach commands Apple does not offer for a Matter vacuum ([details](#automations-in-apple-home))               |
 | `homeKitActionSwitches`                 | `["dock"]`   | Which of those switches to publish: `clean`, `dock`, `empty`, `pause`, `locate`. `empty` is published only for compatible auto-empty docks and runs only while the robot is docked.                                                     |
 | `enableHomeKitStateSensors`             | `false`      | Adds a read-only Home app contact sensor per robot mirroring its state, so an automation can be _triggered_ by the robot — a Matter vacuum is not offered as a trigger, and a contact sensor is ([details](#automations-in-apple-home)) |
-| `homeKitStateSensors`                   | `["docked"]` | Which of those sensors to publish: `docked`, `cleaning`, `waterTankEmpty`                                                                                                                                                               |
+| `homeKitStateSensors`                   | `["docked"]` | Which of those sensors to publish: `docked`, `cleaning`, `waterTankEmpty`, `dirtyWaterTankFull`, `cleaningFluidEmpty`                                                                                                                   |
 | `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)                                                                                                                                                           |
 
@@ -191,7 +191,7 @@ What Apple offers _inside_ Home automations is a separate question, and it is Ap
 
 A press takes exactly the same route as a press on the tile — the same acknowledgement wait, the same timing line in the log, the same retry if Roborock times out while the robot is still cleaning — and it moves the tile with it, so a robot sent home by a schedule does not sit there reading Ready. The log line names which surface asked, so `Sending Vicky back to dock from the Home switch.` and `Sending Vicky back to dock from Matter.` are told apart when a schedule misfires.
 
-**Optional Home app sensors close the trigger gap.** A Matter vacuum is not offered as an automation trigger, but a HomeKit contact sensor is — so turn on **Add Home app sensors so automations can trigger on the robot** and each robot gets one read-only contact sensor per state you pick: `Vicky Docked`, `Vicky Cleaning` and `Vicky Water Tank Empty`. That makes "when the robot leaves its dock, do X" expressible. Each one reads **Closed** while the state it is named after is true and **Open** when it is not: `Vicky Docked` is Closed in the dock and Open once the robot drives off. Nothing is ever sent to the robot — these only report.
+**Optional Home app sensors close the trigger gap.** A Matter vacuum is not offered as an automation trigger, but a HomeKit contact sensor is — so turn on **Add Home app sensors so automations can trigger on the robot** and each robot gets one read-only contact sensor per state you pick: `Vicky Docked`, `Vicky Cleaning`, `Vicky Water Tank Empty`, `Vicky Dirty Water Tank Full` and `Vicky Cleaning Fluid Empty`. That makes "when the robot leaves its dock, do X" expressible. Each one reads **Closed** while the state it is named after is true and **Open** when it is not: `Vicky Docked` is Closed in the dock and Open once the robot drives off. Nothing is ever sent to the robot — these only report.
 
 Docked and Cleaning are more useful together than either alone, and that is the automation they were asked for in [#3](https://github.com/mathiashornbek/homebridge-roborock-matter/issues/3): **not docked and not cleaning means the robot is probably stuck somewhere.** A robot that has genuinely halted reads Open on both.
 
@@ -214,7 +214,7 @@ Four details that are deliberate:
 - **A dock chore is not a cleaning run.** Emptying the dust bin, washing the mop and updating maps leave `Cleaning` exactly where it was — Open if the robot was resting, Closed if it was interrupted mid-run. This is the same rule the Home tile follows since 3.6.2, and the sensor is checked against the tile rather than against a second opinion, so the two can never disagree.
 - **`Docked` does not depend on any other setting.** It reads the robot's own charging state, not the state Apple Home was told, so it works the same whether or not **Dock & Returning status** and **Charging/Docked status** are switched on. `Cleaning` mirrors the tile, so with **Dock & Returning status** off it goes Open when the robot starts driving home rather than when it arrives — that is what the tile says too.
 - **Nothing is claimed before the robot has reported in.** For the first seconds after a Homebridge restart some robots report no usable state at all, and a sensor that guessed would move once the real value arrived — firing every automation watching for it, on every restart. The sensors hold their last known reading instead and only move on real data.
-- **A first-run sensor rests where it will not have to move from.** With no cached reading to hold — a fresh install, or a sensor just switched on — each one answers with its own resting state rather than a shared default: `Docked` closed, `Cleaning` and `Water Tank Empty` open. Until 3.10.0 all three would have answered Closed, so a fresh `Cleaning` sensor announced a finished cleaning the moment the robot first said it was idle.
+- **A first-run sensor rests where it will not have to move from.** With no cached reading to hold — a fresh install, or a sensor just switched on — each one answers with its own resting state rather than a shared default: `Docked` closed, the other four open. Until 3.10.0 all three would have answered Closed, so a fresh `Cleaning` sensor announced a finished cleaning the moment the robot first said it was idle.
 
 They are off by default, because switching them on adds accessories to your Home app.
 
@@ -264,7 +264,7 @@ The complete path — robot → plugin → Homebridge → matter.js store — wa
 
 ## Contributing
 
-Model reports, diagnostics exports, and pull requests are very welcome. The codebase ships with 2066 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 2131 tests (protocol fixtures verified against the [python-roborock](https://github.com/Python-roborock/python-roborock) reference), strict TypeScript checking, and CI across Node 22/24 × Homebridge 1.11/2.x — `npm test` before you push and you're set.
 
 ## Support the project
 

package/config.schema.json

@@ -196,13 +196,19 @@
       },
       "homeKitStateSensors": {
         "title": "Which Sensors to Add",
-        "description": "Which states get a sensor. Docked is the one to start with: it is the state most automations read, and \"not docked\" is its own answer. Cleaning is the pair for it — not docked AND not cleaning means the robot is probably stuck somewhere, which is the automation this was asked for. Water Tank Empty is the one Apple Home cannot show any other way: Matter's vacuum device type has no water-tank attribute, so a sensor is the only route to a notification. Only used when the setting above is on.",
+        "description": "Which states get a sensor. Docked is the one to start with: it is the state most automations read, and \"not docked\" is its own answer. Cleaning is the pair for it — not docked AND not cleaning means the robot is probably stuck somewhere, which is the automation this was asked for. Water Tank Empty is the one Apple Home cannot show any other way: Matter's vacuum device type has no water-tank attribute, so a sensor is the only route to a notification. Dirty Water Tank Full and Cleaning Fluid Empty are the same idea for the dock's other two tanks, read from the dock's own status word; a dock that does not report them leaves the sensor at Open. Only used when the setting above is on.",
         "type": "array",
         "uniqueItems": true,
         "default": ["docked"],
         "items": {
           "type": "string",
-          "enum": ["docked", "cleaning", "waterTankEmpty"],
+          "enum": [
+            "docked",
+            "cleaning",
+            "waterTankEmpty",
+            "dirtyWaterTankFull",
+            "cleaningFluidEmpty"
+          ],
           "oneOf": [
             {
               "title": "Docked (Closed while the robot is in its dock)",
@@ -215,6 +221,14 @@
             {
               "title": "Water Tank Empty (Closed while the robot reports no clean water)",
               "enum": ["waterTankEmpty"]
+            },
+            {
+              "title": "Dirty Water Tank Full (Closed while the dock reports its dirty-water tank full)",
+              "enum": ["dirtyWaterTankFull"]
+            },
+            {
+              "title": "Cleaning Fluid Empty (Closed while the dock reports its cleaning-fluid cartridge empty)",
+              "enum": ["cleaningFluidEmpty"]
             }
           ]
         }