Skip to content

feat: add V1 dock dust collection mode, auto-empty frequency and start/stop - #1036

Open
infy1995 wants to merge 5 commits into
Python-roborock:mainfrom
infy1995:feat/v1-dust-collection-controls
Open

infy1995 wants to merge 5 commits into
Python-roborock:mainfrom
infy1995:feat/v1-dust-collection-controls

Conversation

@infy1995

@infy1995 infy1995 commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

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

  • DustCollectionModeTrait
    • dust_collection_mode_options: smart, light, balanced, max.
    • set_dust_collection_mode(mode) sends set_dust_collection_mode with {"mode": <code>}. A mode outside the options raises RoborockUnsupportedFeature and sends nothing.
    • RoborockDockDustCollectionModeCode gains strong = 3, so reading that code no longer falls back to unknown. It is not a selectable mode, so the setter rejects it.
  • New DustCollectionTrait (PropertiesApi.dust_collection, same name as the B01 Q10 trait): auto-empty setting and manual dust collection, on every collecting dock
    • Reads get_dust_collection_switch_status; set_frequency(frequency) sends set_dust_collection_switch_status with {"status": <code>}.
    • frequency_options (from get_dust_collection_frequencies(features)): off, balanced, high on devices with is_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() send app_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.
    • New RoborockDockDustCollectionFrequencyCode: off 0, balanced 1, high 2 (unknown = -1 for unexpected firmware codes).
  • docs/V1_API_COMMANDS.md: entries for both setters and get/set_dust_collection_switch_status. docs/V1_DEVICE_FEATURES.md: what the device features gate.

Gating

Trait Requires Why
dust_collection_mode is_collectable and is_collect_dust_mode_supported and is_dust_collection_setting_supported Only these robots have an emptying mode to read or set (not Pearl, robot new feature 33554432).
dust_collection is_collectable Every collecting dock has auto-empty and manual emptying; bit 53 only decides whether high is offered.

The mode trait is created explicitly in discover_features, because _is_supported cannot combine dock and device feature checks. The frequency trait follows the WashTowelModeTrait pattern (dock gating plus the device features trait for its options).

Behaviour change: dust_collection_mode (read-only on main so far) is now None on Pearl products such as the Q Revo, and on devices without is_dust_collection_setting_supported, because those robots have no emptying mode to read or set.

Wire formats

Setting Read / write Codes
Dust collection mode get/set_dust_collection_mode, {"mode": n} 0 smart, 1 light, 2 balanced, 3 strong (not selectable), 4 max
Auto-empty frequency get/set_dust_collection_switch_status, {"status": n} 0 off, 1 balanced, 2 high; without bit 53 only 0 off and 1 on (same value as auto_dust_collection in get_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_mode select should take its options from dust_collection_mode_options instead of RoborockDockDustCollectionModeCode.keys(). Otherwise it lists the new strong member, 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.
  • New tests in tests/devices/traits/v1/test_dust_collection_mode.py and test_dust_collection.py: option lists per device, setter commands, rejection of unoffered values without sending (including high without 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.
  • Saros 10R:
    • Read: mode 4 (max), frequency 2 (high); frequency_options off, balanced, high.
    • Write: frequency off and balanced, mode light, smart and balanced, each set through the library and confirmed in the Roborock app; then restored to max / high.
    • Actions: after start_dust_collection() the robot state went from charging to emptying_the_bin; after stop_dust_collection() 5 s later it went to docking and then back to charging.

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 Lash-L added Feature New feature V1 V1 platform labels Nov 15, 2026
@infy1995 infy1995 changed the title feat: add V1 dust collection controls feat: add V1 dock dust collection mode, auto-empty frequency and start/stop Nov 17, 2026

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

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:
    • DustCollectionModeTrait and DustCollectionFrequencyTrait cleanly subclass RoborockBase containers (DustCollectionMode, DustCollectionFrequency), use concrete enum types with no Any on public boundaries, and validate selectable options before sending commands (raising RoborockUnsupportedFeature).
    • DustCollectionModeTrait gating (is_collectable + is_collect_dust_mode_supported + is_dust_collection_setting_supported) matches the app's gating for get/set_dust_collection_mode, and dust_collection_mode_options (0 smart, 1 light, 2 balanced, 4 max; omitting 3 strong) matches the app.
    • Two gating findings (see inline comments): DustCollectionFrequencyTrait should gate on is_auto_collection_2_supported rather than is_collect_dust_mode_supported, and placing start_dust_collection / stop_dust_collection on DustCollectionModeTrait hides manual dust collection from Pearl / non-DCS collecting docks.
  • Priority 2 — Data Lifecycle & State Management:
    • PropertiesApi.discover_features wires both traits cleanly without side-effecting helpers, and optimistic updates (self.mode = mode, self.status = frequency) only occur after send_command succeeds.
  • 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 (RoborockDockDustCollectionModeCode including strong = 3, RoborockDockDustCollectionFrequencyCode with unknown = -1) all match the Roborock app.
  • Tests & Verification:
    • Colocated tests in tests/devices/traits/v1/test_dust_collection_mode.py and test_dust_collection_frequency.py follow repository conventions. All 576 V1 trait tests, conformance tests (536 passed, 53 xfailed), ruff check, and mypy on the changed files pass.

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

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.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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:

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.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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.

@Lash-L Lash-L added the /review run Code review skill (/review) has been run label Nov 18, 2026
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.

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

Feature New feature /review run Code review skill (/review) has been run V1 V1 platform

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants