feat: add MQTT push subscription and real-time state tracking for Zeo devices by NOisi-x · Pull Request #895 · Python-roborock/python-roborock

NOisi-x · 2026-07-22T03:59:10Z

Summary

Builds on #892. Add MQTT push subscription and real-time state tracking for Zeo devices.

What's new in this PR

1. MQTT Push Subscription

ZeoApi.start() subscribes to the device's DPS MQTT topic after connection. All device state changes — both physical (button presses, dial rotations) and remote (App commands) — are received as real-time push messages.

device.connect() → zeo.start() → MQTT subscribe
                                 → _discover_features() pull full state

2. DPS Cache with Incremental Updates

Incoming push messages are decoded from RPC protocol 102, parsed as {dps: {dp_id: value, ...}}, and merged into _dps_cache. Only changed DPs are pushed — the device sends incremental updates, not full state each time.

3. Feature Discovery (`_discover_features`)

Mirrors V1's discover_features() pattern: after subscribing, queries FEATURE_BITS (DP 237) to wake the device and cache supported capabilities. Exposes supports(ZeoFeatureBits) for runtime feature checks.

4. Bug Fixes Found During Testing

ZeoApi.__init__: missing TraitUpdateListener.__init__() call caused _update_callbacks AttributeError
device.py connect(): self.a01_properties (doesn't exist) → self.zeo

5. DP 243 Placeholder

Observed on a114, increments with each push. Not found in the plugin bundle. Added as UNKNOWN_243 with a comment.

Testing

Tested on two Zeo devices (a234, a114) using a multi-device MQTT monitor:

Scenario	Result
Physical operations (power on, dial rotate, wash start/pause/cancel)	Real-time push < 1s
Door lock/unlock events	Correctly tracked
Incremental DP updates	Only changed DPs pushed
Two devices concurrently	Independent streams, no crosstalk
`_discover_features()` wake	Device pushes full state

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

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 Python-roborock#895 (MQTT push subscription).

NOisi-x · 2026-07-27T01:38:16Z

A bit weird. I received some comments via email, but I didn't see anything here. I kept all the notes hoping to help with the review as much as possible, share my findings, and stay compatible with the existing code, leaving room for future changes for syncing and HA integration. If the reviewer thinks some comments aren't needed, I can delete them anytime. Thanks a lot.

allenporter · 2026-07-27T14:14:12Z

+        try:
+            result = await self.query_values([RoborockZeoProtocol.FEATURE_BITS])
+            self._feature_bits = result.get(RoborockZeoProtocol.FEATURE_BITS, 0)
+        except Exception:


Catch more narrow exceptions here, only what we actually expect to see raised here.

If there is a transient RPC here, not clear to me it is OK to fail silently with no features, is it? what do you expect the user to do here with this device?

Changed except Exception → except RoborockException.
The Bundle follows the same pattern: query FEATURE_BITS, default to 0 on null response. featureBits = 0 means all feature-gated operations are disabled — basic start/stop/query still work.

Bundle also skips the FEATURE_BITS query entirely for older device series via isSupportFeatureBits. Only two models are excluded: roborock.wm.a63 (H1) and roborock.wm.a90 (H1 Lite). Should I add an explicit model check for those, or is the current timeout-then-default approach acceptable?

allenporter · 2026-07-27T14:16:02Z

+            self._dps_cache.update(decoded)
+            self._notify_update()
+        except RoborockException:
+            _LOGGER.debug("Failed to decode push message, skipping: %s", message, exc_info=True)


This seems like it should just be around the decode_rpc_response and not the others?

yes yes. fixed

allenporter · 2026-07-27T14:16:52Z

        """Initialize the Zeo API."""
+        TraitUpdateListener.__init__(self, _LOGGER)
        self._channel = channel
+        self._dps_cache: dict[int, Any] = {}


This appears unused in this PR. Can we explain how we expect this to be used here and what the semantics are? when it is ok to use vs when do we need to refresh, etc.

See #897
ZeoCommandTrait._get_start_params() checks the cache for MODE/PROGRAM and only issues a device query on cache miss — avoiding redundant network round-trips when values were already received via push.

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 force-pushed the pr/zeo-push branch 7 times, most recently from 698b11b to 44465af Compare July 22, 2026 04:26

NOisi-X added 2 commits July 22, 2026 18:45

NOisi-x force-pushed the pr/zeo-push branch 4 times, most recently from 8d33ed9 to 2764f2e Compare July 22, 2026 13:28

NOisi-x force-pushed the pr/zeo-push branch from 2764f2e to 910375b Compare July 22, 2026 13:49

Merge branch 'main' into pr/zeo-push

4432a62

NOisi-x mentioned this pull request Jul 22, 2026

feat: add core ZeoApi with ZeoCommandTrait and ZeoFeatureTrait #897

Open

Merge branch 'main' into pr/zeo-push

d57b81e

allenporter requested changes Jul 27, 2026

View reviewed changes

NOisi-x force-pushed the pr/zeo-push branch from 9976fcd to 2558e72 Compare July 28, 2026 01:15

fix(zeo): narrow exceptions, tighten try/except scope

fa44017

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 force-pushed the pr/zeo-push branch from 2558e72 to fa44017 Compare July 28, 2026 01:20

NOisi-x requested a review from allenporter July 28, 2026 02:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add MQTT push subscription and real-time state tracking for Zeo devices - #895

feat: add MQTT push subscription and real-time state tracking for Zeo devices#895
NOisi-x wants to merge 7 commits into
Python-roborock:mainfrom
NOisi-x:pr/zeo-push

NOisi-x commented Jul 22, 2026 •

edited

Loading

Uh oh!

NOisi-x commented Jul 27, 2026

Uh oh!

allenporter Jul 27, 2026

Uh oh!

NOisi-x Jul 28, 2026

Uh oh!

allenporter Jul 27, 2026

Uh oh!

NOisi-x Jul 28, 2026

Uh oh!

allenporter Jul 27, 2026

Uh oh!

NOisi-x Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

NOisi-x commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's new in this PR

1. MQTT Push Subscription

2. DPS Cache with Incremental Updates

3. Feature Discovery (_discover_features)

4. Bug Fixes Found During Testing

5. DP 243 Placeholder

Testing

Uh oh!

NOisi-x commented Jul 27, 2026

Uh oh!

allenporter Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

NOisi-x Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

allenporter Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

NOisi-x Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

allenporter Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

NOisi-x Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

NOisi-x commented Jul 22, 2026 •

edited

Loading

3. Feature Discovery (`_discover_features`)