Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 66 additions & 1 deletion docs/V1_API_COMMANDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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:
Expand Down
12 changes: 6 additions & 6 deletions docs/V1_DEVICE_FEATURES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down Expand Up @@ -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.

---

Expand Down Expand Up @@ -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.

---

Expand Down
22 changes: 20 additions & 2 deletions roborock/data/v1/v1_code_mappings.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 8 additions & 0 deletions roborock/data/v1/v1_containers.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
DustBagStatus,
RoborockChargeStatus,
RoborockCleanType,
RoborockDockDustCollectionFrequencyCode,
RoborockDockDustCollectionModeCode,
RoborockDockErrorCode,
RoborockDockState,
Expand Down Expand Up @@ -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
Expand Down
25 changes: 23 additions & 2 deletions roborock/devices/traits/v1/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -77,6 +82,7 @@
customize_clean_mode,
device_features,
do_not_disturb,
dust_collection,
dust_collection_mode,
flow_led_status,
home,
Expand All @@ -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
Expand Down Expand Up @@ -131,6 +138,7 @@
"customize_clean_mode",
"device_features",
"do_not_disturb",
"dust_collection",
"dust_collection_mode",
"flow_led_status",
"home",
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
):
Expand All @@ -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)
Expand Down
76 changes: 76 additions & 0 deletions roborock/devices/traits/v1/dust_collection.py
Original file line number Diff line number Diff line change
@@ -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)
Loading
Loading