Skip to content

feat: add V1 dock mop wash settings and tray self-clean - #1045

Draft
infy1995 wants to merge 9 commits into
Python-roborock:mainfrom
infy1995:feat/v1-mop-wash-settings
Draft

infy1995 wants to merge 9 commits into
Python-roborock:mainfrom
infy1995:feat/v1-mop-wash-settings

Conversation

@infy1995

@infy1995 infy1995 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Part of the "Dock controls" item in #738: V1 dock mop wash settings and the wash tray self-clean, so consumers can set how often and how the dock washes the mops and start or stop a tray self-clean.

Depends on #1036 (this branch is based on it; the first five commits belong to #1036). I will rebase onto main once #1036 is merged.

Changes

  • New WashWaterTemperatureTrait (PropertiesApi.wash_water_temperature)
    • Reads get_wash_water_temperature; set_wash_water_temperature(temperature) sends set_wash_water_temperature with {"values": <code>}. The device answers reads with wash_water_temperature, but rejects that key on writes (-10007 invalid params).
    • New RoborockDockWashWaterTemperatureCode: room_temperature 0, warm 1, hot 2, steam 3, pet_steam 4.
    • wash_water_temperature_options from the pure get_wash_water_temperatures(dock_features): room temperature and hot always, warm only on docks with neither high temperature water nor steam, steam only on steam docks, pet steam never.
    • Created only for washing docks on devices with is_hot_wash_towel_supported, so docks that cannot heat wash water get no temperature control. The PearlE Pro (PEARLELITE, a169/a170) can heat wash water only with a Shell2E Lite dock, so it gets the trait only with that dock (is_wash_water_temperature_offered).
  • New CleaningFluidTrait (PropertiesApi.cleaning_fluid), cleaning fluid auto-delivery
    • Reads get_auto_delivery_cleaning_fluid; set_cleaning_fluid(mode) sends set_auto_delivery_cleaning_fluid with {"status": <code>}.
    • New RoborockDockCleaningFluidCode: off 0, standard 1, large 3. Code 2 is not a selectable amount.
    • Gated by dock_features.is_clean_fluid_auto_delivery_supported.
  • SmartWashParamsTrait (mop wash frequency)
    • SmartWashParams.smart_wash is now RoborockDockSmartWashModeCode | None (by_time 0, by_room 1, new_smart 2) instead of int | None. It is an IntEnum, so integer comparisons keep working.
    • smart_wash_mode_options: by time and by room, plus new smart with is_back_wash_new_smart_supported. wash_interval_options from the pure get_wash_interval_options(product_nickname): 600, 900, 1200, 1500 s; 600 to 3000 s in steps of 300 on TopazS, TopazSV, TopazSPlus, TopazSC, TopazSPower and UltronSPlus, which accept a free interval in that range.
    • set_smart_wash_params(mode, wash_interval) sends both values together.
    • The trait now takes DeviceFeaturesTrait and the product nickname, and is created in discover_features(), like WashTowelModeTrait.
  • WashTowelModeTrait
    • set_wash_towel_mode(mode) now rejects a mode outside wash_towel_mode_options before sending.
    • New self_clean_tray() sends app_amethyst_self_check, gated by dock_features.is_clean_carousel_self_clean_supported. stop_wash() stops a running self-clean early.
  • All setters raise RoborockUnsupportedFeature for a value the device does not offer, send nothing in that case, and update the trait state only after the command succeeds.
  • docs/V1_API_COMMANDS.md: entries for the new commands and formats, get/set_smart_wash_params codes, set_wash_towel_mode codes, app_amethyst_self_check.

Wire formats

Setting Read / write Codes
Wash water temperature get_wash_water_temperature → {"wash_water_temperature": n}; set_wash_water_temperature {"values": n} 0 room temperature, 1 warm, 2 hot, 3 steam, 4 pet steam
Cleaning fluid auto-delivery get/set_auto_delivery_cleaning_fluid, {"status": n} 0 off, 1 standard, 3 large
Mop wash frequency get/set_smart_wash_params, {"smart_wash": n, "wash_interval": s} 0 by time, 1 by room, 2 new smart; interval 600/900/1200/1500 s
Wash water amount get/set_wash_towel_mode, {"wash_mode": n} 0 light, 1 balanced, 2 deep, 8 super deep, 10 smart (existing WashTowelModes)
Tray self-clean app_amethyst_self_check, no params; stopped by app_stop_wash

The codes, option lists and write formats were compared with the Roborock app's V1 device plugins and match what the app shows. They were confirmed on a Saros 10R (roborock.vacuum.a144, dock type 16).

Left for later

The option lists above are the ones for newer models such as the Saros 10R. Some older models differ in a few places that need model family detection or status fields the library does not have yet; they are left for a follow-up:

  • UltronSV (a97) offers warm also on its high temperature docks (K1R, Shell4RC).
  • ShellE and ShellEA docks cannot heat wash water, so they should get no temperature (needs the ShellE dock flag from the dock types PR, feat: add V1 dock types 48 and 50 and fix F2R, K1S and Hera dock capabilities #1047).
  • Older models offer by room only with map saving on, and never new smart.
  • Wash water amount options depending on the auto-empty state, soak and wash, and newer feature bits.
  • The cleaning fluid trait is gated on the dock only; whether the fluid module is installed is not checked yet.

Behavior changes for consumers

  • set_wash_towel_mode() now raises RoborockUnsupportedFeature for a mode outside wash_towel_mode_options. Callers that pick from that list (as Home Assistant does) are unaffected.
  • SmartWashParams.smart_wash is an enum instead of a plain int (see above).

Testing

  • uv run pre-commit run --all-files: all hooks pass.
  • uv run pytest: 2510 passed. Each commit passes on its own.
  • New and extended tests in tests/devices/traits/v1/ (test_wash_water_temperature.py, test_cleaning_fluid.py, test_smart_wash_params.py, test_wash_towel_mode.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, per hot wash feature and per product (PearlE Pro, older models). A new product_model fixture in tests/devices/traits/v1/fixtures.py sets the test device's model.
  • Saros 10R:
    • Read: temperature 2 (hot), fluid 1 (standard), smart wash by room / 1200 s, wash mode smart.
    • Write: temperature warm and room temperature, fluid large and off, mop wash by time every 15 min, wash mode light, balanced and deep, each set through the library and confirmed in the Roborock app; then restored.
    • Tray self-clean: after self_clean_tray() the robot state went from charging to washing_the_mop (wash_phase 11) and the app showed the self-clean; stop_wash() ended it within 3 s, with the same status changes as the stop button in the app.

Related issues

@infy1995
infy1995 marked this pull request as draft November 13, 2026 20:13
@infy1995 infy1995 mentioned this pull request Nov 14, 2026
9 tasks
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.
@infy1995
infy1995 force-pushed the feat/v1-mop-wash-settings branch from 4662475 to 67f528d Compare November 15, 2026 01:40
@Lash-L Lash-L added Feature New feature V1 V1 platform labels Nov 15, 2026
@infy1995 infy1995 changed the title feat: add V1 mop wash settings feat: add V1 dock mop wash settings and tray self-clean 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).

Stacking note: This branch is stacked on #1036 (1b2efd87, 3dfce1d5, 4897723f); this review covers only PR #1045's own commits (11661023, 93e2e3ae, 42957e16, 67f528d9).

Summary

No issues found. All new traits, enums, option lists, command payloads, and feature/dock gating match the Roborock app's V1 behavior and follow repository conventions.

  • Priority 1 (Public Trait APIs & Consumer Contracts):
    • WashWaterTemperature, CleaningFluidDelivery, and SmartWashParams subclass RoborockBase as @dataclass models with concrete types and no Any or TypedDict.
    • WashWaterTemperatureTrait is gated on dock_features.is_washable, device_features.is_hot_wash_towel_supported, and is_wash_water_temperature_offered (hiding it on PEARLELITE unless dock_type == shell_2e_lite_dock). Option ordering and gating (room_temperature, warm when neither is_high_tmp_water_supported nor is_steam_wash_supported, hot, steam when is_steam_wash_supported) match the app.
    • CleaningFluidTrait is gated on dock_features.is_clean_fluid_auto_delivery_supported and exposes off (0), standard (1), and large (3).
    • SmartWashParamsTrait is gated on dock_features.is_washable, exposes by_time (0), by_room (1), and new_smart (2, gated on is_back_wash_new_smart_supported), and wash_interval_options returns [600, 900, 1200, 1500] s (or 600..3000 s in 300 s steps for TopazS, TopazSV, TopazSPlus, TopazSC, TopazSPower, and UltronSPlus).
    • WashTowelModeTrait.set_wash_towel_mode validates against wash_towel_mode_options, and self_clean_tray sends app_amethyst_self_check gated on dock_features.is_clean_carousel_self_clean_supported.
  • Priority 2 (Data Lifecycle & State Management):
    • Pure option/gating helpers (get_wash_water_temperatures, is_wash_water_temperature_offered, get_wash_interval_options) return values without side effects.
    • Setters validate supported options before sending and perform optimistic state updates only after send_command succeeds.
  • Priority 3 (Wire Protocols & Resilient Enums):
    • RoborockDockWashWaterTemperatureCode, RoborockDockCleaningFluidCode, and RoborockDockSmartWashModeCode inherit from RoborockEnum with unknown = -1.
    • Wire payloads match the app (set_wash_water_temperature {"values": n} vs read {"wash_water_temperature": n}, set_auto_delivery_cleaning_fluid {"status": n}, set_smart_wash_params {"smart_wash": n, "wash_interval": s}, app_amethyst_self_check {}).
  • Tests & Checks:
    • uv run --python 3.12 pytest tests/devices/traits/v1/test_wash_water_temperature.py tests/devices/traits/v1/test_cleaning_fluid.py tests/devices/traits/v1/test_smart_wash_params.py tests/devices/traits/v1/test_wash_towel_mode.py tests/conformance/ -> 672 passed, 53 xfailed.
    • uv run --python 3.12 ruff check roborock tests passed; mypy reported zero errors in PR #1045's files.

@Lash-L Lash-L added /review run Code review skill (/review) has been run Passed /review Passed the /review skill check labels 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 Passed /review Passed the /review skill check /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