python-roborock 7.11.1__tar.gz → 7.12.1__tar.gz

{python_roborock-7.11.1 → python_roborock-7.12.1}/.gitignore

@@ -19,3 +19,6 @@ docs/_build/
 
 # GitHub App credentials
 gha-creds-*.json
+
+# pytest-benchmark storage
+.benchmarks/

{python_roborock-7.11.1 → python_roborock-7.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-roborock
-Version: 7.11.1
+Version: 7.12.1
 Summary: A package to control Roborock vacuums.
 Project-URL: Repository, https://github.com/python-roborock/python-roborock
 Project-URL: Documentation, https://python-roborock.readthedocs.io/

{python_roborock-7.11.1 → python_roborock-7.12.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "7.11.1"
+version = "7.12.1"
 description = "A package to control Roborock vacuums."
 authors = [{ name = "humbertogontijo", email = "humbertogontijo@users.noreply.github.com" }, {name="Lash-L"}, {name="allenporter"}]
 requires-python = ">=3.11, <4"
@@ -67,6 +67,8 @@ dev = [
     "syrupy>=4.9.1,<6",
     "pdoc>=15.0.4,<17",
     "pytest-cov>=7.0.0",
+    "zmqtt>=0.2.0,<0.3.0",
+    "pytest-benchmark>=5.1.0",
 ]
 
 [tool.hatch.build.targets.sdist]
@@ -146,6 +148,8 @@ module = ["roborock.map.proto.*"]
 ignore_errors = true
 
 [tool.pytest.ini_options]
+addopts = "-m 'not mqtt_broker'"
+markers = ["mqtt_broker: tests requiring a real MQTT broker"]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 timeout = 30

{python_roborock-7.11.1 → python_roborock-7.12.1}/roborock/data/v1/v1_clean_modes.py

@@ -57,9 +57,10 @@ class WaterModes(RoborockModeEnum):
     SMART_MODE = ("smart_mode", 209)
     PURE_WATER_FLOW_START = ("slight", 221)
     PURE_WATER_FLOW_SMALL = ("low", 225)
+    PURE_WATER_FLOW_GENTLE = ("gentle", 230)
     PURE_WATER_FLOW_MIDDLE = ("medium", 235)
-    PURE_WATER_FLOW_LARGE = ("moderate", 245)
-    PURE_WATER_SUPER_BEGIN = ("high", 248)
+    PURE_WATER_FLOW_LARGE = ("moderate", 240)
+    PURE_WATER_SUPER_BEGIN = ("high", 245)
     PURE_WATER_FLOW_END = ("extreme", 250)
 
 
@@ -91,12 +92,25 @@ WATER_SLIDE_MODE_MAPPING: dict[int, WaterModes] = {
     200: WaterModes.OFF,
     221: WaterModes.PURE_WATER_FLOW_START,
     225: WaterModes.PURE_WATER_FLOW_SMALL,
+    230: WaterModes.PURE_WATER_FLOW_GENTLE,
     235: WaterModes.PURE_WATER_FLOW_MIDDLE,
-    245: WaterModes.PURE_WATER_FLOW_LARGE,
-    248: WaterModes.PURE_WATER_SUPER_BEGIN,
+    240: WaterModes.PURE_WATER_FLOW_LARGE,
+    245: WaterModes.PURE_WATER_SUPER_BEGIN,
     250: WaterModes.PURE_WATER_FLOW_END,
 }
 
+# Water slide devices report the raw slider position (1-30) as 220 + position.
+# The app groups positions into named ranges, keyed here by their last position.
+_WATER_SLIDE_RANGES: tuple[tuple[int, WaterModes], ...] = (
+    (3, WaterModes.PURE_WATER_FLOW_START),
+    (7, WaterModes.PURE_WATER_FLOW_SMALL),
+    (12, WaterModes.PURE_WATER_FLOW_GENTLE),
+    (17, WaterModes.PURE_WATER_FLOW_MIDDLE),
+    (22, WaterModes.PURE_WATER_FLOW_LARGE),
+    (27, WaterModes.PURE_WATER_SUPER_BEGIN),
+    (30, WaterModes.PURE_WATER_FLOW_END),
+)
+
 ModeEnumT = TypeVar("ModeEnumT", bound=RoborockModeEnum)
 
 
@@ -183,6 +197,19 @@ def get_water_modes(features: DeviceFeatures) -> list[WaterModes]:
     return supported_modes
 
 
+def get_water_slide_mode_name(code: int) -> str | None:
+    """Get the app's range name for a water slide code, or None if out of range."""
+    if code == 200:
+        return WaterModes.OFF.value
+    position = code - 220
+    if position < 1:
+        return None
+    for last_position, mode in _WATER_SLIDE_RANGES:
+        if position <= last_position:
+            return mode.value
+    return None
+
+
 def get_water_mode_mapping(features: DeviceFeatures) -> dict[int, str]:
     """Get water mode mapping by supported feature set.
 

{python_roborock-7.11.1 → python_roborock-7.12.1}/roborock/devices/traits/v1/status.py

@@ -15,6 +15,7 @@ from roborock import (
     get_current_cleaning_mode,
     get_water_mode_mapping,
     get_water_modes,
+    get_water_slide_mode_name,
     resolve_cleaning_mode,
 )
 from roborock.devices.traits.common import DpsDataConverter, TraitUpdateListener
@@ -103,6 +104,8 @@ class StatusTrait(StatusV2, common.V1TraitMixin, TraitUpdateListener):
     def water_mode_name(self) -> str | None:
         if self.water_box_mode is None:
             return None
+        if self._device_features_trait.is_water_slide_mode_supported:
+            return get_water_slide_mode_name(self.water_box_mode)
         return self.water_mode_mapping.get(self.water_box_mode)
 
     @property

{python_roborock-7.11.1 → python_roborock-7.12.1}/roborock/map/b01_q10_map_parser.py

@@ -1,8 +1,9 @@
 """Parser for Roborock Q10 (B01/ss07) map packets.
 
-Q10 devices deliver map data as a protocol-301 ``MAP_RESPONSE`` message after a
-``dpMultiMap`` list/get request. Unlike the Q7 ``SCMap`` protobuf
-format, the Q10 uses a custom, unencrypted binary packet:
+Q10 devices deliver map data as protocol-301 ``MAP_RESPONSE`` pushes. Current
+maps follow a read-only status request, while saved-map and clean-record detail
+packets follow their respective ``select`` requests. Unlike the Q7 ``SCMap``
+protobuf format, the Q10 uses a custom, unencrypted binary packet:
 
 - ``01 01`` marker, then a ``u32be`` map id (bytes 2-5) and two consecutive
   ``u16be`` dimensions: grid width (bytes 7-8) and grid height (bytes 9-10).
@@ -22,6 +23,7 @@ https://github.com/v1b3c0d3x3r/roborock-qseries-map-bridge
 import io
 import math
 import statistics
+import struct
 from dataclasses import dataclass, field, replace
 
 from PIL import Image
@@ -30,6 +32,7 @@ from vacuum_map_parser_base.config.image_config import ImageConfig
 from vacuum_map_parser_base.map_data import ImageData, MapData, Point
 
 from roborock.data.b01_q10.b01_q10_containers import Q10RoborockPoint
+from roborock.data.code_mappings import RoborockEnum
 from roborock.data.containers import RoborockBase
 from roborock.exceptions import RoborockException
 
@@ -67,9 +70,6 @@ def classify_q10_cell(value: int) -> str:
     return LAYER_FLOOR
 
 
-MAP_PACKET_MARKER = b"\x01\x01"
-TRACE_PACKET_MARKER = b"\x02\x01"
-
 _MAP_ID_OFFSET = 2
 # Width and height are two consecutive u16be fields. An earlier revision read the
 # width as u16le at offset 8; that high byte is actually the height's high byte,
@@ -84,6 +84,7 @@ _LAYOUT_COMPRESSED_OFFSET = 29
 _ROOM_RECORD_LENGTH = 47
 _ROOM_NAME_LENGTH_OFFSET = 26
 _MAX_ROOMS = 32
+_MAX_GRID_CELLS = 16_000_000
 # Sanity bound for the erase-zone vector section's vertices-per-polygon field.
 _MAX_ERASE_ZONE_VERTICES = 16
 
@@ -195,10 +196,34 @@ class Q10HeaderCalibration:
         )
 
 
+class Q10MapPacketKind(RoborockEnum):
+    """Semantic kind identified by a Q10 map packet's two-byte marker."""
+
+    unknown = -1
+    CURRENT = 1
+    TRACE = 2
+    CLEAN_RECORD_DETAIL = 3
+    SAVED_MAP_DETAIL = 4
+
+    @property
+    def marker(self) -> bytes:
+        """Return the two-byte wire marker for this packet kind."""
+        return b"" if self is self.unknown else bytes((self.value, 1))
+
+    @classmethod
+    def from_payload(cls, payload: bytes) -> "Q10MapPacketKind | None":
+        """Return the recognized kind for a payload marker."""
+        if len(payload) < 2 or payload[1] != 1:
+            return None
+        kind = cls(payload[0])
+        return None if kind is cls.unknown else kind
+
+
 @dataclass
 class Q10MapPacket:
-    """Decoded contents of a Q10 ``01 01`` map packet."""
+    """Decoded contents of a Q10 current or archived map packet."""
 
+    kind: Q10MapPacketKind
     map_id: int
     width: int
     height: int
@@ -271,6 +296,33 @@ class Q10TracePacket:
         return self.points[-1] if self.points else None
 
 
+@dataclass
+class Q10HistoricalTracePacket:
+    """Cleaning path embedded in a Q10 ``03 01`` clean-record detail packet.
+
+    This is a different wire layout from the live ``02 01`` trace. Its header
+    carries a 16-bit format version, a 32-bit opaque value, a 32-bit
+    point count, a signed heading, and a zero reserved word. Points use the same
+    signed big-endian ``(x, y)`` coordinate pairs as the live trace.
+    """
+
+    points: list[Q10Point] = field(default_factory=list)
+    heading: int = 0
+
+    @property
+    def robot_position(self) -> Q10Point | None:
+        """The final recorded position, if the historical path is non-empty."""
+        return self.points[-1] if self.points else None
+
+
+@dataclass
+class Q10CleanRecordDetail:
+    """A clean-record response containing a map and its recorded path."""
+
+    map: Q10MapPacket
+    trace: Q10HistoricalTracePacket | None = None
+
+
 # Trace packet (``02 01``): a 14-byte header followed by big-endian int16 (x, y)
 # point pairs forming the accumulated session path. Header layout confirmed
 # against live ss07 captures and cross-checked by @andrewlyeats:
@@ -280,18 +332,26 @@ class Q10TracePacket:
 # - bytes 10-11: the 0201 SLAM heading (s16be degrees; 0 = +x, +90 = +y,
 #   +-180 = -x, -90 = -y) -- the robot's current orientation.
 # - bytes 12-13: a constant (0x0000).
-# - byte 14 onward: the path points.
+# - byte 14 onward: exactly ``point_count`` path points.
 # An earlier revision used a 10-byte header, which folded the heading word into
 # a phantom leading point ``(heading, 0)`` -- that is the "stray point" the
 # heuristic below was papering over, and why the count read "one high". The
-# parser reads all 4-byte pairs in the body rather than trusting the count
-# field, so a truncated tail can't desync it.
+# parser requires the declared point count to match the complete body, so a
+# truncated or extended tail cannot be silently interpreted as path data.
 # NOTE: the format documented by roborock-qseries-map-bridge (18-byte header)
 # did not match this firmware -- this 14-byte layout is what the device sent.
 _TRACE_HEADER_LENGTH = 14
 _TRACE_SEQUENCE_OFFSET = 3
+_TRACE_POINT_COUNT_OFFSET = 8
 _TRACE_HEADING_OFFSET = 10
 
+_HISTORICAL_TRACE_HEADER_LENGTH = 14
+_HISTORICAL_TRACE_PREFIX_LENGTH = 1
+_HISTORICAL_TRACE_VERSION = 1
+_HISTORICAL_TRACE_POINT_COUNT_OFFSET = 6
+_HISTORICAL_TRACE_HEADING_OFFSET = 10
+_HISTORICAL_TRACE_RESERVED_OFFSET = 12
+
 # Some cleans still prepend a single near-origin sentinel as the first real
 # point (e.g. ~(5, 76) / (-3, 0) when the path proper starts near (-1700, -800));
 # it skews the rendered start/bounding box and any path-based calibration. (This
@@ -306,12 +366,12 @@ _STRAY_POINT_STEP_RATIO = 20
 
 def is_map_packet(payload: bytes) -> bool:
     """Return True if the payload is a Q10 full-map (``01 01``) packet."""
-    return payload[:2] == MAP_PACKET_MARKER
+    return Q10MapPacketKind.from_payload(payload) is Q10MapPacketKind.CURRENT
 
 
 def is_trace_packet(payload: bytes) -> bool:
     """Return True if the payload is a Q10 live trace (``02 01``) packet."""
-    return payload[:2] == TRACE_PACKET_MARKER
+    return Q10MapPacketKind.from_payload(payload) is Q10MapPacketKind.TRACE
 
 
 def parse_trace_packet(payload: bytes) -> Q10TracePacket:
@@ -323,6 +383,9 @@ def parse_trace_packet(payload: bytes) -> Q10TracePacket:
     body = payload[_TRACE_HEADER_LENGTH:]
     if len(body) % 4:
         raise RoborockException("Q10 trace points are not 4-byte (x, y) pairs")
+    declared_point_count = int.from_bytes(payload[_TRACE_POINT_COUNT_OFFSET : _TRACE_POINT_COUNT_OFFSET + 2], "big")
+    if declared_point_count != len(body) // 4:
+        raise RoborockException("Q10 trace point count does not match its payload")
 
     heading = int.from_bytes(payload[_TRACE_HEADING_OFFSET : _TRACE_HEADING_OFFSET + 2], "big", signed=True)
     points = [
@@ -353,11 +416,13 @@ def _drop_stray_leading_point(points: list[Q10Point]) -> list[Q10Point]:
     return points
 
 
-def lz4_block_decompress(data: bytes) -> bytes:
+def lz4_block_decompress(data: bytes, max_output_size: int) -> bytes:
     """Decompress a raw LZ4 *block* (no frame header).
 
     The Q10 map grid is stored as a single LZ4 block. This implements the
-    standard LZ4 block format so we don't add a native dependency.
+    standard LZ4 block format so we don't add a native dependency. Expansion beyond
+    ``max_output_size`` is rejected before
+    allocating the excess output.
     """
     index = 0
     output = bytearray()
@@ -385,6 +450,8 @@ def lz4_block_decompress(data: bytes) -> bytes:
         end = index + literal_length
         if end > len(data):
             raise RoborockException("Truncated LZ4 block while reading literals")
+        if len(output) + literal_length > max_output_size:
+            raise RoborockException("LZ4 block exceeds maximum output size")
         output.extend(data[index:end])
         index = end
 
@@ -399,6 +466,8 @@ def lz4_block_decompress(data: bytes) -> bytes:
             raise RoborockException("Invalid LZ4 back-reference offset")
 
         match_length = read_length(token & 0x0F) + 4
+        if len(output) + match_length > max_output_size:
+            raise RoborockException("LZ4 block exceeds maximum output size")
         for _ in range(match_length):
             output.append(output[-offset])
 
@@ -463,8 +532,24 @@ def _parse_rooms(room_data: bytes, grid: bytes) -> list[Q10Room]:
 
 
 def parse_map_packet(payload: bytes) -> Q10MapPacket:
-    """Parse a Q10 ``01 01`` map packet into grid + room metadata."""
-    if len(payload) < _LAYOUT_COMPRESSED_OFFSET or not is_map_packet(payload):
+    """Parse the raster and shared metadata of a current or archived map."""
+    packet, _, _ = _parse_map_layout(payload)
+    return packet
+
+
+def parse_clean_record_detail(payload: bytes) -> Q10CleanRecordDetail:
+    """Parse a clean-record response into its map and optional recorded path."""
+    if Q10MapPacketKind.from_payload(payload) is not Q10MapPacketKind.CLEAN_RECORD_DETAIL:
+        raise RoborockException("Payload is not a Q10 clean-record detail packet")
+    packet, tail, trace_offset = _parse_map_layout(payload)
+    trace = _parse_clean_record_trace(tail, trace_offset) if trace_offset is not None else None
+    return Q10CleanRecordDetail(map=packet, trace=trace)
+
+
+def _parse_map_layout(payload: bytes) -> tuple[Q10MapPacket, bytes, int | None]:
+    """Decode shared map fields and return the tail and historical path offset."""
+    kind = Q10MapPacketKind.from_payload(payload)
+    if len(payload) < _LAYOUT_COMPRESSED_OFFSET or kind is None or kind is Q10MapPacketKind.TRACE:
         raise RoborockException("Payload is not a Q10 map packet")
 
     map_id = int.from_bytes(payload[_MAP_ID_OFFSET : _MAP_ID_OFFSET + 4], "big")
@@ -472,6 +557,8 @@ def parse_map_packet(payload: bytes) -> Q10MapPacket:
     height = int.from_bytes(payload[_HEIGHT_OFFSET : _HEIGHT_OFFSET + 2], "big")
     if width <= 0:
         raise RoborockException("Q10 map packet has invalid width")
+    if height > 0 and width * height > _MAX_GRID_CELLS:
+        raise RoborockException("Q10 map packet dimensions exceed the supported grid size")
 
     compressed_length = int.from_bytes(
         payload[_COMPRESSED_LAYOUT_LENGTH_OFFSET : _COMPRESSED_LAYOUT_LENGTH_OFFSET + 2], "big"
@@ -480,7 +567,10 @@ def parse_map_packet(payload: bytes) -> Q10MapPacket:
     if compressed_length <= 0 or layout_end > len(payload):
         raise RoborockException("Q10 map packet has invalid layout block length")
 
-    decoded = lz4_block_decompress(payload[_LAYOUT_COMPRESSED_OFFSET:layout_end])
+    decoded = lz4_block_decompress(
+        payload[_LAYOUT_COMPRESSED_OFFSET:layout_end],
+        max_output_size=_MAX_GRID_CELLS + 2 + _MAX_ROOMS * _ROOM_RECORD_LENGTH,
+    )
     # Prefer the header height; fall back to inference if it doesn't line up
     # (e.g. older captures/fixtures that don't populate the height field).
     split = _split_with_dims(decoded, width, height) if height > 0 else None
@@ -491,9 +581,10 @@ def parse_map_packet(payload: bytes) -> Q10MapPacket:
     rooms = _parse_rooms(room_data, grid)
     tail = payload[layout_end:]
     erase_zones = _parse_erase_zones(tail)
-    carpet_mask = _parse_carpet_mask(tail, width, height)
+    carpet_mask, carpet_end = _parse_carpet_block(tail, width, height)
     header_calibration = _parse_header_calibration(payload)
-    return Q10MapPacket(
+    packet = Q10MapPacket(
+        kind=kind,
         map_id=map_id,
         width=width,
         height=height,
@@ -503,6 +594,7 @@ def parse_map_packet(payload: bytes) -> Q10MapPacket:
         header_calibration=header_calibration,
         carpet_mask=carpet_mask,
     )
+    return packet, tail, carpet_end
 
 
 def _parse_header_calibration(payload: bytes) -> Q10HeaderCalibration | None:
@@ -574,7 +666,18 @@ def _carpet_offset(tail: bytes) -> int:
     return 2 + count * vertices_per * 4
 
 
-def _parse_carpet_mask(tail: bytes, width: int, height: int) -> bytes | None:
+def _erase_section_end(tail: bytes) -> int:
+    """Return the end of a complete, structurally valid erase section."""
+    if len(tail) < 2:
+        return 0
+    count, vertices_per = tail[0], tail[1]
+    if count and not 1 <= vertices_per <= _MAX_ERASE_ZONE_VERTICES:
+        return 0
+    end = _carpet_offset(tail)
+    return end if end <= len(tail) else 0
+
+
+def _parse_carpet_block(tail: bytes, width: int, height: int) -> tuple[bytes | None, int | None]:
     """Decode the carpet mask that follows the erase section in the packet tail.
 
     Framing matches the main grid block: ``[u32 uncompressed_len]``
@@ -583,23 +686,73 @@ def _parse_carpet_mask(tail: bytes, width: int, height: int) -> bytes | None:
     non-zero cell is carpet (the value is the carpet kind). Confirmed byte-exact
     on live ss07 captures (R1 / RDC), where ``uncompressed_len == width*height``.
 
-    Returns the decompressed mask, or ``None`` if the section is absent or does
-    not line up (the ``uncompressed_len == width*height`` invariant is used as the
-    guard so a mis-located section yields no carpet rather than garbage).
+    Returns the decompressed mask and its end offset. Both are ``None`` if the
+    section is absent or does not line up. The end offset is used to anchor
+    optional later sections without scanning arbitrary trailing bytes.
     """
-    offset = _carpet_offset(tail)
+    offset = _erase_section_end(tail)
+    if offset == 0:
+        return None, None
     if offset + 6 > len(tail):
-        return None
+        return None, None
     uncompressed_len = int.from_bytes(tail[offset : offset + 4], "big")
     compressed_len = int.from_bytes(tail[offset + 4 : offset + 6], "big")
     block_end = offset + 6 + compressed_len
     if uncompressed_len != width * height or compressed_len <= 0 or block_end > len(tail):
-        return None
+        return None, None
     try:
-        mask = lz4_block_decompress(tail[offset + 6 : block_end])
+        mask = lz4_block_decompress(tail[offset + 6 : block_end], max_output_size=width * height)
     except RoborockException:
+        return None, None
+    if len(mask) != width * height:
+        return None, None
+    return mask, block_end
+
+
+def _parse_clean_record_trace(
+    tail: bytes,
+    offset: int,
+) -> Q10HistoricalTracePacket | None:
+    """Decode the bounded historical path following a ``03 01`` carpet block.
+
+    The header and declared point count were validated against a physical ss07
+    clean-record response and its point bytes match captured prefixes of the
+    corresponding live trace exactly. One observed zero byte precedes the path;
+    its meaning is unknown, so a non-zero value makes the entire section opaque.
+    Any unsupported version, non-zero reserved word, or truncated point table is
+    likewise left completely opaque. Bytes after the declared points are
+    deliberately not consumed: the observed 12-byte suffix appears structured,
+    but there is not enough controlled evidence to name or decode it safely.
+    """
+    if offset >= len(tail) or tail[offset] != 0:
+        return None
+    offset += _HISTORICAL_TRACE_PREFIX_LENGTH
+    header_end = offset + _HISTORICAL_TRACE_HEADER_LENGTH
+    if header_end > len(tail):
         return None
-    return mask if len(mask) == width * height else None
+    version = int.from_bytes(tail[offset : offset + 2], "big")
+    reserved = int.from_bytes(
+        tail[offset + _HISTORICAL_TRACE_RESERVED_OFFSET : offset + _HISTORICAL_TRACE_RESERVED_OFFSET + 2],
+        "big",
+    )
+    if version != _HISTORICAL_TRACE_VERSION or reserved != 0:
+        return None
+    point_count = int.from_bytes(
+        tail[offset + _HISTORICAL_TRACE_POINT_COUNT_OFFSET : offset + _HISTORICAL_TRACE_POINT_COUNT_OFFSET + 4],
+        "big",
+    )
+    points_end = header_end + point_count * 4
+    if points_end > len(tail):
+        return None
+    coordinates = struct.iter_unpack(">hh", memoryview(tail)[header_end:points_end])
+    return Q10HistoricalTracePacket(
+        points=_drop_stray_leading_point([Q10Point(x=x, y=y) for x, y in coordinates]),
+        heading=int.from_bytes(
+            tail[offset + _HISTORICAL_TRACE_HEADING_OFFSET : offset + _HISTORICAL_TRACE_HEADING_OFFSET + 2],
+            "big",
+            signed=True,
+        ),
+    )
 
 
 def erased_packet(packet: "Q10MapPacket", cells: set[int]) -> "Q10MapPacket":

{python_roborock-7.11.1 → python_roborock-7.12.1}/roborock/map/b01_q10_render.py

@@ -34,6 +34,7 @@ from .b01_q10_map_parser import (
     B01Q10MapParser,
     B01Q10MapParserConfig,
     Q10EraseZone,
+    Q10HistoricalTracePacket,
     Q10MapPacket,
     Q10TracePacket,
     erased_packet,
@@ -62,7 +63,6 @@ _MIN_CALIBRATION_POINTS = 20
 # a much shorter path suffices to confirm it (early in a clean, not just a dense
 # one). See :func:`solve_calibration_with_origin`.
 _MIN_HEADER_CALIBRATION_POINTS = 4
-
 _Q10_DRAWABLE_TYPES = {
     Drawable.CHARGER,
     Drawable.NO_GO_AREAS,
@@ -84,7 +84,7 @@ class Q10MapOverlays:
 
 def render_q10_map(
     packet: Q10MapPacket,
-    trace: Q10TracePacket | None,
+    trace: Q10TracePacket | Q10HistoricalTracePacket | None,
     overlays: Q10MapOverlays,
     *,
     config: B01Q10MapParserConfig,
@@ -133,7 +133,7 @@ def render_q10_map(
 
 def solve_q10_calibration(
     packet: Q10MapPacket,
-    trace: Q10TracePacket | None,
+    trace: Q10TracePacket | Q10HistoricalTracePacket | None,
 ) -> GridCalibration | None:
     """Derive world-to-pixel calibration from a map and its current trace.
 
@@ -232,7 +232,7 @@ def _erased_cells(
 def _place_trace(
     map_data: MapData,
     calibration: GridCalibration,
-    trace: Q10TracePacket,
+    trace: Q10TracePacket | Q10HistoricalTracePacket,
     *,
     charger_heading: int | None = None,
 ) -> None:

{python_roborock-7.11.1 → python_roborock-7.12.1}/roborock/protocols/b01_q10_protocol.py

@@ -11,10 +11,11 @@ from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
 from roborock.data.b01_q10.b01_q10_containers import Q10RoborockPoint
 from roborock.exceptions import RoborockException
 from roborock.map.b01_q10_map_parser import (
+    Q10CleanRecordDetail,
     Q10MapPacket,
+    Q10MapPacketKind,
     Q10TracePacket,
-    is_map_packet,
-    is_trace_packet,
+    parse_clean_record_detail,
     parse_map_packet,
     parse_trace_packet,
 )
@@ -155,24 +156,27 @@ class Q10DpsUpdate:
 # A single decoded message from a Q10 device: a DPS status update, a full map
 # packet, or a live cleaning-path (trace) packet. Map/trace packets arrive as
 # protocol-301 ``MAP_RESPONSE`` pushes; everything else is a DPS update.
-Q10Message = Q10DpsUpdate | Q10MapPacket | Q10TracePacket
+Q10Message = Q10DpsUpdate | Q10MapPacket | Q10TracePacket | Q10CleanRecordDetail
 
 
 def decode_message(message: RoborockMessage) -> Q10Message | None:
     """Decode a pushed Q10 ``RoborockMessage`` into a typed message.
 
-    ``MAP_RESPONSE`` (protocol 301) payloads carry the binary map (``01 01``) or
-    trace (``02 01``) packets, which are parsed by the map parser; any other
-    ``MAP_RESPONSE`` marker is unrecognized and yields ``None``. Every other
-    protocol is treated as a DPS status update.
+    ``MAP_RESPONSE`` (protocol 301) payloads carry binary current-map (``01
+    01``), trace (``02 01``), clean-record detail (``03 01``), or saved-map
+    detail (``04 01``) packets. Any other marker is unrecognized and yields
+    ``None``. Every other protocol is treated as a DPS status update.
 
     Raises ``RoborockException`` if a recognized payload fails to parse.
     """
     if message.protocol == RoborockMessageProtocol.MAP_RESPONSE:
         payload = message.payload or b""
-        if is_map_packet(payload):
-            return parse_map_packet(payload)
-        if is_trace_packet(payload):
+        kind = Q10MapPacketKind.from_payload(payload)
+        if kind is Q10MapPacketKind.TRACE:
             return parse_trace_packet(payload)
+        if kind is Q10MapPacketKind.CLEAN_RECORD_DETAIL:
+            return parse_clean_record_detail(payload)
+        if kind is not None:
+            return parse_map_packet(payload)
         return None
     return Q10DpsUpdate(dps=decode_rpc_response(message))