Skip to content

Commit e37ec5a

Browse files
author
Harry Coureau
committed
chore: merge upstream Q10 map lifecycle updates
2 parents 575f824 + ed5f859 commit e37ec5a

25 files changed

Lines changed: 1587 additions & 191 deletions

‎.agents/skills/code-review/SKILL.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ All reviews are evaluated against the engineering conventions defined in [AGENTS
3737
- **Event Loop Safety**: Are CPU-intensive operations (e.g., heavy map decompression or PIL image rendering) kept off the `asyncio` event loop (such as via `asyncio.to_thread`) with proper concurrency/staleness guards?
3838
- **Concurrency**: Does 1:1 async command-response matching use `asyncio.Future` correlated by protocol request/sequence ID (`request_id` or `msg_id`)?
3939
- **Teardown**: Are all tasks, event listeners, and channels cleanly unhooked in `RoborockDevice.close()`?
40-
- **Capability Gating**: Is capability gating checking protocol version, category (appropriate for device family), and device feature flags?
40+
- **Capability Gating vs. Telemetry Decoding**: Are non-universal traits, commands, and selectable options gated by protocol version, category, and `device.features`? Conversely, avoid over-gating read-only telemetry/status decoding (`from_code_optional()`) on feature flags when wire codes are unambiguous—feature flags in status resolvers are only appropriate to disambiguate genuinely overloaded wire codes or synthetic range interpolation, otherwise unmapped feature bits on new firmware unnecessarily degrade status to `None`/`unknown`.
4141

4242
4. **Evaluate Layer 3: Wire Protocols, Codecs & Resilient Enums**:
4343
- Do status and error code enums subclass `RoborockEnum` (with lowercase `unknown = -1` member) or `RoborockModeEnum` (with `from_code_optional()`)?
@@ -50,7 +50,14 @@ All reviews are evaluated against the engineering conventions defined in [AGENTS
5050
- Are tests using `fake_channel` and `@pytest.mark.parametrize` rather than hand-rolled mocks or duplicate methods?
5151
- Do assertions verify public behavior rather than private `_state` variables?
5252

53-
6. **Format Review Output**:
53+
6. **Adversarial Self-Check on Candidate Findings**:
54+
Before presenting or posting any review comment, subject every candidate finding and suggested diff to hostile adversarial scrutiny and discard any that fail:
55+
- **Baseline & History Check**: Trace concrete inputs across `upstream/main`, the PR, and your proposed fix (inspecting `git log` / blame when existing test or helper intent is non-obvious). Discard suggestions that silently regress `main` behavior on valid inputs or introduce magic-number/boundary duplication.
56+
- **Verify Rationale Against Peer Cases**: Check sibling functions and enum codes in the same module to confirm your stated invariant actually holds across the codebase rather than inventing a stricter rule for the touched lines alone.
57+
- **Independent Check of Prior Reviews**: When comparing competing PRs or prior review comments (human or AI), evaluate those claims with the same adversarial skepticism instead of carrying them forward uncritically.
58+
- **Drop Low-Value Nits & Allow Zero-Defect Approvals**: Drop trivial docstring or comment wording nits (especially in tests) unless factually harmful, and verify any suggested replacement text accurately reflects what the code/test asserts. If no findings survive adversarial scrutiny, report that the PR is clean and ready to approve rather than manufacturing filler comments.
59+
60+
7. **Format Review Output**:
5461
Structure review comments with clear rationale and actionable code recommendations:
5562
- **Priority Level & File Reference**
5663
- **Issue / Anti-Pattern Identified**

‎CHANGELOG.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,70 @@
22

33
<!-- version list -->
44

5+
## v7.22.0 (2026-11-09)
6+
7+
### Bug Fixes
8+
9+
- Preserve Q10 room labels and sample header calibration
10+
([#939](https://github.com/Python-roborock/python-roborock/pull/939),
11+
[`3ec517e`](https://github.com/Python-roborock/python-roborock/commit/3ec517e8d4cdca89f5cd92c20b9403d9103a98f9))
12+
13+
### Features
14+
15+
- Expose Q10 current cleaning room
16+
([#939](https://github.com/Python-roborock/python-roborock/pull/939),
17+
[`3ec517e`](https://github.com/Python-roborock/python-roborock/commit/3ec517e8d4cdca89f5cd92c20b9403d9103a98f9))
18+
19+
20+
## v7.21.0 (2026-11-08)
21+
22+
### Bug Fixes
23+
24+
- Keep Q10 archive traits lightweight
25+
([#937](https://github.com/Python-roborock/python-roborock/pull/937),
26+
[`252ec92`](https://github.com/Python-roborock/python-roborock/commit/252ec92dc19cefb43108fb42a0e8f41e2937517a))
27+
28+
### Features
29+
30+
- Expose Q10 map archives ([#937](https://github.com/Python-roborock/python-roborock/pull/937),
31+
[`252ec92`](https://github.com/Python-roborock/python-roborock/commit/252ec92dc19cefb43108fb42a0e8f41e2937517a))
32+
33+
34+
## v7.20.0 (2026-11-08)
35+
36+
### Bug Fixes
37+
38+
- **v1**: Correct feature gate, require repeat, reject malformed entries
39+
([#984](https://github.com/Python-roborock/python-roborock/pull/984),
40+
[`e6d5196`](https://github.com/Python-roborock/python-roborock/commit/e6d5196649f02360be308e7cc84178571ac7a732))
41+
42+
- **v1**: Require mop_mode in set_clean_then_mop, document repeat reset
43+
([#984](https://github.com/Python-roborock/python-roborock/pull/984),
44+
[`e6d5196`](https://github.com/Python-roborock/python-roborock/commit/e6d5196649f02360be308e7cc84178571ac7a732))
45+
46+
- **v1**: Serialize writes and round-trip unmodeled fields losslessly
47+
([#984](https://github.com/Python-roborock/python-roborock/pull/984),
48+
[`e6d5196`](https://github.com/Python-roborock/python-roborock/commit/e6d5196649f02360be308e7cc84178571ac7a732))
49+
50+
### Chores
51+
52+
- Fix codespell typo in customize clean mode tests
53+
([#984](https://github.com/Python-roborock/python-roborock/pull/984),
54+
[`e6d5196`](https://github.com/Python-roborock/python-roborock/commit/e6d5196649f02360be308e7cc84178571ac7a732))
55+
56+
### Documentation
57+
58+
- Add adversarial self-check to code-review skill
59+
([#1020](https://github.com/Python-roborock/python-roborock/pull/1020),
60+
[`9d73026`](https://github.com/Python-roborock/python-roborock/commit/9d73026844def166c6243db8f586481090d63210))
61+
62+
### Features
63+
64+
- **v1**: Expose per-room clean-then-mop via customize clean mode
65+
([#984](https://github.com/Python-roborock/python-roborock/pull/984),
66+
[`e6d5196`](https://github.com/Python-roborock/python-roborock/commit/e6d5196649f02360be308e7cc84178571ac7a732))
67+
68+
569
## v7.19.0 (2026-11-08)
670

771
### Bug Fixes

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "python-roborock"
3-
version = "7.19.0"
3+
version = "7.22.0"
44
description = "A package to control Roborock vacuums."
55
authors = [{ name = "humbertogontijo", email = "humbertogontijo@users.noreply.github.com" }, {name="Lash-L"}, {name="allenporter"}]
66
requires-python = ">=3.11, <4"

‎roborock/data/b01_q10/b01_q10_containers.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,9 @@ class Q10MapInfo(RoborockBase):
147147
"""A saved map reported by ``dpMultiMap``.
148148
149149
Q10 firmware represents the map identifier as a string on the wire. The
150-
value is sent back unchanged in a subsequent ``{"op": "get"}`` request.
150+
value is sent back unchanged in a subsequent ``{"op": "select"}`` detail
151+
request. On Q10 firmware, ``select`` previews a saved map without applying
152+
it as the active map.
151153
"""
152154

153155
id: str

‎roborock/data/v1/v1_containers.py‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -515,6 +515,56 @@ class WashTowelMode(RoborockBase):
515515
wash_mode: WashTowelModes | None = None
516516

517517

518+
SEQ_TYPE_CLEAN_THEN_MOP = 1
519+
520+
521+
@dataclass
522+
class SegmentCleanMode(RoborockBase):
523+
"""A single room's clean mode override, as reported by the device.
524+
525+
`fan_power` / `water_box_mode` / `mop_mode` / `seq_type` are kept as raw
526+
`int | None` wire codes rather than typed enums, matching `StatusV2`, so
527+
model-specific values (e.g. water-slide codes like 222) round-trip
528+
losslessly even for codes this library doesn't otherwise model.
529+
530+
`mop_power` and `custom_water_box_distance` are only reported by some
531+
models (roller-mop / custom-water-flow devices); they are `None` on
532+
models that don't report them.
533+
"""
534+
535+
segment: int
536+
fan_power: int | None = None
537+
water_box_mode: int | None = None
538+
mop_mode: int | None = None
539+
repeat: int | None = None
540+
seq_type: int | None = None
541+
mop_power: int | None = None
542+
custom_water_box_distance: int | None = None
543+
544+
@property
545+
def clean_then_mop(self) -> bool | None:
546+
"""Whether this room is vacuumed fully before it is mopped.
547+
548+
`None` means the device did not report a sequence type for this
549+
room's override.
550+
"""
551+
if self.seq_type is None:
552+
return None
553+
return self.seq_type == SEQ_TYPE_CLEAN_THEN_MOP
554+
555+
556+
@dataclass
557+
class CustomizeCleanModes(RoborockBase):
558+
"""Collection of per-room clean mode overrides."""
559+
560+
modes: list[SegmentCleanMode] | None = None
561+
562+
@property
563+
def by_segment(self) -> dict[int, SegmentCleanMode]:
564+
"""Index the overrides by segment id."""
565+
return {mode.segment: mode for mode in self.modes or []}
566+
567+
518568
@dataclass
519569
class NetworkInfo(RoborockBase):
520570
ip: str

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

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,13 @@
88
from roborock.data.containers import RoborockBase
99
from roborock.devices.rpc.b01_q10_channel import B01Q10Channel
1010
from roborock.devices.traits import Trait
11-
from roborock.map.b01_q10_map_parser import B01Q10MapParserConfig, Q10MapPacket, Q10TracePacket
11+
from roborock.map.b01_q10_map_parser import (
12+
B01Q10MapParserConfig,
13+
Q10CleanRecordDetail,
14+
Q10MapPacket,
15+
Q10MapPacketKind,
16+
Q10TracePacket,
17+
)
1218
from roborock.protocols.b01_q10_protocol import Q10DpsUpdate, Q10Message
1319

1420
from .button_light import ButtonLightTrait
@@ -97,7 +103,12 @@ class Q10PropertiesApi(Trait):
97103
clean_history: CleanHistoryTrait
98104
"""Trait for fetching the device clean-record history (``dpCleanRecord``)."""
99105

100-
def __init__(self, channel: B01Q10Channel, *, map_parser_config: B01Q10MapParserConfig | None = None) -> None:
106+
def __init__(
107+
self,
108+
channel: B01Q10Channel,
109+
*,
110+
map_parser_config: B01Q10MapParserConfig | None = None,
111+
) -> None:
101112
"""Initialize the B01Props API."""
102113
self._channel = channel
103114
self.command = CommandTrait(channel)
@@ -112,10 +123,14 @@ def __init__(self, channel: B01Q10Channel, *, map_parser_config: B01Q10MapParser
112123
self.consumable = ConsumableTrait()
113124
self._map_dps = MapDpsTrait()
114125
self.maps = MapsTrait(self.command)
115-
self.map = MapContentTrait(self._map_dps, self.maps, self.command, map_parser_config=map_parser_config)
126+
self.map = MapContentTrait(
127+
self._map_dps,
128+
self.command,
129+
map_parser_config=map_parser_config,
130+
)
116131
self.room_cleaning = RoomCleaningTrait(self.command)
117-
self.vacuum = VacuumTrait(self.command, self.status, self.map)
118132
self.clean_history = CleanHistoryTrait(self.command)
133+
self.vacuum = VacuumTrait(self.command, self.status, self.map)
119134
# Read-model traits updated from the device's DPS push stream.
120135
self._updatable_traits = [
121136
self.status,
@@ -165,7 +180,12 @@ def _handle_message(self, message: Q10Message) -> None:
165180
Map-list DPS responses and other DPS updates feed the read-model traits.
166181
"""
167182
if isinstance(message, Q10MapPacket):
168-
self.map.update_from_map_packet(message)
183+
if message.kind is Q10MapPacketKind.CURRENT:
184+
self.map.update_from_map_packet(message)
185+
elif message.kind is Q10MapPacketKind.SAVED_MAP_DETAIL:
186+
self.maps.update_from_map_packet(message)
187+
elif isinstance(message, Q10CleanRecordDetail):
188+
self.clean_history.update_from_detail(message)
169189
elif isinstance(message, Q10TracePacket):
170190
self.map.update_from_trace_packet(message)
171191
elif isinstance(message, Q10DpsUpdate):
@@ -186,6 +206,13 @@ def as_dict(self) -> dict[str, Any]:
186206
return result
187207

188208

189-
def create(channel: B01Q10Channel, *, map_parser_config: B01Q10MapParserConfig | None = None) -> Q10PropertiesApi:
209+
def create(
210+
channel: B01Q10Channel,
211+
*,
212+
map_parser_config: B01Q10MapParserConfig | None = None,
213+
) -> Q10PropertiesApi:
190214
"""Create traits for B01 devices."""
191-
return Q10PropertiesApi(channel, map_parser_config=map_parser_config)
215+
return Q10PropertiesApi(
216+
channel,
217+
map_parser_config=map_parser_config,
218+
)

‎roborock/devices/traits/b01/q10/clean_history.py‎

Lines changed: 71 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
from dataclasses import dataclass, field
1515
from typing import Any
1616

17+
from roborock.data import RoborockBase
1718
from roborock.data.b01_q10.b01_q10_code_mappings import (
1819
B01_Q10_DP,
1920
YXCleaningResult,
@@ -22,11 +23,20 @@
2223
YXStartMethod,
2324
)
2425
from roborock.data.b01_q10.b01_q10_containers import Q10CleanRecord
26+
from roborock.exceptions import RoborockException
27+
from roborock.map.b01_q10_map_parser import (
28+
Q10CleanRecordDetail,
29+
Q10HistoricalTracePacket,
30+
Q10MapPacket,
31+
Q10MapPacketKind,
32+
Q10Point,
33+
)
2534

2635
from .command import CommandTrait
2736
from .common import UpdatableTrait
2837

2938
__all__ = [
39+
"CleanHistory",
3040
"CleanHistoryTrait",
3141
"CleanRecordConverter",
3242
"CleanRecordPush",
@@ -107,40 +117,78 @@ def parse_record(raw: Any | None) -> Q10CleanRecord | None:
107117
return None
108118

109119

110-
class CleanHistoryTrait(UpdatableTrait):
111-
"""Access to the Q10 clean-record history (``dpCleanRecord``, DP 52).
112-
113-
A read-model trait updated from the DPS stream like the others, but it overrides
114-
:meth:`update_from_dps` because the payload is a structured push (a record list,
115-
or a single ``op:"notify"`` record) rather than a flat data-point-to-field map.
116-
"""
120+
@dataclass
121+
class CleanHistory(RoborockBase):
122+
"""Received clean-history data, independent of request and transport state."""
117123

118-
def __init__(self, command: CommandTrait) -> None:
119-
"""Initialize the clean history trait."""
120-
UpdatableTrait.__init__(self, command, _LOGGER)
121-
self._converter = CleanRecordConverter()
122-
self.records: list[Q10CleanRecord] = []
123-
"""Decoded clean records, most recent first."""
124+
records: list[Q10CleanRecord] = field(default_factory=list)
125+
"""Decoded clean records, most recent first."""
126+
detail: Q10CleanRecordDetail | None = None
127+
"""Latest received archive. Its wire payload contains no record identifier."""
128+
detail_path: list[Q10Point] = field(default_factory=list)
129+
"""Historical path points from the latest received archive, included in diagnostics."""
124130

125131
@property
126132
def last_record(self) -> Q10CleanRecord | None:
127133
"""The most recent clean record, or ``None`` if there are none."""
128134
return self.records[0] if self.records else None
129135

136+
@property
137+
def detail_packet(self) -> Q10MapPacket | None:
138+
"""The map from the most recently received clean-record detail."""
139+
return self.detail.map if self.detail else None
140+
141+
@property
142+
def detail_trace(self) -> Q10HistoricalTracePacket | None:
143+
"""Historical path embedded in the latest received clean-record detail."""
144+
return self.detail.trace if self.detail else None
145+
146+
def as_dict(self, exclude: set[str] | None = None) -> dict[str, Any]:
147+
"""Serialize history metadata and path without binary map packets and grids."""
148+
return super().as_dict(exclude=(exclude or set()) | {"detail"})
149+
150+
151+
class CleanHistoryTrait(CleanHistory, UpdatableTrait):
152+
"""Browse past cleaning runs and retrieve their parsed maps and historical paths.
153+
154+
Subscribe with ``add_update_listener`` to receive requested or unsolicited
155+
archives. Archive pushes contain no record ID, so the latest detail cannot
156+
be attributed to a particular selection.
157+
"""
158+
159+
_command: CommandTrait
160+
161+
def __init__(self, command: CommandTrait) -> None:
162+
CleanHistory.__init__(self)
163+
UpdatableTrait.__init__(self, command, _LOGGER)
164+
self._command = command
165+
self._converter = CleanRecordConverter()
166+
130167
async def refresh(self) -> None:
131168
"""Request the clean-record list from the device.
132169
133170
This sends the query and returns immediately; the records arrive
134171
asynchronously on the device stream and populate :attr:`records` once
135172
:meth:`update_from_dps` processes the ``dpCleanRecord`` push.
136173
"""
137-
if self._command is None:
138-
raise ValueError("Trait is read-only; no command channel was provided")
139174
await self._command.send(
140175
B01_Q10_DP.COMMON,
141176
params={str(B01_Q10_DP.CLEAN_RECORD.code): {"op": "list"}},
142177
)
143178

179+
async def refresh_detail(self, record: Q10CleanRecord) -> None:
180+
"""Request the saved map and path for a past cleaning run.
181+
182+
Returns after sending; listeners receive the archive separately. The
183+
push contains no record ID to correlate it with this selection.
184+
"""
185+
if not record.raw or not record.map_len:
186+
raise RoborockException("The Q10 clean record has no saved map detail")
187+
await self._command.send(
188+
B01_Q10_DP.COMMON,
189+
{str(B01_Q10_DP.CLEAN_RECORD.code): {"op": "select", "id": record.raw}},
190+
)
191+
144192
def update_from_dps(self, decoded_dps: dict[B01_Q10_DP, Any]) -> None:
145193
"""Apply a ``dpCleanRecord`` push (a full list reply or a single notify)."""
146194
envelope = decoded_dps.get(B01_Q10_DP.CLEAN_RECORD)
@@ -151,6 +199,14 @@ def update_from_dps(self, decoded_dps: dict[B01_Q10_DP, Any]) -> None:
151199
return
152200
self._apply(push)
153201

202+
def update_from_detail(self, detail: Q10CleanRecordDetail) -> None:
203+
"""Store a pushed clean-record map and path and notify listeners."""
204+
if detail.map.kind is not Q10MapPacketKind.CLEAN_RECORD_DETAIL:
205+
raise ValueError(f"Expected a Q10 clean-record detail packet, got {detail.map.kind.value}")
206+
self.detail = detail
207+
self.detail_path = list(detail.trace.points) if detail.trace else []
208+
self._notify_update()
209+
154210
def _apply(self, push: CleanRecordPush) -> None:
155211
"""Merge or replace the records from ``push``, then sort newest-first and notify."""
156212
if push.replace:

0 commit comments

Comments
 (0)