From 1b2efd8719b90a6ac8b671f1d43e7a2d2fd27ddf Mon Sep 17 00:00:00 2001 From: infy1995 Date: Thu, 12 Nov 2026 20:56:01 +0100 Subject: [PATCH 1/5] 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/5] 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/5] 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/5] 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/5] 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)