From 7b311e81fee67152356c685ecc5d91081effc6f1 Mon Sep 17 00:00:00 2001 From: cptntrps <50712262+cptntrps@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:31:59 -0500 Subject: [PATCH] feat(v1): add CleanSequenceTrait for the room cleaning order Reads get_clean_sequence into CleanSequence.rooms and writes it with set_clean_sequence. Gated on is_order_clean_supported (robot feature 123). --- roborock/data/v1/v1_containers.py | 10 ++ roborock/devices/traits/v1/__init__.py | 4 + roborock/devices/traits/v1/clean_sequence.py | 41 ++++++++ .../devices/traits/v1/test_clean_sequence.py | 95 +++++++++++++++++++ 4 files changed, 150 insertions(+) create mode 100644 roborock/devices/traits/v1/clean_sequence.py create mode 100644 tests/devices/traits/v1/test_clean_sequence.py diff --git a/roborock/data/v1/v1_containers.py b/roborock/data/v1/v1_containers.py index 65bcba64..512c3dd9 100644 --- a/roborock/data/v1/v1_containers.py +++ b/roborock/data/v1/v1_containers.py @@ -553,6 +553,16 @@ def clean_then_mop(self) -> bool | None: return self.seq_type == SEQ_TYPE_CLEAN_THEN_MOP +@dataclass +class CleanSequence(RoborockBase): + """The order in which the device cleans rooms, as segment ids. + + Rooms that are not listed are cleaned after the listed ones. + """ + + rooms: list[int] | None = None + + @dataclass class CustomizeCleanModes(RoborockBase): """Collection of per-room clean mode overrides.""" diff --git a/roborock/devices/traits/v1/__init__.py b/roborock/devices/traits/v1/__init__.py index 28c404d6..1b6034db 100644 --- a/roborock/devices/traits/v1/__init__.py +++ b/roborock/devices/traits/v1/__init__.py @@ -71,6 +71,7 @@ from . import ( camera, child_lock, + clean_sequence, clean_summary, command, common, @@ -97,6 +98,7 @@ ) from .camera import CameraTrait from .child_lock import ChildLockTrait +from .clean_sequence import CleanSequenceTrait from .clean_summary import CleanSummaryTrait from .command import CommandTrait from .common import V1TraitMixin @@ -127,6 +129,7 @@ "PropertiesApi", "camera", "child_lock", + "clean_sequence", "clean_summary", "command", "common", @@ -187,6 +190,7 @@ class PropertiesApi(Trait): obstacle_photos: ObstaclePhotoTrait | None = None mop_dryer: MopDryerTrait | None = None customize_clean_mode: CustomizeCleanModeTrait | None = None + clean_sequence: CleanSequenceTrait | None = None def __init__( self, diff --git a/roborock/devices/traits/v1/clean_sequence.py b/roborock/devices/traits/v1/clean_sequence.py new file mode 100644 index 00000000..f4d942a2 --- /dev/null +++ b/roborock/devices/traits/v1/clean_sequence.py @@ -0,0 +1,41 @@ +"""Trait for the room cleaning order of Roborock devices.""" + +from roborock.data import CleanSequence +from roborock.devices.traits.v1 import common +from roborock.roborock_typing import RoborockCommand + +from .common import V1ResponseData + + +class CleanSequenceConverter(common.V1TraitDataConverter): + """Converts get_clean_sequence responses to CleanSequence.""" + + def convert(self, response: V1ResponseData) -> CleanSequence: + """Parse the list of segment ids returned by the device.""" + if not isinstance(response, list) or not all(isinstance(room, int) for room in response): + raise ValueError(f"Unexpected CleanSequence response format: {response!r}") + return CleanSequence(rooms=list(response)) + + +class CleanSequenceTrait(CleanSequence, common.V1TraitMixin): + """Trait for reading and setting the order in which rooms are cleaned. + + The device keeps this order and uses it for room cleaning + (`app_segment_clean`), whatever order the segments are sent in. + """ + + command = RoborockCommand.GET_CLEAN_SEQUENCE + converter = CleanSequenceConverter() + requires_feature = "is_order_clean_supported" + + async def set_order(self, rooms: list[int]) -> None: + """Set the room cleaning order. + + A device rejects a new order with an invalid status error while it is + cleaning or moving; set it while the device is idle or docked. + """ + if not rooms or len(set(rooms)) != len(rooms): + raise ValueError(f"rooms must be a non-empty list of distinct segment ids: {rooms!r}") + await self.rpc_channel.send_command(RoborockCommand.SET_CLEAN_SEQUENCE, params=list(rooms)) + # Optimistic update to avoid an extra refresh + self.rooms = list(rooms) diff --git a/tests/devices/traits/v1/test_clean_sequence.py b/tests/devices/traits/v1/test_clean_sequence.py new file mode 100644 index 00000000..449e63ff --- /dev/null +++ b/tests/devices/traits/v1/test_clean_sequence.py @@ -0,0 +1,95 @@ +"""Tests for the CleanSequenceTrait class.""" + +from unittest.mock import AsyncMock + +import pytest + +from roborock.data import HomeDataDevice +from roborock.devices.device import RoborockDevice +from roborock.devices.traits.v1.clean_sequence import CleanSequenceTrait +from roborock.exceptions import RoborockParsingException +from roborock.roborock_typing import RoborockCommand +from tests import mock_data + +S5E = mock_data.DEVICE_PRODUCT_PAIRS["home_data_device_s5e.json"][0] + + +@pytest.fixture(name="clean_sequence_trait") +def clean_sequence_trait_fixture( + device: RoborockDevice, + discover_features_fixture: None, +) -> CleanSequenceTrait | None: + """Return the discovered CleanSequenceTrait from the device.""" + assert device.v1_properties + return device.v1_properties.clean_sequence + + +def test_requires_feature() -> None: + """The trait is only created on devices that report order cleaning (robot feature 123).""" + assert CleanSequenceTrait.requires_feature == "is_order_clean_supported" + + +@pytest.mark.parametrize("device_info", [S5E]) +async def test_refresh( + clean_sequence_trait: CleanSequenceTrait | None, + mock_rpc_channel: AsyncMock, + device_info: HomeDataDevice, +) -> None: + """The response is the list of segment ids in cleaning order.""" + assert clean_sequence_trait is not None + mock_rpc_channel.send_command.side_effect = [[8, 3, 7, 10, 1, 9]] + + await clean_sequence_trait.refresh() + + mock_rpc_channel.send_command.assert_called_once_with(RoborockCommand.GET_CLEAN_SEQUENCE) + assert clean_sequence_trait.rooms == [8, 3, 7, 10, 1, 9] + + +@pytest.mark.parametrize("device_info", [S5E]) +@pytest.mark.parametrize("response", [{"unexpected": "shape"}, ["7"], [7, None]]) +async def test_refresh_bad_format( + clean_sequence_trait: CleanSequenceTrait | None, + mock_rpc_channel: AsyncMock, + device_info: HomeDataDevice, + response: object, +) -> None: + """A response that is not a list of segment ids raises a parsing error.""" + assert clean_sequence_trait is not None + mock_rpc_channel.send_command.side_effect = [response] + + with pytest.raises(RoborockParsingException): + await clean_sequence_trait.refresh() + + +@pytest.mark.parametrize("device_info", [S5E]) +async def test_set_order( + clean_sequence_trait: CleanSequenceTrait | None, + mock_rpc_channel: AsyncMock, + device_info: HomeDataDevice, +) -> None: + """set_order sends the list as is and updates the trait.""" + assert clean_sequence_trait is not None + mock_rpc_channel.send_command.side_effect = [["ok"]] + + await clean_sequence_trait.set_order([7, 8, 3, 10, 1, 9]) + + mock_rpc_channel.send_command.assert_called_once_with( + RoborockCommand.SET_CLEAN_SEQUENCE, params=[7, 8, 3, 10, 1, 9] + ) + assert clean_sequence_trait.rooms == [7, 8, 3, 10, 1, 9] + + +@pytest.mark.parametrize("device_info", [S5E]) +@pytest.mark.parametrize("rooms", [[], [7, 7]]) +async def test_set_order_rejects_bad_input( + clean_sequence_trait: CleanSequenceTrait | None, + mock_rpc_channel: AsyncMock, + device_info: HomeDataDevice, + rooms: list[int], +) -> None: + """An empty list or a repeated room is refused before anything is sent.""" + assert clean_sequence_trait is not None + + with pytest.raises(ValueError): + await clean_sequence_trait.set_order(rooms) + mock_rpc_channel.send_command.assert_not_called()