Skip to content

Commit 67ce5a1

Browse files
committed
feat: add Q7 zone cleaning
Add `clean_zone` and `clean_zones` to the Q7 properties API. Zones are given as two opposite corners in the common Roborock millimetre coordinate space through a new `Q7RoborockPoint`, which converts to and from the Q7 world coordinates (meters, origin next to the dock). The device expects the zone preference type to be selected first (`service.set_preference_type`), then the zone corners as a flat list (`service.set_zone_points`), and finally `service.set_zone_clean` to start. Several zones are concatenated into a single task.
1 parent ed5f859 commit 67ce5a1

4 files changed

Lines changed: 133 additions & 2 deletions

File tree

‎roborock/data/b01_q7/b01_q7_containers.py‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
import json
33
from dataclasses import dataclass, field
44
from functools import cached_property
5+
from typing import Self
56

67
from ...exceptions import RoborockException
78
from ..containers import RoborockBase
@@ -77,6 +78,39 @@ class Recommend(RoborockBase):
7778
room_id: list[int] = field(default_factory=list)
7879

7980

81+
_ROBOROCK_COORDINATE_OFFSET_MM = 25_500
82+
_MM_PER_METER = 1000
83+
84+
85+
@dataclass
86+
class Q7RoborockPoint(RoborockBase):
87+
"""A point in the common Roborock millimetre coordinate space.
88+
89+
Q7 firmware uses world coordinates in meters (floats) whose origin is the
90+
map origin next to the dock, with the y axis pointing up. Public Q7 APIs use
91+
this common coordinate system instead, matching other Roborock devices and
92+
placing the map origin at ``(25500, 25500)``.
93+
"""
94+
95+
x: int
96+
y: int
97+
98+
@classmethod
99+
def from_world(cls, x: float, y: float) -> Self:
100+
"""Convert Q7 world coordinates (meters) to common Roborock coordinates."""
101+
return cls(
102+
x=_ROBOROCK_COORDINATE_OFFSET_MM + round(x * _MM_PER_METER),
103+
y=_ROBOROCK_COORDINATE_OFFSET_MM + round(y * _MM_PER_METER),
104+
)
105+
106+
def to_world(self) -> tuple[float, float]:
107+
"""Convert common Roborock coordinates to Q7 world coordinates (meters)."""
108+
return (
109+
(self.x - _ROBOROCK_COORDINATE_OFFSET_MM) / _MM_PER_METER,
110+
(self.y - _ROBOROCK_COORDINATE_OFFSET_MM) / _MM_PER_METER,
111+
)
112+
113+
80114
@dataclass
81115
class Q7MapListEntry(RoborockBase):
82116
"""Single map list entry returned by `service.get_map_list`."""

‎roborock/devices/traits/b01/q7/__init__.py‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
from typing import Any
88

99
from roborock import B01Props
10-
from roborock.data import HomeDataDevice, HomeDataProduct, Q7MapList, Q7MapListEntry
10+
from roborock.data import HomeDataDevice, HomeDataProduct, Q7MapList, Q7MapListEntry, Q7RoborockPoint
1111
from roborock.data.b01_q7.b01_q7_code_mappings import (
1212
CleanPathPreferenceMapping,
1313
CleanRepeatMapping,
@@ -35,8 +35,12 @@
3535
"MapContentTrait",
3636
"Q7MapList",
3737
"Q7MapListEntry",
38+
"Q7RoborockPoint",
3839
]
3940

41+
# ``service.set_preference_type`` value that selects zone cleaning (``custom_type`` 4).
42+
_ZONE_PREFERENCE_TYPE = 4
43+
4044

4145
class Q7PropertiesApi(Trait):
4246
"""API for interacting with B01 Q7 devices."""
@@ -190,6 +194,33 @@ async def clean_segments(self, segment_ids: list[int]) -> None:
190194
},
191195
)
192196

197+
async def clean_zone(self, first_corner: Q7RoborockPoint, second_corner: Q7RoborockPoint) -> None:
198+
"""Clean one rectangular zone given two opposite corners in common Roborock coordinates."""
199+
await self.clean_zones([(first_corner, second_corner)])
200+
201+
async def clean_zones(self, zones: list[tuple[Q7RoborockPoint, Q7RoborockPoint]]) -> None:
202+
"""Clean one or more rectangular zones in a single task.
203+
204+
Each zone is given by two opposite corners in common Roborock coordinates.
205+
The device takes the zones as a flat list of rectangle corners in world
206+
meters (``[x1, y1, x2, y1, x2, y2, x1, y2, ...]``) and needs the zone
207+
preference type selected first; ``set_zone_clean`` then starts the task.
208+
"""
209+
if not zones:
210+
raise ValueError("at least one zone is required")
211+
zone_points: list[float] = []
212+
for first_corner, second_corner in zones:
213+
x1, y1 = first_corner.to_world()
214+
x2, y2 = second_corner.to_world()
215+
if x1 == x2 or y1 == y2:
216+
raise ValueError(f"zone corners must span an area: {first_corner}, {second_corner}")
217+
min_x, max_x = sorted((x1, x2))
218+
min_y, max_y = sorted((y1, y2))
219+
zone_points += [min_x, min_y, max_x, min_y, max_x, max_y, min_x, max_y]
220+
await self.send(RoborockB01Q7Methods.SET_PREFERENCE_TYPE, {"prefer_type": _ZONE_PREFERENCE_TYPE})
221+
await self.send(RoborockB01Q7Methods.SET_ZONE_POINTS, {"zone_points": zone_points})
222+
await self.send(RoborockB01Q7Methods.SET_ZONE_CLEAN, {"ctrl_value": SCDeviceCleanParam.START.code})
223+
193224
async def pause_clean(self) -> None:
194225
"""Pause cleaning."""
195226
await self.send(

‎tests/data/b01_q7/test_b01_q7_containers.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
CleanRecordList,
1414
CleanRepeatMapping,
1515
DustCollectionStateMapping,
16+
Q7RoborockPoint,
1617
SCWindMapping,
1718
StationStateMapping,
1819
WorkStatusMapping,
@@ -277,3 +278,19 @@ def test_b01_q7_clean_record_list_parses_detail_fields():
277278
assert detail.record_faultcode == 0
278279
assert detail.record_dust_num == 0
279280
assert detail.clean_current_map == 0
281+
282+
283+
@pytest.mark.parametrize(
284+
("world", "common"),
285+
[
286+
((0.0, 0.0), (25500, 25500)),
287+
((-0.258, 0.025), (25242, 25525)),
288+
((3.5, -3.2), (29000, 22300)),
289+
],
290+
)
291+
def test_q7_roborock_point_conversion(world: tuple[float, float], common: tuple[int, int]) -> None:
292+
"""Test Q7 world meters convert to the common Roborock millimetre space and back."""
293+
point = Q7RoborockPoint.from_world(*world)
294+
295+
assert (point.x, point.y) == common
296+
assert point.to_world() == pytest.approx(world, abs=0.001)

‎tests/devices/traits/b01/q7/test_init.py‎

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
WaterLevelMapping,
1313
WorkStatusMapping,
1414
)
15-
from roborock.devices.traits.b01.q7 import Q7PropertiesApi
15+
from roborock.devices.traits.b01.q7 import Q7PropertiesApi, Q7RoborockPoint
1616
from roborock.roborock_message import RoborockB01Props
1717
from roborock.roborock_typing import RoborockB01Q7Methods
1818

@@ -360,3 +360,52 @@ async def test_q7_api_clean_segments(q7_api: Q7PropertiesApi, fake_channel: Fake
360360
"ctrl_value": SCDeviceCleanParam.START.code,
361361
"room_ids": [10, 11],
362362
}
363+
364+
365+
async def test_q7_api_clean_zone(q7_api: Q7PropertiesApi, fake_channel: FakeQ7Channel):
366+
"""Test zone cleaning converts common coordinates to Q7 world meters."""
367+
await q7_api.clean_zone(Q7RoborockPoint(x=27000, y=21900), Q7RoborockPoint(x=26000, y=22700))
368+
369+
assert fake_channel.published_commands == [
370+
(RoborockB01Q7Methods.SET_PREFERENCE_TYPE, {"prefer_type": 4}),
371+
(RoborockB01Q7Methods.SET_ZONE_POINTS, {"zone_points": [0.5, -3.6, 1.5, -3.6, 1.5, -2.8, 0.5, -2.8]}),
372+
(RoborockB01Q7Methods.SET_ZONE_CLEAN, {"ctrl_value": SCDeviceCleanParam.START.code}),
373+
]
374+
375+
376+
async def test_q7_api_clean_zones_multiple(q7_api: Q7PropertiesApi, fake_channel: FakeQ7Channel):
377+
"""Test several zones are concatenated into a single task."""
378+
await q7_api.clean_zones(
379+
[
380+
(Q7RoborockPoint(x=26000, y=21900), Q7RoborockPoint(x=27000, y=22700)),
381+
(Q7RoborockPoint(x=28000, y=21900), Q7RoborockPoint(x=28800, y=22700)),
382+
]
383+
)
384+
385+
_, params = fake_channel.published_commands[1]
386+
assert params == {
387+
"zone_points": [
388+
*[0.5, -3.6, 1.5, -3.6, 1.5, -2.8, 0.5, -2.8],
389+
*[2.5, -3.6, 3.3, -3.6, 3.3, -2.8, 2.5, -2.8],
390+
]
391+
}
392+
393+
394+
@pytest.mark.parametrize(
395+
"zones",
396+
[
397+
[],
398+
[(Q7RoborockPoint(x=26000, y=21900), Q7RoborockPoint(x=26000, y=22700))],
399+
[(Q7RoborockPoint(x=26000, y=21900), Q7RoborockPoint(x=27000, y=21900))],
400+
],
401+
)
402+
async def test_q7_api_clean_zones_invalid(
403+
zones: list[tuple[Q7RoborockPoint, Q7RoborockPoint]],
404+
q7_api: Q7PropertiesApi,
405+
fake_channel: FakeQ7Channel,
406+
):
407+
"""Test empty or degenerate zones are rejected before anything is sent."""
408+
with pytest.raises(ValueError):
409+
await q7_api.clean_zones(zones)
410+
411+
assert fake_channel.published_commands == []

0 commit comments

Comments
 (0)