Skip to content

Commit fbea2bb

Browse files
committed
feat: add V1 cleaning fluid auto-delivery trait
1 parent be749e4 commit fbea2bb

6 files changed

Lines changed: 256 additions & 0 deletions

File tree

‎docs/V1_API_COMMANDS.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ Commands can have multiple parameters that can change from one model to another.
2626
* [close_dnd_timer](#close_dnd_timer)
2727
* [del_server_timer](#del_server_timer)
2828
* [dnld_install_sound](#dnld_install_sound)
29+
* [get_auto_delivery_cleaning_fluid](#get_auto_delivery_cleaning_fluid)
2930
* [get_clean_sequence](#get_clean_sequence)
3031
* [get_consumable](#get_consumable)
3132
* [get_custom_mode](#get_custom_mode)
@@ -63,6 +64,7 @@ Commands can have multiple parameters that can change from one model to another.
6364
* [save_map](#save_map)
6465
* [send_ice_to_robot](#send_ice_to_robot)
6566
* [send_sdp_to_robot](#send_sdp_to_robot)
67+
* [set_auto_delivery_cleaning_fluid](#set_auto_delivery_cleaning_fluid)
6668
* [set_server_timer](#set_server_timer)
6769
* [set_clean_motor_mode](#set_clean_motor_mode)
6870
* [set_customize_clean_mode](#set_customize_clean_mode)
@@ -1377,6 +1379,48 @@ Source: Roborock Saros 10R
13771379

13781380
* Roborock Saros 10R: ✅
13791381

1382+
### get_auto_delivery_cleaning_fluid
1383+
1384+
Description: Get how much cleaning fluid the dock adds automatically (app: cleaning fluid auto-delivery).
1385+
1386+
Parameters: None
1387+
1388+
Returns:
1389+
1390+
status: 0 off, 1 standard, 3 large. Code 2 is not used by the app.
1391+
1392+
Return example:
1393+
1394+
```json
1395+
{'status': 1}
1396+
```
1397+
1398+
Source: Roborock Saros 10R, Roborock app plugin
1399+
1400+
**Supported devices:**
1401+
1402+
* Roborock Saros 10R: ✅
1403+
1404+
### set_auto_delivery_cleaning_fluid
1405+
1406+
Description: Set how much cleaning fluid the dock adds automatically.
1407+
1408+
Parameters:
1409+
1410+
status: 0 off, 1 standard, 3 large.
1411+
1412+
Example:
1413+
1414+
```json
1415+
{'status': 1}
1416+
```
1417+
1418+
Source: Roborock Saros 10R, Roborock app plugin
1419+
1420+
**Supported devices:**
1421+
1422+
* Roborock Saros 10R: ✅
1423+
13801424
### get_collision_avoid_status
13811425

13821426
Description:

‎roborock/data/v1/v1_code_mappings.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -429,6 +429,15 @@ class RoborockDockWashWaterTemperatureCode(RoborockEnum):
429429
pet_steam = 4
430430

431431

432+
class RoborockDockCleaningFluidCode(RoborockEnum):
433+
"""Describes how much cleaning fluid the dock adds automatically (app: cleaning fluid auto-delivery)."""
434+
435+
unknown = -1
436+
off = 0
437+
standard = 1
438+
large = 3
439+
440+
432441
class RoborockStateCode(RoborockEnum):
433442
unknown = 0
434443
starting = 1

‎roborock/data/v1/v1_containers.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
DustBagStatus,
2828
RoborockChargeStatus,
2929
RoborockCleanType,
30+
RoborockDockCleaningFluidCode,
3031
RoborockDockDustCollectionFrequencyCode,
3132
RoborockDockDustCollectionModeCode,
3233
RoborockDockErrorCode,
@@ -492,6 +493,13 @@ class WashWaterTemperature(RoborockBase):
492493
wash_water_temperature: RoborockDockWashWaterTemperatureCode | None = None
493494

494495

496+
@dataclass
497+
class CleaningFluidDelivery(RoborockBase):
498+
"""Cleaning fluid auto-delivery amount, as returned by GET_AUTO_DELIVERY_CLEANING_FLUID."""
499+
500+
status: RoborockDockCleaningFluidCode | None = None
501+
502+
495503
@dataclass
496504
class MopDryerProfile(RoborockBase):
497505
"""Dryer parameters for one state of the auto mop-drying setting."""

‎roborock/devices/traits/v1/__init__.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@
7676
from . import (
7777
child_lock,
7878
clean_summary,
79+
cleaning_fluid,
7980
command,
8081
common,
8182
consumeable,
@@ -103,6 +104,7 @@
103104
)
104105
from .child_lock import ChildLockTrait
105106
from .clean_summary import CleanSummaryTrait
107+
from .cleaning_fluid import CleaningFluidTrait
106108
from .command import CommandTrait
107109
from .common import V1TraitMixin
108110
from .consumeable import ConsumableTrait
@@ -134,6 +136,7 @@
134136
"PropertiesApi",
135137
"child_lock",
136138
"clean_summary",
139+
"cleaning_fluid",
137140
"command",
138141
"common",
139142
"consumeable",
@@ -193,6 +196,7 @@ class PropertiesApi(Trait):
193196
wash_towel_mode: WashTowelModeTrait | None = None
194197
smart_wash_params: SmartWashParamsTrait | None = None
195198
wash_water_temperature: WashWaterTemperatureTrait | None = None
199+
cleaning_fluid: CleaningFluidTrait | None = None
196200
obstacle_photos: ObstaclePhotoTrait | None = None
197201
mop_dryer: MopDryerTrait | None = None
198202
customize_clean_mode: CustomizeCleanModeTrait | None = None
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
"""Trait for the cleaning fluid auto-delivery of the dock."""
2+
3+
from roborock.data import CleaningFluidDelivery, RoborockDockCleaningFluidCode
4+
from roborock.device_features import RoborockDockFeatures
5+
from roborock.devices.traits.v1 import common
6+
from roborock.exceptions import RoborockUnsupportedFeature
7+
from roborock.roborock_typing import RoborockCommand
8+
9+
_CLEANING_FLUID_OPTIONS = [
10+
RoborockDockCleaningFluidCode.off,
11+
RoborockDockCleaningFluidCode.standard,
12+
RoborockDockCleaningFluidCode.large,
13+
]
14+
15+
16+
def _supports_cleaning_fluid(dock_features: RoborockDockFeatures) -> bool:
17+
return dock_features.is_clean_fluid_auto_delivery_supported
18+
19+
20+
class CleaningFluidTrait(CleaningFluidDelivery, common.V1TraitMixin):
21+
"""Amount of cleaning fluid the dock adds automatically (app: cleaning fluid auto-delivery).
22+
23+
The large amount is wire code 3; code 2 is not used by the app.
24+
"""
25+
26+
command = RoborockCommand.GET_AUTO_DELIVERY_CLEANING_FLUID
27+
converter = common.DefaultConverter(CleaningFluidDelivery)
28+
requires_dock_features = _supports_cleaning_fluid
29+
30+
@property
31+
def cleaning_fluid_options(self) -> list[RoborockDockCleaningFluidCode]:
32+
"""Return the cleaning fluid amounts offered by the app."""
33+
return list(_CLEANING_FLUID_OPTIONS)
34+
35+
async def set_cleaning_fluid(self, mode: RoborockDockCleaningFluidCode) -> None:
36+
"""Set the cleaning fluid auto-delivery amount."""
37+
if mode not in self.cleaning_fluid_options:
38+
raise RoborockUnsupportedFeature(f"Cleaning fluid amount {mode.name} is not supported")
39+
await self.rpc_channel.send_command(
40+
RoborockCommand.SET_AUTO_DELIVERY_CLEANING_FLUID, params={"status": mode.value}
41+
)
42+
# Optimistic update to avoid an extra refresh
43+
self.status = mode
Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
"""Tests for the CleaningFluidTrait class."""
2+
3+
from unittest.mock import AsyncMock
4+
5+
import pytest
6+
7+
from roborock.data import RoborockDockCleaningFluidCode, RoborockDockTypeCode
8+
from roborock.devices.device import RoborockDevice
9+
from roborock.devices.traits.v1.cleaning_fluid import CleaningFluidTrait
10+
from roborock.exceptions import RoborockException, RoborockUnsupportedFeature
11+
from roborock.roborock_typing import RoborockCommand
12+
from tests.devices.traits.v1.helpers import dock_types_with_capability
13+
14+
SAROS_10R_DOCK = RoborockDockTypeCode.shell_3s_dock
15+
16+
17+
@pytest.fixture(name="cleaning_fluid")
18+
def cleaning_fluid_trait(
19+
device: RoborockDevice,
20+
discover_features_fixture: None,
21+
) -> CleaningFluidTrait | None:
22+
"""Create a CleaningFluidTrait instance with mocked dependencies."""
23+
assert device.v1_properties
24+
return device.v1_properties.cleaning_fluid
25+
26+
27+
@pytest.mark.parametrize(
28+
("dock_type_code"),
29+
dock_types_with_capability("is_clean_fluid_auto_delivery_supported"),
30+
)
31+
async def test_cleaning_fluid_available(
32+
cleaning_fluid: CleaningFluidTrait | None,
33+
dock_type_code: RoborockDockTypeCode,
34+
) -> None:
35+
"""Test that the trait is available for docks with cleaning fluid auto-delivery."""
36+
assert cleaning_fluid is not None
37+
38+
39+
@pytest.mark.parametrize(
40+
("dock_type_code"),
41+
dock_types_with_capability("is_clean_fluid_auto_delivery_supported", expected=False),
42+
)
43+
async def test_unsupported_cleaning_fluid(
44+
cleaning_fluid: CleaningFluidTrait | None,
45+
dock_type_code: RoborockDockTypeCode,
46+
) -> None:
47+
"""Test that the trait is not available for docks without cleaning fluid auto-delivery."""
48+
assert cleaning_fluid is None
49+
50+
51+
@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK])
52+
@pytest.mark.parametrize(
53+
("response", "expected"),
54+
[
55+
({"status": 1}, RoborockDockCleaningFluidCode.standard), # Saros 10R
56+
({"status": 3}, RoborockDockCleaningFluidCode.large),
57+
({"status": 0}, RoborockDockCleaningFluidCode.off),
58+
({"status": 2}, RoborockDockCleaningFluidCode.unknown),
59+
],
60+
)
61+
async def test_refresh_unknown_code(
62+
cleaning_fluid: CleaningFluidTrait | None,
63+
mock_rpc_channel: AsyncMock,
64+
dock_type_code: RoborockDockTypeCode,
65+
response: dict[str, int],
66+
expected: RoborockDockCleaningFluidCode,
67+
) -> None:
68+
"""Test that refresh decodes known codes and tolerates unknown ones."""
69+
assert cleaning_fluid is not None
70+
mock_rpc_channel.send_command.side_effect = [response]
71+
72+
await cleaning_fluid.refresh()
73+
74+
mock_rpc_channel.send_command.assert_called_once_with(RoborockCommand.GET_AUTO_DELIVERY_CLEANING_FLUID)
75+
assert cleaning_fluid.status == expected
76+
77+
78+
@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK])
79+
async def test_options(
80+
cleaning_fluid: CleaningFluidTrait | None,
81+
dock_type_code: RoborockDockTypeCode,
82+
) -> None:
83+
"""Test the cleaning fluid amounts offered by the app."""
84+
assert cleaning_fluid is not None
85+
assert cleaning_fluid.cleaning_fluid_options == [
86+
RoborockDockCleaningFluidCode.off,
87+
RoborockDockCleaningFluidCode.standard,
88+
RoborockDockCleaningFluidCode.large,
89+
]
90+
91+
92+
@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK])
93+
@pytest.mark.parametrize(
94+
("mode", "expected_code"),
95+
[
96+
(RoborockDockCleaningFluidCode.off, 0),
97+
(RoborockDockCleaningFluidCode.standard, 1),
98+
(RoborockDockCleaningFluidCode.large, 3),
99+
],
100+
)
101+
async def test_set_cleaning_fluid(
102+
cleaning_fluid: CleaningFluidTrait | None,
103+
mock_rpc_channel: AsyncMock,
104+
dock_type_code: RoborockDockTypeCode,
105+
mode: RoborockDockCleaningFluidCode,
106+
expected_code: int,
107+
) -> None:
108+
"""Test setting an offered cleaning fluid amount sends its wire code."""
109+
assert cleaning_fluid is not None
110+
111+
await cleaning_fluid.set_cleaning_fluid(mode)
112+
113+
mock_rpc_channel.send_command.assert_called_once_with(
114+
RoborockCommand.SET_AUTO_DELIVERY_CLEANING_FLUID, params={"status": expected_code}
115+
)
116+
assert cleaning_fluid.status == mode
117+
118+
119+
@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK])
120+
async def test_set_rejects_unoffered(
121+
cleaning_fluid: CleaningFluidTrait | None,
122+
mock_rpc_channel: AsyncMock,
123+
dock_type_code: RoborockDockTypeCode,
124+
) -> None:
125+
"""Test that an amount the app does not offer is rejected without sending."""
126+
assert cleaning_fluid is not None
127+
128+
with pytest.raises(RoborockUnsupportedFeature):
129+
await cleaning_fluid.set_cleaning_fluid(RoborockDockCleaningFluidCode.unknown)
130+
131+
mock_rpc_channel.send_command.assert_not_called()
132+
133+
134+
@pytest.mark.parametrize(("dock_type_code"), [SAROS_10R_DOCK])
135+
async def test_set_failure_keeps_state(
136+
cleaning_fluid: CleaningFluidTrait | None,
137+
mock_rpc_channel: AsyncMock,
138+
dock_type_code: RoborockDockTypeCode,
139+
) -> None:
140+
"""Test that a failed command leaves the amount unchanged."""
141+
assert cleaning_fluid is not None
142+
cleaning_fluid.status = RoborockDockCleaningFluidCode.standard
143+
mock_rpc_channel.send_command.side_effect = RoborockException("boom")
144+
145+
with pytest.raises(RoborockException):
146+
await cleaning_fluid.set_cleaning_fluid(RoborockDockCleaningFluidCode.large)
147+
148+
assert cleaning_fluid.status == RoborockDockCleaningFluidCode.standard

0 commit comments

Comments
 (0)