feat(zeo): add core ZeoApi with ZeoCommandTrait and ZeoFeatureTrait

ZeoCommandTrait (new: command.py, 165 lines)
- start_program: bundles start params via FIELD_TO_DP, QoS 1
- pause / resume / shutdown: single-DP commands
- Start param sets split by device type (washer 10 DPs, dryer 7 DPs)
- Feature-gated DPs conditionally included from cache
- Dependencies injected: channel, dps_cache, feature_trait, proto_entries

ZeoFeatureTrait (new: device_features.py, 185 lines)
- ZeoFeatures dataclass (24 bool flags): from_feature_bits() via name reflection
- Product type detection: static model ID whitelists (dryer/Hyperion/M1)
- is_dryer / is_hyperion_halia_hera / is_m1_muse_metis — no device query
- refresh(): query DP 237 once, cache in memory

ZeoStartParams (zeo_containers.py): expanded to 13 fields covering washer + dryer
ZEO_PROTOCOL_ENTRIES (__init__.py): expanded to ~69 DP-type mappings
RoborockZeoProtocol: add UNKNOWN_246, UNKNOWN_259 placeholders

Builds on #895 (MQTT push subscription).

Author: NOisi-X

roborock/data/zeo/zeo_containers.py

@@ -19,20 +19,31 @@
 
 @dataclass
 class ZeoStartParams(RoborockBase):
-    """Parameters that must be bundled with a START command.
+    """All parameters that may be bundled with a START command.
 
-    All Zeo devices require ``mode`` and ``program`` to be sent together
-    with the start signal. The remaining fields are optional and only
-    included when the device reports a non-None value.
+    ``mode`` and ``program`` are mandatory for every device.  Every other
+    field is optional — when ``None`` it is simply omitted from the MQTT
+    payload, so the same superset works for washers and dryers alike.
     """
 
     mode: ZeoMode
     program: ZeoProgram
+
+    # Washer
     temperature: ZeoTemperature | None = None
     rinse: ZeoRinse | None = None
     spin: ZeoSpin | None = None
     drying_mode: ZeoDryingMode | None = None
 
+    # Dryer
+    drying_method: ZeoDryingMethod | None = None
+    steam_volume: ZeoSteamVolume | None = None
+    total_time: int | None = None
+
+    # Optional across both device families
+    soak: ZeoSoak | None = None
+    dry_and_care: ZeoDryAndCare | None = None
+
 
 # ── DP 222 (LoadCloudProgram) bitfield decoder ──────────────────────────
 # The official app packs all custom-program parameters into a single

roborock/devices/traits/a01/__init__.py

@@ -38,16 +38,24 @@
     RoborockDyadStateCode,
 )
 from roborock.data.zeo.zeo_code_mappings import (
+    ZeoDetergentExpansionType,
     ZeoDetergentType,
+    ZeoDirtDetectionStatus,
+    ZeoDryAndCare,
+    ZeoDryerStartError,
+    ZeoDryingMethod,
     ZeoDryingMode,
     ZeoError,
     ZeoFeatureBits,
     ZeoMode,
     ZeoProgram,
     ZeoRinse,
+    ZeoSoak,
+    ZeoSoftenerExpansionType,
     ZeoSoftenerType,
     ZeoSpin,
     ZeoState,
+    ZeoSteamVolume,
     ZeoTemperature,
 )
 from roborock.devices.rpc.a01_channel import send_decoded_command
@@ -63,11 +71,16 @@
     RoborockZeoProtocol,
 )
 
+from .command import ZeoCommandTrait  # noqa: F401 — re‑export
+from .device_features import ZeoFeatures, ZeoFeatureTrait  # noqa: F401 — re‑export
+
 _LOGGER = logging.getLogger(__name__)
 
 __init__ = [
     "DyadApi",
     "ZeoApi",
+    "ZeoCommandTrait",
+    "ZeoFeatureTrait",
 ]
 
 
@@ -112,6 +125,16 @@
     }
 )
 
+
+def _try_json(val: Any) -> Any:
+    """Return *val* parsed as JSON when it is a JSON string, else *val*."""
+    if isinstance(val, str):
+        try:
+            return json.loads(val)
+        except (json.JSONDecodeError, TypeError):
+            pass
+    return val
+
 ZEO_PROTOCOL_ENTRIES: dict[RoborockZeoProtocol, Callable] = {
     # read-only
     RoborockZeoProtocol.STATE: lambda val: ZeoState(val).name,
@@ -121,6 +144,27 @@
     RoborockZeoProtocol.TIMES_AFTER_CLEAN: lambda val: int(val),
     RoborockZeoProtocol.DETERGENT_EMPTY: lambda val: bool(val),
     RoborockZeoProtocol.SOFTENER_EMPTY: lambda val: bool(val),
+    RoborockZeoProtocol.DIRT_DETECTION_STATUS: lambda val: ZeoDirtDetectionStatus(val).name,
+    RoborockZeoProtocol.TOTAL_TIME: lambda val: int(val),
+    RoborockZeoProtocol.FEATURE_BITS: lambda val: int(val),
+    RoborockZeoProtocol.SMART_HOSTING_WAITED_TIME: lambda val: int(val),
+    RoborockZeoProtocol.IS_NEED_FLUFF_CLEAN: lambda val: bool(val),
+    RoborockZeoProtocol.PANEL_PROGRAM_PARAMS_SET_RESULT: lambda val: int(val),
+    RoborockZeoProtocol.DEVICE_BOUND: lambda val: bool(val),
+    RoborockZeoProtocol.CLOTH_PUT_IN: lambda val: bool(val),
+    RoborockZeoProtocol.CLOTH_READY_TO_DRY_COUNT_DOWN: lambda val: int(val),
+    RoborockZeoProtocol.START_DRYER_ERROR: lambda val: ZeoDryerStartError(val).name,
+    RoborockZeoProtocol.DOORLOCK_STATE: lambda val: bool(val),
+    RoborockZeoProtocol.APP_AUTHORIZATION: lambda val: bool(val),
+    RoborockZeoProtocol.SMART_HOSTING_TIME: lambda val: int(val),
+    RoborockZeoProtocol.CUSTOM_PROGRAM_CLEANING_TIME: lambda val: int(val),
+    RoborockZeoProtocol.PANEL_TIMING_PROGRAM_PARAMS: lambda val: int(val),
+    RoborockZeoProtocol.STEAM_CARE_TIME: lambda val: int(val),
+    # meta — read-only (JSON)
+    RoborockZeoProtocol.PRODUCT_INFO: lambda val: _try_json(val),
+    RoborockZeoProtocol.WASHING_LOG: lambda val: _try_json(val),
+    RoborockZeoProtocol.VOICE_RECORD_INFO: lambda val: _try_json(val),
+    RoborockZeoProtocol.VOICE_RECORD: lambda val: _try_json(val),
     # read-write
     RoborockZeoProtocol.MODE: lambda val: ZeoMode(val).name,
     RoborockZeoProtocol.PROGRAM: lambda val: ZeoProgram(val).name,
@@ -131,6 +175,41 @@
     RoborockZeoProtocol.DETERGENT_TYPE: lambda val: ZeoDetergentType(val).name,
     RoborockZeoProtocol.SOFTENER_TYPE: lambda val: ZeoSoftenerType(val).name,
     RoborockZeoProtocol.SOUND_SET: lambda val: bool(val),
+    RoborockZeoProtocol.DIRT_DETECTION_SWITCH: lambda val: bool(val),
+    RoborockZeoProtocol.SOAK: lambda val: ZeoSoak(val).name,
+    RoborockZeoProtocol.SILENT_MODE_ON: lambda val: bool(val),
+    RoborockZeoProtocol.SILENT_MODE_START_TIME: lambda val: int(val),
+    RoborockZeoProtocol.SILENT_MODE_END_TIME: lambda val: int(val),
+    RoborockZeoProtocol.DRY_CARE_MODE: lambda val: ZeoDryAndCare(val).name,
+    RoborockZeoProtocol.WASH_DRY_LINKED: lambda val: bool(val),
+    RoborockZeoProtocol.DRYING_METHOD: lambda val: ZeoDryingMethod(val).name,
+    RoborockZeoProtocol.STEAM_VOLUME: lambda val: ZeoSteamVolume(val).name,
+    RoborockZeoProtocol.ION_DEODORIZATION: lambda val: bool(val),
+    RoborockZeoProtocol.UV_LIGHT: lambda val: bool(val),
+    RoborockZeoProtocol.SMART_HOSTING: lambda val: bool(val),
+    RoborockZeoProtocol.SOFTENER_EXPANSION_TYPE: lambda val: ZeoSoftenerExpansionType(val).name,
+    RoborockZeoProtocol.DETERGENT_EXPANSION_TYPE: lambda val: ZeoDetergentExpansionType(val).name,
+    RoborockZeoProtocol.SMILE_LIGHT_STATUS: lambda val: bool(val),
+    RoborockZeoProtocol.POWER_LIGHT: lambda val: bool(val),
+    RoborockZeoProtocol.PANEL_PROGRAM_PARAMS_SET: lambda val: int(val),
+    RoborockZeoProtocol.WIFI_LINKAGE_RESET: lambda val: int(val),
+    RoborockZeoProtocol.SAVE_ADAPTED_CLOUD_PROGRAM: lambda val: int(val),
+    RoborockZeoProtocol.CHILD_LOCK: lambda val: bool(val),
+    RoborockZeoProtocol.DETERGENT_SET: lambda val: bool(val),
+    RoborockZeoProtocol.SOFTENER_SET: lambda val: bool(val),
+    RoborockZeoProtocol.FLUFF_CLEANED: lambda val: bool(val),
+    # read-write (int-valued)
+    RoborockZeoProtocol.CUSTOM_PARAM_SAVE: lambda val: int(val),
+    RoborockZeoProtocol.CUSTOM_PARAM_GET: lambda val: int(val),
+    RoborockZeoProtocol.DEFAULT_SETTING: lambda val: int(val),
+    RoborockZeoProtocol.LIGHT_SETTING: lambda val: bool(val),
+    RoborockZeoProtocol.DETERGENT_VOLUME: lambda val: int(val),
+    RoborockZeoProtocol.SOFTENER_VOLUME: lambda val: int(val),
+    # meta — read-write
+    RoborockZeoProtocol.SET_SOUND_PACKAGE: lambda val: val,
+    RoborockZeoProtocol.VOICE_VOLUME: lambda val: val,
+    RoborockZeoProtocol.VOICE_SWITCH: lambda val: bool(val),
+    RoborockZeoProtocol.VOICE_RECORD_DELETE: lambda val: int(val),
 }
 
 
@@ -189,13 +268,23 @@ def __init__(self, channel: MqttChannel, product_id: str | None = None) -> None:
         self._dps_unsub: Callable[[], None] | None = None
         self._feature_bits: int = 0
         self._product_id = product_id
+        self._feature_trait = ZeoFeatureTrait(channel, product_id)
+        self._command: ZeoCommandTrait | None = None
+
+    @property
+    def command(self) -> ZeoCommandTrait:
+        """Lazily-built trait for wash-programme commands."""
+        if self._command is None:
+            self._command = ZeoCommandTrait(
+                channel=self._channel,
+                dps_cache=self._dps_cache,
+                feature_trait=self._feature_trait,
+                proto_entries=ZEO_PROTOCOL_ENTRIES,
+            )
+        return self._command
 
     async def start(self) -> None:
-        """Subscribe to MQTT push and discover device features.
-
-        Subscribes to the DPS MQTT topic, then queries FEATURE_BITS
-        (DP 237) to wake the device and cache supported capabilities.
-        """
+        """Subscribe to MQTT push and discover device capabilities."""
         await self._ensure_subscribed()
         await self._discover_features()
 
@@ -215,9 +304,9 @@ async def _discover_features(self) -> None:
         """Query FEATURE_BITS to wake the device and cache capabilities.
 
         Only devices that support the FeatureBits DP will respond;
-        For devices known to lack this DP
-        the query is skipped entirely; for all other devices a
-        timeout propagates as a connection error.
+        For devices known to lack this DP the query is skipped
+        entirely; for all other devices a timeout propagates as a
+        connection error.
         """
         if self._product_id in _UNSUPPORTED_FEATURE_BITS:
             return

roborock/devices/traits/a01/command.py

@@ -0,0 +1,163 @@
+"""Zeo command trait"""
+
+import json
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from roborock.data.zeo.zeo_containers import ZeoStartParams
+from roborock.devices.rpc.a01_channel import send_decoded_command
+from roborock.devices.traits.a01.device_features import ZeoFeatureTrait
+from roborock.devices.transport.mqtt_channel import MqttChannel
+from roborock.mqtt.session import MqttQos
+from roborock.roborock_message import RoborockZeoProtocol
+
+_LOGGER = logging.getLogger(__name__)
+
+_START_PARAM_DPS_WASHER: list[RoborockZeoProtocol] = [
+    RoborockZeoProtocol.MODE,
+    RoborockZeoProtocol.PROGRAM,
+    RoborockZeoProtocol.TEMP,
+    RoborockZeoProtocol.RINSE_TIMES,
+    RoborockZeoProtocol.SPIN_LEVEL,
+    RoborockZeoProtocol.DRYING_MODE,
+    RoborockZeoProtocol.DETERGENT_SET,
+    RoborockZeoProtocol.SOFTENER_SET,
+    RoborockZeoProtocol.COUNTDOWN,
+    RoborockZeoProtocol.SOAK,
+]
+
+_START_PARAM_DPS_DRYER: list[RoborockZeoProtocol] = [
+    RoborockZeoProtocol.MODE,
+    RoborockZeoProtocol.PROGRAM,
+    RoborockZeoProtocol.DRYING_MODE,
+    RoborockZeoProtocol.TOTAL_TIME,
+    RoborockZeoProtocol.DRYING_METHOD,
+    RoborockZeoProtocol.STEAM_VOLUME,
+    RoborockZeoProtocol.COUNTDOWN,
+]
+
+_FIELD_TO_DP: dict[str, RoborockZeoProtocol] = {
+    "mode": RoborockZeoProtocol.MODE,
+    "program": RoborockZeoProtocol.PROGRAM,
+    "temperature": RoborockZeoProtocol.TEMP,
+    "rinse": RoborockZeoProtocol.RINSE_TIMES,
+    "spin": RoborockZeoProtocol.SPIN_LEVEL,
+    "drying_mode": RoborockZeoProtocol.DRYING_MODE,
+    "drying_method": RoborockZeoProtocol.DRYING_METHOD,
+    "steam_volume": RoborockZeoProtocol.STEAM_VOLUME,
+    "total_time": RoborockZeoProtocol.TOTAL_TIME,
+    "soak": RoborockZeoProtocol.SOAK,
+    "dry_and_care": RoborockZeoProtocol.DRY_CARE_MODE,
+}
+
+_FEATURE_GATED_DPS: dict[RoborockZeoProtocol, str] = {
+    RoborockZeoProtocol.ION_DEODORIZATION: "ion_deodorization",
+    RoborockZeoProtocol.WASH_DRY_LINKED: "wash_dry_linkage",
+    RoborockZeoProtocol.SMART_HOSTING: "smart_hosting",
+}
+
+
+class ZeoCommandTrait:
+    """Trait for sending commands to Zeo devices."""
+
+    def __init__(
+        self,
+        *,
+        channel: MqttChannel,
+        dps_cache: dict[int, Any],
+        feature_trait: ZeoFeatureTrait,
+        proto_entries: dict[RoborockZeoProtocol, Callable],
+    ) -> None:
+        """Initialize the command trait."""
+
+        self._channel = channel
+        self._dps_cache = dps_cache
+        self._feature_trait = feature_trait
+        self._proto_entries = proto_entries
+
+    def _convert_value(self, protocol: RoborockZeoProtocol, value: Any) -> Any:
+        """Convert a protocol value using the injected entries table."""
+        if (converter := self._proto_entries.get(protocol)) is not None:
+            try:
+                return converter(value)
+            except (ValueError, TypeError):
+                return None
+        return None
+
+    async def start_program(self) -> dict[RoborockZeoProtocol, Any]:
+        """Start the device, bundling the current programme parameters."""
+        features = self._feature_trait.features
+        p = await self._get_start_params()
+        dps: dict[RoborockZeoProtocol, Any] = {RoborockZeoProtocol.START: "True"}
+        for field_name, dp in _FIELD_TO_DP.items():
+            val = getattr(p, field_name)
+            if val is not None:
+                dps[dp] = val
+        for dp, attr_name in _FEATURE_GATED_DPS.items():
+            if features is not None and getattr(features, attr_name, False):
+                val = self._dps_cache.get(int(dp))
+                if val is not None:
+                    dps[dp] = val
+        await send_decoded_command(
+            self._channel,
+            dps,
+            qos=MqttQos.AT_LEAST_ONCE,
+            value_encoder=lambda x: x,
+        )
+        for dp, v in dps.items():
+            self._dps_cache[int(dp)] = v
+        return {proto: self._convert_value(proto, dps.get(proto)) for proto in dps}
+
+    async def pause(self) -> dict[RoborockZeoProtocol, Any]:
+        """Pause the current programme (DP 201 = "True")."""
+        dps = {RoborockZeoProtocol.PAUSE: "True"}
+        result = await send_decoded_command(self._channel, dps)
+        self._dps_cache[int(RoborockZeoProtocol.PAUSE)] = 1
+        return result
+
+    async def resume(self) -> dict[RoborockZeoProtocol, Any]:
+        """Start/continue a paused programme (DP 200 = "True").
+        Only works while the device is powered on.
+        """
+        dps = {RoborockZeoProtocol.START: "True"}
+        result = await send_decoded_command(self._channel, dps)
+        self._dps_cache[int(RoborockZeoProtocol.START)] = 1
+        return result
+
+    async def shutdown(self) -> dict[RoborockZeoProtocol, Any]:
+        """Power off the device (DP 202 = "True").
+        Only works while the device is powered on.
+        """
+        dps = {RoborockZeoProtocol.SHUTDOWN: "True"}
+        result = await send_decoded_command(self._channel, dps)
+        self._dps_cache[int(RoborockZeoProtocol.SHUTDOWN)] = 1
+        return result
+
+    async def _get_start_params(self) -> ZeoStartParams:
+        """Read programme settings, querying the device on cache miss."""
+        cache = self._dps_cache
+        wanted = _START_PARAM_DPS_DRYER if self._feature_trait.is_dryer else _START_PARAM_DPS_WASHER
+        need_refresh = int(RoborockZeoProtocol.MODE) not in cache or int(RoborockZeoProtocol.PROGRAM) not in cache
+        if need_refresh:
+            raw = await send_decoded_command(
+                self._channel,
+                {RoborockZeoProtocol.ID_QUERY: wanted},
+                value_encoder=json.dumps,
+            )
+            for dp in wanted:
+                if (val := raw.get(dp)) is not None:
+                    cache[int(dp)] = val
+        return ZeoStartParams(
+            mode=cache[int(RoborockZeoProtocol.MODE)],
+            program=cache[int(RoborockZeoProtocol.PROGRAM)],
+            temperature=cache.get(int(RoborockZeoProtocol.TEMP)),
+            rinse=cache.get(int(RoborockZeoProtocol.RINSE_TIMES)),
+            spin=cache.get(int(RoborockZeoProtocol.SPIN_LEVEL)),
+            drying_mode=cache.get(int(RoborockZeoProtocol.DRYING_MODE)),
+            drying_method=cache.get(int(RoborockZeoProtocol.DRYING_METHOD)),
+            steam_volume=cache.get(int(RoborockZeoProtocol.STEAM_VOLUME)),
+            total_time=cache.get(int(RoborockZeoProtocol.TOTAL_TIME)),
+            soak=cache.get(int(RoborockZeoProtocol.SOAK)),
+            dry_and_care=cache.get(int(RoborockZeoProtocol.DRY_CARE_MODE)),
+        )