From 1b2efd8719b90a6ac8b671f1d43e7a2d2fd27ddf Mon Sep 17 00:00:00 2001 From: infy1995 Date: Thu, 12 Nov 2026 20:56:01 +0100 Subject: [PATCH 1/9] feat: add V1 dust collection mode setter and actions --- docs/V1_API_COMMANDS.md | 23 +++- roborock/data/v1/v1_code_mappings.py | 9 +- .../devices/traits/v1/dust_collection_mode.py | 38 +++++- .../traits/v1/test_dust_collection_mode.py | 129 ++++++++++++++++++ 4 files changed, 194 insertions(+), 5 deletions(-) diff --git a/docs/V1_API_COMMANDS.md b/docs/V1_API_COMMANDS.md index 68776ef41..5799774b3 100644 --- a/docs/V1_API_COMMANDS.md +++ b/docs/V1_API_COMMANDS.md @@ -1202,18 +1202,39 @@ Return example: Source: Roborock S7 MaxV Ultra +Saros 10R return example: + +```json + {'mode': 4} +``` + **Supported devices:** * Roborock S7 MaxV Ultra: ✅ * Roborock S8 Pro Ultra: ✅ +* Roborock Saros 10R: ✅ ### set_dust_collection_mode -Description: +Description: Set the dock dust collection mode. Parameters: + mode: 0 smart, 1 light, 2 balanced, 3 strong, 4 max. The app offers 0, 1, 2 and 4. + +Example: + +```json + {'mode': 4} +``` + +Source: Roborock Saros 10R + +**Supported devices:** + +* Roborock Saros 10R: ✅ + ### get_wash_towel_mode Description: diff --git a/roborock/data/v1/v1_code_mappings.py b/roborock/data/v1/v1_code_mappings.py index c5d5037f7..d6a75405f 100644 --- a/roborock/data/v1/v1_code_mappings.py +++ b/roborock/data/v1/v1_code_mappings.py @@ -390,13 +390,18 @@ class RoborockDockTypeCode(RoborockEnum): class RoborockDockDustCollectionModeCode(RoborockEnum): - """Describes the dust collection mode of the vacuum cleaner.""" + """Describes the dust collection mode of the vacuum cleaner. + + Codes follow the Roborock app: 0 smart, 1 quick (``light``), 2 daily (``balanced``), + 3 strong, 4 max. The app offers every mode except ``strong``, which is kept so that + reading it does not fail. + """ - # TODO: Get the correct values for various different docks unknown = -9999 smart = 0 light = 1 balanced = 2 + strong = 3 max = 4 diff --git a/roborock/devices/traits/v1/dust_collection_mode.py b/roborock/devices/traits/v1/dust_collection_mode.py index e738e30d1..72975b35b 100644 --- a/roborock/devices/traits/v1/dust_collection_mode.py +++ b/roborock/devices/traits/v1/dust_collection_mode.py @@ -1,18 +1,52 @@ """Trait for dust collection mode.""" -from roborock.data import DustCollectionMode +from roborock.data import DustCollectionMode, RoborockDockDustCollectionModeCode from roborock.device_features import RoborockDockFeatures from roborock.devices.traits.v1 import common +from roborock.exceptions import RoborockUnsupportedFeature from roborock.roborock_typing import RoborockCommand +_DUST_COLLECTION_MODE_OPTIONS = [ + RoborockDockDustCollectionModeCode.smart, + RoborockDockDustCollectionModeCode.light, + RoborockDockDustCollectionModeCode.balanced, + RoborockDockDustCollectionModeCode.max, +] + def _supports_dust_collection_mode(dock_features: RoborockDockFeatures) -> bool: return dock_features.is_collectable class DustCollectionModeTrait(DustCollectionMode, common.V1TraitMixin): - """Trait for dust collection mode.""" + """Trait for the dock dust collection mode. + + ``set_dust_collection_mode`` changes how strongly the dock empties the + dustbin. ``start_dust_collection`` and ``stop_dust_collection`` control a + manual dust collection directly. + """ command = RoborockCommand.GET_DUST_COLLECTION_MODE converter = common.DefaultConverter(DustCollectionMode) requires_dock_features = _supports_dust_collection_mode + + @property + def dust_collection_mode_options(self) -> list[RoborockDockDustCollectionModeCode]: + """Return the dust collection modes offered by the app.""" + return list(_DUST_COLLECTION_MODE_OPTIONS) + + async def set_dust_collection_mode(self, mode: RoborockDockDustCollectionModeCode) -> None: + """Set the dust collection mode.""" + if mode not in self.dust_collection_mode_options: + raise RoborockUnsupportedFeature(f"Dust collection mode {mode.name} is not supported") + await self.rpc_channel.send_command(RoborockCommand.SET_DUST_COLLECTION_MODE, params={"mode": mode.value}) + # Optimistic update to avoid an extra refresh + self.mode = mode + + async def start_dust_collection(self) -> None: + """Start a manual dust collection.""" + await self.rpc_channel.send_command(RoborockCommand.APP_START_COLLECT_DUST) + + async def stop_dust_collection(self) -> None: + """Stop the running dust collection.""" + await self.rpc_channel.send_command(RoborockCommand.APP_STOP_COLLECT_DUST) diff --git a/tests/devices/traits/v1/test_dust_collection_mode.py b/tests/devices/traits/v1/test_dust_collection_mode.py index f8e847b4d..3255179df 100644 --- a/tests/devices/traits/v1/test_dust_collection_mode.py +++ b/tests/devices/traits/v1/test_dust_collection_mode.py @@ -7,6 +7,7 @@ from roborock.data import RoborockDockDustCollectionModeCode, RoborockDockTypeCode from roborock.devices.device import RoborockDevice from roborock.devices.traits.v1.dust_collection_mode import DustCollectionModeTrait +from roborock.exceptions import RoborockException, RoborockUnsupportedFeature from roborock.roborock_typing import RoborockCommand from tests.devices.traits.v1.helpers import dock_types_with_capability @@ -60,3 +61,131 @@ async def test_unsupported_dust_collection_mode( ) -> None: """Test that the trait is not available for unsupported dock types.""" assert dust_collection_mode is None + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +async def test_options( + dust_collection_mode: DustCollectionModeTrait | None, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test the dust collection modes offered by the app.""" + assert dust_collection_mode is not None + assert dust_collection_mode.dust_collection_mode_options == [ + RoborockDockDustCollectionModeCode.smart, + RoborockDockDustCollectionModeCode.light, + RoborockDockDustCollectionModeCode.balanced, + RoborockDockDustCollectionModeCode.max, + ] + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize( + ("mode"), + [ + RoborockDockDustCollectionModeCode.smart, + RoborockDockDustCollectionModeCode.light, + RoborockDockDustCollectionModeCode.balanced, + RoborockDockDustCollectionModeCode.max, + ], +) +async def test_set_dust_collection_mode( + dust_collection_mode: DustCollectionModeTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + mode: RoborockDockDustCollectionModeCode, +) -> None: + """Test setting an offered dust collection mode.""" + assert dust_collection_mode is not None + + await dust_collection_mode.set_dust_collection_mode(mode) + + mock_rpc_channel.send_command.assert_called_once_with( + RoborockCommand.SET_DUST_COLLECTION_MODE, params={"mode": mode.value} + ) + assert dust_collection_mode.mode == mode + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize( + ("mode"), + [RoborockDockDustCollectionModeCode.strong, RoborockDockDustCollectionModeCode.unknown], +) +async def test_set_rejects_unoffered( + dust_collection_mode: DustCollectionModeTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + mode: RoborockDockDustCollectionModeCode, +) -> None: + """Test that a mode the app does not offer is rejected without sending.""" + assert dust_collection_mode is not None + + with pytest.raises(RoborockUnsupportedFeature): + await dust_collection_mode.set_dust_collection_mode(mode) + + mock_rpc_channel.send_command.assert_not_called() + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +async def test_set_failure_keeps_state( + dust_collection_mode: DustCollectionModeTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that a failed command leaves the mode unchanged.""" + assert dust_collection_mode is not None + dust_collection_mode.mode = RoborockDockDustCollectionModeCode.max + mock_rpc_channel.send_command.side_effect = RoborockException("boom") + + with pytest.raises(RoborockException): + await dust_collection_mode.set_dust_collection_mode(RoborockDockDustCollectionModeCode.smart) + + assert dust_collection_mode.mode == RoborockDockDustCollectionModeCode.max + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize( + ("response", "expected"), + [ + ({"mode": 4}, RoborockDockDustCollectionModeCode.max), # Saros 10R + ({"mode": 3}, RoborockDockDustCollectionModeCode.strong), + ({"mode": 5}, RoborockDockDustCollectionModeCode.unknown), + ], +) +async def test_refresh_unknown_code( + dust_collection_mode: DustCollectionModeTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + response: dict[str, int], + expected: RoborockDockDustCollectionModeCode, +) -> None: + """Test that refresh decodes known codes and tolerates unknown ones.""" + assert dust_collection_mode is not None + mock_rpc_channel.send_command.side_effect = [response] + + await dust_collection_mode.refresh() + + mock_rpc_channel.send_command.assert_called_once_with(RoborockCommand.GET_DUST_COLLECTION_MODE) + assert dust_collection_mode.mode == expected + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize( + ("method_name", "command"), + [ + ("start_dust_collection", RoborockCommand.APP_START_COLLECT_DUST), + ("stop_dust_collection", RoborockCommand.APP_STOP_COLLECT_DUST), + ], +) +async def test_dust_collection_actions( + dust_collection_mode: DustCollectionModeTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + method_name: str, + command: RoborockCommand, +) -> None: + """Test starting and stopping a manual dust collection.""" + assert dust_collection_mode is not None + + await getattr(dust_collection_mode, method_name)() + + mock_rpc_channel.send_command.assert_called_once_with(command) From 3dfce1d50e748772fbb3fd9af1d4b0705a3e369b Mon Sep 17 00:00:00 2001 From: infy1995 Date: Thu, 12 Nov 2026 20:56:08 +0100 Subject: [PATCH 2/9] feat: add V1 dust collection frequency trait --- docs/V1_API_COMMANDS.md | 44 ++++++ roborock/data/v1/v1_code_mappings.py | 9 ++ roborock/data/v1/v1_containers.py | 8 + roborock/devices/traits/v1/__init__.py | 4 + .../traits/v1/dust_collection_frequency.py | 45 ++++++ .../v1/test_dust_collection_frequency.py | 144 ++++++++++++++++++ 6 files changed, 254 insertions(+) create mode 100644 roborock/devices/traits/v1/dust_collection_frequency.py create mode 100644 tests/devices/traits/v1/test_dust_collection_frequency.py diff --git a/docs/V1_API_COMMANDS.md b/docs/V1_API_COMMANDS.md index 5799774b3..0fc0bf9c1 100644 --- a/docs/V1_API_COMMANDS.md +++ b/docs/V1_API_COMMANDS.md @@ -32,6 +32,7 @@ Commands can have multiple parameters that can change from one model to another. * [get_customize_clean_mode](#get_customize_clean_mode) * [get_dnd_timer](#get_dnd_timer) * [get_dust_collection_mode](#get_dust_collection_mode) +* [get_dust_collection_switch_status](#get_dust_collection_switch_status) * [get_clean_follow_ground_material_status](#get_clean_follow_ground_material_status) * [get_identify_furniture_status](#get_identify_furniture_status) * [get_identify_ground_material_status](#get_identify_ground_material_status) @@ -66,6 +67,7 @@ Commands can have multiple parameters that can change from one model to another. * [set_customize_clean_mode](#set_customize_clean_mode) * [set_dnd_timer](#set_dnd_timer) * [set_dust_collection_mode](#set_dust_collection_mode) +* [set_dust_collection_switch_status](#set_dust_collection_switch_status) * [set_fds_endpoint](#set_fds_endpoint) * [set_identify_furniture_status](#set_identify_furniture_status) * [set_identify_ground_material_status](#set_identify_ground_material_status) @@ -1235,6 +1237,48 @@ Source: Roborock Saros 10R * Roborock Saros 10R: ✅ +### get_dust_collection_switch_status + +Description: Get how often the dock empties the dustbin automatically (app: auto-empty frequency). + +Parameters: None + +Returns: + + status: 0 off, 1 balanced, 2 high. Mirrors `auto_dust_collection` in `get_status`. + +Return example: + +```json + {'status': 2} +``` + +Source: Roborock Saros 10R + +**Supported devices:** + +* Roborock Saros 10R: ✅ + +### set_dust_collection_switch_status + +Description: Set how often the dock empties the dustbin automatically. + +Parameters: + + status: 0 off, 1 balanced, 2 high. + +Example: + +```json + {'status': 2} +``` + +Source: Roborock Saros 10R + +**Supported devices:** + +* Roborock Saros 10R: ✅ + ### get_wash_towel_mode Description: diff --git a/roborock/data/v1/v1_code_mappings.py b/roborock/data/v1/v1_code_mappings.py index d6a75405f..3bbd4ba64 100644 --- a/roborock/data/v1/v1_code_mappings.py +++ b/roborock/data/v1/v1_code_mappings.py @@ -405,6 +405,15 @@ class RoborockDockDustCollectionModeCode(RoborockEnum): max = 4 +class RoborockDockDustCollectionFrequencyCode(RoborockEnum): + """Describes how often the dock empties the dustbin automatically (app: auto-empty frequency).""" + + unknown = -1 + off = 0 + balanced = 1 + high = 2 + + class RoborockStateCode(RoborockEnum): unknown = 0 starting = 1 diff --git a/roborock/data/v1/v1_containers.py b/roborock/data/v1/v1_containers.py index 65bcba64a..3a42ca78e 100644 --- a/roborock/data/v1/v1_containers.py +++ b/roborock/data/v1/v1_containers.py @@ -27,6 +27,7 @@ DustBagStatus, RoborockChargeStatus, RoborockCleanType, + RoborockDockDustCollectionFrequencyCode, RoborockDockDustCollectionModeCode, RoborockDockErrorCode, RoborockDockState, @@ -510,6 +511,13 @@ class DustCollectionMode(RoborockBase): mode: RoborockDockDustCollectionModeCode | None = None +@dataclass +class DustCollectionFrequency(RoborockBase): + """Automatic dust collection frequency, as returned by GET_DUST_COLLECTION_SWITCH_STATUS.""" + + status: RoborockDockDustCollectionFrequencyCode | None = None + + @dataclass class WashTowelMode(RoborockBase): wash_mode: WashTowelModes | None = None diff --git a/roborock/devices/traits/v1/__init__.py b/roborock/devices/traits/v1/__init__.py index d8af621b2..6bf7f3c1b 100644 --- a/roborock/devices/traits/v1/__init__.py +++ b/roborock/devices/traits/v1/__init__.py @@ -77,6 +77,7 @@ customize_clean_mode, device_features, do_not_disturb, + dust_collection_frequency, dust_collection_mode, flow_led_status, home, @@ -102,6 +103,7 @@ from .customize_clean_mode import CustomizeCleanModeTrait from .device_features import DeviceFeaturesTrait from .do_not_disturb import DoNotDisturbTrait +from .dust_collection_frequency import DustCollectionFrequencyTrait from .dust_collection_mode import DustCollectionModeTrait from .flow_led_status import FlowLedStatusTrait from .home import HomeTrait @@ -131,6 +133,7 @@ "customize_clean_mode", "device_features", "do_not_disturb", + "dust_collection_frequency", "dust_collection_mode", "flow_led_status", "home", @@ -178,6 +181,7 @@ class PropertiesApi(Trait): flow_led_status: FlowLedStatusTrait | None = None valley_electricity_timer: ValleyElectricityTimerTrait | None = None dust_collection_mode: DustCollectionModeTrait | None = None + dust_collection_frequency: DustCollectionFrequencyTrait | None = None wash_towel_mode: WashTowelModeTrait | None = None smart_wash_params: SmartWashParamsTrait | None = None obstacle_photos: ObstaclePhotoTrait | None = None diff --git a/roborock/devices/traits/v1/dust_collection_frequency.py b/roborock/devices/traits/v1/dust_collection_frequency.py new file mode 100644 index 000000000..95f5943d5 --- /dev/null +++ b/roborock/devices/traits/v1/dust_collection_frequency.py @@ -0,0 +1,45 @@ +"""Trait for the automatic dust collection frequency.""" + +from roborock.data import DustCollectionFrequency, RoborockDockDustCollectionFrequencyCode +from roborock.device_features import RoborockDockFeatures +from roborock.devices.traits.v1 import common +from roborock.exceptions import RoborockUnsupportedFeature +from roborock.roborock_typing import RoborockCommand + +_FREQUENCY_OPTIONS = [ + RoborockDockDustCollectionFrequencyCode.off, + RoborockDockDustCollectionFrequencyCode.balanced, + RoborockDockDustCollectionFrequencyCode.high, +] + + +def _supports_dust_collection_frequency(dock_features: RoborockDockFeatures) -> bool: + return dock_features.is_collectable + + +class DustCollectionFrequencyTrait(DustCollectionFrequency, common.V1TraitMixin): + """Automatic dust collection frequency of the dock (app: auto-empty frequency). + + The same value is reported as ``auto_dust_collection`` on the device status, + which only picks up a change made here on its next refresh. Verified on the + Saros 10R; other collecting docks are assumed to answer the same command. + """ + + command = RoborockCommand.GET_DUST_COLLECTION_SWITCH_STATUS + converter = common.DefaultConverter(DustCollectionFrequency) + requires_dock_features = _supports_dust_collection_frequency + + @property + def frequency_options(self) -> list[RoborockDockDustCollectionFrequencyCode]: + """Return the auto-empty frequencies offered by the app.""" + return list(_FREQUENCY_OPTIONS) + + async def set_frequency(self, frequency: RoborockDockDustCollectionFrequencyCode) -> None: + """Set the automatic dust collection frequency.""" + if frequency not in self.frequency_options: + raise RoborockUnsupportedFeature(f"Dust collection frequency {frequency.name} is not supported") + await self.rpc_channel.send_command( + RoborockCommand.SET_DUST_COLLECTION_SWITCH_STATUS, params={"status": frequency.value} + ) + # Optimistic update to avoid an extra refresh + self.status = frequency diff --git a/tests/devices/traits/v1/test_dust_collection_frequency.py b/tests/devices/traits/v1/test_dust_collection_frequency.py new file mode 100644 index 000000000..bd624b283 --- /dev/null +++ b/tests/devices/traits/v1/test_dust_collection_frequency.py @@ -0,0 +1,144 @@ +"""Tests for the DustCollectionFrequencyTrait class.""" + +from unittest.mock import AsyncMock + +import pytest + +from roborock.data import RoborockDockDustCollectionFrequencyCode, RoborockDockTypeCode +from roborock.devices.device import RoborockDevice +from roborock.devices.traits.v1.dust_collection_frequency import DustCollectionFrequencyTrait +from roborock.exceptions import RoborockException, RoborockUnsupportedFeature +from roborock.roborock_typing import RoborockCommand +from tests.devices.traits.v1.helpers import dock_types_with_capability + + +@pytest.fixture(name="dust_collection_frequency") +def dust_collection_frequency_trait( + device: RoborockDevice, + discover_features_fixture: None, +) -> DustCollectionFrequencyTrait | None: + """Create a DustCollectionFrequencyTrait instance with mocked dependencies.""" + assert device.v1_properties + return device.v1_properties.dust_collection_frequency + + +@pytest.mark.parametrize( + ("dock_type_code"), + dock_types_with_capability("is_collectable"), +) +async def test_dust_collection_frequency_available( + dust_collection_frequency: DustCollectionFrequencyTrait | None, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that the trait is available for collecting docks.""" + assert dust_collection_frequency is not None + + +@pytest.mark.parametrize( + ("dock_type_code"), + dock_types_with_capability("is_collectable", expected=False), +) +async def test_unsupported_dust_collection_frequency( + dust_collection_frequency: DustCollectionFrequencyTrait | None, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that the trait is not available for unsupported dock types.""" + assert dust_collection_frequency is None + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize( + ("response", "expected"), + [ + ({"status": 2}, RoborockDockDustCollectionFrequencyCode.high), # Saros 10R + ({"status": 0}, RoborockDockDustCollectionFrequencyCode.off), + ({"status": 7}, RoborockDockDustCollectionFrequencyCode.unknown), + ], +) +async def test_refresh_unknown_code( + dust_collection_frequency: DustCollectionFrequencyTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + response: dict[str, int], + expected: RoborockDockDustCollectionFrequencyCode, +) -> None: + """Test that refresh decodes known codes and tolerates unknown ones.""" + assert dust_collection_frequency is not None + mock_rpc_channel.send_command.side_effect = [response] + + await dust_collection_frequency.refresh() + + mock_rpc_channel.send_command.assert_called_once_with(RoborockCommand.GET_DUST_COLLECTION_SWITCH_STATUS) + assert dust_collection_frequency.status == expected + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +async def test_options( + dust_collection_frequency: DustCollectionFrequencyTrait | None, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test the auto-empty frequencies offered by the app.""" + assert dust_collection_frequency is not None + assert dust_collection_frequency.frequency_options == [ + RoborockDockDustCollectionFrequencyCode.off, + RoborockDockDustCollectionFrequencyCode.balanced, + RoborockDockDustCollectionFrequencyCode.high, + ] + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize( + ("frequency"), + [ + RoborockDockDustCollectionFrequencyCode.off, + RoborockDockDustCollectionFrequencyCode.balanced, + RoborockDockDustCollectionFrequencyCode.high, + ], +) +async def test_set_frequency( + dust_collection_frequency: DustCollectionFrequencyTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + frequency: RoborockDockDustCollectionFrequencyCode, +) -> None: + """Test setting an offered auto-empty frequency.""" + assert dust_collection_frequency is not None + + await dust_collection_frequency.set_frequency(frequency) + + mock_rpc_channel.send_command.assert_called_once_with( + RoborockCommand.SET_DUST_COLLECTION_SWITCH_STATUS, params={"status": frequency.value} + ) + assert dust_collection_frequency.status == frequency + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +async def test_set_rejects_unoffered( + dust_collection_frequency: DustCollectionFrequencyTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that a frequency the app does not offer is rejected without sending.""" + assert dust_collection_frequency is not None + + with pytest.raises(RoborockUnsupportedFeature): + await dust_collection_frequency.set_frequency(RoborockDockDustCollectionFrequencyCode.unknown) + + mock_rpc_channel.send_command.assert_not_called() + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +async def test_set_failure_keeps_state( + dust_collection_frequency: DustCollectionFrequencyTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that a failed command leaves the frequency unchanged.""" + assert dust_collection_frequency is not None + dust_collection_frequency.status = RoborockDockDustCollectionFrequencyCode.high + mock_rpc_channel.send_command.side_effect = RoborockException("boom") + + with pytest.raises(RoborockException): + await dust_collection_frequency.set_frequency(RoborockDockDustCollectionFrequencyCode.off) + + assert dust_collection_frequency.status == RoborockDockDustCollectionFrequencyCode.high From 4897723f8d2695bfe6ef16c6675a465354dffb94 Mon Sep 17 00:00:00 2001 From: infy1995 Date: Sun, 15 Nov 2026 02:26:36 +0100 Subject: [PATCH 3/9] fix: gate V1 dust collection traits like the app 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. --- docs/V1_DEVICE_FEATURES.md | 8 ++--- roborock/devices/traits/v1/__init__.py | 24 +++++++++++++-- .../traits/v1/dust_collection_frequency.py | 14 ++++++--- .../devices/traits/v1/dust_collection_mode.py | 19 +++++++++--- .../v1/test_dust_collection_frequency.py | 29 ++++++++++++++++++- .../traits/v1/test_dust_collection_mode.py | 28 +++++++++++++++++- 6 files changed, 105 insertions(+), 17 deletions(-) diff --git a/docs/V1_DEVICE_FEATURES.md b/docs/V1_DEVICE_FEATURES.md index f9b0b9e10..01acd4196 100644 --- a/docs/V1_DEVICE_FEATURES.md +++ b/docs/V1_DEVICE_FEATURES.md @@ -200,8 +200,8 @@ An array of integer feature IDs. Feature is supported if ID is present in the ar ### is_dust_collection_setting_supported **Bit Mask:** `33554432` (bit 25) **Feature:** Dust Collection Settings -**Description:** Options for auto-empty dock dust collection frequency and duration. -**Impact:** Configure when and how aggressively the dock empties the dustbin. +**Description:** The app loads and shows the dock's dust collection mode (`get_dust_collection_mode`) only with this feature. The auto-empty frequency does not depend on it. +**Impact:** Gates `DustCollectionModeTrait`, together with `is_collect_dust_mode_supported` and a collecting dock. --- @@ -1362,8 +1362,8 @@ These features are enabled/disabled based on specific device model whitelists or ### is_collect_dust_mode_supported **Model Blacklist:** PEARL (all except PEARL) **Feature:** Dust Collection Mode -**Description:** Auto-empty dock dust collection. -**Impact:** Automatic dustbin emptying at dock. +**Description:** Auto-empty dock dust collection. The app shows the dock's dust collection page (mode and auto-empty frequency) only with this feature and a collecting dock. +**Impact:** Gates `DustCollectionModeTrait` and `DustCollectionFrequencyTrait`. --- diff --git a/roborock/devices/traits/v1/__init__.py b/roborock/devices/traits/v1/__init__.py index 6bf7f3c1b..40510efd9 100644 --- a/roborock/devices/traits/v1/__init__.py +++ b/roborock/devices/traits/v1/__init__.py @@ -45,6 +45,10 @@ - `requires_dock_features` - If set, this is a function that accepts a `RoborockDockFeatures` and returns a boolean indicating whether the trait is supported for that dock. +Traits that need constructor arguments, or gating on both device and dock features, +are created explicitly in `PropertiesApi.discover_features` and skipped by the +generic discovery loop, so the attributes above have no effect on them. + Additionally, DeviceFeaturesTrait has a method `is_field_supported` that is used to check individual trait field values. This is a more fine grained version to allow optional fields in a dataclass, vs the above feature checks that apply to an entire @@ -103,8 +107,8 @@ from .customize_clean_mode import CustomizeCleanModeTrait from .device_features import DeviceFeaturesTrait from .do_not_disturb import DoNotDisturbTrait -from .dust_collection_frequency import DustCollectionFrequencyTrait -from .dust_collection_mode import DustCollectionModeTrait +from .dust_collection_frequency import DustCollectionFrequencyTrait, supports_dust_collection_frequency +from .dust_collection_mode import DustCollectionModeTrait, supports_dust_collection_mode from .flow_led_status import FlowLedStatusTrait from .home import HomeTrait from .led_status import LedStatusTrait @@ -292,6 +296,19 @@ async def discover_features(self) -> None: wash_towel_mode._rpc_channel = self._get_rpc_channel(wash_towel_mode) # type: ignore[assignment] self.wash_towel_mode = wash_towel_mode + # Dust collection traits need both device and dock features, like the app + if self.dust_collection_mode is None and supports_dust_collection_mode(self.device_features, dock_features): + dust_collection_mode = DustCollectionModeTrait() + dust_collection_mode._rpc_channel = self._get_rpc_channel(dust_collection_mode) + self.dust_collection_mode = dust_collection_mode + + if self.dust_collection_frequency is None and supports_dust_collection_frequency( + self.device_features, dock_features + ): + dust_collection_frequency = DustCollectionFrequencyTrait() + dust_collection_frequency._rpc_channel = self._get_rpc_channel(dust_collection_frequency) + self.dust_collection_frequency = dust_collection_frequency + if self.customize_clean_mode is None and self._is_supported( CustomizeCleanModeTrait, "customize_clean_mode", dock_features ): @@ -315,7 +332,8 @@ async def discover_features(self) -> None: # Union args may not be in declared order item_type = union_args[0] if union_args[1] is type(None) else union_args[1] - if item_type is ObstaclePhotoTrait: + # Created above with constructor arguments or extra gating + if item_type in (ObstaclePhotoTrait, DustCollectionModeTrait, DustCollectionFrequencyTrait): continue if not self._is_supported(item_type, item.name, dock_features): _LOGGER.debug("Trait '%s' not supported, skipping", item.name) diff --git a/roborock/devices/traits/v1/dust_collection_frequency.py b/roborock/devices/traits/v1/dust_collection_frequency.py index 95f5943d5..8f9f83173 100644 --- a/roborock/devices/traits/v1/dust_collection_frequency.py +++ b/roborock/devices/traits/v1/dust_collection_frequency.py @@ -1,7 +1,7 @@ """Trait for the automatic dust collection frequency.""" from roborock.data import DustCollectionFrequency, RoborockDockDustCollectionFrequencyCode -from roborock.device_features import RoborockDockFeatures +from roborock.device_features import DeviceFeatures, RoborockDockFeatures from roborock.devices.traits.v1 import common from roborock.exceptions import RoborockUnsupportedFeature from roborock.roborock_typing import RoborockCommand @@ -13,8 +13,13 @@ ] -def _supports_dust_collection_frequency(dock_features: RoborockDockFeatures) -> bool: - return dock_features.is_collectable +def supports_dust_collection_frequency(device_features: DeviceFeatures, dock_features: RoborockDockFeatures) -> bool: + """Return whether the app shows the auto-empty frequency for this device. + + 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 class DustCollectionFrequencyTrait(DustCollectionFrequency, common.V1TraitMixin): @@ -23,11 +28,12 @@ class DustCollectionFrequencyTrait(DustCollectionFrequency, common.V1TraitMixin) The same value is reported as ``auto_dust_collection`` on the device status, which only picks up a change made here on its next refresh. Verified on the Saros 10R; other collecting docks are assumed to answer the same command. + + Created by ``PropertiesApi`` when ``supports_dust_collection_frequency`` is true. """ command = RoborockCommand.GET_DUST_COLLECTION_SWITCH_STATUS converter = common.DefaultConverter(DustCollectionFrequency) - requires_dock_features = _supports_dust_collection_frequency @property def frequency_options(self) -> list[RoborockDockDustCollectionFrequencyCode]: diff --git a/roborock/devices/traits/v1/dust_collection_mode.py b/roborock/devices/traits/v1/dust_collection_mode.py index 72975b35b..feb1b9727 100644 --- a/roborock/devices/traits/v1/dust_collection_mode.py +++ b/roborock/devices/traits/v1/dust_collection_mode.py @@ -1,7 +1,7 @@ """Trait for dust collection mode.""" from roborock.data import DustCollectionMode, RoborockDockDustCollectionModeCode -from roborock.device_features import RoborockDockFeatures +from roborock.device_features import DeviceFeatures, RoborockDockFeatures from roborock.devices.traits.v1 import common from roborock.exceptions import RoborockUnsupportedFeature from roborock.roborock_typing import RoborockCommand @@ -14,8 +14,18 @@ ] -def _supports_dust_collection_mode(dock_features: RoborockDockFeatures) -> bool: - return dock_features.is_collectable +def supports_dust_collection_mode(device_features: DeviceFeatures, dock_features: RoborockDockFeatures) -> bool: + """Return whether the app shows the dust collection mode for this device. + + The 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``. + """ + return ( + dock_features.is_collectable + and device_features.is_collect_dust_mode_supported + and device_features.is_dust_collection_setting_supported + ) class DustCollectionModeTrait(DustCollectionMode, common.V1TraitMixin): @@ -24,11 +34,12 @@ class DustCollectionModeTrait(DustCollectionMode, common.V1TraitMixin): ``set_dust_collection_mode`` changes how strongly the dock empties the dustbin. ``start_dust_collection`` and ``stop_dust_collection`` control a manual dust collection directly. + + Created by ``PropertiesApi`` when ``supports_dust_collection_mode`` is true. """ command = RoborockCommand.GET_DUST_COLLECTION_MODE converter = common.DefaultConverter(DustCollectionMode) - requires_dock_features = _supports_dust_collection_mode @property def dust_collection_mode_options(self) -> list[RoborockDockDustCollectionModeCode]: diff --git a/tests/devices/traits/v1/test_dust_collection_frequency.py b/tests/devices/traits/v1/test_dust_collection_frequency.py index bd624b283..96aa4d23c 100644 --- a/tests/devices/traits/v1/test_dust_collection_frequency.py +++ b/tests/devices/traits/v1/test_dust_collection_frequency.py @@ -4,13 +4,21 @@ import pytest -from roborock.data import RoborockDockDustCollectionFrequencyCode, RoborockDockTypeCode +from roborock.data import HomeDataDevice, RoborockDockDustCollectionFrequencyCode, RoborockDockTypeCode from roborock.devices.device import RoborockDevice from roborock.devices.traits.v1.dust_collection_frequency import DustCollectionFrequencyTrait from roborock.exceptions import RoborockException, RoborockUnsupportedFeature from roborock.roborock_typing import RoborockCommand +from tests import mock_data from tests.devices.traits.v1.helpers import dock_types_with_capability +SAROS_10R = mock_data.DEVICE_PRODUCT_PAIRS["home_data_device_saros_10r.json"][0] +# The S7 MaxV fixture's newFeatureSet (0x2041), as the test fixtures decode it, lacks the +# dust collection setting bit, which only the mode needs. This is a property of the fixture. +S7_MAXV = mock_data.DEVICE_PRODUCT_PAIRS["home_data_device_s7_maxv.json"][0] +# Q Revo is a Pearl product, for which the app hides the dust collection page. +Q_REVO = mock_data.DEVICE_PRODUCT_PAIRS["home_data_device_q_revo.json"][0] + @pytest.fixture(name="dust_collection_frequency") def dust_collection_frequency_trait( @@ -46,6 +54,25 @@ async def test_unsupported_dust_collection_frequency( assert dust_collection_frequency is None +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize( + ("device_info", "available"), + [(SAROS_10R, True), (S7_MAXV, True), (Q_REVO, False)], + ids=["saros_10r", "fixture_without_dcs", "pearl"], +) +async def test_dust_collection_frequency_device_gating( + dust_collection_frequency: DustCollectionFrequencyTrait | None, + dock_type_code: RoborockDockTypeCode, + device_info: HomeDataDevice, + available: bool, +) -> None: + """Test that the trait follows the app's device gating on a collecting dock. + + Unlike the mode, the frequency does not need the dust collection setting feature. + """ + assert (dust_collection_frequency is not None) is available + + @pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) @pytest.mark.parametrize( ("response", "expected"), diff --git a/tests/devices/traits/v1/test_dust_collection_mode.py b/tests/devices/traits/v1/test_dust_collection_mode.py index 3255179df..0fdfcc324 100644 --- a/tests/devices/traits/v1/test_dust_collection_mode.py +++ b/tests/devices/traits/v1/test_dust_collection_mode.py @@ -4,15 +4,30 @@ import pytest -from roborock.data import RoborockDockDustCollectionModeCode, RoborockDockTypeCode +from roborock.data import HomeDataDevice, RoborockDockDustCollectionModeCode, RoborockDockTypeCode from roborock.devices.device import RoborockDevice from roborock.devices.traits.v1.dust_collection_mode import DustCollectionModeTrait from roborock.exceptions import RoborockException, RoborockUnsupportedFeature from roborock.roborock_typing import RoborockCommand +from tests import mock_data from tests.devices.traits.v1.helpers import dock_types_with_capability DUST_COLLECTION_MODE_DATA = [{"mode": 2}] +# Saros 10R supports the dust collection setting (DCS) and is not a Pearl product. +SAROS_10R = mock_data.DEVICE_PRODUCT_PAIRS["home_data_device_saros_10r.json"][0] +# The S7 MaxV fixture's newFeatureSet (0x2041), as the test fixtures decode it, lacks the +# dust collection setting bit. This is a property of the fixture, not of the real device. +S7_MAXV = mock_data.DEVICE_PRODUCT_PAIRS["home_data_device_s7_maxv.json"][0] +# Q Revo is a Pearl product, for which the app hides the dust collection page. +Q_REVO = mock_data.DEVICE_PRODUCT_PAIRS["home_data_device_q_revo.json"][0] + + +@pytest.fixture(name="device_info") +def saros_10r_device_info() -> HomeDataDevice: + """Default to a device that supports the dust collection mode.""" + return SAROS_10R + @pytest.fixture(name="dust_collection_mode") def dust_collection_mode_trait( @@ -63,6 +78,17 @@ async def test_unsupported_dust_collection_mode( assert dust_collection_mode is None +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize(("device_info"), [S7_MAXV, Q_REVO], ids=["fixture_without_dcs", "pearl"]) +async def test_unsupported_device_dust_collection_mode( + dust_collection_mode: DustCollectionModeTrait | None, + dock_type_code: RoborockDockTypeCode, + device_info: HomeDataDevice, +) -> None: + """Test that the trait follows the app's device gating on a collecting dock.""" + assert dust_collection_mode is None + + @pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) async def test_options( dust_collection_mode: DustCollectionModeTrait | None, From 360e096cfbaabcebbfa00d3be4aa5854dda8df67 Mon Sep 17 00:00:00 2001 From: infy1995 Date: Sun, 15 Nov 2026 10:35:55 +0100 Subject: [PATCH 4/9] docs: clarify explicit trait discovery in v1 traits module --- roborock/devices/traits/v1/__init__.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/roborock/devices/traits/v1/__init__.py b/roborock/devices/traits/v1/__init__.py index 40510efd9..88ad19c5f 100644 --- a/roborock/devices/traits/v1/__init__.py +++ b/roborock/devices/traits/v1/__init__.py @@ -46,8 +46,9 @@ and returns a boolean indicating whether the trait is supported for that dock. Traits that need constructor arguments, or gating on both device and dock features, -are created explicitly in `PropertiesApi.discover_features` and skipped by the -generic discovery loop, so the attributes above have no effect on them. +are created explicitly in `PropertiesApi.discover_features`. Traits gated there by a +`supports_*` helper bypass `_is_supported`, so the attributes above have no effect on +them; the other explicitly created traits are still gated through `_is_supported`. Additionally, DeviceFeaturesTrait has a method `is_field_supported` that is used to check individual trait field values. This is a more fine grained version to allow From 4f7f77c0b5324a3a412f5fb1391e75b290d23488 Mon Sep 17 00:00:00 2001 From: infy1995 Date: Wed, 18 Nov 2026 08:53:43 +0100 Subject: [PATCH 5/9] fix: offer V1 dust collection on every collecting dock 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. --- docs/V1_API_COMMANDS.md | 4 +- docs/V1_DEVICE_FEATURES.md | 10 +- roborock/data/v1/v1_code_mappings.py | 6 +- roborock/devices/traits/v1/__init__.py | 22 ++- roborock/devices/traits/v1/dust_collection.py | 76 +++++++++ .../traits/v1/dust_collection_frequency.py | 51 ------ .../devices/traits/v1/dust_collection_mode.py | 12 +- ...n_frequency.py => test_dust_collection.py} | 152 ++++++++++-------- .../traits/v1/test_dust_collection_mode.py | 23 --- 9 files changed, 186 insertions(+), 170 deletions(-) create mode 100644 roborock/devices/traits/v1/dust_collection.py delete mode 100644 roborock/devices/traits/v1/dust_collection_frequency.py rename tests/devices/traits/v1/{test_dust_collection_frequency.py => test_dust_collection.py} (50%) diff --git a/docs/V1_API_COMMANDS.md b/docs/V1_API_COMMANDS.md index 0fc0bf9c1..e415e3977 100644 --- a/docs/V1_API_COMMANDS.md +++ b/docs/V1_API_COMMANDS.md @@ -1245,7 +1245,7 @@ Parameters: None Returns: - status: 0 off, 1 balanced, 2 high. Mirrors `auto_dust_collection` in `get_status`. + status: 0 off, 1 balanced, 2 high. Devices without new feature string bit 53 only use 0 (off) and 1 (on). Mirrors `auto_dust_collection` in `get_status`. Return example: @@ -1265,7 +1265,7 @@ Description: Set how often the dock empties the dustbin automatically. Parameters: - status: 0 off, 1 balanced, 2 high. + status: 0 off, 1 balanced, 2 high. Devices without new feature string bit 53 only use 0 (off) and 1 (on). Example: diff --git a/docs/V1_DEVICE_FEATURES.md b/docs/V1_DEVICE_FEATURES.md index 01acd4196..c5671be28 100644 --- a/docs/V1_DEVICE_FEATURES.md +++ b/docs/V1_DEVICE_FEATURES.md @@ -200,7 +200,7 @@ An array of integer feature IDs. Feature is supported if ID is present in the ar ### is_dust_collection_setting_supported **Bit Mask:** `33554432` (bit 25) **Feature:** Dust Collection Settings -**Description:** The app loads and shows the dock's dust collection mode (`get_dust_collection_mode`) only with this feature. The auto-empty frequency does not depend on it. +**Description:** The app loads and shows the dock's dust collection mode (`get_dust_collection_mode`) only with this feature. The auto-empty frequency and manual dust collection do not depend on it. **Impact:** Gates `DustCollectionModeTrait`, together with `is_collect_dust_mode_supported` and a collecting dock. --- @@ -762,8 +762,8 @@ These features are encoded as individual bits in the `new_feature_info_str` hex ### is_auto_collection_2_supported **Bit Index:** 53 **Feature:** Auto-Empty 2.0 -**Description:** Second generation auto-empty dock system. -**Impact:** Improved dustbin emptying with better suction and reliability. +**Description:** Second generation auto-empty dock system. With this feature the app offers an auto-empty frequency (off, balanced, high); without it, collecting docks only have an auto-empty on/off switch. +**Impact:** `DustCollectionTrait.frequency_options` includes `high` only with this feature. --- @@ -1362,8 +1362,8 @@ These features are enabled/disabled based on specific device model whitelists or ### is_collect_dust_mode_supported **Model Blacklist:** PEARL (all except PEARL) **Feature:** Dust Collection Mode -**Description:** Auto-empty dock dust collection. The app shows the dock's dust collection page (mode and auto-empty frequency) only with this feature and a collecting dock. -**Impact:** Gates `DustCollectionModeTrait` and `DustCollectionFrequencyTrait`. +**Description:** Auto-empty dock dust collection mode. The app shows the dock's dust collection mode page only with this feature and a collecting dock. The auto-empty frequency and manual dust collection do not depend on it. +**Impact:** Gates `DustCollectionModeTrait`, together with `is_dust_collection_setting_supported` and a collecting dock. --- diff --git a/roborock/data/v1/v1_code_mappings.py b/roborock/data/v1/v1_code_mappings.py index 3bbd4ba64..7e0fbd70b 100644 --- a/roborock/data/v1/v1_code_mappings.py +++ b/roborock/data/v1/v1_code_mappings.py @@ -406,7 +406,11 @@ class RoborockDockDustCollectionModeCode(RoborockEnum): class RoborockDockDustCollectionFrequencyCode(RoborockEnum): - """Describes how often the dock empties the dustbin automatically (app: auto-empty frequency).""" + """Describes how often the dock empties the dustbin automatically (app: auto-empty frequency). + + Devices without the auto-empty frequency only use ``off`` and ``balanced`` (code 1), + which then means auto-empty is on. + """ unknown = -1 off = 0 diff --git a/roborock/devices/traits/v1/__init__.py b/roborock/devices/traits/v1/__init__.py index 88ad19c5f..5a9a6f8b9 100644 --- a/roborock/devices/traits/v1/__init__.py +++ b/roborock/devices/traits/v1/__init__.py @@ -82,7 +82,7 @@ customize_clean_mode, device_features, do_not_disturb, - dust_collection_frequency, + dust_collection, dust_collection_mode, flow_led_status, home, @@ -108,7 +108,7 @@ from .customize_clean_mode import CustomizeCleanModeTrait from .device_features import DeviceFeaturesTrait from .do_not_disturb import DoNotDisturbTrait -from .dust_collection_frequency import DustCollectionFrequencyTrait, supports_dust_collection_frequency +from .dust_collection import DustCollectionTrait from .dust_collection_mode import DustCollectionModeTrait, supports_dust_collection_mode from .flow_led_status import FlowLedStatusTrait from .home import HomeTrait @@ -138,7 +138,7 @@ "customize_clean_mode", "device_features", "do_not_disturb", - "dust_collection_frequency", + "dust_collection", "dust_collection_mode", "flow_led_status", "home", @@ -186,7 +186,7 @@ class PropertiesApi(Trait): flow_led_status: FlowLedStatusTrait | None = None valley_electricity_timer: ValleyElectricityTimerTrait | None = None dust_collection_mode: DustCollectionModeTrait | None = None - dust_collection_frequency: DustCollectionFrequencyTrait | None = None + dust_collection: DustCollectionTrait | None = None wash_towel_mode: WashTowelModeTrait | None = None smart_wash_params: SmartWashParamsTrait | None = None obstacle_photos: ObstaclePhotoTrait | None = None @@ -297,18 +297,16 @@ async def discover_features(self) -> None: wash_towel_mode._rpc_channel = self._get_rpc_channel(wash_towel_mode) # type: ignore[assignment] self.wash_towel_mode = wash_towel_mode - # Dust collection traits need both device and dock features, like the app + # The dust collection mode needs both device and dock features if self.dust_collection_mode is None and supports_dust_collection_mode(self.device_features, dock_features): dust_collection_mode = DustCollectionModeTrait() dust_collection_mode._rpc_channel = self._get_rpc_channel(dust_collection_mode) self.dust_collection_mode = dust_collection_mode - if self.dust_collection_frequency is None and supports_dust_collection_frequency( - self.device_features, dock_features - ): - dust_collection_frequency = DustCollectionFrequencyTrait() - dust_collection_frequency._rpc_channel = self._get_rpc_channel(dust_collection_frequency) - self.dust_collection_frequency = dust_collection_frequency + if self.dust_collection is None and self._is_supported(DustCollectionTrait, "dust_collection", dock_features): + dust_collection = DustCollectionTrait(self.device_features) + dust_collection._rpc_channel = self._get_rpc_channel(dust_collection) # type: ignore[assignment] + self.dust_collection = dust_collection if self.customize_clean_mode is None and self._is_supported( CustomizeCleanModeTrait, "customize_clean_mode", dock_features @@ -334,7 +332,7 @@ async def discover_features(self) -> None: # Union args may not be in declared order item_type = union_args[0] if union_args[1] is type(None) else union_args[1] # Created above with constructor arguments or extra gating - if item_type in (ObstaclePhotoTrait, DustCollectionModeTrait, DustCollectionFrequencyTrait): + if item_type in (ObstaclePhotoTrait, DustCollectionModeTrait): continue if not self._is_supported(item_type, item.name, dock_features): _LOGGER.debug("Trait '%s' not supported, skipping", item.name) diff --git a/roborock/devices/traits/v1/dust_collection.py b/roborock/devices/traits/v1/dust_collection.py new file mode 100644 index 000000000..07a9ef286 --- /dev/null +++ b/roborock/devices/traits/v1/dust_collection.py @@ -0,0 +1,76 @@ +"""Trait for the dock's automatic and manual dust collection.""" + +from functools import cached_property + +from roborock.data import DustCollectionFrequency, RoborockDockDustCollectionFrequencyCode +from roborock.device_features import DeviceFeatures, RoborockDockFeatures +from roborock.devices.traits.v1 import common +from roborock.devices.traits.v1.device_features import DeviceFeaturesTrait +from roborock.exceptions import RoborockUnsupportedFeature +from roborock.roborock_typing import RoborockCommand + + +def _supports_dust_collection(dock_features: RoborockDockFeatures) -> bool: + return dock_features.is_collectable + + +def get_dust_collection_frequencies(features: DeviceFeatures) -> list[RoborockDockDustCollectionFrequencyCode]: + """Return the auto-empty settings a device offers. + + Devices with ``is_auto_collection_2_supported`` (new feature string bit 53) choose + between off, balanced and high. Other collecting docks only switch auto-empty off + (``off``) or on (``balanced``, code 1). + """ + options = [RoborockDockDustCollectionFrequencyCode.off, RoborockDockDustCollectionFrequencyCode.balanced] + if features.is_auto_collection_2_supported: + options.append(RoborockDockDustCollectionFrequencyCode.high) + return options + + +class DustCollectionTrait(DustCollectionFrequency, common.V1TraitMixin): + """Automatic and manual dust collection of a collecting dock. + + ``set_frequency`` changes how often the dock empties the dustbin automatically + (auto-empty frequency, or only on/off without bit 53). The same value is + reported as ``auto_dust_collection`` on the device status, which only picks up + a change made here on its next refresh. ``start_dust_collection`` and + ``stop_dust_collection`` control a manual dust collection directly. + + Verified on the Saros 10R; other collecting docks are assumed to answer the + same commands. + """ + + command = RoborockCommand.GET_DUST_COLLECTION_SWITCH_STATUS + converter = common.DefaultConverter(DustCollectionFrequency) + requires_dock_features = _supports_dust_collection + + def __init__(self, device_feature_trait: DeviceFeaturesTrait) -> None: + super().__init__() + self.device_feature_trait = device_feature_trait + + @cached_property + def frequency_options(self) -> list[RoborockDockDustCollectionFrequencyCode]: + """Return the auto-empty settings this device offers. + + Two options (``off``, ``balanced``) mean the device only has an auto-empty + on/off switch, where ``balanced`` stands for on. + """ + return get_dust_collection_frequencies(self.device_feature_trait) + + async def set_frequency(self, frequency: RoborockDockDustCollectionFrequencyCode) -> None: + """Set the automatic dust collection frequency.""" + if frequency not in self.frequency_options: + raise RoborockUnsupportedFeature(f"Dust collection frequency {frequency.name} is not supported") + await self.rpc_channel.send_command( + RoborockCommand.SET_DUST_COLLECTION_SWITCH_STATUS, params={"status": frequency.value} + ) + # Optimistic update to avoid an extra refresh + self.status = frequency + + async def start_dust_collection(self) -> None: + """Start a manual dust collection.""" + await self.rpc_channel.send_command(RoborockCommand.APP_START_COLLECT_DUST) + + async def stop_dust_collection(self) -> None: + """Stop the running dust collection.""" + await self.rpc_channel.send_command(RoborockCommand.APP_STOP_COLLECT_DUST) diff --git a/roborock/devices/traits/v1/dust_collection_frequency.py b/roborock/devices/traits/v1/dust_collection_frequency.py deleted file mode 100644 index 8f9f83173..000000000 --- a/roborock/devices/traits/v1/dust_collection_frequency.py +++ /dev/null @@ -1,51 +0,0 @@ -"""Trait for the automatic dust collection frequency.""" - -from roborock.data import DustCollectionFrequency, RoborockDockDustCollectionFrequencyCode -from roborock.device_features import DeviceFeatures, RoborockDockFeatures -from roborock.devices.traits.v1 import common -from roborock.exceptions import RoborockUnsupportedFeature -from roborock.roborock_typing import RoborockCommand - -_FREQUENCY_OPTIONS = [ - RoborockDockDustCollectionFrequencyCode.off, - RoborockDockDustCollectionFrequencyCode.balanced, - RoborockDockDustCollectionFrequencyCode.high, -] - - -def supports_dust_collection_frequency(device_features: DeviceFeatures, dock_features: RoborockDockFeatures) -> bool: - """Return whether the app shows the auto-empty frequency for this device. - - 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 - - -class DustCollectionFrequencyTrait(DustCollectionFrequency, common.V1TraitMixin): - """Automatic dust collection frequency of the dock (app: auto-empty frequency). - - The same value is reported as ``auto_dust_collection`` on the device status, - which only picks up a change made here on its next refresh. Verified on the - Saros 10R; other collecting docks are assumed to answer the same command. - - Created by ``PropertiesApi`` when ``supports_dust_collection_frequency`` is true. - """ - - command = RoborockCommand.GET_DUST_COLLECTION_SWITCH_STATUS - converter = common.DefaultConverter(DustCollectionFrequency) - - @property - def frequency_options(self) -> list[RoborockDockDustCollectionFrequencyCode]: - """Return the auto-empty frequencies offered by the app.""" - return list(_FREQUENCY_OPTIONS) - - async def set_frequency(self, frequency: RoborockDockDustCollectionFrequencyCode) -> None: - """Set the automatic dust collection frequency.""" - if frequency not in self.frequency_options: - raise RoborockUnsupportedFeature(f"Dust collection frequency {frequency.name} is not supported") - await self.rpc_channel.send_command( - RoborockCommand.SET_DUST_COLLECTION_SWITCH_STATUS, params={"status": frequency.value} - ) - # Optimistic update to avoid an extra refresh - self.status = frequency diff --git a/roborock/devices/traits/v1/dust_collection_mode.py b/roborock/devices/traits/v1/dust_collection_mode.py index feb1b9727..4afc9ecc2 100644 --- a/roborock/devices/traits/v1/dust_collection_mode.py +++ b/roborock/devices/traits/v1/dust_collection_mode.py @@ -32,8 +32,8 @@ class DustCollectionModeTrait(DustCollectionMode, common.V1TraitMixin): """Trait for the dock dust collection mode. ``set_dust_collection_mode`` changes how strongly the dock empties the - dustbin. ``start_dust_collection`` and ``stop_dust_collection`` control a - manual dust collection directly. + dustbin. Manual dust collection is on ``DustCollectionTrait``, which + every collecting dock has. Created by ``PropertiesApi`` when ``supports_dust_collection_mode`` is true. """ @@ -53,11 +53,3 @@ async def set_dust_collection_mode(self, mode: RoborockDockDustCollectionModeCod await self.rpc_channel.send_command(RoborockCommand.SET_DUST_COLLECTION_MODE, params={"mode": mode.value}) # Optimistic update to avoid an extra refresh self.mode = mode - - async def start_dust_collection(self) -> None: - """Start a manual dust collection.""" - await self.rpc_channel.send_command(RoborockCommand.APP_START_COLLECT_DUST) - - async def stop_dust_collection(self) -> None: - """Stop the running dust collection.""" - await self.rpc_channel.send_command(RoborockCommand.APP_STOP_COLLECT_DUST) diff --git a/tests/devices/traits/v1/test_dust_collection_frequency.py b/tests/devices/traits/v1/test_dust_collection.py similarity index 50% rename from tests/devices/traits/v1/test_dust_collection_frequency.py rename to tests/devices/traits/v1/test_dust_collection.py index 96aa4d23c..36e43b5e1 100644 --- a/tests/devices/traits/v1/test_dust_collection_frequency.py +++ b/tests/devices/traits/v1/test_dust_collection.py @@ -1,4 +1,4 @@ -"""Tests for the DustCollectionFrequencyTrait class.""" +"""Tests for the DustCollectionTrait class.""" from unittest.mock import AsyncMock @@ -6,71 +6,77 @@ from roborock.data import HomeDataDevice, RoborockDockDustCollectionFrequencyCode, RoborockDockTypeCode from roborock.devices.device import RoborockDevice -from roborock.devices.traits.v1.dust_collection_frequency import DustCollectionFrequencyTrait +from roborock.devices.traits.v1.dust_collection import DustCollectionTrait from roborock.exceptions import RoborockException, RoborockUnsupportedFeature from roborock.roborock_typing import RoborockCommand from tests import mock_data from tests.devices.traits.v1.helpers import dock_types_with_capability +# Saros 10R supports the three-level auto-empty frequency (new feature string bit 53). SAROS_10R = mock_data.DEVICE_PRODUCT_PAIRS["home_data_device_saros_10r.json"][0] -# The S7 MaxV fixture's newFeatureSet (0x2041), as the test fixtures decode it, lacks the -# dust collection setting bit, which only the mode needs. This is a property of the fixture. +# The S7 MaxV and Q Revo (Pearl) fixtures lack bit 53, so auto-empty is only on or off. S7_MAXV = mock_data.DEVICE_PRODUCT_PAIRS["home_data_device_s7_maxv.json"][0] -# Q Revo is a Pearl product, for which the app hides the dust collection page. Q_REVO = mock_data.DEVICE_PRODUCT_PAIRS["home_data_device_q_revo.json"][0] +ON_OFF = [RoborockDockDustCollectionFrequencyCode.off, RoborockDockDustCollectionFrequencyCode.balanced] +THREE_LEVELS = [*ON_OFF, RoborockDockDustCollectionFrequencyCode.high] -@pytest.fixture(name="dust_collection_frequency") -def dust_collection_frequency_trait( + +@pytest.fixture(name="device_info") +def saros_10r_device_info() -> HomeDataDevice: + """Default to a device that supports the three-level auto-empty frequency.""" + return SAROS_10R + + +@pytest.fixture(name="dust_collection") +def dust_collection_trait( device: RoborockDevice, discover_features_fixture: None, -) -> DustCollectionFrequencyTrait | None: - """Create a DustCollectionFrequencyTrait instance with mocked dependencies.""" +) -> DustCollectionTrait | None: + """Create a DustCollectionTrait instance with mocked dependencies.""" assert device.v1_properties - return device.v1_properties.dust_collection_frequency + return device.v1_properties.dust_collection @pytest.mark.parametrize( ("dock_type_code"), dock_types_with_capability("is_collectable"), ) -async def test_dust_collection_frequency_available( - dust_collection_frequency: DustCollectionFrequencyTrait | None, +async def test_dust_collection_available( + dust_collection: DustCollectionTrait | None, dock_type_code: RoborockDockTypeCode, ) -> None: """Test that the trait is available for collecting docks.""" - assert dust_collection_frequency is not None + assert dust_collection is not None @pytest.mark.parametrize( ("dock_type_code"), dock_types_with_capability("is_collectable", expected=False), ) -async def test_unsupported_dust_collection_frequency( - dust_collection_frequency: DustCollectionFrequencyTrait | None, +async def test_unsupported_dust_collection( + dust_collection: DustCollectionTrait | None, dock_type_code: RoborockDockTypeCode, ) -> None: """Test that the trait is not available for unsupported dock types.""" - assert dust_collection_frequency is None + assert dust_collection is None @pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) @pytest.mark.parametrize( - ("device_info", "available"), - [(SAROS_10R, True), (S7_MAXV, True), (Q_REVO, False)], - ids=["saros_10r", "fixture_without_dcs", "pearl"], + ("device_info", "expected"), + [(SAROS_10R, THREE_LEVELS), (S7_MAXV, ON_OFF), (Q_REVO, ON_OFF)], + ids=["saros_10r", "s7_maxv", "pearl"], ) -async def test_dust_collection_frequency_device_gating( - dust_collection_frequency: DustCollectionFrequencyTrait | None, +async def test_options( + dust_collection: DustCollectionTrait | None, dock_type_code: RoborockDockTypeCode, device_info: HomeDataDevice, - available: bool, + expected: list[RoborockDockDustCollectionFrequencyCode], ) -> None: - """Test that the trait follows the app's device gating on a collecting dock. - - Unlike the mode, the frequency does not need the dust collection setting feature. - """ - assert (dust_collection_frequency is not None) is available + """Test that every collecting dock gets the trait, with options depending on bit 53.""" + assert dust_collection is not None + assert dust_collection.frequency_options == expected @pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) @@ -83,89 +89,103 @@ async def test_dust_collection_frequency_device_gating( ], ) async def test_refresh_unknown_code( - dust_collection_frequency: DustCollectionFrequencyTrait | None, + dust_collection: DustCollectionTrait | None, mock_rpc_channel: AsyncMock, dock_type_code: RoborockDockTypeCode, response: dict[str, int], expected: RoborockDockDustCollectionFrequencyCode, ) -> None: """Test that refresh decodes known codes and tolerates unknown ones.""" - assert dust_collection_frequency is not None + assert dust_collection is not None mock_rpc_channel.send_command.side_effect = [response] - await dust_collection_frequency.refresh() + await dust_collection.refresh() mock_rpc_channel.send_command.assert_called_once_with(RoborockCommand.GET_DUST_COLLECTION_SWITCH_STATUS) - assert dust_collection_frequency.status == expected + assert dust_collection.status == expected @pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) -async def test_options( - dust_collection_frequency: DustCollectionFrequencyTrait | None, - dock_type_code: RoborockDockTypeCode, -) -> None: - """Test the auto-empty frequencies offered by the app.""" - assert dust_collection_frequency is not None - assert dust_collection_frequency.frequency_options == [ - RoborockDockDustCollectionFrequencyCode.off, - RoborockDockDustCollectionFrequencyCode.balanced, - RoborockDockDustCollectionFrequencyCode.high, - ] - - -@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) -@pytest.mark.parametrize( - ("frequency"), - [ - RoborockDockDustCollectionFrequencyCode.off, - RoborockDockDustCollectionFrequencyCode.balanced, - RoborockDockDustCollectionFrequencyCode.high, - ], -) +@pytest.mark.parametrize(("frequency"), THREE_LEVELS) async def test_set_frequency( - dust_collection_frequency: DustCollectionFrequencyTrait | None, + dust_collection: DustCollectionTrait | None, mock_rpc_channel: AsyncMock, dock_type_code: RoborockDockTypeCode, frequency: RoborockDockDustCollectionFrequencyCode, ) -> None: """Test setting an offered auto-empty frequency.""" - assert dust_collection_frequency is not None + assert dust_collection is not None - await dust_collection_frequency.set_frequency(frequency) + await dust_collection.set_frequency(frequency) mock_rpc_channel.send_command.assert_called_once_with( RoborockCommand.SET_DUST_COLLECTION_SWITCH_STATUS, params={"status": frequency.value} ) - assert dust_collection_frequency.status == frequency + assert dust_collection.status == frequency @pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize( + ("device_info", "frequency"), + [ + (SAROS_10R, RoborockDockDustCollectionFrequencyCode.unknown), + (S7_MAXV, RoborockDockDustCollectionFrequencyCode.high), + ], + ids=["unknown", "high_without_bit_53"], +) async def test_set_rejects_unoffered( - dust_collection_frequency: DustCollectionFrequencyTrait | None, + dust_collection: DustCollectionTrait | None, mock_rpc_channel: AsyncMock, dock_type_code: RoborockDockTypeCode, + device_info: HomeDataDevice, + frequency: RoborockDockDustCollectionFrequencyCode, ) -> None: - """Test that a frequency the app does not offer is rejected without sending.""" - assert dust_collection_frequency is not None + """Test that a frequency the device does not offer is rejected without sending.""" + assert dust_collection is not None with pytest.raises(RoborockUnsupportedFeature): - await dust_collection_frequency.set_frequency(RoborockDockDustCollectionFrequencyCode.unknown) + await dust_collection.set_frequency(frequency) mock_rpc_channel.send_command.assert_not_called() @pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) async def test_set_failure_keeps_state( - dust_collection_frequency: DustCollectionFrequencyTrait | None, + dust_collection: DustCollectionTrait | None, mock_rpc_channel: AsyncMock, dock_type_code: RoborockDockTypeCode, ) -> None: """Test that a failed command leaves the frequency unchanged.""" - assert dust_collection_frequency is not None - dust_collection_frequency.status = RoborockDockDustCollectionFrequencyCode.high + assert dust_collection is not None + dust_collection.status = RoborockDockDustCollectionFrequencyCode.high mock_rpc_channel.send_command.side_effect = RoborockException("boom") with pytest.raises(RoborockException): - await dust_collection_frequency.set_frequency(RoborockDockDustCollectionFrequencyCode.off) + await dust_collection.set_frequency(RoborockDockDustCollectionFrequencyCode.off) + + assert dust_collection.status == RoborockDockDustCollectionFrequencyCode.high + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize(("device_info"), [SAROS_10R, Q_REVO], ids=["saros_10r", "pearl"]) +@pytest.mark.parametrize( + ("method_name", "command"), + [ + ("start_dust_collection", RoborockCommand.APP_START_COLLECT_DUST), + ("stop_dust_collection", RoborockCommand.APP_STOP_COLLECT_DUST), + ], +) +async def test_dust_collection_actions( + dust_collection: DustCollectionTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + device_info: HomeDataDevice, + method_name: str, + command: RoborockCommand, +) -> None: + """Test manual dust collection on every collecting dock, including Pearl products.""" + assert dust_collection is not None + + await getattr(dust_collection, method_name)() - assert dust_collection_frequency.status == RoborockDockDustCollectionFrequencyCode.high + mock_rpc_channel.send_command.assert_called_once_with(command) diff --git a/tests/devices/traits/v1/test_dust_collection_mode.py b/tests/devices/traits/v1/test_dust_collection_mode.py index 0fdfcc324..51a2b0dea 100644 --- a/tests/devices/traits/v1/test_dust_collection_mode.py +++ b/tests/devices/traits/v1/test_dust_collection_mode.py @@ -192,26 +192,3 @@ async def test_refresh_unknown_code( mock_rpc_channel.send_command.assert_called_once_with(RoborockCommand.GET_DUST_COLLECTION_MODE) assert dust_collection_mode.mode == expected - - -@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) -@pytest.mark.parametrize( - ("method_name", "command"), - [ - ("start_dust_collection", RoborockCommand.APP_START_COLLECT_DUST), - ("stop_dust_collection", RoborockCommand.APP_STOP_COLLECT_DUST), - ], -) -async def test_dust_collection_actions( - dust_collection_mode: DustCollectionModeTrait | None, - mock_rpc_channel: AsyncMock, - dock_type_code: RoborockDockTypeCode, - method_name: str, - command: RoborockCommand, -) -> None: - """Test starting and stopping a manual dust collection.""" - assert dust_collection_mode is not None - - await getattr(dust_collection_mode, method_name)() - - mock_rpc_channel.send_command.assert_called_once_with(command) From be749e4c77e107f7c4b01f2d462852bea74e4de4 Mon Sep 17 00:00:00 2001 From: infy1995 Date: Thu, 12 Nov 2026 21:30:18 +0100 Subject: [PATCH 6/9] feat: add V1 wash water temperature trait --- docs/V1_API_COMMANDS.md | 49 +++ roborock/data/v1/v1_code_mappings.py | 11 + roborock/data/v1/v1_containers.py | 8 + roborock/devices/traits/v1/__init__.py | 19 +- .../traits/v1/wash_water_temperature.py | 78 +++++ tests/devices/traits/v1/fixtures.py | 20 +- .../traits/v1/test_wash_water_temperature.py | 278 ++++++++++++++++++ 7 files changed, 460 insertions(+), 3 deletions(-) create mode 100644 roborock/devices/traits/v1/wash_water_temperature.py create mode 100644 tests/devices/traits/v1/test_wash_water_temperature.py diff --git a/docs/V1_API_COMMANDS.md b/docs/V1_API_COMMANDS.md index e415e3977..821cb1ca2 100644 --- a/docs/V1_API_COMMANDS.md +++ b/docs/V1_API_COMMANDS.md @@ -52,6 +52,7 @@ Commands can have multiple parameters that can change from one model to another. * [get_turn_server](#get_turn_server) * [get_valley_electricity_timer](#get_valley_electricity_timer) * [get_wash_towel_mode](#get_wash_towel_mode) +* [get_wash_water_temperature](#get_wash_water_temperature) * [load_multi_map](#load_multi_map) * [name_segment](#name_segment) * [reset_consumable](#reset_consumable) @@ -80,6 +81,7 @@ Commands can have multiple parameters that can change from one model to another. * [set_timezone](#set_timezone) * [set_valley_electricity_timer](#set_valley_electricity_timer) * [set_wash_towel_mode](#set_wash_towel_mode) +* [set_wash_water_temperature](#set_wash_water_temperature) * [set_water_box_custom_mode](#set_water_box_custom_mode) * [start_camera_preview](#start_camera_preview) * [start_edit_map](#start_edit_map) @@ -1328,6 +1330,53 @@ Source: S8 Pro Ultra * Roborock S7 MaxV Ultra: ✅ * Roborock S8 Pro Ultra: ✅ +### get_wash_water_temperature + +Description: Get the water temperature the dock uses to wash the mop (app: water temperature). Available on +washing docks of devices with the hot wash towel feature (`is_hot_wash_towel_supported`). Not available on the +PearlE Pro (a169/a170) unless the dock is a Shell2E Lite. + +Parameters: None + +Returns: + + wash_water_temperature: 0 room temperature, 1 warm, 2 hot, 3 steam, 4 pet steam. + Docks offer 0 and 2; 1 only on docks with neither high temperature water nor steam; 3 only on steam docks. + +Return example: + +```json + {'wash_water_temperature': 2} +``` + +Source: Roborock Saros 10R + +**Supported devices:** + +* Roborock Saros 10R: ✅ + +### set_wash_water_temperature + +Description: Set the water temperature the dock uses to wash the mop. + +Parameters: + + values: 0 room temperature, 1 warm, 2 hot, 3 steam, 4 pet steam. + The key differs from the one `get_wash_water_temperature` returns; `{'wash_water_temperature': 2}` is + rejected with -10007 invalid params. + +Example: + +```json + {'values': 2} +``` + +Source: Roborock Saros 10R + +**Supported devices:** + +* Roborock Saros 10R: ✅ + ### get_collision_avoid_status Description: diff --git a/roborock/data/v1/v1_code_mappings.py b/roborock/data/v1/v1_code_mappings.py index 7e0fbd70b..e7a91dbf9 100644 --- a/roborock/data/v1/v1_code_mappings.py +++ b/roborock/data/v1/v1_code_mappings.py @@ -418,6 +418,17 @@ class RoborockDockDustCollectionFrequencyCode(RoborockEnum): high = 2 +class RoborockDockWashWaterTemperatureCode(RoborockEnum): + """Describes the water temperature the dock uses to wash the mop (app: water temperature).""" + + unknown = -1 + room_temperature = 0 + warm = 1 + hot = 2 + steam = 3 + pet_steam = 4 + + class RoborockStateCode(RoborockEnum): unknown = 0 starting = 1 diff --git a/roborock/data/v1/v1_containers.py b/roborock/data/v1/v1_containers.py index 3a42ca78e..c68695d81 100644 --- a/roborock/data/v1/v1_containers.py +++ b/roborock/data/v1/v1_containers.py @@ -32,6 +32,7 @@ RoborockDockErrorCode, RoborockDockState, RoborockDockTypeCode, + RoborockDockWashWaterTemperatureCode, RoborockErrorCode, RoborockFinishReason, RoborockInCleaning, @@ -484,6 +485,13 @@ class SmartWashParams(RoborockBase): wash_interval: int | None = None +@dataclass +class WashWaterTemperature(RoborockBase): + """Mop wash water temperature, as returned by GET_WASH_WATER_TEMPERATURE.""" + + wash_water_temperature: RoborockDockWashWaterTemperatureCode | None = None + + @dataclass class MopDryerProfile(RoborockBase): """Dryer parameters for one state of the auto mop-drying setting.""" diff --git a/roborock/devices/traits/v1/__init__.py b/roborock/devices/traits/v1/__init__.py index 5a9a6f8b9..3bd4b209d 100644 --- a/roborock/devices/traits/v1/__init__.py +++ b/roborock/devices/traits/v1/__init__.py @@ -99,6 +99,7 @@ valley_electricity_timer, volume, wash_towel_mode, + wash_water_temperature, ) from .child_lock import ChildLockTrait from .clean_summary import CleanSummaryTrait @@ -125,6 +126,7 @@ from .valley_electricity_timer import ValleyElectricityTimerTrait from .volume import SoundVolumeTrait from .wash_towel_mode import WashTowelModeTrait +from .wash_water_temperature import WashWaterTemperatureTrait, is_wash_water_temperature_offered _LOGGER = logging.getLogger(__name__) @@ -155,6 +157,7 @@ "valley_electricity_timer", "volume", "wash_towel_mode", + "wash_water_temperature", ] @@ -189,6 +192,7 @@ class PropertiesApi(Trait): dust_collection: DustCollectionTrait | None = None wash_towel_mode: WashTowelModeTrait | None = None smart_wash_params: SmartWashParamsTrait | None = None + wash_water_temperature: WashWaterTemperatureTrait | None = None obstacle_photos: ObstaclePhotoTrait | None = None mop_dryer: MopDryerTrait | None = None customize_clean_mode: CustomizeCleanModeTrait | None = None @@ -210,6 +214,7 @@ def __init__( ) -> None: """Initialize the V1TraitProps.""" self._device_uid = device_uid + self._product = product self._rpc_channel = rpc_channel self._mqtt_rpc_channel = mqtt_rpc_channel self._map_rpc_channel = map_rpc_channel @@ -297,6 +302,18 @@ async def discover_features(self) -> None: wash_towel_mode._rpc_channel = self._get_rpc_channel(wash_towel_mode) # type: ignore[assignment] self.wash_towel_mode = wash_towel_mode + # The wash water temperature needs a washing dock, a device that can heat wash water, + # and a product and dock for which the app shows it. + if ( + self.wash_water_temperature is None + and self.device_features.is_hot_wash_towel_supported + and is_wash_water_temperature_offered(self._product.product_nickname, dock_features) + and self._is_supported(WashWaterTemperatureTrait, "wash_water_temperature", dock_features) + ): + wash_water_temperature = WashWaterTemperatureTrait(self.device_features) + wash_water_temperature._rpc_channel = self._get_rpc_channel(wash_water_temperature) # type: ignore[assignment] + self.wash_water_temperature = wash_water_temperature + # The dust collection mode needs both device and dock features if self.dust_collection_mode is None and supports_dust_collection_mode(self.device_features, dock_features): dust_collection_mode = DustCollectionModeTrait() @@ -332,7 +349,7 @@ async def discover_features(self) -> None: # Union args may not be in declared order item_type = union_args[0] if union_args[1] is type(None) else union_args[1] # Created above with constructor arguments or extra gating - if item_type in (ObstaclePhotoTrait, DustCollectionModeTrait): + if item_type in (ObstaclePhotoTrait, DustCollectionModeTrait, WashWaterTemperatureTrait): continue if not self._is_supported(item_type, item.name, dock_features): _LOGGER.debug("Trait '%s' not supported, skipping", item.name) diff --git a/roborock/devices/traits/v1/wash_water_temperature.py b/roborock/devices/traits/v1/wash_water_temperature.py new file mode 100644 index 000000000..bbe14ef25 --- /dev/null +++ b/roborock/devices/traits/v1/wash_water_temperature.py @@ -0,0 +1,78 @@ +"""Trait for the mop wash water temperature.""" + +from roborock.data import ( + RoborockDockTypeCode, + RoborockDockWashWaterTemperatureCode, + RoborockProductNickname, + WashWaterTemperature, +) +from roborock.device_features import RoborockDockFeatures +from roborock.devices.traits.v1 import common +from roborock.devices.traits.v1.device_features import DeviceFeaturesTrait +from roborock.exceptions import RoborockUnsupportedFeature +from roborock.roborock_typing import RoborockCommand + + +def get_wash_water_temperatures(dock_features: RoborockDockFeatures) -> list[RoborockDockWashWaterTemperatureCode]: + """Return the wash water temperatures the app offers for a dock, in app order. + + Warm is offered only by docks with neither high temperature water nor steam; steam + only by steam docks. Pet steam is never offered. Known exception: the app for the UltronSV + (a97) also shows warm on its high temperature docks; that needs plugin family detection. + """ + options = [RoborockDockWashWaterTemperatureCode.room_temperature] + if not dock_features.is_high_tmp_water_supported and not dock_features.is_steam_wash_supported: + options.append(RoborockDockWashWaterTemperatureCode.warm) + options.append(RoborockDockWashWaterTemperatureCode.hot) + if dock_features.is_steam_wash_supported: + options.append(RoborockDockWashWaterTemperatureCode.steam) + return options + + +def is_wash_water_temperature_offered( + product_nickname: RoborockProductNickname, dock_features: RoborockDockFeatures +) -> bool: + """Return whether the app shows the wash water temperature for this product and dock. + + The app hides it on the PearlE Pro (``PEARLELITE``) unless the dock is a Shell2E Lite. + """ + return ( + product_nickname != RoborockProductNickname.PEARLELITE + or dock_features.dock_type == RoborockDockTypeCode.shell_2e_lite_dock + ) + + +def _supports_wash_water_temperature(dock_features: RoborockDockFeatures) -> bool: + return dock_features.is_washable + + +class WashWaterTemperatureTrait(WashWaterTemperature, common.V1TraitMixin): + """Water temperature the dock uses to wash the mop (app: water temperature). + + Created only for washing docks on devices with ``is_hot_wash_towel_supported``, and + when ``is_wash_water_temperature_offered`` allows it. + """ + + command = RoborockCommand.GET_WASH_WATER_TEMPERATURE + converter = common.DefaultConverter(WashWaterTemperature) + requires_dock_features = _supports_wash_water_temperature + + def __init__(self, device_feature_trait: DeviceFeaturesTrait) -> None: + super().__init__() + self.device_feature_trait = device_feature_trait + + @property + def wash_water_temperature_options(self) -> list[RoborockDockWashWaterTemperatureCode]: + """Return the wash water temperatures offered by the dock.""" + return get_wash_water_temperatures(self.device_feature_trait.dock_features) + + async def set_wash_water_temperature(self, temperature: RoborockDockWashWaterTemperatureCode) -> None: + """Set the mop wash water temperature.""" + if temperature not in self.wash_water_temperature_options: + raise RoborockUnsupportedFeature(f"Wash water temperature {temperature.name} is not supported") + # The device reads back "wash_water_temperature" but expects the new value under "values". + await self.rpc_channel.send_command( + RoborockCommand.SET_WASH_WATER_TEMPERATURE, params={"values": temperature.value} + ) + # Optimistic update to avoid an extra refresh + self.wash_water_temperature = temperature diff --git a/tests/devices/traits/v1/fixtures.py b/tests/devices/traits/v1/fixtures.py index b760d2589..cacb168e8 100644 --- a/tests/devices/traits/v1/fixtures.py +++ b/tests/devices/traits/v1/fixtures.py @@ -1,6 +1,7 @@ """Fixtures for V1 trait tests.""" from copy import deepcopy +from dataclasses import replace from unittest.mock import AsyncMock, Mock import pytest @@ -76,10 +77,25 @@ def device_info_fixture(trait_home_data: HomeData) -> HomeDataDevice: return trait_home_data.get_all_devices()[0] +@pytest.fixture(name="product_model") +def product_model_fixture() -> str | None: + """Model of the test device's product, e.g. "roborock.vacuum.a144". + + None keeps the fixture's model: the S7 MaxV (a27, TopazSV), which the app treats as an older product. + """ + return None + + @pytest.fixture(name="products") -def products_fixture() -> list[HomeDataProduct]: +def products_fixture(device_info: HomeDataDevice, product_model: str | None) -> list[HomeDataProduct]: """Fixture to provide a Product instance for tests.""" - return [HomeDataProduct.from_dict(product) for product in mock_data.PRODUCTS.values()] + products = [HomeDataProduct.from_dict(product) for product in mock_data.PRODUCTS.values()] + if product_model is None: + return products + return [ + replace(product, model=product_model) if product.id == device_info.product_id else product + for product in products + ] @pytest.fixture(autouse=True, name="device") diff --git a/tests/devices/traits/v1/test_wash_water_temperature.py b/tests/devices/traits/v1/test_wash_water_temperature.py new file mode 100644 index 000000000..c2a2de59d --- /dev/null +++ b/tests/devices/traits/v1/test_wash_water_temperature.py @@ -0,0 +1,278 @@ +"""Tests for the WashWaterTemperatureTrait class.""" + +from unittest.mock import AsyncMock + +import pytest + +from roborock.data import ( + HomeData, + RoborockDockTypeCode, + RoborockDockWashWaterTemperatureCode, + RoborockProductNickname, +) +from roborock.device_features import NewFeatureStrBit, RoborockDockFeatures +from roborock.devices.device import RoborockDevice +from roborock.devices.traits.v1.wash_water_temperature import ( + WashWaterTemperatureTrait, + get_wash_water_temperatures, + is_wash_water_temperature_offered, +) +from roborock.exceptions import RoborockException, RoborockUnsupportedFeature +from roborock.roborock_typing import RoborockCommand +from tests import mock_data +from tests.devices.traits.v1.helpers import dock_types_with_capability + +SAROS_10R_DOCK = RoborockDockTypeCode.shell_3s_dock + + +@pytest.fixture(name="wash_water_temperature") +def wash_water_temperature_trait( + device: RoborockDevice, + discover_features_fixture: None, +) -> WashWaterTemperatureTrait | None: + """Create a WashWaterTemperatureTrait instance with mocked dependencies.""" + assert device.v1_properties + return device.v1_properties.wash_water_temperature + + +@pytest.mark.parametrize( + ("dock_type_code", "expected"), + [ + ( + # Saros 10R: neither high temperature nor steam + RoborockDockTypeCode.shell_3s_dock, + [ + RoborockDockWashWaterTemperatureCode.room_temperature, + RoborockDockWashWaterTemperatureCode.warm, + RoborockDockWashWaterTemperatureCode.hot, + ], + ), + ( + # Steam only + RoborockDockTypeCode.o7h_dock, + [ + RoborockDockWashWaterTemperatureCode.room_temperature, + RoborockDockWashWaterTemperatureCode.hot, + RoborockDockWashWaterTemperatureCode.steam, + ], + ), + ( + # High temperature only: the app hides warm + RoborockDockTypeCode.k1r_dock, + [ + RoborockDockWashWaterTemperatureCode.room_temperature, + RoborockDockWashWaterTemperatureCode.hot, + ], + ), + ], +) +def test_get_wash_water_temperatures( + dock_type_code: RoborockDockTypeCode, + expected: list[RoborockDockWashWaterTemperatureCode], +) -> None: + """Test the temperatures offered for each dock family.""" + assert get_wash_water_temperatures(RoborockDockFeatures.from_dock_type(dock_type_code)) == expected + + +@pytest.mark.parametrize( + ("product_nickname", "dock_type_code", "expected"), + [ + (RoborockProductNickname.CORALPRO, SAROS_10R_DOCK, True), + (RoborockProductNickname.TOPAZSV, RoborockDockTypeCode.shell_2e_lite_dock, True), + (RoborockProductNickname.PEARLELITE, SAROS_10R_DOCK, False), + (RoborockProductNickname.PEARLELITE, RoborockDockTypeCode.shell_e_dock, False), + (RoborockProductNickname.PEARLELITE, RoborockDockTypeCode.shell_2e_lite_dock, True), + ], +) +def test_is_wash_water_temperature_offered( + product_nickname: RoborockProductNickname, + dock_type_code: RoborockDockTypeCode, + expected: bool, +) -> None: + """Test that the PearlE Pro offers the temperature only with a Shell2E Lite dock.""" + dock_features = RoborockDockFeatures.from_dock_type(dock_type_code) + assert is_wash_water_temperature_offered(product_nickname, dock_features) is expected + + +@pytest.mark.parametrize(("product_model"), ["roborock.vacuum.a170"]) # PearlE Pro +@pytest.mark.parametrize( + ("dock_type_code", "available"), + [ + (SAROS_10R_DOCK, False), + (RoborockDockTypeCode.shell_2e_lite_dock, True), + ], +) +async def test_pearl_e_pro_wash_water_temperature( + device: RoborockDevice, + wash_water_temperature: WashWaterTemperatureTrait | None, + product_model: str, + dock_type_code: RoborockDockTypeCode, + available: bool, +) -> None: + """Test that a PearlE Pro gets the temperature trait only on a Shell2E Lite dock.""" + assert device.is_connected + assert (wash_water_temperature is not None) is available + + +@pytest.mark.parametrize( + ("dock_type_code"), + dock_types_with_capability("is_washable"), +) +async def test_wash_water_temperature_available( + wash_water_temperature: WashWaterTemperatureTrait | None, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that the trait is available for washing docks.""" + assert wash_water_temperature is not None + + +@pytest.mark.parametrize( + ("dock_type_code"), + dock_types_with_capability("is_washable", expected=False), +) +async def test_unsupported_wash_water_temperature( + wash_water_temperature: WashWaterTemperatureTrait | None, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that the trait is not available for docks without mop washing.""" + assert wash_water_temperature is None + + +def _home_data_with_hot_wash(supported: bool) -> HomeData: + """Return home data whose device has the hot wash towel feature bit set or cleared.""" + home_data = HomeData.from_dict(mock_data.HOME_DATA_RAW) + device = home_data.get_all_devices()[0] + assert device.new_feature_set is not None + bits = int(device.new_feature_set, 16) + mask = 1 << NewFeatureStrBit.HOT_WASH_TOWEL + bits = bits | mask if supported else bits & ~mask + device.new_feature_set = format(bits, "x").zfill(len(device.new_feature_set)) + return home_data + + +@pytest.fixture(name="trait_home_data") +def trait_home_data_fixture(request: pytest.FixtureRequest) -> HomeData: + """Default to a device that can heat wash water, as the Saros 10R.""" + return getattr(request, "param", _home_data_with_hot_wash(True)) + + +@pytest.mark.parametrize("trait_home_data", [_home_data_with_hot_wash(False)], indirect=True) +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +async def test_unsupported_without_hot_wash( + trait_home_data: HomeData, + device: RoborockDevice, + wash_water_temperature: WashWaterTemperatureTrait | None, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that a washing dock on a device that cannot heat wash water has no temperature trait.""" + assert device.v1_properties + assert device.is_connected + assert not device.v1_properties.device_features.is_hot_wash_towel_supported + assert wash_water_temperature is None + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +@pytest.mark.parametrize( + ("response", "expected"), + [ + ({"wash_water_temperature": 2}, RoborockDockWashWaterTemperatureCode.hot), # Saros 10R + ({"wash_water_temperature": 0}, RoborockDockWashWaterTemperatureCode.room_temperature), + ({"wash_water_temperature": 9}, RoborockDockWashWaterTemperatureCode.unknown), + ], +) +async def test_refresh_unknown_code( + wash_water_temperature: WashWaterTemperatureTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + response: dict[str, int], + expected: RoborockDockWashWaterTemperatureCode, +) -> None: + """Test that refresh decodes known codes and tolerates unknown ones.""" + assert wash_water_temperature is not None + mock_rpc_channel.send_command.side_effect = [response] + + await wash_water_temperature.refresh() + + mock_rpc_channel.send_command.assert_called_once_with(RoborockCommand.GET_WASH_WATER_TEMPERATURE) + assert wash_water_temperature.wash_water_temperature == expected + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +async def test_options( + wash_water_temperature: WashWaterTemperatureTrait | None, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that the trait offers the temperatures of its dock.""" + assert wash_water_temperature is not None + assert wash_water_temperature.wash_water_temperature_options == [ + RoborockDockWashWaterTemperatureCode.room_temperature, + RoborockDockWashWaterTemperatureCode.warm, + RoborockDockWashWaterTemperatureCode.hot, + ] + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +@pytest.mark.parametrize( + ("temperature"), + [ + RoborockDockWashWaterTemperatureCode.room_temperature, + RoborockDockWashWaterTemperatureCode.warm, + RoborockDockWashWaterTemperatureCode.hot, + ], +) +async def test_set_wash_water_temperature( + wash_water_temperature: WashWaterTemperatureTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + temperature: RoborockDockWashWaterTemperatureCode, +) -> None: + """Test setting an offered wash water temperature.""" + assert wash_water_temperature is not None + + await wash_water_temperature.set_wash_water_temperature(temperature) + + mock_rpc_channel.send_command.assert_called_once_with( + RoborockCommand.SET_WASH_WATER_TEMPERATURE, params={"values": temperature.value} + ) + assert wash_water_temperature.wash_water_temperature == temperature + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +@pytest.mark.parametrize( + ("temperature"), + [ + RoborockDockWashWaterTemperatureCode.steam, + RoborockDockWashWaterTemperatureCode.pet_steam, + RoborockDockWashWaterTemperatureCode.unknown, + ], +) +async def test_set_rejects_unoffered( + wash_water_temperature: WashWaterTemperatureTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + temperature: RoborockDockWashWaterTemperatureCode, +) -> None: + """Test that a temperature the dock does not offer is rejected without sending.""" + assert wash_water_temperature is not None + + with pytest.raises(RoborockUnsupportedFeature): + await wash_water_temperature.set_wash_water_temperature(temperature) + + mock_rpc_channel.send_command.assert_not_called() + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +async def test_set_failure_keeps_state( + wash_water_temperature: WashWaterTemperatureTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that a failed command leaves the temperature unchanged.""" + assert wash_water_temperature is not None + wash_water_temperature.wash_water_temperature = RoborockDockWashWaterTemperatureCode.hot + mock_rpc_channel.send_command.side_effect = RoborockException("boom") + + with pytest.raises(RoborockException): + await wash_water_temperature.set_wash_water_temperature(RoborockDockWashWaterTemperatureCode.warm) + + assert wash_water_temperature.wash_water_temperature == RoborockDockWashWaterTemperatureCode.hot From fbea2bb04bc86d9fa018a99430e80f6abbc1c7cb Mon Sep 17 00:00:00 2001 From: infy1995 Date: Thu, 12 Nov 2026 21:31:49 +0100 Subject: [PATCH 7/9] feat: add V1 cleaning fluid auto-delivery trait --- docs/V1_API_COMMANDS.md | 44 ++++++ roborock/data/v1/v1_code_mappings.py | 9 ++ roborock/data/v1/v1_containers.py | 8 + roborock/devices/traits/v1/__init__.py | 4 + roborock/devices/traits/v1/cleaning_fluid.py | 43 +++++ .../devices/traits/v1/test_cleaning_fluid.py | 148 ++++++++++++++++++ 6 files changed, 256 insertions(+) create mode 100644 roborock/devices/traits/v1/cleaning_fluid.py create mode 100644 tests/devices/traits/v1/test_cleaning_fluid.py diff --git a/docs/V1_API_COMMANDS.md b/docs/V1_API_COMMANDS.md index 821cb1ca2..d5c4bfdc4 100644 --- a/docs/V1_API_COMMANDS.md +++ b/docs/V1_API_COMMANDS.md @@ -26,6 +26,7 @@ Commands can have multiple parameters that can change from one model to another. * [close_dnd_timer](#close_dnd_timer) * [del_server_timer](#del_server_timer) * [dnld_install_sound](#dnld_install_sound) +* [get_auto_delivery_cleaning_fluid](#get_auto_delivery_cleaning_fluid) * [get_clean_sequence](#get_clean_sequence) * [get_consumable](#get_consumable) * [get_custom_mode](#get_custom_mode) @@ -63,6 +64,7 @@ Commands can have multiple parameters that can change from one model to another. * [save_map](#save_map) * [send_ice_to_robot](#send_ice_to_robot) * [send_sdp_to_robot](#send_sdp_to_robot) +* [set_auto_delivery_cleaning_fluid](#set_auto_delivery_cleaning_fluid) * [set_server_timer](#set_server_timer) * [set_clean_motor_mode](#set_clean_motor_mode) * [set_customize_clean_mode](#set_customize_clean_mode) @@ -1377,6 +1379,48 @@ Source: Roborock Saros 10R * Roborock Saros 10R: ✅ +### get_auto_delivery_cleaning_fluid + +Description: Get how much cleaning fluid the dock adds automatically (app: cleaning fluid auto-delivery). + +Parameters: None + +Returns: + + status: 0 off, 1 standard, 3 large. Code 2 is not used by the app. + +Return example: + +```json + {'status': 1} +``` + +Source: Roborock Saros 10R, Roborock app plugin + +**Supported devices:** + +* Roborock Saros 10R: ✅ + +### set_auto_delivery_cleaning_fluid + +Description: Set how much cleaning fluid the dock adds automatically. + +Parameters: + + status: 0 off, 1 standard, 3 large. + +Example: + +```json + {'status': 1} +``` + +Source: Roborock Saros 10R, Roborock app plugin + +**Supported devices:** + +* Roborock Saros 10R: ✅ + ### get_collision_avoid_status Description: diff --git a/roborock/data/v1/v1_code_mappings.py b/roborock/data/v1/v1_code_mappings.py index e7a91dbf9..58c5544c9 100644 --- a/roborock/data/v1/v1_code_mappings.py +++ b/roborock/data/v1/v1_code_mappings.py @@ -429,6 +429,15 @@ class RoborockDockWashWaterTemperatureCode(RoborockEnum): pet_steam = 4 +class RoborockDockCleaningFluidCode(RoborockEnum): + """Describes how much cleaning fluid the dock adds automatically (app: cleaning fluid auto-delivery).""" + + unknown = -1 + off = 0 + standard = 1 + large = 3 + + class RoborockStateCode(RoborockEnum): unknown = 0 starting = 1 diff --git a/roborock/data/v1/v1_containers.py b/roborock/data/v1/v1_containers.py index c68695d81..f3c5c0bd9 100644 --- a/roborock/data/v1/v1_containers.py +++ b/roborock/data/v1/v1_containers.py @@ -27,6 +27,7 @@ DustBagStatus, RoborockChargeStatus, RoborockCleanType, + RoborockDockCleaningFluidCode, RoborockDockDustCollectionFrequencyCode, RoborockDockDustCollectionModeCode, RoborockDockErrorCode, @@ -492,6 +493,13 @@ class WashWaterTemperature(RoborockBase): wash_water_temperature: RoborockDockWashWaterTemperatureCode | None = None +@dataclass +class CleaningFluidDelivery(RoborockBase): + """Cleaning fluid auto-delivery amount, as returned by GET_AUTO_DELIVERY_CLEANING_FLUID.""" + + status: RoborockDockCleaningFluidCode | None = None + + @dataclass class MopDryerProfile(RoborockBase): """Dryer parameters for one state of the auto mop-drying setting.""" diff --git a/roborock/devices/traits/v1/__init__.py b/roborock/devices/traits/v1/__init__.py index 3bd4b209d..1a935bc21 100644 --- a/roborock/devices/traits/v1/__init__.py +++ b/roborock/devices/traits/v1/__init__.py @@ -76,6 +76,7 @@ from . import ( child_lock, clean_summary, + cleaning_fluid, command, common, consumeable, @@ -103,6 +104,7 @@ ) from .child_lock import ChildLockTrait from .clean_summary import CleanSummaryTrait +from .cleaning_fluid import CleaningFluidTrait from .command import CommandTrait from .common import V1TraitMixin from .consumeable import ConsumableTrait @@ -134,6 +136,7 @@ "PropertiesApi", "child_lock", "clean_summary", + "cleaning_fluid", "command", "common", "consumeable", @@ -193,6 +196,7 @@ class PropertiesApi(Trait): wash_towel_mode: WashTowelModeTrait | None = None smart_wash_params: SmartWashParamsTrait | None = None wash_water_temperature: WashWaterTemperatureTrait | None = None + cleaning_fluid: CleaningFluidTrait | None = None obstacle_photos: ObstaclePhotoTrait | None = None mop_dryer: MopDryerTrait | None = None customize_clean_mode: CustomizeCleanModeTrait | None = None diff --git a/roborock/devices/traits/v1/cleaning_fluid.py b/roborock/devices/traits/v1/cleaning_fluid.py new file mode 100644 index 000000000..a5cab5596 --- /dev/null +++ b/roborock/devices/traits/v1/cleaning_fluid.py @@ -0,0 +1,43 @@ +"""Trait for the cleaning fluid auto-delivery of the dock.""" + +from roborock.data import CleaningFluidDelivery, RoborockDockCleaningFluidCode +from roborock.device_features import RoborockDockFeatures +from roborock.devices.traits.v1 import common +from roborock.exceptions import RoborockUnsupportedFeature +from roborock.roborock_typing import RoborockCommand + +_CLEANING_FLUID_OPTIONS = [ + RoborockDockCleaningFluidCode.off, + RoborockDockCleaningFluidCode.standard, + RoborockDockCleaningFluidCode.large, +] + + +def _supports_cleaning_fluid(dock_features: RoborockDockFeatures) -> bool: + return dock_features.is_clean_fluid_auto_delivery_supported + + +class CleaningFluidTrait(CleaningFluidDelivery, common.V1TraitMixin): + """Amount of cleaning fluid the dock adds automatically (app: cleaning fluid auto-delivery). + + The large amount is wire code 3; code 2 is not used by the app. + """ + + command = RoborockCommand.GET_AUTO_DELIVERY_CLEANING_FLUID + converter = common.DefaultConverter(CleaningFluidDelivery) + requires_dock_features = _supports_cleaning_fluid + + @property + def cleaning_fluid_options(self) -> list[RoborockDockCleaningFluidCode]: + """Return the cleaning fluid amounts offered by the app.""" + return list(_CLEANING_FLUID_OPTIONS) + + async def set_cleaning_fluid(self, mode: RoborockDockCleaningFluidCode) -> None: + """Set the cleaning fluid auto-delivery amount.""" + if mode not in self.cleaning_fluid_options: + raise RoborockUnsupportedFeature(f"Cleaning fluid amount {mode.name} is not supported") + await self.rpc_channel.send_command( + RoborockCommand.SET_AUTO_DELIVERY_CLEANING_FLUID, params={"status": mode.value} + ) + # Optimistic update to avoid an extra refresh + self.status = mode diff --git a/tests/devices/traits/v1/test_cleaning_fluid.py b/tests/devices/traits/v1/test_cleaning_fluid.py new file mode 100644 index 000000000..921a1251a --- /dev/null +++ b/tests/devices/traits/v1/test_cleaning_fluid.py @@ -0,0 +1,148 @@ +"""Tests for the CleaningFluidTrait class.""" + +from unittest.mock import AsyncMock + +import pytest + +from roborock.data import RoborockDockCleaningFluidCode, RoborockDockTypeCode +from roborock.devices.device import RoborockDevice +from roborock.devices.traits.v1.cleaning_fluid import CleaningFluidTrait +from roborock.exceptions import RoborockException, RoborockUnsupportedFeature +from roborock.roborock_typing import RoborockCommand +from tests.devices.traits.v1.helpers import dock_types_with_capability + +SAROS_10R_DOCK = RoborockDockTypeCode.shell_3s_dock + + +@pytest.fixture(name="cleaning_fluid") +def cleaning_fluid_trait( + device: RoborockDevice, + discover_features_fixture: None, +) -> CleaningFluidTrait | None: + """Create a CleaningFluidTrait instance with mocked dependencies.""" + assert device.v1_properties + return device.v1_properties.cleaning_fluid + + +@pytest.mark.parametrize( + ("dock_type_code"), + dock_types_with_capability("is_clean_fluid_auto_delivery_supported"), +) +async def test_cleaning_fluid_available( + cleaning_fluid: CleaningFluidTrait | None, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that the trait is available for docks with cleaning fluid auto-delivery.""" + assert cleaning_fluid is not None + + +@pytest.mark.parametrize( + ("dock_type_code"), + dock_types_with_capability("is_clean_fluid_auto_delivery_supported", expected=False), +) +async def test_unsupported_cleaning_fluid( + cleaning_fluid: CleaningFluidTrait | None, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that the trait is not available for docks without cleaning fluid auto-delivery.""" + assert cleaning_fluid is None + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +@pytest.mark.parametrize( + ("response", "expected"), + [ + ({"status": 1}, RoborockDockCleaningFluidCode.standard), # Saros 10R + ({"status": 3}, RoborockDockCleaningFluidCode.large), + ({"status": 0}, RoborockDockCleaningFluidCode.off), + ({"status": 2}, RoborockDockCleaningFluidCode.unknown), + ], +) +async def test_refresh_unknown_code( + cleaning_fluid: CleaningFluidTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + response: dict[str, int], + expected: RoborockDockCleaningFluidCode, +) -> None: + """Test that refresh decodes known codes and tolerates unknown ones.""" + assert cleaning_fluid is not None + mock_rpc_channel.send_command.side_effect = [response] + + await cleaning_fluid.refresh() + + mock_rpc_channel.send_command.assert_called_once_with(RoborockCommand.GET_AUTO_DELIVERY_CLEANING_FLUID) + assert cleaning_fluid.status == expected + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +async def test_options( + cleaning_fluid: CleaningFluidTrait | None, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test the cleaning fluid amounts offered by the app.""" + assert cleaning_fluid is not None + assert cleaning_fluid.cleaning_fluid_options == [ + RoborockDockCleaningFluidCode.off, + RoborockDockCleaningFluidCode.standard, + RoborockDockCleaningFluidCode.large, + ] + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +@pytest.mark.parametrize( + ("mode", "expected_code"), + [ + (RoborockDockCleaningFluidCode.off, 0), + (RoborockDockCleaningFluidCode.standard, 1), + (RoborockDockCleaningFluidCode.large, 3), + ], +) +async def test_set_cleaning_fluid( + cleaning_fluid: CleaningFluidTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + mode: RoborockDockCleaningFluidCode, + expected_code: int, +) -> None: + """Test setting an offered cleaning fluid amount sends its wire code.""" + assert cleaning_fluid is not None + + await cleaning_fluid.set_cleaning_fluid(mode) + + mock_rpc_channel.send_command.assert_called_once_with( + RoborockCommand.SET_AUTO_DELIVERY_CLEANING_FLUID, params={"status": expected_code} + ) + assert cleaning_fluid.status == mode + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +async def test_set_rejects_unoffered( + cleaning_fluid: CleaningFluidTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that an amount the app does not offer is rejected without sending.""" + assert cleaning_fluid is not None + + with pytest.raises(RoborockUnsupportedFeature): + await cleaning_fluid.set_cleaning_fluid(RoborockDockCleaningFluidCode.unknown) + + mock_rpc_channel.send_command.assert_not_called() + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +async def test_set_failure_keeps_state( + cleaning_fluid: CleaningFluidTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that a failed command leaves the amount unchanged.""" + assert cleaning_fluid is not None + cleaning_fluid.status = RoborockDockCleaningFluidCode.standard + mock_rpc_channel.send_command.side_effect = RoborockException("boom") + + with pytest.raises(RoborockException): + await cleaning_fluid.set_cleaning_fluid(RoborockDockCleaningFluidCode.large) + + assert cleaning_fluid.status == RoborockDockCleaningFluidCode.standard From d244532452022fce9e5900d6e1b720e3688bcff0 Mon Sep 17 00:00:00 2001 From: infy1995 Date: Thu, 12 Nov 2026 21:33:19 +0100 Subject: [PATCH 8/9] feat: add V1 smart wash params setter --- docs/V1_API_COMMANDS.md | 24 +-- roborock/data/v1/v1_code_mappings.py | 9 + roborock/data/v1/v1_containers.py | 4 +- roborock/devices/traits/v1/__init__.py | 7 + .../devices/traits/v1/smart_wash_params.py | 57 +++++- .../traits/v1/test_smart_wash_params.py | 184 +++++++++++++++++- 6 files changed, 265 insertions(+), 20 deletions(-) diff --git a/docs/V1_API_COMMANDS.md b/docs/V1_API_COMMANDS.md index d5c4bfdc4..69d65131c 100644 --- a/docs/V1_API_COMMANDS.md +++ b/docs/V1_API_COMMANDS.md @@ -718,48 +718,48 @@ Parameters: ### get_smart_wash_params -Description: Returns the smartwash parameters +Description: Returns when the dock washes the mop during a clean (app: mop wash frequency) Parameters: None - - Returns: - smart_wash: 0 is off, 1 is on + smart_wash: 0 by time, 1 by room, 2 new smart (only on devices with is_back_wash_new_smart_supported) - wash_interval: The interval in seconds between washes + wash_interval: The interval in seconds between washes when washing by time (app offers 600, 900, 1200, 1500; 600 to 3000 in steps of 300 on TopazS, TopazSV, TopazSPlus, TopazSC, TopazSPower and UltronSPlus) Example: ```json -{'smart_wash': 0, 'wash_interval': 1200} +{'smart_wash': 1, 'wash_interval': 1200} ``` +Source: Roborock Saros 10R **Supported devices:** * Roborock S8 Pro Ultra: ✅ +* Roborock Saros 10R: ✅ ### set_smart_wash_params -Description: Sets the smartwash parameters +Description: Sets when the dock washes the mop during a clean Parameters: - smart_wash: 0 is off, 1 is on + smart_wash: 0 by time, 1 by room, 2 new smart (only on devices with is_back_wash_new_smart_supported) - wash_interval: The interval in seconds between washes + wash_interval: The interval in seconds between washes when washing by time: 600, 900, 1200 or 1500; 600 to 3000 in steps of 300 on TopazS, TopazSV, TopazSPlus, TopazSC, TopazSPower and UltronSPlus -`{'smart_wash': 0, 'wash_interval': 1200}` +`{'smart_wash': 1, 'wash_interval': 1200}` +Source: Roborock Saros 10R, Roborock app plugin **Supported devices:** * Roborock S8 Pro Ultra: ✅ +* Roborock Saros 10R: ✅ ## Cleaning history diff --git a/roborock/data/v1/v1_code_mappings.py b/roborock/data/v1/v1_code_mappings.py index 58c5544c9..db5adb0ad 100644 --- a/roborock/data/v1/v1_code_mappings.py +++ b/roborock/data/v1/v1_code_mappings.py @@ -438,6 +438,15 @@ class RoborockDockCleaningFluidCode(RoborockEnum): large = 3 +class RoborockDockSmartWashModeCode(RoborockEnum): + """Describes when the dock washes the mop during a clean (app: mop wash frequency).""" + + unknown = -1 + by_time = 0 + by_room = 1 + new_smart = 2 + + class RoborockStateCode(RoborockEnum): unknown = 0 starting = 1 diff --git a/roborock/data/v1/v1_containers.py b/roborock/data/v1/v1_containers.py index f3c5c0bd9..0c3d6e5e3 100644 --- a/roborock/data/v1/v1_containers.py +++ b/roborock/data/v1/v1_containers.py @@ -31,6 +31,7 @@ RoborockDockDustCollectionFrequencyCode, RoborockDockDustCollectionModeCode, RoborockDockErrorCode, + RoborockDockSmartWashModeCode, RoborockDockState, RoborockDockTypeCode, RoborockDockWashWaterTemperatureCode, @@ -482,8 +483,9 @@ class MultiMapsList(RoborockBase): @dataclass class SmartWashParams(RoborockBase): - smart_wash: int | None = None + smart_wash: RoborockDockSmartWashModeCode | None = None wash_interval: int | None = None + """Seconds between mop washes when washing by time.""" @dataclass diff --git a/roborock/devices/traits/v1/__init__.py b/roborock/devices/traits/v1/__init__.py index 1a935bc21..5be99cf28 100644 --- a/roborock/devices/traits/v1/__init__.py +++ b/roborock/devices/traits/v1/__init__.py @@ -306,6 +306,13 @@ async def discover_features(self) -> None: wash_towel_mode._rpc_channel = self._get_rpc_channel(wash_towel_mode) # type: ignore[assignment] self.wash_towel_mode = wash_towel_mode + if self.smart_wash_params is None and self._is_supported( + SmartWashParamsTrait, "smart_wash_params", dock_features + ): + smart_wash_params = SmartWashParamsTrait(self.device_features, self._product.product_nickname) + smart_wash_params._rpc_channel = self._get_rpc_channel(smart_wash_params) # type: ignore[assignment] + self.smart_wash_params = smart_wash_params + # The wash water temperature needs a washing dock, a device that can heat wash water, # and a product and dock for which the app shows it. if ( diff --git a/roborock/devices/traits/v1/smart_wash_params.py b/roborock/devices/traits/v1/smart_wash_params.py index 78da74e20..0321e6e93 100644 --- a/roborock/devices/traits/v1/smart_wash_params.py +++ b/roborock/devices/traits/v1/smart_wash_params.py @@ -1,18 +1,71 @@ """Trait for smart wash parameters.""" -from roborock.data import SmartWashParams +from roborock.data import RoborockDockSmartWashModeCode, RoborockProductNickname, SmartWashParams from roborock.device_features import RoborockDockFeatures from roborock.devices.traits.v1 import common +from roborock.devices.traits.v1.device_features import DeviceFeaturesTrait +from roborock.exceptions import RoborockUnsupportedFeature from roborock.roborock_typing import RoborockCommand +# Products the app gives a 10 to 50 minute slider instead of the four interval buttons +_OLD_WASH_FREQUENCY_PRODUCTS = { + RoborockProductNickname.TOPAZS, + RoborockProductNickname.TOPAZSV, + RoborockProductNickname.TOPAZSPLUS, + RoborockProductNickname.TOPAZSC, + RoborockProductNickname.TOPAZSPOWER, + RoborockProductNickname.ULTRONSPLUS, +} + + +def get_wash_interval_options(product_nickname: RoborockProductNickname) -> list[int]: + """Return the mop wash intervals in seconds the app offers for a product. + + Older products get 10 to 50 minutes in 5 minute steps; all others 10, 15, 20 and 25 minutes. + """ + if product_nickname in _OLD_WASH_FREQUENCY_PRODUCTS: + return list(range(600, 3001, 300)) + return [600, 900, 1200, 1500] + def _supports_smart_wash_params(dock_features: RoborockDockFeatures) -> bool: return dock_features.is_washable class SmartWashParamsTrait(SmartWashParams, common.V1TraitMixin): - """Trait for smart wash parameters.""" + """When the dock washes the mop during a clean (app: mop wash frequency).""" command = RoborockCommand.GET_SMART_WASH_PARAMS converter = common.DefaultConverter(SmartWashParams) requires_dock_features = _supports_smart_wash_params + + def __init__(self, device_feature_trait: DeviceFeaturesTrait, product_nickname: RoborockProductNickname) -> None: + super().__init__() + self.device_feature_trait = device_feature_trait + self.product_nickname = product_nickname + + @property + def smart_wash_mode_options(self) -> list[RoborockDockSmartWashModeCode]: + """Return the mop wash modes offered by the device.""" + options = [RoborockDockSmartWashModeCode.by_time, RoborockDockSmartWashModeCode.by_room] + if self.device_feature_trait.is_back_wash_new_smart_supported: + options.append(RoborockDockSmartWashModeCode.new_smart) + return options + + @property + def wash_interval_options(self) -> list[int]: + """Return the mop wash intervals in seconds offered by the app.""" + return get_wash_interval_options(self.product_nickname) + + async def set_smart_wash_params(self, mode: RoborockDockSmartWashModeCode, wash_interval: int) -> None: + """Set the mop wash mode and the interval in seconds used when washing by time.""" + if mode not in self.smart_wash_mode_options: + raise RoborockUnsupportedFeature(f"Smart wash mode {mode.name} is not supported") + if wash_interval not in self.wash_interval_options: + raise RoborockUnsupportedFeature(f"Wash interval {wash_interval} is not supported") + await self.rpc_channel.send_command( + RoborockCommand.SET_SMART_WASH_PARAMS, params={"smart_wash": mode.value, "wash_interval": wash_interval} + ) + # Optimistic update to avoid an extra refresh + self.smart_wash = mode + self.wash_interval = wash_interval diff --git a/tests/devices/traits/v1/test_smart_wash_params.py b/tests/devices/traits/v1/test_smart_wash_params.py index 328d5c649..e0d3b9e69 100644 --- a/tests/devices/traits/v1/test_smart_wash_params.py +++ b/tests/devices/traits/v1/test_smart_wash_params.py @@ -1,18 +1,69 @@ -"""Tests for the DockSummaryTrait class.""" +"""Tests for the SmartWashParamsTrait class.""" from unittest.mock import AsyncMock, call import pytest +from roborock.data import RoborockDockSmartWashModeCode, RoborockProductNickname from roborock.data.v1.v1_code_mappings import ( RoborockDockTypeCode, ) from roborock.devices.device import RoborockDevice -from roborock.devices.traits.v1.smart_wash_params import SmartWashParamsTrait +from roborock.devices.traits.v1.smart_wash_params import SmartWashParamsTrait, get_wash_interval_options +from roborock.exceptions import RoborockException, RoborockUnsupportedFeature from roborock.roborock_typing import RoborockCommand from tests.devices.traits.v1.helpers import dock_types_with_capability -SMART_WASH_DATA = [{"smart_wash": 5, "wash_interval": 6}] +# Saros 10R: wash the mop after every room, interval 1200 s kept for the time mode +SMART_WASH_DATA = [{"smart_wash": 1, "wash_interval": 1200}] +SAROS_10R_DOCK = RoborockDockTypeCode.shell_3s_dock +# 10 to 50 minutes in 5 minute steps +OLD_WASH_INTERVALS = [600, 900, 1200, 1500, 1800, 2100, 2400, 2700, 3000] + + +@pytest.fixture(name="product_model") +def product_model_fixture() -> str: + """Default to the Saros 10R, which has the four interval buttons.""" + return "roborock.vacuum.a144" + + +@pytest.mark.parametrize( + ("product_nickname", "expected"), + [ + (RoborockProductNickname.CORALPRO, [600, 900, 1200, 1500]), # Saros 10R + (RoborockProductNickname.PEARLPLUS, [600, 900, 1200, 1500]), + (RoborockProductNickname.TOPAZS, OLD_WASH_INTERVALS), + (RoborockProductNickname.TOPAZSV, OLD_WASH_INTERVALS), + (RoborockProductNickname.TOPAZSPLUS, OLD_WASH_INTERVALS), + (RoborockProductNickname.TOPAZSC, OLD_WASH_INTERVALS), + (RoborockProductNickname.TOPAZSPOWER, OLD_WASH_INTERVALS), + (RoborockProductNickname.ULTRONSPLUS, OLD_WASH_INTERVALS), + ], +) +def test_get_wash_interval_options(product_nickname: RoborockProductNickname, expected: list[int]) -> None: + """Test the wash intervals offered for each product.""" + assert get_wash_interval_options(product_nickname) == expected + + +@pytest.mark.parametrize(("product_model"), ["roborock.vacuum.a27"]) # S7 MaxV (TopazSV) +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o6_dock]) +async def test_old_product_wash_intervals( + smart_wash_params: SmartWashParamsTrait | None, + mock_rpc_channel: AsyncMock, + product_model: str, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that an older product offers and accepts the longer wash intervals.""" + assert smart_wash_params is not None + assert smart_wash_params.wash_interval_options == OLD_WASH_INTERVALS + + await smart_wash_params.set_smart_wash_params(RoborockDockSmartWashModeCode.by_time, 3000) + + mock_rpc_channel.send_command.assert_called_once_with( + RoborockCommand.SET_SMART_WASH_PARAMS, params={"smart_wash": 0, "wash_interval": 3000} + ) + with pytest.raises(RoborockUnsupportedFeature): + await smart_wash_params.set_smart_wash_params(RoborockDockSmartWashModeCode.by_time, 3300) @pytest.fixture(name="smart_wash_params") @@ -53,8 +104,8 @@ async def test_smart_wash_available( ) # Verify the summary object contains the traits - assert smart_wash_params.smart_wash == 5 - assert smart_wash_params.wash_interval == 6 + assert smart_wash_params.smart_wash == RoborockDockSmartWashModeCode.by_room + assert smart_wash_params.wash_interval == 1200 @pytest.mark.parametrize( @@ -66,3 +117,126 @@ async def test_unsupported_smart_wash_params( ) -> None: """Test successfully refreshing the dock summary.""" assert smart_wash_params is None + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +async def test_refresh_unknown_code( + smart_wash_params: SmartWashParamsTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that refresh tolerates an unknown smart wash mode code.""" + assert smart_wash_params is not None + mock_rpc_channel.send_command.side_effect = [[{"smart_wash": 7, "wash_interval": 1200}]] + + await smart_wash_params.refresh() + + assert smart_wash_params.smart_wash == RoborockDockSmartWashModeCode.unknown + assert smart_wash_params.wash_interval == 1200 + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +@pytest.mark.parametrize( + ("new_smart_supported", "expected"), + [ + (False, [RoborockDockSmartWashModeCode.by_time, RoborockDockSmartWashModeCode.by_room]), + ( + True, + [ + RoborockDockSmartWashModeCode.by_time, + RoborockDockSmartWashModeCode.by_room, + RoborockDockSmartWashModeCode.new_smart, + ], + ), + ], +) +async def test_smart_wash_mode_options( + device: RoborockDevice, + smart_wash_params: SmartWashParamsTrait | None, + dock_type_code: RoborockDockTypeCode, + new_smart_supported: bool, + expected: list[RoborockDockSmartWashModeCode], +) -> None: + """Test that the new smart mode is offered only with its device feature.""" + assert device.v1_properties + assert smart_wash_params is not None + device.v1_properties.device_features.is_back_wash_new_smart_supported = new_smart_supported + + assert smart_wash_params.smart_wash_mode_options == expected + assert smart_wash_params.wash_interval_options == [600, 900, 1200, 1500] + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +@pytest.mark.parametrize( + ("mode", "wash_interval"), + [ + (RoborockDockSmartWashModeCode.by_room, 1200), + (RoborockDockSmartWashModeCode.by_time, 900), + (RoborockDockSmartWashModeCode.by_time, 600), + (RoborockDockSmartWashModeCode.by_time, 1500), + ], +) +async def test_set_smart_wash_params( + smart_wash_params: SmartWashParamsTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + mode: RoborockDockSmartWashModeCode, + wash_interval: int, +) -> None: + """Test setting an offered smart wash mode and interval.""" + assert smart_wash_params is not None + + await smart_wash_params.set_smart_wash_params(mode, wash_interval) + + mock_rpc_channel.send_command.assert_called_once_with( + RoborockCommand.SET_SMART_WASH_PARAMS, params={"smart_wash": mode.value, "wash_interval": wash_interval} + ) + assert smart_wash_params.smart_wash == mode + assert smart_wash_params.wash_interval == wash_interval + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +@pytest.mark.parametrize( + ("mode", "wash_interval"), + [ + (RoborockDockSmartWashModeCode.new_smart, 1200), + (RoborockDockSmartWashModeCode.unknown, 1200), + (RoborockDockSmartWashModeCode.by_time, 1000), + ], +) +async def test_set_rejects_unoffered( + device: RoborockDevice, + smart_wash_params: SmartWashParamsTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + mode: RoborockDockSmartWashModeCode, + wash_interval: int, +) -> None: + """Test that a mode or interval the device does not offer is rejected without sending.""" + assert device.v1_properties + assert smart_wash_params is not None + device.v1_properties.device_features.is_back_wash_new_smart_supported = False + + with pytest.raises(RoborockUnsupportedFeature): + await smart_wash_params.set_smart_wash_params(mode, wash_interval) + + mock_rpc_channel.send_command.assert_not_called() + + +@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK]) +async def test_set_failure_keeps_state( + smart_wash_params: SmartWashParamsTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that a failed command leaves the smart wash params unchanged.""" + assert smart_wash_params is not None + smart_wash_params.smart_wash = RoborockDockSmartWashModeCode.by_room + smart_wash_params.wash_interval = 1200 + mock_rpc_channel.send_command.side_effect = RoborockException("boom") + + with pytest.raises(RoborockException): + await smart_wash_params.set_smart_wash_params(RoborockDockSmartWashModeCode.by_time, 900) + + assert smart_wash_params.smart_wash == RoborockDockSmartWashModeCode.by_room + assert smart_wash_params.wash_interval == 1200 From b8b4a17fb45677c35d0dfa7bc03e06e6c0c1246e Mon Sep 17 00:00:00 2001 From: infy1995 Date: Thu, 12 Nov 2026 21:34:43 +0100 Subject: [PATCH 9/9] feat: add V1 wash tray self-clean and wash mode validation --- docs/V1_API_COMMANDS.md | 40 +++++++++---- roborock/devices/traits/v1/wash_towel_mode.py | 14 ++++- .../devices/traits/v1/test_wash_towel_mode.py | 59 +++++++++++++++++++ 3 files changed, 100 insertions(+), 13 deletions(-) diff --git a/docs/V1_API_COMMANDS.md b/docs/V1_API_COMMANDS.md index 69d65131c..cd14896ea 100644 --- a/docs/V1_API_COMMANDS.md +++ b/docs/V1_API_COMMANDS.md @@ -6,6 +6,7 @@ Commands do not immediately make it to this page. You can find more commands [he Commands can have multiple parameters that can change from one model to another. +* [app_amethyst_self_check](#app_amethyst_self_check) * [app_charge](#app_charge) * [app_get_dryer_setting](#app_get_dryer_setting) * [app_get_init_status](#app_get_init_status) @@ -254,13 +255,15 @@ Parameters: None ### app_stop_wash -Description: This stops washing the mop whiloe docked +Description: This stops washing the mop whiloe docked. It also stops a running wash tray self-clean +([app_amethyst_self_check](#app_amethyst_self_check)). Parameters: None **Supported devices:** * Roborock S8 Pro Ultra: ✅ +* Roborock Saros 10R: ✅ ### app_goto_target @@ -1291,7 +1294,7 @@ Parameters: None Returns: - wash_mode: + wash_mode: 0 light, 1 balanced, 2 deep, 8 super deep, 10 smart Return example: @@ -1299,16 +1302,7 @@ Return example: {'wash_mode': 1} ``` -Source: Roborock S7 MaxV Ultra - - - unknown = -9999 - - light = 0 - - balanced = 1 - - deep = 2 +Source: Roborock S7 MaxV Ultra; smart (10) seen on the Roborock Saros 10R **Supported devices:** @@ -1323,6 +1317,9 @@ Description: Sets the wash wash_towel_mode Parameters: {'wash_mode': 2} + wash_mode: 0 light, 1 balanced, 2 deep, 8 super deep, 10 smart. Super deep and smart are offered only on + devices that support them. + Returns: ok or error Source: S8 Pro Ultra @@ -1332,6 +1329,25 @@ Source: S8 Pro Ultra * Roborock S7 MaxV Ultra: ✅ * Roborock S8 Pro Ultra: ✅ +### app_amethyst_self_check + +Description: Start the self-clean of the dock's mop wash tray (app: tray self-cleaning). Offered on docks with a +self-cleaning wash carousel, such as the Saros 10R dock (dock type 16). + +Parameters: None + +Returns: ok or error + +While it runs, `get_status` reports `state` 23 (washing the mop) and `wash_phase` 11, the same as when the +self-clean is started from the app. The dock needs clean water (`dock_error_status` 38, water empty, otherwise). +It ends by itself after about a minute; `app_stop_wash` stops it early, like the stop button in the app. + +Source: Roborock Saros 10R, Roborock app plugin + +**Supported devices:** + +* Roborock Saros 10R: ✅ + ### get_wash_water_temperature Description: Get the water temperature the dock uses to wash the mop (app: water temperature). Available on diff --git a/roborock/devices/traits/v1/wash_towel_mode.py b/roborock/devices/traits/v1/wash_towel_mode.py index 909e96b68..9daaa2eec 100644 --- a/roborock/devices/traits/v1/wash_towel_mode.py +++ b/roborock/devices/traits/v1/wash_towel_mode.py @@ -7,6 +7,7 @@ from roborock.device_features import RoborockDockFeatures from roborock.devices.traits.v1 import common from roborock.devices.traits.v1.device_features import DeviceFeaturesTrait +from roborock.exceptions import RoborockUnsupportedFeature from roborock.roborock_typing import RoborockCommand @@ -42,6 +43,8 @@ def wash_towel_mode_options(self) -> list[WashTowelModes]: async def set_wash_towel_mode(self, mode: WashTowelModes) -> None: """Set the wash towel mode.""" + if mode not in self.wash_towel_mode_options: + raise RoborockUnsupportedFeature(f"Wash towel mode {mode.value} is not supported") await self.rpc_channel.send_command(RoborockCommand.SET_WASH_TOWEL_MODE, params={"wash_mode": mode.code}) async def start_wash(self) -> None: @@ -49,5 +52,14 @@ async def start_wash(self) -> None: await self.rpc_channel.send_command(RoborockCommand.APP_START_WASH) async def stop_wash(self) -> None: - """Stop washing the mop.""" + """Stop washing the mop. Also stops a running wash tray self-clean.""" await self.rpc_channel.send_command(RoborockCommand.APP_STOP_WASH) + + async def self_clean_tray(self) -> None: + """Start the self-clean of the dock's mop wash tray (app: tray self-cleaning). + + It runs for about a minute; `stop_wash()` stops it early, as the app's stop button does. + """ + if not self.device_feature_trait.dock_features.is_clean_carousel_self_clean_supported: + raise RoborockUnsupportedFeature("Wash tray self-clean is not supported by this dock") + await self.rpc_channel.send_command(RoborockCommand.APP_AMETHYST_SELF_CHECK) diff --git a/tests/devices/traits/v1/test_wash_towel_mode.py b/tests/devices/traits/v1/test_wash_towel_mode.py index 8395c70ce..98bdc4b2c 100644 --- a/tests/devices/traits/v1/test_wash_towel_mode.py +++ b/tests/devices/traits/v1/test_wash_towel_mode.py @@ -10,6 +10,7 @@ ) from roborock.devices.device import RoborockDevice from roborock.devices.traits.v1.wash_towel_mode import WashTowelModeTrait +from roborock.exceptions import RoborockUnsupportedFeature from roborock.roborock_typing import RoborockCommand from tests.devices.traits.v1.helpers import dock_types_with_capability @@ -83,6 +84,8 @@ async def test_set_wash_towel_mode( ) -> None: """Test setting the wash towel mode.""" assert wash_towel_mode is not None + # Offer the smart mode, as on the Saros 10R + wash_towel_mode.device_feature_trait.is_dirty_replenish_clean_supported = True await wash_towel_mode.set_wash_towel_mode(wash_mode) @@ -189,3 +192,59 @@ async def test_wash_towel_mode_options( wash_towel_mode.device_feature_trait.is_dirty_replenish_clean_supported = is_dirty_replenish_clean_supported assert wash_towel_mode.wash_towel_mode_options == expected_modes + + +@pytest.mark.parametrize( + ("dock_type_code"), + [(RoborockDockTypeCode.o4_dock)], +) +async def test_set_wash_towel_mode_rejects_unoffered( + wash_towel_mode: WashTowelModeTrait, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that a wash mode the device does not offer is rejected without sending.""" + assert wash_towel_mode is not None + wash_towel_mode.device_feature_trait.is_super_deep_wash_supported = True + wash_towel_mode.device_feature_trait.is_dirty_replenish_clean_supported = True + assert WashTowelModes.SUPER_DEEP not in wash_towel_mode.wash_towel_mode_options + + with pytest.raises(RoborockUnsupportedFeature): + await wash_towel_mode.set_wash_towel_mode(WashTowelModes.SUPER_DEEP) + + mock_rpc_channel.send_command.assert_not_called() + + +@pytest.mark.parametrize( + ("dock_type_code"), + [(RoborockDockTypeCode.shell_3s_dock)], +) +async def test_self_clean_tray( + wash_towel_mode: WashTowelModeTrait, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test starting the wash tray self-clean on a dock with the carousel.""" + assert wash_towel_mode is not None + + await wash_towel_mode.self_clean_tray() + + mock_rpc_channel.send_command.assert_called_once_with(RoborockCommand.APP_AMETHYST_SELF_CHECK) + + +@pytest.mark.parametrize( + ("dock_type_code"), + [(RoborockDockTypeCode.o4_dock)], +) +async def test_self_clean_tray_unsupported( + wash_towel_mode: WashTowelModeTrait, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that the tray self-clean is rejected without sending on a dock without the carousel.""" + assert wash_towel_mode is not None + + with pytest.raises(RoborockUnsupportedFeature): + await wash_towel_mode.self_clean_tray() + + mock_rpc_channel.send_command.assert_not_called()