diff --git a/docs/V1_API_COMMANDS.md b/docs/V1_API_COMMANDS.md index 68776ef4..e415e397 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) @@ -1202,18 +1204,81 @@ 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_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. Devices without new feature string bit 53 only use 0 (off) and 1 (on). 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. Devices without new feature string bit 53 only use 0 (off) and 1 (on). + +Example: + +```json + {'status': 2} +``` + +Source: Roborock Saros 10R + +**Supported devices:** + +* Roborock Saros 10R: ✅ + ### get_wash_towel_mode Description: diff --git a/docs/V1_DEVICE_FEATURES.md b/docs/V1_DEVICE_FEATURES.md index f9b0b9e1..c5671be2 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 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. -**Impact:** Automatic dustbin emptying at dock. +**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 c5d5037f..7e0fbd70 100644 --- a/roborock/data/v1/v1_code_mappings.py +++ b/roborock/data/v1/v1_code_mappings.py @@ -390,16 +390,34 @@ 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 +class RoborockDockDustCollectionFrequencyCode(RoborockEnum): + """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 + 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 65bcba64..3a42ca78 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 d8af621b..5a9a6f8b 100644 --- a/roborock/devices/traits/v1/__init__.py +++ b/roborock/devices/traits/v1/__init__.py @@ -45,6 +45,11 @@ - `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`. 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 optional fields in a dataclass, vs the above feature checks that apply to an entire @@ -77,6 +82,7 @@ customize_clean_mode, device_features, do_not_disturb, + dust_collection, dust_collection_mode, flow_led_status, home, @@ -102,7 +108,8 @@ from .customize_clean_mode import CustomizeCleanModeTrait from .device_features import DeviceFeaturesTrait from .do_not_disturb import DoNotDisturbTrait -from .dust_collection_mode import DustCollectionModeTrait +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 from .led_status import LedStatusTrait @@ -131,6 +138,7 @@ "customize_clean_mode", "device_features", "do_not_disturb", + "dust_collection", "dust_collection_mode", "flow_led_status", "home", @@ -178,6 +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: DustCollectionTrait | None = None wash_towel_mode: WashTowelModeTrait | None = None smart_wash_params: SmartWashParamsTrait | None = None obstacle_photos: ObstaclePhotoTrait | None = None @@ -288,6 +297,17 @@ 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 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 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 ): @@ -311,7 +331,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): 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 00000000..07a9ef28 --- /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_mode.py b/roborock/devices/traits/v1/dust_collection_mode.py index e738e30d..4afc9ecc 100644 --- a/roborock/devices/traits/v1/dust_collection_mode.py +++ b/roborock/devices/traits/v1/dust_collection_mode.py @@ -1,18 +1,55 @@ """Trait for dust collection mode.""" -from roborock.data import DustCollectionMode -from roborock.device_features import RoborockDockFeatures +from roborock.data import DustCollectionMode, RoborockDockDustCollectionModeCode +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 +_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 + +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): - """Trait for dust collection mode.""" + """Trait for the dock dust collection mode. + + ``set_dust_collection_mode`` changes how strongly the dock empties the + dustbin. Manual dust collection is on ``DustCollectionTrait``, which + every collecting dock has. + + 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]: + """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 diff --git a/tests/devices/traits/v1/test_dust_collection.py b/tests/devices/traits/v1/test_dust_collection.py new file mode 100644 index 00000000..36e43b5e --- /dev/null +++ b/tests/devices/traits/v1/test_dust_collection.py @@ -0,0 +1,191 @@ +"""Tests for the DustCollectionTrait class.""" + +from unittest.mock import AsyncMock + +import pytest + +from roborock.data import HomeDataDevice, RoborockDockDustCollectionFrequencyCode, RoborockDockTypeCode +from roborock.devices.device import RoborockDevice +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 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 = 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="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, +) -> DustCollectionTrait | None: + """Create a DustCollectionTrait instance with mocked dependencies.""" + assert device.v1_properties + return device.v1_properties.dust_collection + + +@pytest.mark.parametrize( + ("dock_type_code"), + dock_types_with_capability("is_collectable"), +) +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 is not None + + +@pytest.mark.parametrize( + ("dock_type_code"), + dock_types_with_capability("is_collectable", expected=False), +) +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 is None + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize( + ("device_info", "expected"), + [(SAROS_10R, THREE_LEVELS), (S7_MAXV, ON_OFF), (Q_REVO, ON_OFF)], + ids=["saros_10r", "s7_maxv", "pearl"], +) +async def test_options( + dust_collection: DustCollectionTrait | None, + dock_type_code: RoborockDockTypeCode, + device_info: HomeDataDevice, + expected: list[RoborockDockDustCollectionFrequencyCode], +) -> None: + """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]) +@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: 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 is not None + mock_rpc_channel.send_command.side_effect = [response] + + await dust_collection.refresh() + + mock_rpc_channel.send_command.assert_called_once_with(RoborockCommand.GET_DUST_COLLECTION_SWITCH_STATUS) + assert dust_collection.status == expected + + +@pytest.mark.parametrize(("dock_type_code"), [RoborockDockTypeCode.o4_dock]) +@pytest.mark.parametrize(("frequency"), THREE_LEVELS) +async def test_set_frequency( + 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 is not None + + 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.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: DustCollectionTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, + device_info: HomeDataDevice, + frequency: RoborockDockDustCollectionFrequencyCode, +) -> 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.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: DustCollectionTrait | None, + mock_rpc_channel: AsyncMock, + dock_type_code: RoborockDockTypeCode, +) -> None: + """Test that a failed command leaves the frequency unchanged.""" + 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.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)() + + 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 f8e847b4..51a2b0de 100644 --- a/tests/devices/traits/v1/test_dust_collection_mode.py +++ b/tests/devices/traits/v1/test_dust_collection_mode.py @@ -4,14 +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( @@ -60,3 +76,119 @@ 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]) +@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, + 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