feat!: complete full Zeo device support#871
Conversation
|
Hey @NOisi-x something about your changes seem to have broken tests. Tests are running indefinitely, can you take a look? |
This reverts commit 613db33.
…erministic results
Hi, @Lash-L ,I've updated the test files and all tests are now passing. Thanks！ CI Failure Analysis and Fix SummaryApologies for the broken CI — I'm a hobbyist with fairly limited programming experience and I overlooked the fact that the source changes would affect the existing test suite. Lesson learned for next time. Below is an analysis of what went wrong and what was changed to fix it. Root CausesThe CI test suite failed for three reasons:
Changes Made
|
allenporter
left a comment
allenporter
left a comment
There was a problem hiding this comment.
Fantastic contribution, thank you so much for the improvements here!
| done = 10 | ||
| aftercare = 12 | ||
| waiting_for_aftercare = 13 | ||
| updating = 11 |
There was a problem hiding this comment.
let's tag as a breaking change. i think it's that commits have feat!: ?
There was a problem hiding this comment.
I change the title. Is that right?
There was a problem hiding this comment.
I think so yeah.
For context: This is currently used by Home Assistant for example, so it can't be merged without changing the translation strings there. Another way to do it could be to leave the enum alone, add a comment on the enum, then later go add the translations in home assistant.
There was a problem hiding this comment.
The names smart_hosting / smart_hosting_waiting come from reverse-engineering the official Roborock app bundle. The previous names aftercare / waiting_for_aftercare were also from my PR — I translated them from the Chinese status labels shown in the app UI. I've reverted to the old names and added a comment noting the canonical app-bundle names.
| params = {protocol: value} | ||
| return await send_decoded_command(self._channel, params, value_encoder=lambda x: x) | ||
| params: dict[RoborockZeoProtocol, Any] = {protocol: value} | ||
| if protocol == RoborockZeoProtocol.START and value == 1: |
There was a problem hiding this comment.
This makes me think it may be time to define actual API methods for these specialized commands rather than a single generic query_values/set_values (e.g. a "start" and "stop" methods etc for the washing machine.
Do you expect there to be more specialized commands like this or is this the only one?
At a minimum: Split out the function that queries the current values to a separate method
There was a problem hiding this comment.
The query logic has been split into _get_current_params() as requested. Based on testing with physical Zeo devices, I believe START is the only command that requires parameter bundling.
START (200) will wake up the device. The Zeo firmware requires MODE and PROGRAM to be present in the same MQTT message as the start signal because the device needs to know what to do when it wakes up. If the device is already manually powered on (via the physical power button), even START(200) can be sent as a simple set_value with QoS 0, and commands like PAUSE (201) and SHUTDOWN (202) work without any bundling at all.
Through testing with the actual Roborock app, I confirmed the DPs fall into two distinct categories:
- Immediate DPs (sound, child lock, UV light, etc) — set independently via
set_valueand take effect immediately. - Deferred DPs (mode, program, temperature, rinse, spin, drying, etc) — the app collects user selections locally and only sends them bundled with the START command. The device internally caches these values — either factory defaults or the user's last selection depending on whether the device model supports parameter persistence — which is why
_get_current_params()can query them at start time.
The current query+bundle approach in _get_current_params() is functional and has been verified on physical hardware. However, in the broader HomeAssistant ecosystem similar devices (thermostats, climate controls) use a coordinator caching pattern: entity state changes update a local value immediately but don't push to the device; all accumulated changes are sent as a single payload when the user triggers an action (e.g. "set temperature"). Implementing this pattern for Zeo devices would require changes to the HA integration layer and is probably best left for a separate PR. I would greatly appreciate it if someone could help make thses improvements.
There was a problem hiding this comment.
This is helpful to understand the end state you recommend.
We can do a lot of that in this library without large changes to Home Assistant. The way we do this in other device types is through traits that (a) define typed interfaces for data (b) handle commands related to that data/state and (c) hold on to the latest state with functions for refreshing. So we won't solve all of that now in this PR, but here is what we can do:
- Define a dataclass with the arguments to start that are required (mode, program, etc)
- Define a method (can be private) that can query and return those
- Define a separate method
startthat users will call that handles the now logic for querying and calling the start command
We can work on the rest in the future.
There was a problem hiding this comment.
Thanks for the explanation and guidance — that was really helpful for understanding this project. I've updated the code per your suggestions.
| params[dp] = fallback | ||
| except RoborockException: | ||
| _LOGGER.warning( | ||
| "Failed to query device state before start, using defaults", |
There was a problem hiding this comment.
i'm not sure this fallback is a great idea e.g. if the user is expecting some values to be preserved then silently not preserving them worries me e.g. as a user I would be concerned if my washing machine changed my water temp due to flaky wifi and i might prefer it just fail rather than shrinking cotton clothes or whatever.
Can we either remove or provide some rationale here why this is expected or ok?
There was a problem hiding this comment.
Your concern was completely valid — I've removed the fallback.
| ) -> None: | ||
| """Test the device manager end to end flow with an A01 device.""" | ||
| # Use a fixed timestamp so the MQTT payload snapshot is deterministic. | ||
| monkeypatch.setattr("roborock.protocols.a01_protocol.time.time", lambda: 1755750947.0) |
There was a problem hiding this comment.
We have deterministic_message_fixtures
There was a problem hiding this comment.
I move A01 timestamp patch into deterministic_message_fixtures.
NOisi-x
changed the title
|
|
||
| Determines the delivery guarantee for published messages: | ||
|
|
||
| - AT_MOST_ONCE (0): Fire-and-forget. No acknowledgment required. |
There was a problem hiding this comment.
You can move these to the actual enums like:
AT_MOST_ONCE = 0
"""Fire-and-forget. No acknowledgment required.""""
| params = {protocol: value} | ||
| return await send_decoded_command(self._channel, params, value_encoder=lambda x: x) | ||
| params: dict[RoborockZeoProtocol, Any] = {protocol: value} | ||
| if protocol == RoborockZeoProtocol.START and value == 1: |
There was a problem hiding this comment.
This is helpful to understand the end state you recommend.
We can do a lot of that in this library without large changes to Home Assistant. The way we do this in other device types is through traits that (a) define typed interfaces for data (b) handle commands related to that data/state and (c) hold on to the latest state with functions for refreshing. So we won't solve all of that now in this PR, but here is what we can do:
- Define a dataclass with the arguments to start that are required (mode, program, etc)
- Define a method (can be private) that can query and return those
- Define a separate method
startthat users will call that handles the now logic for querying and calling the start command
We can work on the rest in the future.
| done = 10 | ||
| aftercare = 12 | ||
| waiting_for_aftercare = 13 | ||
| updating = 11 |
There was a problem hiding this comment.
I think so yeah.
For context: This is currently used by Home Assistant for example, so it can't be merged without changing the translation strings there. Another way to do it could be to leave the enum alone, add a comment on the enum, then later go add the translations in home assistant.
…antee descriptions
3 participants
Summary
This PR completes Zeo (washing machine) device support in
python-roborock.The library already had foundational A01 protocol support for Zeo devices, but several critical gaps prevented practical use: the start command didn't work, roughly half of the DP IDs were undefined, several device states and enum classes were missing, and most data points had no value converters. This PR closes those gaps, bringing the DP and enum definitions in line with the Roborock Washer app protocol.
With these changes, Zeo devices support the full range of operations defined by the protocol: start/stop/pause/shutdown, mode and program selection, temperature, rinse, spin, drying control, child lock, auto detergent/softener, UV sterilization, soak, silent mode, dry care, steam, ion deodorization, wash-dry linkage, and more.
Motivation
The library's existing Zeo
set_value(START, 1)did not actually start the device. Through protocol analysis and comparison with the Roborock Washer HomeAssistant integration, three root causes were identified:"t"(Unix timestamp) field.Beyond the start command,
RoborockZeoProtocolcovered only 31 of 67 known DP IDs,zeo_code_mappings.pywas missing 4 enum classes and several enum values, andZEO_PROTOCOL_ENTRIESprovided converters for only 16 of the 52 user-facing DPs — meaningquery_values()silently returnedNonefor most data points.Changes
1. MQTT QoS —
roborock/mqtt/roborock_session.pyChanged
client.publish()to useqos=1(at-least-once delivery).2. A01 payload timestamp —
roborock/protocols/a01_protocol.pyAdded
"t": int(time.time())to the JSON payload structure inencode_mqtt_payload().3. Combined start command —
roborock/devices/traits/a01/__init__.pyZeoApi.set_value(START, 1)now:{START: 1}into a single MQTT messageMODE=1, PROGRAM=1if the query fails4. Extended DP ID enum —
roborock/roborock_message.pyRoborockZeoProtocolexpanded from 31 to 67 entries, now covering all 52 user-facing DPs (200-266) plus meta DPs. Newly added: dirt detection (215-216), UV light (228), soak (233), total time (234), smart hosting (235-238), silent mode (240-242), dry care mode (244), wash-dry linkage (255), drying method (256), steam volume (257), ion deodorization (258), dryer start error (265), and more.5. Enum updates —
roborock/data/zeo/zeo_code_mappings.pyZeoMode: addedtreatment = 4ZeoState: expanded from 13 to 20 statesZeoSoak: addedvery_max = 5ZeoDryingMethod,ZeoSteamVolume,ZeoDryAndCare,ZeoDryerStartError6. Value converters —
roborock/devices/traits/a01/__init__.pyZEO_PROTOCOL_ENTRIESexpanded from 16 to 57 entries, providing typed converters for all user-facing DPs (200-266).Backward Compatibility
All changes are additive or transparent:
ZeoApi.query_values()andZeoApi.set_value()signatures unchangedset_valuecalls unaffectedKnown Limitation
sent_decoded_commanduses a strict "all requested DPs must respond" completion condition. Since A01 devices do not expose a capability probing mechanism, there is currently no clean way to determine which optional DPs (e.g., SOAK, STEAM_VOLUME) a given device supports before querying them.As a temporary workaround, the start command queries and bundles only the following 6 core DPs, which has been verified to successfully start devices on physical Zeo hardware:
These are bundled with
{START: 1}and sent as a single MQTT message. The device applies its internally-stored values for any parameters not explicitly included.A better long-term solution for dynamically detecting device capabilities is welcome — contributions or ideas in this area are appreciated.
Testing
set_value(START, 1)verified working on physical Zeo One and Zeo M1S devicesset_valuefor non-START DPs (mode, program, temperature, etc.) continues to work as beforeAcknowledgments
This PR draws heavily on the excellent reverse-engineering work done in ndwzy/roborock_washer_ha. The A01 protocol structure, DP definitions, enum mappings, and the combined start command behavior were all cross-referenced against that project's implementation. The DP ID list (200-266), state enum values, and device error codes were verified against the Roborock app bundle extracted and analyzed by that project.
Closes #833