Skip to content

Commit a13b6f4

Browse files
committed
feat(v1): report which cleaning settings each model supports
1 parent a79c8f7 commit a13b6f4

6 files changed

Lines changed: 287 additions & 13 deletions

File tree

‎docs/V1_API_COMMANDS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1197,6 +1197,10 @@ A mop route is sent only when the model supports both route setting (`is_clean_r
11971197

11981198
Parameters: List with a dictionary, e.g. `[{"fan_power": 102, "water_box_mode": 202}]`. `mop_mode` is added where the table says so.
11991199

1200+
`StatusTrait.supported_cleaning_settings` (helper `get_supported_settings`) lists the cleaning settings a model has at all, independent of the current cleaning mode, so a consumer can decide which settings to offer without combining feature flags. It is the set of settings that are adjustable in at least one regular cleaning mode: the fan speed always; the water mode when the model has a mop (`is_support_water_mode`); the mop route when the model has a mop and the shake module (`is_shake_mop_set_supported`) and either a mop-only mode (`is_pure_clean_mop_supported`) or the fast route outside mopping (`is_clean_route_fast_mode_supported` with route setting). The `fan_speed_options`/`water_mode_options`/`mop_route_options` lists and their `_mapping` dicts are empty for a setting the model does not have (the fan speed is never empty). The cleaning mode select has no entry in the set: it exists exactly when `cleaning_mode_options` is not empty, which is the case when `is_support_water_mode` is true. Whether a setting can be changed right now is still `is_fan_speed_adjustable`, `is_water_mode_adjustable` and `is_mop_route_adjustable`.
1201+
1202+
When the robot reports SmartPlan or custom codes (for example `106`/`204`/`302` or `110`/`209`/`306`) the adjustable, display and setter rules treat it as being in that mode, even if the model lacks the SmartPlan or custom support flags and `current_cleaning_mode` is therefore `None` (helper `get_reported_special_mode`). In that state the display options show only the SmartPlan or custom value, the settings are not adjustable and the setters raise `RoborockUnsupportedFeature`. `current_cleaning_mode` itself is unchanged.
1203+
12001204
`StatusTrait` setters: `set_fan_speed`, `set_water_mode` and `set_mop_route` only work when the matching `is_fan_speed_adjustable`, `is_water_mode_adjustable` or `is_mop_route_adjustable` is true, and only accept the values valid in the current cleaning mode, which are the same values that `fan_speed_display_options`, `water_mode_display_options` and `mop_route_display_options` list (`fan_speed_options`, `water_mode_options` and `mop_route_options` stay the model's full lists). SmartPlan, custom and unknown modes, and values that are not offered in the current mode, raise `RoborockUnsupportedFeature`; nothing is sent. They raise `RoborockException` when the status has not been loaded yet. Water slide codes `221`-`250` are accepted when the model supports water slide mode. After the commands succeed the local status fields are updated. Devices without a mop (`is_support_water_mode` false) have no water mode: `set_fan_speed` only needs the fan power loaded and sends only `set_custom_mode`.
12011205

12021206
The lists depend on the cleaning mode, following the mode tabs of the robot settings:

‎roborock/data/v1/v1_clean_modes.py‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,26 @@ def get_adjustable_settings(mode: CleaningMode | None, features: DeviceFeatures)
226226
return frozenset(settings)
227227

228228

229+
def get_supported_settings(features: DeviceFeatures) -> frozenset[CleaningSetting]:
230+
"""Return the cleaning settings the model has at all, whatever the current cleaning mode.
231+
232+
This is the set of settings that can be adjusted in at least one regular cleaning
233+
mode. The fan speed is on every model. The water mode needs a mop module. The mop
234+
route needs water mode, the shake module, and either the mop-only tab or fast mode
235+
with the route setting.
236+
"""
237+
settings = {CleaningSetting.FAN_SPEED}
238+
if not features.is_support_water_mode:
239+
return frozenset(settings)
240+
settings.add(CleaningSetting.WATER_MODE)
241+
if features.is_shake_mop_set_supported and (
242+
features.is_pure_clean_mop_supported
243+
or (features.is_clean_route_fast_mode_supported and features.is_clean_route_setting_supported)
244+
):
245+
settings.add(CleaningSetting.MOP_ROUTE)
246+
return frozenset(settings)
247+
248+
229249
def get_mode_options(
230250
setting: CleaningSetting,
231251
mode: CleaningMode | None,
@@ -674,6 +694,32 @@ def _classify_cleaning_mode(
674694
return CleaningMode.VAC_AND_MOP
675695

676696

697+
def get_reported_special_mode(
698+
clean_mode: int | VacuumModes | None,
699+
water_mode: int | WaterModes | None,
700+
mop_mode: int | CleanRoutes | None,
701+
features: DeviceFeatures,
702+
) -> CleaningMode | None:
703+
"""Return CUSTOM or SMART_MODE when the reported codes say the robot is in that mode.
704+
705+
The codes decide, whatever the model's support flags say: a robot that reports
706+
custom or SmartPlan values is in that mode, even if get_current_cleaning_mode
707+
returns None because the mode is not in get_cleaning_mode_options. Custom is
708+
checked before SmartPlan. Devices without a mop only report the fan power.
709+
"""
710+
clean_enum = _resolve_clean_mode(clean_mode, features)
711+
if not features.is_support_water_mode:
712+
water_enum, mop_enum = None, None
713+
else:
714+
water_enum = _resolve_water_mode(water_mode, features)
715+
mop_enum = _resolve_mode_code(mop_mode, CleanRoutes)
716+
if is_mode_customized(clean_enum, water_enum, mop_enum):
717+
return CleaningMode.CUSTOM
718+
if is_smart_mode_set(water_enum, clean_enum, mop_enum):
719+
return CleaningMode.SMART_MODE
720+
return None
721+
722+
677723
def is_mode_customized(
678724
clean_mode: VacuumModes | None,
679725
water_mode: WaterModes | None,

‎roborock/devices/traits/v1/status.py‎

Lines changed: 39 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,9 @@
2121
get_fan_speed_name,
2222
get_mop_route_name,
2323
get_motor_mode_commands,
24+
get_reported_special_mode,
2425
get_setting_change_codes,
26+
get_supported_settings,
2527
get_water_mode_mapping,
2628
get_water_mode_name,
2729
get_water_modes,
@@ -100,16 +102,34 @@ def fan_speed_options(self) -> list[VacuumModes]:
100102
def fan_speed_mapping(self) -> dict[int, str]:
101103
return {fan.code: fan.value for fan in self.fan_speed_options}
102104

105+
@property
106+
def supported_cleaning_settings(self) -> frozenset[CleaningSetting]:
107+
"""The cleaning settings this model has at all, independent of the current cleaning mode.
108+
109+
Use it to decide which settings to offer. Whether a setting can be changed right
110+
now is is_fan_speed_adjustable, is_water_mode_adjustable and is_mop_route_adjustable.
111+
The options and mapping of a setting the model does not have are empty. The cleaning
112+
mode has no entry here: it exists exactly when cleaning_mode_options is not empty,
113+
which is the case for models with a mop (is_support_water_mode).
114+
"""
115+
return get_supported_settings(self._device_features_trait)
116+
103117
@cached_property
104118
def water_mode_options(self) -> list[WaterModes]:
119+
if CleaningSetting.WATER_MODE not in self.supported_cleaning_settings:
120+
return []
105121
return get_water_modes(self._device_features_trait)
106122

107123
@cached_property
108124
def water_mode_mapping(self) -> dict[int, str]:
125+
if CleaningSetting.WATER_MODE not in self.supported_cleaning_settings:
126+
return {}
109127
return get_water_mode_mapping(self._device_features_trait)
110128

111129
@cached_property
112130
def mop_route_options(self) -> list[CleanRoutes]:
131+
if CleaningSetting.MOP_ROUTE not in self.supported_cleaning_settings:
132+
return []
113133
return get_clean_routes(self._device_features_trait, self._region or "us")
114134

115135
@cached_property
@@ -153,43 +173,55 @@ def current_cleaning_mode_name(self) -> str | None:
153173
return None
154174
return cleaning_mode.value
155175

176+
@property
177+
def _rules_mode(self) -> CleaningMode | None:
178+
"""The mode the adjustable, display and setter rules use.
179+
180+
A reported SmartPlan or custom state counts even when the model lacks the support
181+
flags that would make current_cleaning_mode report it.
182+
"""
183+
special = get_reported_special_mode(
184+
self.fan_power, self.water_box_mode, self.mop_mode, self._device_features_trait
185+
)
186+
return special or self.current_cleaning_mode
187+
156188
@property
157189
def is_fan_speed_adjustable(self) -> bool:
158190
"""Whether the fan speed can be changed in the current cleaning mode."""
159-
adjustable = get_adjustable_settings(self.current_cleaning_mode, self._device_features_trait)
191+
adjustable = get_adjustable_settings(self._rules_mode, self._device_features_trait)
160192
return CleaningSetting.FAN_SPEED in adjustable
161193

162194
@property
163195
def is_water_mode_adjustable(self) -> bool:
164196
"""Whether the water mode can be changed in the current cleaning mode."""
165-
adjustable = get_adjustable_settings(self.current_cleaning_mode, self._device_features_trait)
197+
adjustable = get_adjustable_settings(self._rules_mode, self._device_features_trait)
166198
return CleaningSetting.WATER_MODE in adjustable
167199

168200
@property
169201
def is_mop_route_adjustable(self) -> bool:
170202
"""Whether the mop route can be changed in the current cleaning mode."""
171-
adjustable = get_adjustable_settings(self.current_cleaning_mode, self._device_features_trait)
203+
adjustable = get_adjustable_settings(self._rules_mode, self._device_features_trait)
172204
return CleaningSetting.MOP_ROUTE in adjustable
173205

174206
@property
175207
def fan_speed_display_options(self) -> list[VacuumModes]:
176208
"""Fan speeds to show for the current cleaning mode."""
177209
return get_display_options(
178-
CleaningSetting.FAN_SPEED, self.current_cleaning_mode, self._device_features_trait, self.fan_speed_options
210+
CleaningSetting.FAN_SPEED, self._rules_mode, self._device_features_trait, self.fan_speed_options
179211
)
180212

181213
@property
182214
def water_mode_display_options(self) -> list[WaterModes]:
183215
"""Water modes to show for the current cleaning mode."""
184216
return get_display_options(
185-
CleaningSetting.WATER_MODE, self.current_cleaning_mode, self._device_features_trait, self.water_mode_options
217+
CleaningSetting.WATER_MODE, self._rules_mode, self._device_features_trait, self.water_mode_options
186218
)
187219

188220
@property
189221
def mop_route_display_options(self) -> list[CleanRoutes]:
190222
"""Mop routes to show for the current cleaning mode."""
191223
return get_display_options(
192-
CleaningSetting.MOP_ROUTE, self.current_cleaning_mode, self._device_features_trait, self.mop_route_options
224+
CleaningSetting.MOP_ROUTE, self._rules_mode, self._device_features_trait, self.mop_route_options
193225
)
194226

195227
async def set_cleaning_mode(self, cleaning_mode: str | CleaningMode) -> None:
@@ -219,7 +251,7 @@ async def _set_cleaning_setting(self, setting: CleaningSetting, code: int) -> No
219251
fan_power, water_box_mode, mop_mode = get_setting_change_codes(
220252
setting,
221253
code,
222-
self.current_cleaning_mode,
254+
self._rules_mode,
223255
features,
224256
self._region or "us",
225257
fan_power=self.fan_power,

‎tests/data/v1/test_v1_clean_modes.py‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
"""Tests for the pure V1 cleaning mode helpers."""
22

3+
import itertools
4+
35
import pytest
46

57
from roborock.data.v1.v1_clean_modes import (
@@ -13,9 +15,12 @@
1315
get_clean_modes,
1416
get_clean_routes,
1517
get_cleaning_mode_codes,
18+
get_cleaning_mode_options,
1619
get_display_options,
1720
get_motor_mode_commands,
21+
get_reported_special_mode,
1822
get_setting_change_codes,
23+
get_supported_settings,
1924
get_water_modes,
2025
)
2126
from roborock.device_features import DeviceFeatures
@@ -551,3 +556,108 @@ def test_fan_speed_display_options_keep_full_list_without_a_mop() -> None:
551556
options = get_clean_modes(features)
552557
assert VacuumModes.MAX_PLUS in options
553558
assert get_display_options(CleaningSetting.FAN_SPEED, None, features, options) == options
559+
560+
561+
_FAN = CleaningSetting.FAN_SPEED
562+
_WATER = CleaningSetting.WATER_MODE
563+
_ROUTE = CleaningSetting.MOP_ROUTE
564+
565+
566+
@pytest.mark.parametrize(
567+
("overrides", "expected"),
568+
[
569+
# Vacuum-only: no mop module, so only the fan speed.
570+
({"is_support_water_mode": False}, frozenset({_FAN})),
571+
# Saros-like: shake module with fast route, mop-only tab and water slide.
572+
(
573+
{"is_pure_clean_mop_supported": True, "is_water_slide_mode_supported": True},
574+
frozenset({_FAN, _WATER, _ROUTE}),
575+
),
576+
# Shake module without fast route but with a mop-only tab: the route exists in mop mode.
577+
(
578+
{"is_pure_clean_mop_supported": True, "is_clean_route_fast_mode_supported": False},
579+
frozenset({_FAN, _WATER, _ROUTE}),
580+
),
581+
# Shake module without mop-only tab and without fast route: the route is never adjustable.
582+
(
583+
{"is_pure_clean_mop_supported": False, "is_clean_route_fast_mode_supported": False},
584+
frozenset({_FAN, _WATER}),
585+
),
586+
# Spin or roller mop: route setting without the shake module.
587+
({"is_shake_mop_set_supported": False, "is_pure_clean_mop_supported": True}, frozenset({_FAN, _WATER})),
588+
({"is_shake_mop_set_supported": False}, frozenset({_FAN, _WATER})),
589+
# Clean efficiency only changes the route values.
590+
(
591+
{"is_pure_clean_mop_supported": True, "is_clean_efficiency_supported": True},
592+
frozenset({_FAN, _WATER, _ROUTE}),
593+
),
594+
# Max+ without a mop-only tab only changes the route values.
595+
({"is_none_pure_clean_mop_with_max_plus": True}, frozenset({_FAN, _WATER, _ROUTE})),
596+
],
597+
)
598+
def test_get_supported_settings(overrides: dict[str, bool], expected: frozenset[CleaningSetting]) -> None:
599+
assert get_supported_settings(_features(**overrides)) == expected
600+
601+
602+
_GRID_FLAGS = (
603+
"is_shake_mop_set_supported",
604+
"is_clean_route_fast_mode_supported",
605+
"is_pure_clean_mop_supported",
606+
"is_support_water_mode",
607+
"is_clean_route_setting_supported",
608+
"is_clean_efficiency_supported",
609+
"is_none_pure_clean_mop_with_max_plus",
610+
)
611+
612+
613+
@pytest.mark.parametrize("values", list(itertools.product((False, True), repeat=len(_GRID_FLAGS))))
614+
def test_supported_settings_match_adjustable_settings(values: tuple[bool, ...]) -> None:
615+
"""A setting is supported exactly when it can be adjusted in at least one reachable cleaning mode."""
616+
features = _features(**dict(zip(_GRID_FLAGS, values, strict=True)))
617+
reachable: list[CleaningMode | None] = [
618+
mode
619+
for mode in get_cleaning_mode_options(features)
620+
if mode not in (CleaningMode.SMART_MODE, CleaningMode.CUSTOM)
621+
] or [None]
622+
adjustable_somewhere: set[CleaningSetting] = set()
623+
for mode in reachable:
624+
adjustable_somewhere |= get_adjustable_settings(mode, features)
625+
assert get_supported_settings(features) == adjustable_somewhere
626+
627+
628+
@pytest.mark.parametrize(
629+
("fan", "water", "route", "expected"),
630+
[
631+
# Custom wins over SmartPlan when both are reported.
632+
(106, 202, 300, CleaningMode.CUSTOM),
633+
(102, 204, 300, CleaningMode.CUSTOM),
634+
(102, 202, 302, CleaningMode.CUSTOM),
635+
(106, 209, 300, CleaningMode.CUSTOM),
636+
(110, 202, 300, CleaningMode.SMART_MODE),
637+
(102, 209, 300, CleaningMode.SMART_MODE),
638+
(102, 202, 306, CleaningMode.SMART_MODE),
639+
# Regular codes, including a water slide position and the fast route, are not special.
640+
(102, 202, 300, None),
641+
(102, 235, 304, None),
642+
],
643+
)
644+
def test_get_reported_special_mode(fan: int, water: int, route: int, expected: CleaningMode | None) -> None:
645+
features = _features(is_pure_clean_mop_supported=True)
646+
assert get_reported_special_mode(fan, water, route, features) == expected
647+
648+
649+
@pytest.mark.parametrize(
650+
("fan", "water", "route", "expected"),
651+
[
652+
# Without a mop only the fan power is read, so water and route codes do not count.
653+
(102, 204, 300, None),
654+
(102, 209, 306, None),
655+
(110, 204, 302, CleaningMode.SMART_MODE),
656+
(106, 209, 306, CleaningMode.CUSTOM),
657+
],
658+
)
659+
def test_get_reported_special_mode_ignores_water_and_route_without_mop(
660+
fan: int, water: int, route: int, expected: CleaningMode | None
661+
) -> None:
662+
features = _features(is_support_water_mode=False)
663+
assert get_reported_special_mode(fan, water, route, features) == expected

0 commit comments

Comments
 (0)