Skip to content

feat(v1): add fan speed, water and mop route setters that refuse changes in SmartPlan and custom mode - #1064

Draft
infy1995 wants to merge 11 commits into
Python-roborock:mainfrom
infy1995:claude/v1-cleaning-mode-setters-56db40
Draft

infy1995 wants to merge 11 commits into
Python-roborock:mainfrom
infy1995:claude/v1-cleaning-mode-setters-56db40

Conversation

@infy1995

@infy1995 infy1995 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Part of #738

Depends on #1055. This branch is built on top of #1055 (SmartPlan and custom cleaning modes, option lists). The first five commits are #1055; this PR's own changes are the last six commits:

  1. feat(v1): report which cleaning settings can be changed and which values to show in each mode
  2. feat(v1): send cleaning mode changes with the commands each model supports
  3. feat(v1): add fan speed, water mode and mop route setters that refuse changes in SmartPlan and custom mode
  4. docs(v1): describe cleaning setting rules, setters and per-model commands
  5. feat(v1): report which cleaning settings each model supports
  6. fix(v1): list supported cleaning settings in a stable order

Once #1055 merges I will rebase, so only these six remain.

Summary

In SmartPlan the robot picks fan speed, water and mop route itself, and in custom mode they come from the per-room settings, so a consumer must not offer or send those settings. And outside those modes, not every value is valid in every mode: for example the Saros 10R rejects deep route 301 in vacuum-and-mop mode with -10005. This PR gives consumers what they need to show and change these settings safely, so a consumer such as Home Assistant only presents what the library reports and never combines feature flags itself:

  • StatusTrait.supported_cleaning_settings: which of fan speed, water mode and mop route the model has at all, from the device features (fan speed always; water mode with is_support_water_mode; mop route with water mode, the shake module, and either a mop-only mode or the fast route). A setting is in this set exactly when it can be changed in at least one cleaning mode. The cleaning mode select exists when cleaning_mode_options is not empty.
  • StatusTrait.is_fan_speed_adjustable, is_water_mode_adjustable, is_mop_route_adjustable: whether the setting can be changed in the current cleaning mode.
  • StatusTrait.fan_speed_display_options, water_mode_display_options, mop_route_display_options: the values to show in the current mode. In SmartPlan or custom mode only the SmartPlan or custom value; nothing when the setting doesn't apply; otherwise the mode's list:
    • fan: Max+ (108) only in vacuum-only mode;
    • mop route: only fast and standard outside mop-only mode, unless the model offers all routes; needs the shake module;
    • water: no "off" on models with a mop-only mode.
  • New StatusTrait.set_fan_speed, set_water_mode, set_mop_route. They raise RoborockUnsupportedFeature and send nothing in SmartPlan, custom or unknown mode and for values not offered in the current mode (checked by code, so aliases with the same code pass; any water slide code 221–250 is accepted). They raise RoborockException when the status is not loaded.
  • New DeviceFeatures.is_set_clean_motor_mode_supported (robot feature 118): models that take fan_power and water_box_mode together in set_clean_motor_mode.

The per-mode lists and command order were compared with the Roborock app plugin and match what the app shows.

Behavior changes

  • set_cleaning_mode sends the commands each model supports. Before, every model got one set_clean_motor_mode with three fields:
    • shake-module models: one set_clean_motor_mode with fan_power, water_box_mode, mop_mode (unchanged);
    • models with feature 118: set_clean_motor_mode with fan_power and water_box_mode;
    • other models: set_custom_mode, then set_water_box_custom_mode;
    • devices without a mop: only set_custom_mode.
    • Models without the shake module get set_mop_mode [300] only when leaving SmartPlan or custom mode (route 306/302), so the robot is not still reported in that mode.
  • After all commands succeed, set_cleaning_mode and the new setters update fan_power, water_box_mode and mop_mode locally and notify listeners once. On an error nothing is updated.
  • Values left over from another mode are replaced before sending: a fan speed not offered in the mode (Max+ outside vacuum-only, 105 outside mop-only) becomes 102, a mop route not offered in the mode becomes 300.
  • The mop route can only be changed on models with the shake module.
  • water_mode_options / water_mode_mapping and mop_route_options / mop_route_mapping are now empty when the model does not support the setting (water mode on devices without a mop; mop route on models without the shake module, or without both a mop-only mode and the fast route). Before, they listed values that could never be set, so a consumer created a selector that was always unavailable. fan_speed_options and cleaning_mode_options are unchanged. get_cleaning_mode_parameters returns the same payload as before.
  • When the robot reports SmartPlan or custom codes on a model whose flags don't list that mode, current_cleaning_mode stays None (unchanged), but the display options show the SmartPlan or custom value and the setters refuse, because the robot is in that mode.
  • The new feature field makes feature sets cached by older versions incomplete, so they are fetched from the device once.

Testing

  • pytest: 2750 passed. Each of the first four commits passes the suite and ruff on its own. pre-commit run --all-files (ruff, mypy, codespell) passes.
  • Tested on a Saros 10R (water slide, shake module): every cleaning mode including SmartPlan (110/209/306) and custom (106/204/302), each setter in vacuum and mop, mop only and vacuum only, the refusals in SmartPlan, custom and for values not offered in the mode, and Max+ and the fast route in vacuum-only mode. Each step was checked in the Roborock app. docs/V1_API_COMMANDS.md lists the Saros 10R under the tested commands.

Conflicts with open PRs

Test-merged (git merge-tree) against every open PR that touches the same files:

PR Files with a text conflict Kind Who rebases
#1024 (CleaningMode.VAC_THEN_MOP) roborock/data/v1/v1_clean_modes.py, roborock/devices/traits/v1/status.py, tests/devices/__snapshots__/test_v1_device.ambr, tests/devices/traits/v1/test_status.py code + snapshot Whichever merges second. VAC_THEN_MOP needs a row in the adjustable rules (same as vacuum and mop) and in the command builder.
#959 (clean-then-mop status) roborock/devices/traits/v1/status.py, tests/devices/__snapshots__/test_v1_device.ambr, tests/devices/traits/v1/test_status.py code + snapshot Whichever merges second. Both add methods next to set_cleaning_mode; the local field update follows #959's convention.
#1025 (custom and SmartPlan on water-slide devices) roborock/data/v1/v1_clean_modes.py, tests/devices/traits/v1/test_status.py code Already a conflict with #1055, which includes #1025's fix.
#1054 (V1 feature flag bits) docs/V1_DEVICE_FEATURES.md, roborock/device_features.py, tests/__snapshots__/test_supported_features.ambr, tests/devices/__snapshots__/test_file_cache.ambr code (both add a feature field) + snapshot Whichever merges second keeps both fields and regenerates the snapshots.
#1030 (obstacle photos for Qrevo 2 Pro) tests/__snapshots__/test_supported_features.ambr snapshot only Whichever merges second regenerates the snapshot.
#1066 (VacuumModes.OFF code distinct from GENTLE) tests/data/v1/test_v1_clean_modes.py tests Whichever merges second combines the test additions.
#1067 (refresh status after fan or water pushes) tests/devices/traits/v1/test_status.py tests Whichever merges second combines the test additions.

Same files, no text conflict: #1065, #1059, #1026, #1044 (snapshots), #1057 (status.py, test_status.py), #1046, #1047 (device_features.py, feature docs and tests), #1045, #1036, #1035 (docs/V1_API_COMMANDS.md).

@infy1995 infy1995 mentioned this pull request Nov 17, 2026
9 tasks
@Lash-L Lash-L added Feature New feature V1 V1 platform labels Nov 18, 2026
@infy1995 infy1995 closed this Nov 18, 2026
@infy1995
infy1995 deleted the claude/v1-cleaning-mode-setters-56db40 branch November 18, 2026 20:00
@infy1995
infy1995 restored the claude/v1-cleaning-mode-setters-56db40 branch November 18, 2026 20:00
@infy1995 infy1995 reopened this Nov 18, 2026
@infy1995
infy1995 marked this pull request as draft November 18, 2026 22:40

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 V1 V1 platform

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants