Skip to content

feat: typed commands, settings & status for Zeo devices - #897

Draft
NOisi-x wants to merge 28 commits into
Python-roborock:mainfrom
NOisi-x:pr/zeo-core-api-v2
Draft

NOisi-x wants to merge 28 commits into
Python-roborock:mainfrom
NOisi-x:pr/zeo-core-api-v2

Conversation

@NOisi-x

@NOisi-x NOisi-x commented Jul 22, 2026 •

Copy link
Copy Markdown
Contributor

Builds on #895
Closes #833

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 + ZeoFeatureTrait draft, restructured into a single
ZeoApi entry point with three lazily-built sub-traits, and hardened by
on-device verification.

The API surface

api: ZeoApi = device.zeo  # built by a01 create() from the product category

# Read-only state, typed (state, error, timers, tank levels, wash log, ...)
api.status.state                 # ZeoState.standby / washing / ...
api.status.washing_left          # minutes remaining
api.status.washing_log           # ZeoWashLog with typed ZeoProgram / ZeoMode

# Writable state + typed setters (mode, programme, temperature, spin, ...)
api.settings.mode                # ZeoMode.wash
api.settings.temperature         # ZeoTemperature.medium
await api.settings.set_temperature(ZeoTemperature.high)

# Commands
await api.command.start_with(ZeoStartParams(
    mode=ZeoMode.wash_and_dry,
    program=ZeoProgram.silk,
    temperature=ZeoTemperature.low,
    rinse=ZeoRinse.high,
    spin=ZeoSpin.mid,
    drying_mode=ZeoDryingMode.quick,
    ion_deodorization=True,       # caller-supplied, feature-gated
))
await api.command.start_with_custom_mode()   # reuse device's saved DP 222 programme
await api.command.preset_with(params, minutes=120)  # delayed start (>30 min enters countdown)
await api.command.pause() / resume() / stop() / shutdown()

Key pieces

Module Role
traits/a01/__init__.py ZeoApi — MQTT push subscription, two-stage force-load, query_values/set_value/get_custom_mode, lazily exposes command/settings/status
traits/a01/command.py ZeoCommandTrait — start_with, start_with_custom_mode, preset_with, pause, resume, stop, shutdown
traits/a01/settings.py ZeoSettingTrait — typed writable state + typed setters, build_param_dps (params → DPs)
traits/a01/status.py ZeoStatusTrait — read-only state (state/error/timers/tanks/wash log)
traits/a01/device_feature.py Series whitelists (is_dryer, supports_uv_light, ...) + ZeoFeatures parsed from DP 237 FEATURE_BITS

Design decisions

  1. 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_dryer flag — resolved once at
    construction from the model ID — mirrors how V1's CommandTrait handles
    vastly different dock types through one class.

  2. Two-stage state load, matching the app. ZeoApi.start() queries the
    base 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 is
    non-fatal on failure (logged, backfilled by subsequent MQTT pushes).

  3. Caller-supplied start parameters. ZeoStartParams is the single
    source
    of what gets started. Feature-gated values like
    ion_deodorization (DP 258) and wash_dry_linked (DP 255) are passed by
    the caller (None omits the DP), instead of being silently read back from
    the device cache. start_with(params) is a pure input → command function.

  4. Integer boolean protocol. Boolean DPs (auto-dosing 211/212, feature
    gates) are sent as integers 1/0 — on-device testing showed string
    booleans ("False") are silently ignored by the device.

  5. Typed wash log. ZeoWashRecord.prog_type → ZeoProgram and
    category → ZeoMode, so consumers get record.prog_type.name directly.
    Unknown values degrade to None instead 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 into
    ZeoStartParams and the device boots with exactly those parameters
    (state: standby → washing, program: boiling_wash → silk), auto-dosing
    integers accepted.
  • preset_with — a valid parameter combination with minutes > 30
    reliably enters the delay-start countdown state (under_delay_start,
    countdown set). Constraint documented in the docstring.
  • pause / resume / shutdown — single-DP commands, QoS 1.

Follow-ups (next PR)

  • Programme-config table-Solve the problem of making startup parameters valid

NOisi-X and others added 5 commits July 20, 2026 11:39
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().
@NOisi-x
NOisi-x force-pushed the pr/zeo-core-api-v2 branch 3 times, most recently from cbb254f to c57f0b7 Compare July 22, 2026 14:38

@allenporter allenporter left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

@NOisi-x

NOisi-x commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

@allenporter The difference between washer and dryer in ZeoCommandTrait is just the start parameter list — 10 DPs vs 7 DPs. Everything else (start_program, pause, resume, shutdown, cache checking, feature gating) is identical since they are all Zeo devices. Splitting into two classes would duplicate ~95% of the code.

V1's CommandTrait serves the same role for vacuums with vastly different dock types (pure collect vs collect+wash+dry+plumbing) — all through a single trait. The is_dryer flag here is equivalent to V1's dock_features check: resolved once at construction, not at runtime.

Given the minimal difference, is the current single-trait approach acceptable, or would you still prefer separate classes?

@allenporter

Copy link
Copy Markdown
Contributor

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)

NOisi-X and others added 2 commits August 6, 2026 16:46
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
@NOisi-x
NOisi-x force-pushed the pr/zeo-core-api-v2 branch from 437ec29 to 1fcacf4 Compare August 6, 2026 08:53
@NOisi-x

NOisi-x commented Aug 6, 2026

Copy link
Copy Markdown
Contributor Author

@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?

@NOisi-x
NOisi-x force-pushed the pr/zeo-core-api-v2 branch from 1fcacf4 to 103266a Compare August 6, 2026 09:06
NOisi-x and others added 4 commits August 12, 2026 08:44
…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.
@NOisi-x
NOisi-x marked this pull request as draft August 13, 2026 14:44
@NOisi-x
NOisi-x force-pushed the pr/zeo-core-api-v2 branch from 103266a to 7716150 Compare August 15, 2026 06:29
@NOisi-x NOisi-x changed the title feat: add core ZeoApi with ZeoCommandTrait and ZeoFeatureTrait feat: typed commands, settings & status for Zeo devices Aug 15, 2026
@NOisi-x

NOisi-x commented Aug 15, 2026

Copy link
Copy Markdown
Contributor Author

@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.

@allenporter
allenporter marked this pull request as ready for review August 15, 2026 17:42
@NOisi-x
NOisi-x force-pushed the pr/zeo-core-api-v2 branch from 2cba1cf to 9ea7225 Compare August 17, 2026 02:31
NOisi-X added 4 commits August 17, 2026 10:47
_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.
@NOisi-x

NOisi-x commented Aug 17, 2026 •

Copy link
Copy Markdown
Contributor Author

Hi, this PR is over 1k lines and is pretty huge, so not going to be something i can review quickly.

We're adding features, fixing small issues/enums, and also there are also multiple fundamental architecture shifts we're making here because the existing support is pretty naive. We're going to need to work on these more incrementally. Can we tease this apart into a multiple smaller logical PRs please?

@allenporter Please don't be put off by the line count — the bulk of the diff is three new
trait files (settings.py, command.py, status.py), and most of their
methods are trivial semantic wrappers over the raw MQTT/DPS protocol. There's almost no branching logic in them.

I wrote them for completeness of the semantic API surface. If you feel some of
them are unnecessary, they can be trimmed — I'm happy to drop the ones that
carry no real logic and keep only the wrappers that do meaningful work.

On splitting: I'd still prefer to land this as one PR, because the existing
Zeo support is a raw passthrough with almost no typed surface, and this PR
collectively gives Zeo a nearly complete typed API (commands, setters, status,
feature detection). Splitting would mean landing half-working slices. But I'm open to it — if you point at a seam
you'd like to split along, I'll follow your lead. There's no deadline here, so
please review at whatever pace is comfortable.

Finally — thank you for the careful review. Your comments have been really
valuable to me; each one made me re-examine my work and the resulting code
is much better for it. I really appreciate the time you're putting into this.

@Lash-L

Lash-L commented Sep 17, 2026 •

Copy link
Copy Markdown
Collaborator

@NOisi-x can you fix the merge conflicts and then mark as ready for review?

@Lash-L
Lash-L marked this pull request as draft September 17, 2026 13:07
NOisi-X added 3 commits September 19, 2026 17:10
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.
@NOisi-x

NOisi-x commented Sep 19, 2026

Copy link
Copy Markdown
Contributor Author

@NOisi-x can you fix the merge conflicts and then mark as ready for review?

@Lash-L Done. Based on #941 I also made some small improvements and removed dead code. Thanks!

@Lash-L Lash-L left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Few more comments -

I think most of the setters and commands should return None

Comment thread roborock/devices/traits/a01/settings.py Resolved
Comment thread roborock/devices/traits/a01/settings.py Resolved
Comment thread roborock/devices/traits/a01/command.py Resolved
Comment thread roborock/devices/traits/a01/settings.py Resolved
Comment thread roborock/devices/traits/a01/status.py Resolved
NOisi-x pushed a commit to NOisi-x/python-roborock that referenced this pull request Oct 8, 2026
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.
@NOisi-x
NOisi-x force-pushed the pr/zeo-core-api-v2 branch from 1beefb3 to cd2d425 Compare October 8, 2026 05:34
NOisi-X added 3 commits October 8, 2026 13:41
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.
@NOisi-x

NOisi-x commented Oct 8, 2026

Copy link
Copy Markdown
Contributor Author

Few more comments -

I think most of the setters and commands should return None

Done. The 34 public setters plus the three shared helpers (_send / _set_enum / _set_bool) in settings.py now return None.

I kept the frame as the return value of start_with() / preset_with() / start_with_custom_mode().
Reason: those three append DPs the caller cannot derive from its arguments — auto-dosing (211/212) and the feature-gated DPs (255/258) — and that returned frame is what I use to check that a programme's option combination is valid, see #967.

@Lash-L

Lash-L commented Oct 10, 2026

Copy link
Copy Markdown
Collaborator

I kept the frame as the return value of start_with() / preset_with() / start_with_custom_mode(). Reason: those three append DPs the caller cannot derive from its arguments — auto-dosing (211/212) and the feature-gated DPs (255/258) — and that returned frame is what I use to check that a programme's option combination is valid, see #967.

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.
@NOisi-x

NOisi-x commented Oct 13, 2026

Copy link
Copy Markdown
Contributor Author

I kept the frame as the return value of start_with() / preset_with() / start_with_custom_mode(). Reason: those three append DPs the caller cannot derive from its arguments — auto-dosing (211/212) and the feature-gated DPs (255/258) — and that returned frame is what I use to check that a programme's option combination is valid, see #967.

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

Fair — agreed, and it's done. start_with() / preset_with() / start_with_custom_mode() now return None.

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 allenporter left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(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?

  1. PR 1 — Status & Features (ZeoStatusTrait + ZeoFeatures): status.py, ZeoFeatures in device_feature.py, ZeoWashLog/ZeoWashRecord in zeo_containers.py, and wiring api.status + api.features in a01/__init__.py, with unit tests for status decoding, wash log parsing, and feature bits.
  2. PR 2 — Settings (ZeoSettingTrait): settings.py (with unit tests for model-specific detergent/softener logic and feature-gated setters).
  3. PR 3 — Commands (ZeoCommandTrait + ZeoStartParams): command.py, ZeoStartParams, build_param_dps, and get_custom_mode(), with unit tests for the command payloads.

High-Level Design Comments (across the traits)

  1. Remove TEST-ONLY start-parameter setters from ZeoSettingTrait:
    settings.py includes 12 public setters (set_mode, set_program, set_temperature, set_rinse, set_spin, etc.) documented as Test-only: carried by START with no practical use in production. Let's omit these from the public ZeoSettingTrait API so consumers aren't confused about how to configure/start a cycle (api.set_value() already exists for raw single-DP debugging).
  2. Missing read fields on ZeoSettingTrait for runtime switches:
    ZeoSettingTrait has 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 on ZeoSettingTrait. If ZeoSettingTrait holds the writable state of the device, those fields should be on the dataclass too so callers don't have to fall back to api.values.
  3. Avoid raw dict[str, Any] on public trait boundaries:
    Properties and methods like ZeoStatusTrait.product_info, ZeoApi.update_sound_package_info(), and ZeoSettingTrait.set_sound_package() expose dict[str, Any]. Please use concrete RoborockBase dataclasses on public trait boundaries (similar to DyadProductInfo and DyadSndState).

I've also left a few specific inline comments on the code below.

Comment on lines +434 to +439
self._command = ZeoCommandTrait(
channel=channel,
settings=lambda: self._settings,
features=lambda: self._features,
custom_mode=lambda: self.get_custom_mode(),
)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Since self._settings is now constructed eagerly right above self._command, we can pass settings=self._settings directly instead of settings=lambda: self._settings.
  • Also, self._features is currently only populated in _force_load(). If initial_status or an MQTT push includes FEATURE_BITS (DP 237), _merge_datapoints should update self._feature_bits and self._features as well so api.features is 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])

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Comment on lines +17 to +18
if TYPE_CHECKING:
from roborock.devices.traits.a01.settings import ZeoSettingTrait

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +157 to +181
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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Comment on lines +150 to +185
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`."""

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Comment on lines +91 to +95
if field_name == "total_time":
if val is not None and val > 0:
dps[dp] = val
elif val is not None:
dps[dp] = val

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +152 to +185

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)})

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • DpsDataConverter.from_dataclass(...) can be computed once as a class attribute (_CONVERTER = ...) rather than re-running dataclass reflection in every __init__ (same for ZeoStatusTrait).
  • In _set_enum (if retained), please remove the runtime if not isinstance(value, enum_cls): check and rely on static type annotations.

Comment on lines +346 to +348
if features is not None and not features.silent_mode:
raise ValueError("This device does not support silent mode")
dps: dict[RoborockZeoProtocol, Any] = {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@NOisi-x
NOisi-x marked this pull request as draft October 22, 2026 06:37
@Lash-L Lash-L added Feature New feature /review run Code review skill (/review) has been run A01 A01 (Dyad / Zeo) platform labels Nov 15, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A01 A01 (Dyad / Zeo) platform Feature New feature /review run Code review skill (/review) has been run

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature/Bug] Zeo Washing Machine (M1S Ultra): Deep Sleep Wakeup Failure & Missing DP Mappings

4 participants