Repository navigation
Conversation
Add MqttQos enum (AT_MOST_ONCE=0, AT_LEAST_ONCE=1, EXACTLY_ONCE=2) and thread a qos parameter through the publish chain (MqttSession -> MqttChannel -> send_decoded_command). All existing callers keep default AT_MOST_ONCE (backward compatible). Also add a unix timestamp field to A01 encode_mqtt_payload, required by Zeo/Dyad devices for command acceptance.
… all 56 devices covered Expand RoborockZeoProtocol from 31 to 67 DP entries, ordered by numeric ID. Add all missing enum classes (ZeoFeatureBits, ZeoDryingMethod, ZeoSteamVolume, ZeoDryAndCare, ZeoDryerStartError) and extend existing enums to cover every state/value found in the official app plugin bundle. Add ZeoStartParams, ZeoCustomMode, and ZeoDryerCustomMode data containers inheriting from RoborockBase, placed in zeo_containers.py per reviewer guidance.
Update ZeoStartParams, ZeoCustomMode, and ZeoDryerCustomMode to use typed enum fields (ZeoMode, ZeoProgram, ZeoTemperature, etc.) instead of raw int, aligning with the V1 container pattern in v1_containers.py. Rename shorthand fields (rinse_times→rinse, spin_level→spin) for consistency across all three classes. Unify drying-mode field naming.
…overy Subscribes to the device DPS MQTT topic after connection. Incoming RPC_RESPONSE messages are decoded and merged into _dps_cache with incremental updates. _discover_features() queries FEATURE_BITS (DP 237) to wake the device and cache capabilities — equivalent to V1's discover_features(). Also fixes TraitUpdateListener init in ZeoApi and a01_properties routing in connect().
cbb254f to
c57f0b7
Compare
allenporter
left a comment
There was a problem hiding this comment.
Great work articulating the differences between the washer and dryer. Given the differences (e.g. params, modes, etc). This seems like a perfect use for separate traits. It seems like a "washer trait" and "dryer trait" now make sense to introduce.
Can you review the existing trait pattern for prior art?
|
@allenporter The difference between washer and dryer in V1's Given the minimal difference, is the current single-trait approach acceptable, or would you still prefer separate classes? |
|
II'm thinking of this more like: What do solid washer and dryer APIs look like? My assumption is we'll want APIs that return the current settings to the caller in these new modes -- not just start params but also querying the values and/or holding on to the current state. That is, if we're moving to traits there are more benefit is in terms of using these new types we have defined. The thing to prioritize is what the API looks like. We can avoid code duplicating by sharing code where it makes sense. (If its really all duplicated, then there are more solutions than just having all the code in the same file. (e.g. sharing code between separate files is possible) |
except Exception → except RoborockException (aligns with Bundle's silent fallback to 0) try/except only wraps decode_rpc_response — cache updates and notify must propagate
437ec29 to
1fcacf4
Compare
|
@allenporter I agree with the direction — separate washer/dryer traits with type-safe APIs returning our enum types is the right end state. The individual DP getters/setters (set_program(ZeoTemperature), get_mode() → ZeoMode, etc.) are where the washer/dryer API divergence really shows up, and that's exactly where splitting makes sense. However, those methods are out of scope for this PR. Right now the trait only does start_program (bundled command), pause, resume, shutdown — all of which are identical for washers and dryers. Adding typed per-DP methods would roughly double the size of this PR, and I have limited time for this project in the near future. I'd prefer to land this as-is (single trait, scope limited to composite commands + feature discovery) and handle the trait split together with the typed getter/setter work in a follow-up PR. Would that be acceptable? |
1fcacf4 to
103266a
Compare
…e's forceLoad() Sends ID_QUERY with 28 base DPs (including FEATURE_BITS) in a single round-trip after MQTT subscribe. This triggers a complete state dump from the device 鈥?matching Bundle's startup flow exactly. For devices known to lack FEATURE_BITS (a63, a90), the DP is excluded from the query list.
Address reviewer feedback: integrate ZeoApi.close() into RoborockDevice.close() and implement the second-stage feature DP load matching Bundle's loadFeatureDps(). The first force-load now also includes smart-hosting DPs (235/236/238), and a follow-up query fetches feature-gated DPs (silent mode, dry care, smile light, dirt detection, wash/dry linkage, etc.) plus UV light gated by a series whitelist. Feature-load failures are non-fatal.
…pplied start params
103266a to
7716150
Compare
|
@allenporter Now that I have some time to continue diving into this project, I've refactored this PR. Please check out my updated PR description and review it. Thanks a lot. |
2cba1cf to
9ea7225
Compare
_settings/_status are lazily constructed; _update_settings_from_dps only routed pushes into a trait after it was built. State pushed before the first access landed in _dps_cache but was never applied, so the first access returned a fresh empty trait and silently lost all prior state. Treat _dps_cache as the single source of truth: on first construction, each trait backfills itself via update_from_dps(self._dps_cache). update_from_dps ignores undeclared DPs, so feeding the whole cache is safe.
…n on start methods
@allenporter Please don't be put off by the line count — the bulk of the diff is three new I wrote them for completeness of the semantic API surface. If you feel some of On splitting: I'd still prefer to land this as one PR, because the existing Finally — thank you for the careful review. Your comments have been really |
|
@NOisi-x can you fix the merge conflicts and then mark as ready for review? |
Resolve conflicts in the A01 traits after upstream Python-roborock#941 (track A01 device state from push updates) and Python-roborock#946 (skip DP 225 on Zeo H1): - Adopt the upstream A01Api base class and its �alues state tracking. - Build the typed Zeo traits (command/settings/status) eagerly instead of lazily, and drop _dps_cache plus the first-access backfill entirely. - Add an A01Api._merge_datapoints() hook so raw datapoints are projected into the traits and merged into �alues from a single path: unsolicited pushes, the initial cloud status snapshot, and (when not subscribed) query responses. - Keep the upstream supports() helper, and derive eatures from _feature_bits as before. - Keep upstream's supports_default_setting() (H1 lacks DP 225).
decode_rpc_response() keys the response by integer DP code, while the send_decoded_command() overload reports RoborockZeoProtocol keys. mypy flagged the mismatch when the response was passed to _update_traits(), which expects dict[int, Any]. Normalize the keys explicitly so the runtime representation and the declared type agree.
Lash-L
left a comment
There was a problem hiding this comment.
Few more comments -
I think most of the setters and commands should return None
The settings setters are fire-and-forget — send_decoded_command() only publishes the payload — so returning the internal DPS frame implies a confirmation the device never sends. Drop the return value from the 34 public setters (set_*/save_*/load_*) and the _send/_set_enum/_set_bool helpers; they now return None. start_with/preset_with/start_with_custom_mode keep returning the frame: they take an arbitrary parameter combination and the frame also carries DPs the method adds on its own (auto-dosing 211/212, feature-gated 255/258), which the caller cannot derive from the arguments. Addresses the review feedback on Python-roborock#897.
The settings setters are fire-and-forget — send_decoded_command() only publishes the payload — so returning the internal DPS frame implies a confirmation the device never sends. Drop the return value from the 34 public setters (set_*/save_*/load_*) and the _send/_set_enum/_set_bool helpers; they now return None. start_with/preset_with/start_with_custom_mode keep returning the frame: they take an arbitrary parameter combination and the frame also carries DPs the method adds on its own (auto-dosing 211/212, feature-gated 255/258), which the caller cannot derive from the arguments.
1beefb3 to
cd2d425
Compare
Comments should describe the code's behaviour, not where it was observed. Reword the ZeoStartParams docstring, the feature-gated DP mapping section header and the build_param_dps comment to drop the "the Bundle" wording.
build_param_dps() dropped any optional enum parameter whose value was 0, so real levels such as ZeoSoak.normal (0), ZeoRinse.none (0) and ZeoSteamVolume.none (0) were silently omitted from the START frame. Send every parameter that is set; None still means "not set" and is omitted. total_time (DP 234) keeps its > 0 gate as it doubles as the washer/dryer branch selector.
ZeoStatusTrait.update_from_dps() parsed the JSON meta fields (product_info, washing_log) by writing the parsed objects back into the dictionary it was handed, so a caller that still held that dictionary saw it change underneath. Parse into a local copy and give that to the converter instead; the argument is now read-only. The resulting field values are unchanged.
Done. The 34 public setters plus the three shared helpers ( I kept the frame as the return value of |
I think let's not return dict[RoborockZeoProtocol, Any]. I understand what you are saying, but it is a bit confusing from a API contract stand point. These commands are fire and forget, returning a dict implies that the device returned the values or confirmed them. None of our other traits return the MQTT wire frame from an action. If a caller needs to validate or preview a payload before its sent, there should be a helper. callers like start_with() should just execute the action Thoughts? cc @allenporter |
start_with(), preset_with() and start_with_custom_mode() returned the DPS frame they published, which implies the device confirmed it. These actions are fire-and-forget — the reply is not awaited — and no other trait hands back the MQTT wire frame from an action. Drop the return value, along with the docstring text that advertised it. Callers that need to inspect or validate a payload should build it up front; the validation helpers live in Python-roborock#967. preset_with()'s cancel path (minutes <= 0) still returns early, just without a value.
Fair — agreed, and it's done. On the helper: I am sorry that I forgot I already have it! Please see #967. I will keep on finished it when I have time. @allenporter happy to hear your take as well. |
allenporter
left a comment
There was a problem hiding this comment.
(Review conducted using the repository review skill by Gemini 4 Argon in Antigravity.)
Thanks for rebasing this onto A01Api (#941) and addressing the return value feedback! Moving to eagerly constructed traits fed by _merge_datapoints() is much cleaner and eliminates all the _dps_cache complexity from the earlier revision.
Because this PR still introduces ~1,250 lines across status, settings, feature detection, and commands—with only ~64 lines of unit tests in test_zeo_traits.py—it is still quite a lot of surface area to review and verify in one go. Earlier you mentioned:
"if you point at a seam you'd like to split along, I'll follow your lead."
Could we split this along the three trait seams so we can land them quickly with thorough unit tests for each?
- PR 1 — Status & Features (
ZeoStatusTrait+ZeoFeatures):status.py,ZeoFeaturesindevice_feature.py,ZeoWashLog/ZeoWashRecordinzeo_containers.py, and wiringapi.status+api.featuresina01/__init__.py, with unit tests for status decoding, wash log parsing, and feature bits. - PR 2 — Settings (
ZeoSettingTrait):settings.py(with unit tests for model-specific detergent/softener logic and feature-gated setters). - PR 3 — Commands (
ZeoCommandTrait+ZeoStartParams):command.py,ZeoStartParams,build_param_dps, andget_custom_mode(), with unit tests for the command payloads.
High-Level Design Comments (across the traits)
- Remove
TEST-ONLYstart-parameter setters fromZeoSettingTrait:
settings.pyincludes 12 public setters (set_mode,set_program,set_temperature,set_rinse,set_spin, etc.) documented asTest-only: carried by STARTwith no practical use in production. Let's omit these from the publicZeoSettingTraitAPI so consumers aren't confused about how to configure/start a cycle (api.set_value()already exists for raw single-DP debugging). - Missing read fields on
ZeoSettingTraitfor runtime switches:
ZeoSettingTraithas setters for runtime switches (set_child_lock,set_sound,set_dirt_detection,set_uv_light,set_smart_hosting,set_silent_mode,set_smile_light,set_power_light, etc.), but none of those DPs have corresponding dataclass fields onZeoSettingTrait. IfZeoSettingTraitholds the writable state of the device, those fields should be on the dataclass too so callers don't have to fall back toapi.values. - Avoid raw
dict[str, Any]on public trait boundaries:
Properties and methods likeZeoStatusTrait.product_info,ZeoApi.update_sound_package_info(), andZeoSettingTrait.set_sound_package()exposedict[str, Any]. Please use concreteRoborockBasedataclasses on public trait boundaries (similar toDyadProductInfoandDyadSndState).
I've also left a few specific inline comments on the code below.
| self._command = ZeoCommandTrait( | ||
| channel=channel, | ||
| settings=lambda: self._settings, | ||
| features=lambda: self._features, | ||
| custom_mode=lambda: self.get_custom_mode(), | ||
| ) |
There was a problem hiding this comment.
- Since
self._settingsis now constructed eagerly right aboveself._command, we can passsettings=self._settingsdirectly instead ofsettings=lambda: self._settings. - Also,
self._featuresis currently only populated in_force_load(). Ifinitial_statusor an MQTT push includesFEATURE_BITS(DP 237),_merge_datapointsshould updateself._feature_bitsandself._featuresas well soapi.featuresis populated from the initial cloud snapshot too.
|
|
||
| async def get_custom_mode(self) -> ZeoCustomMode | ZeoDryerCustomMode | None: | ||
| """Query and decode the current custom programme (DP 222).""" | ||
| result = await self.query_values([RoborockZeoProtocol.CUSTOM_PARAM_GET, RoborockZeoProtocol.TOTAL_TIME]) |
There was a problem hiding this comment.
ZeoCustomMode.total_time_min is documented in zeo_containers.py as coming from DP 239 (CUSTOM_PROGRAM_CLEANING_TIME), whereas TOTAL_TIME (DP 234) is a dryer DP not in the washer force-load list. Since send_decoded_command blocks until every queried DP in ID_QUERY responds (len(result) == len(query_values)), querying TOTAL_TIME on a washer that doesn't answer DP 234 will cause get_custom_mode() to time out after 10s. Should this read from cached status or query DP 239 only when supports_smart_clean(self._model) is true?
| if TYPE_CHECKING: | ||
| from roborock.devices.traits.a01.settings import ZeoSettingTrait |
There was a problem hiding this comment.
settings.py does not import command.py, so there is no circular import here. Please import ZeoSettingTrait directly at top-level (alongside FeaturesFn and build_param_dps) and remove if TYPE_CHECKING: and the stringified "ZeoSettingTrait" forward reference.
| async def pause(self) -> None: | ||
| """Pause the current programme (DP 201 = 1).""" | ||
| dps = {RoborockZeoProtocol.PAUSE: 1} | ||
| await send_decoded_command(self._channel, dps) | ||
|
|
||
| async def resume(self) -> None: | ||
| """Start/continue a paused programme (DP 200 = 1). | ||
|
|
||
| Only works while the device is powered on. | ||
| """ | ||
| dps = {RoborockZeoProtocol.START: 1} | ||
| await send_decoded_command(self._channel, dps) | ||
|
|
||
| async def stop(self) -> None: | ||
| """Stop the current programme (DP 200 = 0).""" | ||
| dps = {RoborockZeoProtocol.START: 0} | ||
| await send_decoded_command(self._channel, dps) | ||
|
|
||
| async def shutdown(self) -> None: | ||
| """Power off the device (DP 202 = 1). | ||
|
|
||
| Only works while the device is powered on. | ||
| """ | ||
| dps = {RoborockZeoProtocol.SHUTDOWN: 1} | ||
| await send_decoded_command(self._channel, dps) |
There was a problem hiding this comment.
The PR description notes that pause, resume, stop, and shutdown are sent with QoS 1, but these four calls omit qos=MqttQos.AT_LEAST_ONCE (defaulting to AT_MOST_ONCE).
| class ZeoFeatures: | ||
| """Device capability flags parsed from DP 237 (FEATURE_BITS). | ||
|
|
||
| Field names match :class:`ZeoFeatureBits` members one-to-one, so | ||
| :meth:`from_feature_bits` derives the mapping by name reflection | ||
| instead of a hardcoded lookup table. | ||
| """ | ||
|
|
||
| adapted_custom_program: bool = False | ||
| concentrated_detergent: bool = False | ||
| deep_self_clean: bool = False | ||
| detect_door_status: bool = False | ||
| dirt_detection: bool = False | ||
| dry_care: bool = False | ||
| expand_softener: bool = False | ||
| fluff_clean_notification: bool = False | ||
| ion_deodorization: bool = False | ||
| new_custom_program: bool = False | ||
| power_button_indicator_light: bool = False | ||
| save_panel_program_params: bool = False | ||
| set_params_in_working: bool = False | ||
| set_uvc_in_appointment: bool = False | ||
| set_uvc_in_pause: bool = False | ||
| silent_mode: bool = False | ||
| smart_hosting: bool = False | ||
| smile_light: bool = False | ||
| steam_care: bool = False | ||
| thirty_min_soak: bool = False | ||
| voice_assistant: bool = False | ||
| voice_assistant_record: bool = False | ||
| wash_dry_linkage: bool = False | ||
| wool_detergent: bool = False | ||
|
|
||
| @classmethod | ||
| def from_feature_bits(cls, raw: int) -> ZeoFeatures: | ||
| """Parse a raw FEATURE_BITS integer into a :class:`ZeoFeatures`.""" |
There was a problem hiding this comment.
Please drop from __future__ import annotations at the top of the file and use from typing import Self for from_feature_bits(cls, raw: int) -> Self, and have ZeoFeatures subclass RoborockBase (matching DeviceFeaturesTrait).
| if field_name == "total_time": | ||
| if val is not None and val > 0: | ||
| dps[dp] = val | ||
| elif val is not None: | ||
| dps[dp] = val |
There was a problem hiding this comment.
Let's convert enum values explicitly with int(val) (e.g. dps[dp] = int(val)) so the returned DPS dict contains plain wire integers consistently, matching set_detergent_type and set_cleanser_config.
|
|
||
| def update_from_dps(self, decoded_dps: dict[int, Any]) -> bool: | ||
| """Update trait fields from raw device DPS data. | ||
|
|
||
| Returns True if any field changed (and notifies update listeners). | ||
| """ | ||
| if self._converter.update_from_dps(self, decoded_dps): | ||
| self._notify_update() | ||
| return True | ||
| return False | ||
|
|
||
| @property | ||
| def auto_detergent(self) -> bool | None: | ||
| """Whether auto-dosing of detergent is on, derived from series state.""" | ||
| if self._is_dryer: | ||
| return None | ||
| if is_addition_type_control_auto_addition(self._model): | ||
| return self.detergent_type is not None and self.detergent_type != ZeoDetergentType.empty | ||
| return self.detergent_set | ||
|
|
||
| @property | ||
| def auto_softener(self) -> bool | None: | ||
| """Whether auto-dosing of softener is on, derived from series state.""" | ||
| if self._is_dryer: | ||
| return None | ||
| if is_addition_type_control_auto_addition(self._model): | ||
| return self.softener_type is not None and self.softener_type != ZeoSoftenerType.empty | ||
| return self.softener_set | ||
|
|
||
| async def _set_enum(self, dp: RoborockZeoProtocol, enum_cls: type[_T], value: _T) -> None: | ||
| """Validate *value* against *enum_cls* and send it to the device.""" | ||
| if not isinstance(value, enum_cls): | ||
| raise TypeError(f"Expected {enum_cls.__name__}, got {type(value).__name__}") | ||
| await self._send({dp: int(value)}) |
There was a problem hiding this comment.
DpsDataConverter.from_dataclass(...)can be computed once as a class attribute (_CONVERTER = ...) rather than re-running dataclass reflection in every__init__(same forZeoStatusTrait).- In
_set_enum(if retained), please remove the runtimeif not isinstance(value, enum_cls):check and rely on static type annotations.
| if features is not None and not features.silent_mode: | ||
| raise ValueError("This device does not support silent mode") | ||
| dps: dict[RoborockZeoProtocol, Any] = { |
There was a problem hiding this comment.
When features is None (e.g., before start() completes), if features is not None and not features.silent_mode: silently bypasses the feature check and sends the command anyway.
What this PR adds
This PR delivers the core Zeo API — the ability to actually start, pause,
resume, stop and schedule a wash programme on Zeo (washing machine / dryer)
devices, with fully typed parameters. It is the successor to the earlier
ZeoCommandTrait+ZeoFeatureTraitdraft, restructured into a singleZeoApientry point with three lazily-built sub-traits, and hardened byon-device verification.
The API surface
Key pieces
traits/a01/__init__.pyZeoApi— MQTT push subscription, two-stage force-load,query_values/set_value/get_custom_mode, lazily exposescommand/settings/statustraits/a01/command.pyZeoCommandTrait—start_with,start_with_custom_mode,preset_with,pause,resume,stop,shutdowntraits/a01/settings.pyZeoSettingTrait— typed writable state + typed setters,build_param_dps(params → DPs)traits/a01/status.pyZeoStatusTrait— read-only state (state/error/timers/tanks/wash log)traits/a01/device_feature.pyis_dryer,supports_uv_light, ...) +ZeoFeaturesparsed from DP 237 FEATURE_BITSDesign decisions
One trait family, not per-device classes. Washer vs dryer differ only in
which start parameters are sent (10 DPs vs 7). Everything else is shared, so
a single set of traits with an
is_dryerflag — resolved once atconstruction from the model ID — mirrors how V1's
CommandTraithandlesvastly different dock types through one class.
Two-stage state load, matching the app.
ZeoApi.start()queries thebase DP list first, then issues a follow-up query for the DPs gated behind
each enabled FEATURE_BITS (DP 237) bit — the same
forceLoad()→loadFeatureDps()flow in the official Bundle. The second stage isnon-fatal on failure (logged, backfilled by subsequent MQTT pushes).
Caller-supplied start parameters.
ZeoStartParamsis the singlesource of what gets started. Feature-gated values like
ion_deodorization(DP 258) andwash_dry_linked(DP 255) are passed bythe caller (
Noneomits the DP), instead of being silently read back fromthe device cache.
start_with(params)is a pure input → command function.Integer boolean protocol. Boolean DPs (auto-dosing 211/212, feature
gates) are sent as integers
1/0— on-device testing showed stringbooleans (
"False") are silently ignored by the device.Typed wash log.
ZeoWashRecord.prog_type→ZeoProgramandcategory→ZeoMode, so consumers getrecord.prog_type.namedirectly.Unknown values degrade to
Noneinstead of breaking the whole log decode.Verified on real hardware
All command paths below were tested against a physical device (MQTT trace +
state transitions confirmed):
start_with_custom_mode— DP 222 custom programme is decoded intoZeoStartParamsand the device boots with exactly those parameters(
state: standby → washing,program: boiling_wash → silk), auto-dosingintegers accepted.
preset_with— a valid parameter combination withminutes > 30reliably enters the delay-start countdown state (
under_delay_start,countdownset). Constraint documented in the docstring.pause/resume/shutdown— single-DP commands, QoS 1.Follow-ups (next PR)