feat: add V1 dust collection controls

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. 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:

roborock/data/v1/v1_code_mappings.py

@@ -390,16 +390,30 @@ 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)."""
+
+    unknown = -1
+    off = 0
+    balanced = 1
+    high = 2
+
+
 class RoborockStateCode(RoborockEnum):
     unknown = 0
     starting = 1

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

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

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

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)