[infy1995]

Part of the "Dock controls" item in #738: V1 dock dust collection settings and actions.

Changes

• DustCollectionModeTrait
  • dust_collection_mode_options: smart, light, balanced, max (the set the Roborock app offers).
  • set_dust_collection_mode(mode) sends set_dust_collection_mode with {"mode": <code>}. A mode outside the options raises RoborockUnsupportedFeature and sends nothing.
  • start_dust_collection() / stop_dust_collection() send app_start_collect_dust / app_stop_collect_dust.
  • RoborockDockDustCollectionModeCode gains strong = 3, so reading that code no longer falls back to unknown. The app never offers it, so the setter rejects it.
• New DustCollectionFrequencyTrait (PropertiesApi.dust_collection_frequency), the app's auto-empty frequency
  • Reads get_dust_collection_switch_status; set_frequency(frequency) sends set_dust_collection_switch_status with {"status": <code>}.
  • New RoborockDockDustCollectionFrequencyCode: off 0, balanced 1, high 2 (unknown = -1 for unexpected firmware codes).
  • Gated by dock_features.is_collectable, same as the mode trait.
• docs/V1_API_COMMANDS.md: entries for both setters and get/set_dust_collection_switch_status.

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 offered by the app), 4 max
Auto-empty frequency	get/set_dust_collection_switch_status, {"status": n}	0 off, 1 balanced, 2 high (same value as auto_dust_collection in get_status)

Codes and option lists come from the Roborock app's V1 device plugin, and were confirmed on a Saros 10R (roborock.vacuum.a144, dock type 16).

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 the app does not offer and which 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: 2350 passed.
• New tests in tests/devices/traits/v1/test_dust_collection_mode.py and test_dust_collection_frequency.py: option lists, setter commands, rejection of unoffered values without sending, state unchanged after a failed command, unknown firmware codes, trait availability per dock type.
• Saros 10R:
  • Read: mode 4 (max), frequency 2 (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.