python-roborock 5.19.0__tar.gz → 5.20.0__tar.gz

{python_roborock-5.19.0 → python_roborock-5.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-roborock
-Version: 5.19.0
+Version: 5.20.0
 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-5.19.0 → python_roborock-5.20.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "5.19.0"
+version = "5.20.0"
 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"

{python_roborock-5.19.0 → python_roborock-5.20.0}/roborock/cli.py

@@ -56,6 +56,7 @@ from roborock.devices.cache import Cache, CacheData
 from roborock.devices.device import RoborockDevice
 from roborock.devices.device_manager import DeviceManager, UserParams, create_device_manager
 from roborock.devices.traits import Trait
+from roborock.devices.traits.b01.q10 import Q10PropertiesApi
 from roborock.devices.traits.b01.q10.vacuum import VacuumTrait
 from roborock.devices.traits.v1 import V1TraitMixin
 from roborock.devices.traits.v1.consumeable import ConsumableAttribute
@@ -527,6 +528,45 @@ async def maps(ctx, device_id: str):
     await _display_v1_trait(context, device_id, lambda v1: v1.maps)
 
 
+# The Q10 pushes its map ~9s after a dpRequestDps; firmware throttles pushes to
+# ~once per 60-70s, so a single request is answered quickly but rapid re-requests
+# may not be. This bounds how long a one-shot CLI command waits for that push.
+_Q10_MAP_PUSH_TIMEOUT = 30.0
+
+
+async def _await_q10_map_push(
+    properties: Q10PropertiesApi,
+    predicate: Callable[[], bool],
+    *,
+    timeout: float = _Q10_MAP_PUSH_TIMEOUT,
+    allow_cached_on_timeout: bool = False,
+) -> bool:
+    """Nudge a Q10 to push its map/trace and wait for a fresh update.
+
+    The Q10 map API is entirely push-driven: there is no synchronous get-map
+    request. A ``dpRequestDps`` causes the device to publish a ``MAP_RESPONSE``,
+    which the device's subscribe loop feeds into the map trait. Here we register
+    an update listener, send the request, and wait for a newly pushed update to
+    satisfy ``predicate``. Returns whether it did within ``timeout``.
+    """
+    loop = asyncio.get_running_loop()
+    updated: asyncio.Future[None] = loop.create_future()
+
+    def on_update() -> None:
+        if predicate() and not updated.done():
+            updated.set_result(None)
+
+    unsub = properties.map.add_update_listener(on_update)
+    try:
+        await properties.refresh()
+        await asyncio.wait_for(updated, timeout=timeout)
+        return True
+    except TimeoutError:
+        return allow_cached_on_timeout and predicate()
+    finally:
+        unsub()
+
+
 @session.command()
 @click.option("--device_id", required=True)
 @click.option("--output-file", required=True, help="Path to save the map image.")
@@ -535,10 +575,22 @@ async def maps(ctx, device_id: str):
 async def map_image(ctx, device_id: str, output_file: str):
     """Get device map image and save it to a file."""
     context: RoborockContext = ctx.obj
-    trait: MapContentTrait = await _v1_trait(context, device_id, lambda v1: v1.map_content)
-    if trait.image_content:
+    device_manager = await context.get_device_manager()
+    device = await device_manager.get_device(device_id)
+    if device.b01_q10_properties is not None:
+        properties = device.b01_q10_properties
+        await _await_q10_map_push(
+            properties,
+            lambda: properties.map.image_content is not None,
+            allow_cached_on_timeout=True,
+        )
+        image_content = properties.map.image_content
+    else:
+        v1_trait: MapContentTrait = await _v1_trait(context, device_id, lambda v1: v1.map_content)
+        image_content = v1_trait.image_content
+    if image_content:
         with open(output_file, "wb") as f:
-            f.write(trait.image_content)
+            f.write(image_content)
         click.echo(f"Map image saved to {output_file}")
     else:
         click.echo("No map image content available.")
@@ -570,6 +622,39 @@ async def map_data(ctx, device_id: str, include_path: bool):
     click.echo(dump_json(data_summary))
 
 
+@session.command()
+@click.option("--device_id", required=True)
+@click.option("--include_path", is_flag=True, default=False, help="Include all path points in the output.")
+@click.pass_context
+@async_command
+async def q10_position(ctx, device_id: str, include_path: bool):
+    """Get the current Q10 robot position and live cleaning path.
+
+    The Q10 only streams its position/path while it is actively cleaning, so this
+    will report that no live trace is available for an idle/docked robot.
+    """
+    context: RoborockContext = ctx.obj
+    device_manager = await context.get_device_manager()
+    device = await device_manager.get_device(device_id)
+    if device.b01_q10_properties is None:
+        click.echo("Feature not supported by device")
+        return
+    properties = device.b01_q10_properties
+    got_trace = await _await_q10_map_push(properties, lambda: bool(properties.map.path))
+    if not got_trace:
+        click.echo("No live trace available (the robot only reports position while cleaning).")
+        return
+    map_trait = properties.map
+    position = map_trait.robot_position
+    summary: dict[str, Any] = {
+        "robot_position": {"x": position.x, "y": position.y} if position else None,
+        "path_points": len(map_trait.path),
+    }
+    if include_path:
+        summary["path"] = [[p.x, p.y] for p in map_trait.path]
+    click.echo(dump_json(summary))
+
+
 @session.command()
 @click.option("--device_id", required=True)
 @click.pass_context
@@ -711,7 +796,20 @@ async def set_child_lock(ctx, device_id: str, enabled: bool):
 async def rooms(ctx, device_id: str):
     """Get device room mapping info."""
     context: RoborockContext = ctx.obj
-    await _display_v1_trait(context, device_id, lambda v1: v1.rooms)
+    device_manager = await context.get_device_manager()
+    device = await device_manager.get_device(device_id)
+    if device.b01_q10_properties is not None:
+        properties = device.b01_q10_properties
+        # A valid map may have no room records, so wait on the map arriving
+        # (image_content) rather than on rooms being non-empty.
+        await _await_q10_map_push(
+            properties,
+            lambda: properties.map.image_content is not None,
+            allow_cached_on_timeout=True,
+        )
+        click.echo(dump_json({room.id: room.name for room in properties.map.rooms}))
+    else:
+        await _display_v1_trait(context, device_id, lambda v1: v1.rooms)
 
 
 @session.command()
@@ -1200,6 +1298,7 @@ cli.add_command(set_volume)
 cli.add_command(maps)
 cli.add_command(map_image)
 cli.add_command(map_data)
+cli.add_command(q10_position)
 cli.add_command(consumables)
 cli.add_command(reset_consumable)
 cli.add_command(rooms)

{python_roborock-5.19.0 → python_roborock-5.20.0}/roborock/devices/rpc/b01_q10_channel.py

@@ -2,36 +2,42 @@
 
 import logging
 from collections.abc import AsyncGenerator
-from typing import Any
 
 from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
 from roborock.devices.transport.mqtt_channel import MqttChannel
 from roborock.exceptions import RoborockException
 from roborock.protocols.b01_q10_protocol import (
     ParamsType,
-    decode_rpc_response,
+    Q10Message,
+    decode_message,
     encode_mqtt_payload,
 )
 
 _LOGGER = logging.getLogger(__name__)
 
 
-async def stream_decoded_responses(
+async def stream_decoded_messages(
     mqtt_channel: MqttChannel,
-) -> AsyncGenerator[dict[B01_Q10_DP, Any], None]:
-    """Stream decoded DPS messages received via MQTT."""
+) -> AsyncGenerator[Q10Message, None]:
+    """Stream decoded Q10 messages received via MQTT.
 
-    async for response_message in mqtt_channel.subscribe_stream():
+    Each pushed ``RoborockMessage`` is decoded into a typed :data:`Q10Message`
+    (a DPS status update, a map packet, or a trace packet). Messages that fail
+    to decode or carry an unrecognized payload are skipped.
+    """
+
+    async for message in mqtt_channel.subscribe_stream():
         try:
-            decoded_dps = decode_rpc_response(response_message)
+            decoded = decode_message(message)
         except RoborockException as ex:
             _LOGGER.debug(
-                "Failed to decode B01 Q10 RPC response: %s: %s",
-                response_message,
+                "Failed to decode B01 Q10 message: %s: %s",
+                message,
                 ex,
             )
             continue
-        yield decoded_dps
+        if decoded is not None:
+            yield decoded
 
 
 async def send_command(

{python_roborock-5.19.0 → python_roborock-5.20.0}/roborock/devices/traits/b01/q10/__init__.py

@@ -4,17 +4,21 @@ import asyncio
 import logging
 
 from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
-from roborock.devices.rpc.b01_q10_channel import stream_decoded_responses
+from roborock.devices.rpc.b01_q10_channel import stream_decoded_messages
 from roborock.devices.traits import Trait
 from roborock.devices.transport.mqtt_channel import MqttChannel
+from roborock.map.b01_q10_map_parser import Q10MapPacket, Q10TracePacket
+from roborock.protocols.b01_q10_protocol import Q10DpsUpdate, Q10Message
 
 from .command import CommandTrait
+from .map import MapContentTrait
 from .remote import RemoteTrait
 from .status import StatusTrait
 from .vacuum import VacuumTrait
 
 __all__ = [
     "Q10PropertiesApi",
+    "MapContentTrait",
 ]
 
 _LOGGER = logging.getLogger(__name__)
@@ -35,6 +39,9 @@ class Q10PropertiesApi(Trait):
     remote: RemoteTrait
     """Trait for sending remote control related commands to Q10 devices."""
 
+    map: MapContentTrait
+    """Trait for fetching the current parsed map (image + rooms)."""
+
     def __init__(self, channel: MqttChannel) -> None:
         """Initialize the B01Props API."""
         self._channel = channel
@@ -42,6 +49,7 @@ class Q10PropertiesApi(Trait):
         self.vacuum = VacuumTrait(self.command)
         self.remote = RemoteTrait(self.command)
         self.status = StatusTrait()
+        self.map = MapContentTrait()
         self._subscribe_task: asyncio.Task[None] | None = None
 
     async def start(self) -> None:
@@ -65,14 +73,25 @@ class Q10PropertiesApi(Trait):
         await self.command.send(B01_Q10_DP.REQUEST_DPS, params={})
 
     async def _subscribe_loop(self) -> None:
-        """Persistent loop to listen for status updates."""
-        async for decoded_dps in stream_decoded_responses(self._channel):
-            _LOGGER.debug("Received Q10 status update: %s", decoded_dps)
-
-            # Notify all traits about a new message and each trait will
-            # only update what fields that it is responsible for.
-            # More traits can be added here below.
-            self.status.update_from_dps(decoded_dps)
+        """Persistent loop dispatching decoded messages to the read-model traits."""
+        async for message in stream_decoded_messages(self._channel):
+            self._handle_message(message)
+
+    def _handle_message(self, message: Q10Message) -> None:
+        """Route a single decoded message to the trait responsible for it.
+
+        Map and trace packets arrive as protocol-301 ``MAP_RESPONSE`` pushes (the
+        Q10 is entirely push-driven: there is no synchronous get-map request, a
+        ``dpRequestDps`` just nudges the device to publish its current map). DPS
+        updates feed the status trait. More traits can be dispatched here below.
+        """
+        if isinstance(message, Q10MapPacket):
+            self.map.update_from_map_packet(message)
+        elif isinstance(message, Q10TracePacket):
+            self.map.update_from_trace_packet(message)
+        elif isinstance(message, Q10DpsUpdate):
+            _LOGGER.debug("Received Q10 status update: %s", message.dps)
+            self.status.update_from_dps(message.dps)
 
 
 def create(channel: MqttChannel) -> Q10PropertiesApi:

python_roborock-5.20.0/roborock/devices/traits/b01/q10/map.py

@@ -0,0 +1,110 @@
+"""Map content trait for B01 Q10 devices.
+
+Unlike the v1 / Q7 maps, the Q10 has no synchronous "get map" command, so this
+trait is purely push-driven and mirrors the Q10 ``StatusTrait`` contract:
+
+- The device pushes its current map/path as protocol-301 ``MAP_RESPONSE``
+  messages (a ``dpRequestDps`` nudges it to do so). The protocol layer decodes
+  those into :class:`Q10MapPacket` / :class:`Q10TracePacket` objects and the
+  ``Q10PropertiesApi`` subscribe loop routes them to
+  :meth:`MapContentTrait.update_from_map_packet` /
+  :meth:`MapContentTrait.update_from_trace_packet`.
+- Those methods render/cache the content and notify update listeners (register
+  via :meth:`add_update_listener`).
+- ``image_content``, ``map_data``, ``rooms``, ``path`` and ``robot_position``
+  are readable and reflect the most recently pushed map.
+
+Unlike the Q7, the Q10 map payload is unencrypted, so no map key is required.
+"""
+
+import logging
+from dataclasses import dataclass, field
+
+from vacuum_map_parser_base.map_data import MapData
+
+from roborock.data import RoborockBase
+from roborock.devices.traits.common import TraitUpdateListener
+from roborock.map.b01_q10_map_parser import (
+    B01Q10MapParser,
+    B01Q10MapParserConfig,
+    Q10MapPacket,
+    Q10Point,
+    Q10Room,
+    Q10TracePacket,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+_TRUNCATE_LENGTH = 20
+
+
+@dataclass
+class MapContent(RoborockBase):
+    """Dataclass representing Q10 map content."""
+
+    image_content: bytes | None = None
+    """The rendered image of the map in PNG format."""
+
+    map_data: MapData | None = None
+    """Parsed map data (image metadata + room names)."""
+
+    rooms: list[Q10Room] = field(default_factory=list)
+    """Rooms (segments) reported by the device, with ids and names."""
+
+    path: list[Q10Point] = field(default_factory=list)
+    """Full path of the current cleaning session (oldest point first).
+
+    The robot accumulates this server-side and serves the whole trajectory so
+    far in one packet, so it is complete even if we connect mid-session. Only
+    populated while a cleaning session is active."""
+
+    robot_position: Q10Point | None = None
+    """Current robot position (the most recent path point), if known."""
+
+    def __repr__(self) -> str:
+        img = self.image_content
+        if img and len(img) > _TRUNCATE_LENGTH:
+            img = img[: _TRUNCATE_LENGTH - 3] + b"..."
+        return f"MapContent(image_content={img!r}, rooms={self.rooms!r})"
+
+
+class MapContentTrait(MapContent, TraitUpdateListener):
+    """Trait holding the most recently pushed parsed map content for Q10 devices.
+
+    The Q10 has no synchronous get-map request; the device pushes map and trace
+    packets, which the protocol layer decodes and the ``Q10PropertiesApi``
+    subscribe loop feeds into :meth:`update_from_map_packet` /
+    :meth:`update_from_trace_packet`. Consumers read the cached fields and/or
+    register a callback with :meth:`add_update_listener` to be notified when new
+    map content arrives.
+    """
+
+    def __init__(
+        self,
+        *,
+        map_parser_config: B01Q10MapParserConfig | None = None,
+    ) -> None:
+        super().__init__()
+        TraitUpdateListener.__init__(self, logger=_LOGGER)
+        self._map_parser = B01Q10MapParser(map_parser_config)
+
+    def update_from_map_packet(self, packet: Q10MapPacket) -> None:
+        """Render a pushed full-map packet into the cached image/rooms.
+
+        Rendering failures are logged and skipped (listeners are not notified) so
+        a single bad push cannot tear down the subscribe loop.
+        """
+        parsed = self._map_parser.parse_packet(packet)
+        if parsed.image_content is None:
+            _LOGGER.debug("Failed to render Q10 map image")
+            return
+        self.image_content = parsed.image_content
+        self.map_data = parsed.map_data
+        self.rooms = packet.rooms
+        self._notify_update()
+
+    def update_from_trace_packet(self, packet: Q10TracePacket) -> None:
+        """Cache the path/robot position from a pushed trace packet."""
+        self.path = packet.points
+        self.robot_position = packet.robot_position
+        self._notify_update()

python_roborock-5.20.0/roborock/map/b01_q10_map_parser.py

@@ -0,0 +1,399 @@
+"""Parser for Roborock Q10 (B01/ss07) map packets.
+
+Q10 devices deliver map data as a protocol-301 ``MAP_RESPONSE`` message (pushed a
+few seconds after a ``dpRequestDps`` request). 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).
+- A header field at offset 27 (``u16be``) giving the compressed layout length.
+- An LZ4-block-compressed occupancy grid starting at offset 29. Once inflated it
+  is ``width * height`` cells of grid data followed by room metadata records.
+- Room metadata begins with ``01 <room_count>`` followed by fixed 47-byte
+  records (id, hints, ascii name). Each room paints cells with value
+  ``room_id * 4`` in the grid.
+
+The packet layout was confirmed against live Q10 captures. The format
+documentation that informed this clean-room implementation comes from the
+``roborock-qseries-map-bridge`` project (GPL-3.0-or-later):
+https://github.com/v1b3c0d3x3r/roborock-qseries-map-bridge
+"""
+
+import colorsys
+import io
+import math
+import statistics
+from dataclasses import dataclass, field
+
+from PIL import Image
+from vacuum_map_parser_base.config.image_config import ImageConfig
+from vacuum_map_parser_base.map_data import ImageData, MapData
+
+from roborock.exceptions import RoborockException
+
+from .map_parser import ParsedMapData
+
+_MAP_FILE_FORMAT = "PNG"
+
+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,
+# so it only matched the true width when width and height fell in the same
+# 256-band -- e.g. a 222x261 map decoded its width as 478 and failed to split.
+# Reported and diagnosed by @andrewlyeats (independent B01/Q10 decoder), and
+# corroborated by the ioBroker roborock adapter (both read these as u16be).
+_WIDTH_OFFSET = 7
+_HEIGHT_OFFSET = 9
+_COMPRESSED_LAYOUT_LENGTH_OFFSET = 27
+_LAYOUT_COMPRESSED_OFFSET = 29
+_ROOM_RECORD_LENGTH = 47
+_ROOM_NAME_LENGTH_OFFSET = 26
+_MAX_ROOMS = 32
+
+# Grid cell values >= this are walls / borders rather than room segments.
+_WALL_THRESHOLD = 240
+
+
+@dataclass
+class Q10Room:
+    """A room (segment) described in a Q10 map packet."""
+
+    id: int
+    raw_name: str
+    pixel_value: int
+    pixel_count: int
+
+    @property
+    def name(self) -> str:
+        """User friendly room name (firmware ``rr_`` defaults are normalized)."""
+        return self.raw_name.removeprefix("rr_").replace("_", " ").strip().title()
+
+
+@dataclass
+class Q10MapPacket:
+    """Decoded contents of a Q10 ``01 01`` map packet."""
+
+    map_id: int
+    width: int
+    height: int
+    grid: bytes
+    rooms: list[Q10Room] = field(default_factory=list)
+
+
+@dataclass
+class Q10Point:
+    """A single point in Q10 map/trace coordinate space."""
+
+    x: int
+    y: int
+
+
+@dataclass
+class Q10TracePacket:
+    """Decoded contents of a Q10 ``02 01`` cleaning-path packet.
+
+    The robot accumulates the **full path of the current cleaning session** and
+    serves it in a single packet: ``points`` holds the whole trajectory so far
+    (oldest first), growing as the robot cleans. This was confirmed live -- a
+    corridor run produced packets of 1, then 3, then 15 points, each a strict
+    superset describing the path travelled. Because the robot keeps the path
+    server-side, a client that connects mid-session still receives the complete
+    path (this is how the app shows the trail even after a cold launch).
+
+    The robot only emits these while a session is active, so an idle/docked robot
+    will not produce them. The most recent point is the current robot position.
+    """
+
+    points: list[Q10Point] = field(default_factory=list)
+    sequence: int = 0
+    """Session counter (byte 3); increments per cleaning session, tracking the
+    device clean count. Not a per-packet sequence."""
+
+    @property
+    def robot_position(self) -> Q10Point | None:
+        """The current robot position (the most recent point)."""
+        return self.points[-1] if self.points else None
+
+
+# Trace packet (``02 01``): a 10-byte header followed by big-endian int16 (x, y)
+# point pairs forming the accumulated session path. Header layout confirmed
+# against live ss07 captures: byte 3 is a session counter (tracks the device
+# clean count); bytes 8-9 are a u16be point count minus one (verified: a 15-point
+# packet carried 0x000e == 14). The parser reads all 4-byte pairs in the body
+# rather than trusting the count field, so a truncated tail can't desync it.
+# NOTE: the format documented by roborock-qseries-map-bridge (18-byte header)
+# did not match this firmware -- this 10-byte layout is what the device sent.
+_TRACE_HEADER_LENGTH = 10
+_TRACE_SEQUENCE_OFFSET = 3
+
+# Some cleans prepend a single stray point to the path, far outside the map
+# (e.g. ~(0, -1907) when the real path starts near (-3760, -1920)); it skews the
+# rendered start/bounding box and any path-based calibration. We drop points[0]
+# only when its step to points[1] is a gross outlier (this multiple of the
+# median step of the rest of the path), so a genuine first point is never lost.
+# The current position (last point) is unaffected. Trigger and threshold
+# reported and verified by @andrewlyeats across independent B01/Q10 captures.
+_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
+
+
+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
+
+
+def parse_trace_packet(payload: bytes) -> Q10TracePacket:
+    """Parse a Q10 ``02 01`` trace packet into path points + robot position."""
+    if not is_trace_packet(payload):
+        raise RoborockException("Payload is not a Q10 trace packet")
+    if len(payload) < _TRACE_HEADER_LENGTH:
+        raise RoborockException("Q10 trace packet is shorter than its header")
+    body = payload[_TRACE_HEADER_LENGTH:]
+    if len(body) % 4:
+        raise RoborockException("Q10 trace points are not 4-byte (x, y) pairs")
+
+    points = [
+        Q10Point(
+            x=int.from_bytes(body[offset : offset + 2], "big", signed=True),
+            y=int.from_bytes(body[offset + 2 : offset + 4], "big", signed=True),
+        )
+        for offset in range(0, len(body), 4)
+    ]
+    points = _drop_stray_leading_point(points)
+    return Q10TracePacket(points=points, sequence=payload[_TRACE_SEQUENCE_OFFSET])
+
+
+def _drop_stray_leading_point(points: list[Q10Point]) -> list[Q10Point]:
+    """Drop a spurious leading point that some cleans prepend to the trace.
+
+    Returns ``points`` unchanged unless the very first step is a gross outlier
+    versus the median of the remaining steps (see ``_STRAY_POINT_STEP_RATIO``),
+    in which case the first point is dropped. Needs at least three points to have
+    a stable median to compare against.
+    """
+    if len(points) < 3:
+        return points
+    steps = [math.hypot(b.x - a.x, b.y - a.y) for a, b in zip(points, points[1:])]
+    median_rest = statistics.median(steps[1:])
+    if median_rest > 0 and steps[0] > _STRAY_POINT_STEP_RATIO * median_rest:
+        return points[1:]
+    return points
+
+
+def lz4_block_decompress(data: bytes) -> 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.
+    """
+    index = 0
+    output = bytearray()
+
+    def read_length(value: int) -> int:
+        nonlocal index
+        if value != 0x0F:
+            return value
+        while True:
+            if index >= len(data):
+                raise RoborockException("Truncated LZ4 block while reading length")
+            part = data[index]
+            index += 1
+            value += part
+            if part != 0xFF:
+                return value
+
+    while True:
+        if index >= len(data):
+            raise RoborockException("Truncated LZ4 block while reading token")
+        token = data[index]
+        index += 1
+
+        literal_length = read_length((token >> 4) & 0x0F)
+        end = index + literal_length
+        if end > len(data):
+            raise RoborockException("Truncated LZ4 block while reading literals")
+        output.extend(data[index:end])
+        index = end
+
+        if index == len(data):
+            return bytes(output)
+        if index + 2 > len(data):
+            raise RoborockException("Truncated LZ4 block while reading match offset")
+
+        offset = data[index] | (data[index + 1] << 8)
+        index += 2
+        if offset == 0 or offset > len(output):
+            raise RoborockException("Invalid LZ4 back-reference offset")
+
+        match_length = read_length(token & 0x0F) + 4
+        for _ in range(match_length):
+            output.append(output[-offset])
+
+
+def _split_with_dims(decoded: bytes, width: int, height: int) -> tuple[bytes, bytes] | None:
+    """Split the inflated layout into (grid, room_data) using header dimensions.
+
+    Returns ``None`` when ``width * height`` does not leave a well-formed
+    ``01 <room_count>`` room-record section, so the caller can fall back to
+    brute-force inference (e.g. for captures/fixtures without a height field).
+    """
+    area = width * height
+    if area <= 0 or area > len(decoded):
+        return None
+    room_data = decoded[area:]
+    if len(room_data) < 2 or room_data[0] != 1:
+        return None
+    if len(room_data) != 2 + room_data[1] * _ROOM_RECORD_LENGTH:
+        return None
+    return decoded[:area], room_data
+
+
+def _infer_layout(decoded: bytes, width: int) -> tuple[int, bytes, bytes]:
+    """Split the inflated layout into (height, grid, room_data).
+
+    The grid is ``width * height`` cells; the remaining bytes are room records
+    introduced by an ``01 <room_count>`` marker. The room count is unknown up
+    front, so we search for the split that makes the grid rectangular and lines
+    up with the marker. Used as a fallback when the header carries no usable
+    height.
+    """
+    for room_count in range(0, _MAX_ROOMS + 1):
+        room_data_length = 2 + room_count * _ROOM_RECORD_LENGTH
+        area = len(decoded) - room_data_length
+        if area <= 0 or area % width:
+            continue
+        room_data = decoded[area:]
+        if room_data[0] == 1 and room_data[1] == room_count:
+            return area // width, decoded[:area], room_data
+    raise RoborockException("Could not infer Q10 layout dimensions / room records")
+
+
+def _parse_rooms(room_data: bytes, grid: bytes) -> list[Q10Room]:
+    rooms: list[Q10Room] = []
+    room_count = room_data[1]
+    for index in range(room_count):
+        start = 2 + index * _ROOM_RECORD_LENGTH
+        record = room_data[start : start + _ROOM_RECORD_LENGTH]
+        room_id = int.from_bytes(record[0:2], "big")
+        name_length = record[_ROOM_NAME_LENGTH_OFFSET]
+        raw_name = record[27 : 27 + name_length].decode("utf-8", errors="replace")
+        pixel_value = (room_id * 4) & 0xFF
+        rooms.append(
+            Q10Room(
+                id=room_id,
+                raw_name=raw_name,
+                pixel_value=pixel_value,
+                pixel_count=grid.count(pixel_value),
+            )
+        )
+    return rooms
+
+
+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):
+        raise RoborockException("Payload is not a Q10 map packet")
+
+    map_id = int.from_bytes(payload[_MAP_ID_OFFSET : _MAP_ID_OFFSET + 4], "big")
+    width = int.from_bytes(payload[_WIDTH_OFFSET : _WIDTH_OFFSET + 2], "big")
+    height = int.from_bytes(payload[_HEIGHT_OFFSET : _HEIGHT_OFFSET + 2], "big")
+    if width <= 0:
+        raise RoborockException("Q10 map packet has invalid width")
+
+    compressed_length = int.from_bytes(
+        payload[_COMPRESSED_LAYOUT_LENGTH_OFFSET : _COMPRESSED_LAYOUT_LENGTH_OFFSET + 2], "big"
+    )
+    layout_end = _LAYOUT_COMPRESSED_OFFSET + compressed_length
+    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])
+    # 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
+    if split is not None:
+        grid, room_data = split
+    else:
+        height, grid, room_data = _infer_layout(decoded, width)
+    rooms = _parse_rooms(room_data, grid)
+    return Q10MapPacket(map_id=map_id, width=width, height=height, grid=grid, rooms=rooms)
+
+
+@dataclass
+class B01Q10MapParserConfig:
+    """Configuration for the Q10 map parser."""
+
+    map_scale: int = 4
+    """Scale factor for the rendered map image."""
+
+
+class B01Q10MapParser:
+    """Decoder/renderer for Q10 ``MAP_RESPONSE`` (protocol 301) payloads."""
+
+    def __init__(self, config: B01Q10MapParserConfig | None = None) -> None:
+        self._config = config or B01Q10MapParserConfig()
+
+    def parse(self, payload: bytes) -> ParsedMapData:
+        """Parse a raw Q10 map packet into a rendered PNG + ``MapData``."""
+        return self.parse_packet(parse_map_packet(payload))
+
+    def parse_packet(self, packet: Q10MapPacket) -> ParsedMapData:
+        """Render an already-parsed Q10 map packet into a PNG + ``MapData``.
+
+        The protocol layer parses the wire bytes into a :class:`Q10MapPacket`;
+        this renders that packet without re-parsing it.
+        """
+        image = self._render(packet)
+
+        map_data = MapData()
+        map_data.image = ImageData(
+            size=packet.width * packet.height,
+            top=0,
+            left=0,
+            height=packet.height,
+            width=packet.width,
+            image_config=ImageConfig(scale=self._config.map_scale),
+            data=image,
+            img_transformation=lambda p: p,
+        )
+        room_names = {room.id: room.name for room in packet.rooms}
+        if room_names:
+            map_data.additional_parameters["room_names"] = room_names
+
+        image_bytes = io.BytesIO()
+        image.save(image_bytes, format=_MAP_FILE_FORMAT)
+        return ParsedMapData(image_content=image_bytes.getvalue(), map_data=map_data)
+
+    def _render(self, packet: Q10MapPacket) -> Image.Image:
+        """Render the Q10 grid: rooms get distinct colors, walls white, rest dark."""
+        palette = _build_palette(packet.grid)
+        rgb = bytearray()
+        for value in packet.grid:
+            rgb.extend(palette[value])
+        img = Image.frombytes("RGB", (packet.width, packet.height), bytes(rgb))
+        img = img.transpose(Image.Transpose.FLIP_TOP_BOTTOM)
+        scale = self._config.map_scale
+        if scale > 1:
+            img = img.resize((packet.width * scale, packet.height * scale), resample=Image.Resampling.NEAREST)
+        return img
+
+
+def _build_palette(grid: bytes) -> list[tuple[int, int, int]]:
+    """Map each grid value to an RGB color (rooms distinct, walls white)."""
+    palette: list[tuple[int, int, int]] = [(28, 30, 38)] * 256  # default: unknown/outside
+    room_values = sorted({v for v in set(grid) if 0 < v < _WALL_THRESHOLD})
+    for index, value in enumerate(room_values):
+        hue = (index * 0.139) % 1.0
+        r, g, b = colorsys.hsv_to_rgb(hue, 0.5, 0.95)
+        palette[value] = (int(r * 255), int(g * 255), int(b * 255))
+    for value in range(_WALL_THRESHOLD, 256):
+        palette[value] = (235, 235, 240)  # walls / borders
+    palette[0] = (28, 30, 38)
+    return palette

{python_roborock-5.19.0 → python_roborock-5.20.0}/roborock/protocols/b01_q10_protocol.py

@@ -2,10 +2,19 @@
 
 import json
 import logging
+from dataclasses import dataclass
 from typing import Any
 
 from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
 from roborock.exceptions import RoborockException
+from roborock.map.b01_q10_map_parser import (
+    Q10MapPacket,
+    Q10TracePacket,
+    is_map_packet,
+    is_trace_packet,
+    parse_map_packet,
+    parse_trace_packet,
+)
 from roborock.roborock_message import (
     RoborockMessage,
     RoborockMessageProtocol,
@@ -85,3 +94,37 @@ def decode_rpc_response(message: RoborockMessage) -> dict[B01_Q10_DP, Any]:
         result.update(common_dps_result)
 
     return result
+
+
+@dataclass
+class Q10DpsUpdate:
+    """A decoded Q10 DPS status update pushed by the device."""
+
+    dps: dict[B01_Q10_DP, Any]
+    """Data points keyed by ``B01_Q10_DP`` code."""
+
+
+# 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
+
+
+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.
+
+    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):
+            return parse_trace_packet(payload)
+        return None
+    return Q10DpsUpdate(dps=decode_rpc_response(message))