Repository navigation
Conversation
The Roborock app shows the dock's dust collection page only for a collecting dock on a product that supports it (isCollectDustModeSupported, not Pearl), and loads the mode only with isDustCollectionSettingSupported. - DustCollectionModeTrait now requires is_collectable, is_collect_dust_mode_supported and is_dust_collection_setting_supported. - DustCollectionFrequencyTrait now requires is_collectable and is_collect_dust_mode_supported. Both traits are created explicitly in discover_features, because _is_supported cannot combine dock and device feature checks. Behaviour change: on Pearl products (e.g. Q Revo) and on devices without the dust collection setting feature, dust_collection_mode is now None.
Lash-L
left a comment
There was a problem hiding this comment.
Automated code review by Gemini 4 Hydrogen in Antigravity using our /review (/code-review) skill (.agents/skills/code-review/SKILL.md / AGENTS.md).
Summary by Architectural Layer
- Priority 1 — Public Trait APIs & Consumer Contracts:
DustCollectionModeTraitandDustCollectionFrequencyTraitcleanly subclassRoborockBasecontainers (DustCollectionMode,DustCollectionFrequency), use concrete enum types with noAnyon public boundaries, and validate selectable options before sending commands (raisingRoborockUnsupportedFeature).DustCollectionModeTraitgating (is_collectable+is_collect_dust_mode_supported+is_dust_collection_setting_supported) matches the app's gating forget/set_dust_collection_mode, anddust_collection_mode_options(0smart,1light,2balanced,4max; omitting3strong) matches the app.- Two gating findings (see inline comments):
DustCollectionFrequencyTraitshould gate onis_auto_collection_2_supportedrather thanis_collect_dust_mode_supported, and placingstart_dust_collection/stop_dust_collectiononDustCollectionModeTraithides manual dust collection from Pearl / non-DCS collecting docks.
- Priority 2 — Data Lifecycle & State Management:
PropertiesApi.discover_featureswires both traits cleanly without side-effecting helpers, and optimistic updates (self.mode = mode,self.status = frequency) only occur aftersend_commandsucceeds.
- Priority 3 — Wire Protocols & Enums:
- Command names (
get/set_dust_collection_mode,get/set_dust_collection_switch_status,app_start_collect_dust,app_stop_collect_dust), payload shapes ({"mode": n},{"status": n}, no params for start/stop), and enum codes (RoborockDockDustCollectionModeCodeincludingstrong = 3,RoborockDockDustCollectionFrequencyCodewithunknown = -1) all match the Roborock app.
- Command names (
- Tests & Verification:
- Colocated tests in
tests/devices/traits/v1/test_dust_collection_mode.pyandtest_dust_collection_frequency.pyfollow repository conventions. All 576 V1 trait tests, conformance tests (536 passed, 53 xfailed),ruff check, andmypyon the changed files pass.
- Colocated tests in
| The app shows the dock's dust collection page only for a collecting dock on a | ||
| product that supports it (``isCollectDustModeSupported``, not Pearl). | ||
| """ | ||
| return dock_features.is_collectable and device_features.is_collect_dust_mode_supported |
There was a problem hiding this comment.
Capability gating mismatch with the app (is_auto_collection_2_supported vs is_collect_dust_mode_supported)
In the Roborock app, the 3-way Auto-Empty Frequency selector (0 off, 1 balanced, 2 high) is gated on dock_features.is_collectable and NewFeatureStrBit.AUTO_COLLECTION_2 (device_features.is_auto_collection_2_supported, bit 53)—it does not check is_collect_dust_mode_supported (which only gates the Empty Mode entry).
On collecting docks without is_auto_collection_2_supported (e.g., S7 MaxV Ultra, Q5 Max+), the app only shows a binary on/off Auto Emptying switch (0/1) and never offers 2 (high).
Suggested fix:
def supports_dust_collection_frequency(device_features: DeviceFeatures, dock_features: RoborockDockFeatures) -> bool:
"""Return whether the app shows the auto-empty frequency for this device."""
return dock_features.is_collectable and bool(device_features.is_auto_collection_2_supported)(Or, if you want the trait present on all collecting docks to read/toggle 0/1, gate frequency_options to [off, balanced] when not device_features.is_auto_collection_2_supported.) Please also update docs/V1_DEVICE_FEATURES.md if you change this.
There was a problem hiding this comment.
Thanks, addressed in 4f7f77c. The auto-empty setting is now available on every collecting dock (is_collectable) and no longer gated by is_collect_dust_mode_supported. frequency_options offers off/balanced/high with is_auto_collection_2_supported (bit 53), and only off/balanced (on/off) without it; set_frequency rejects high there. Since the trait now covers more than the frequency, it is renamed to DustCollectionTrait / PropertiesApi.dust_collection, matching the B01 Q10 trait. docs/V1_DEVICE_FEATURES.md is updated. The on/off case without bit 53 is not tested on a real device.
| # Optimistic update to avoid an extra refresh | ||
| self.mode = mode | ||
|
|
||
| async def start_dust_collection(self) -> None: |
There was a problem hiding this comment.
start_dust_collection / stop_dust_collection are unavailable on Pearl and non-DCS collecting docks
Narrowing DustCollectionModeTrait to is_collectable and is_collect_dust_mode_supported and is_dust_collection_setting_supported matches the app's gating for get_dust_collection_mode / set_dust_collection_mode.
However, app_start_collect_dust and app_stop_collect_dust are supported on collecting docks regardless of is_collect_dust_mode_supported (Pearl, e.g. Q Revo) or is_dust_collection_setting_supported (older collecting docks without bit 25). Because these methods live on DustCollectionModeTrait, consumers have no way to trigger manual dust collection when dust_collection_mode is None.
Suggested fix:
Consider exposing start_dust_collection / stop_dust_collection on a trait gated solely by dock_features.is_collectable (or a dedicated dock-action trait) so manual dust collection remains available on all collecting docks.
There was a problem hiding this comment.
Thanks, addressed in 4f7f77c: start_dust_collection / stop_dust_collection moved from DustCollectionModeTrait to DustCollectionTrait, which every collecting dock has, so Pearl and docks without is_dust_collection_setting_supported keep manual dust collection. Covered by tests on the Saros 10R and Q Revo fixtures.
Every collecting dock has an auto-empty setting and manual dust collection, but only devices with new feature string bit 53 choose an auto-empty frequency; the others only switch auto-empty on or off. - Rename DustCollectionFrequencyTrait to DustCollectionTrait (PropertiesApi.dust_collection), matching the B01 Q10 trait, since it now covers more than the frequency. - Gate it only on is_collectable. frequency_options is off/balanced/high with is_auto_collection_2_supported and off/balanced (on/off) without it. - Move start_dust_collection / stop_dust_collection from DustCollectionModeTrait to DustCollectionTrait, so Pearl and docks without the dust collection setting keep manual dust collection. - Update V1_DEVICE_FEATURES.md and V1_API_COMMANDS.md.
Part of the "Dock controls" item in #738: V1 dock dust collection settings and actions, so consumers can change the emptying mode and the auto-empty setting, and start or stop emptying the bin.
Changes
DustCollectionModeTraitdust_collection_mode_options: smart, light, balanced, max.set_dust_collection_mode(mode)sendsset_dust_collection_modewith{"mode": <code>}. A mode outside the options raisesRoborockUnsupportedFeatureand sends nothing.RoborockDockDustCollectionModeCodegainsstrong = 3, so reading that code no longer falls back tounknown. It is not a selectable mode, so the setter rejects it.DustCollectionTrait(PropertiesApi.dust_collection, same name as the B01 Q10 trait): auto-empty setting and manual dust collection, on every collecting dockget_dust_collection_switch_status;set_frequency(frequency)sendsset_dust_collection_switch_statuswith{"status": <code>}.frequency_options(fromget_dust_collection_frequencies(features)): off, balanced, high on devices withis_auto_collection_2_supported(new feature string bit 53); only off and balanced (code 1, meaning on) on other collecting docks, which only have an auto-empty on/off switch.start_dust_collection()/stop_dust_collection()sendapp_start_collect_dust/app_stop_collect_dust. They live here, not on the mode trait, so collecting docks without an emptying mode (e.g. Pearl products) can still empty the bin manually.RoborockDockDustCollectionFrequencyCode: off 0, balanced 1, high 2 (unknown = -1for unexpected firmware codes).docs/V1_API_COMMANDS.md: entries for both setters andget/set_dust_collection_switch_status.docs/V1_DEVICE_FEATURES.md: what the device features gate.Gating
dust_collection_modeis_collectableandis_collect_dust_mode_supportedandis_dust_collection_setting_supporteddust_collectionis_collectablehighis offered.The mode trait is created explicitly in
discover_features, because_is_supportedcannot combine dock and device feature checks. The frequency trait follows theWashTowelModeTraitpattern (dock gating plus the device features trait for its options).Behaviour change:
dust_collection_mode(read-only on main so far) is nowNoneon Pearl products such as the Q Revo, and on devices withoutis_dust_collection_setting_supported, because those robots have no emptying mode to read or set.Wire formats
get/set_dust_collection_mode,{"mode": n}get/set_dust_collection_switch_status,{"status": n}auto_dust_collectioninget_status)The option lists, codes and gating were compared with the Roborock app's V1 device plugin. They were confirmed on a Saros 10R (
roborock.vacuum.a144, dock type 16). The on/off case without bit 53 was not tested on a device.Home Assistant
When Home Assistant bumps to this version, the
dust_collection_modeselect should take its options fromdust_collection_mode_optionsinstead ofRoborockDockDustCollectionModeCode.keys(). Otherwise it lists the newstrongmember, which is not selectable and has no translation.set_dust_collection_mode()validates against the same list.Testing
uv run pre-commit run --all-files: all hooks pass.uv run pytest: 2357 passed.tests/devices/traits/v1/test_dust_collection_mode.pyandtest_dust_collection.py: option lists per device, setter commands, rejection of unoffered values without sending (includinghighwithout bit 53), state unchanged after a failed command, unknown firmware codes, trait availability per dock type, mode gating (Saros 10R has it, a fixture without the dust collection setting bit and the Q Revo (Pearl) do not), and manual dust collection on the Saros 10R and the Q Revo.frequency_optionsoff, balanced, high.start_dust_collection()the robot state went fromchargingtoemptying_the_bin; afterstop_dust_collection()5 s later it went todockingand then back tocharging.