feat: align Q10 map rendering with V1

Author: tubededentifrice

roborock/cli.py

@@ -594,9 +594,9 @@ 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.
+# The Q10 publishes its map asynchronously after a dpMultiMap list/get request.
+# Firmware throttles pushes to ~once per 60-70s, so rapid re-requests may not be
+# answered immediately. This bounds how long a one-shot CLI command waits.
 _Q10_MAP_PUSH_TIMEOUT = 30.0
 
 
@@ -609,11 +609,11 @@ async def _await_q10_map_push(
 ) -> 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``.
+    The Q10 map response remains asynchronous: ``refresh`` starts a
+    ``dpMultiMap`` list/get exchange, after which the device publishes a
+    ``MAP_RESPONSE`` that its 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()

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

@@ -2,10 +2,12 @@
 
 import asyncio
 import logging
+from typing import Any
 
 from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
 from roborock.devices.rpc.b01_q10_channel import B01Q10Channel
 from roborock.devices.traits import Trait
+from roborock.exceptions import RoborockException
 from roborock.map.b01_q10_map_parser import Q10MapPacket, Q10TracePacket
 from roborock.protocols.b01_q10_protocol import Q10DpsUpdate, Q10Message
 
@@ -40,6 +42,23 @@
 _LOGGER = logging.getLogger(__name__)
 
 
+def _map_id_from_list_response(response: Any) -> int | str | None:
+    """Return the first usable map ID from a ``dpMultiMap`` list response."""
+    if not isinstance(response, dict) or response.get("op") != "list":
+        return None
+    data = response.get("data")
+    if not isinstance(data, list):
+        return None
+    for map_info in data:
+        if isinstance(map_info, dict):
+            map_id = map_info.get("id")
+        else:
+            map_id = map_info
+        if isinstance(map_id, (int, str)) and not isinstance(map_id, bool):
+            return map_id
+    return None
+
+
 class Q10PropertiesApi(Trait):
     """API for interacting with B01 devices."""
 
@@ -115,6 +134,7 @@ def __init__(self, channel: B01Q10Channel) -> None:
             self._map_dps,
         ]
         self._subscribe_task: asyncio.Task[None] | None = None
+        self._map_list_requested = False
 
     async def start(self) -> None:
         """Start any necessary subscriptions for the trait."""
@@ -132,22 +152,42 @@ async def close(self) -> None:
 
     async def refresh(self) -> None:
         """Refresh all traits."""
-        # Sending the REQUEST_DPS will cause the device to send all DPS values
-        # to the device. Updates will be received by the subscribe loop below.
+        # Status and map retrieval use separate Q10 requests. A bare REQUEST_DPS
+        # reliably refreshes status but does not reliably make every firmware
+        # publish its map.
         await self.command.send(B01_Q10_DP.REQUEST_DPS, params={})
+        await self.request_map()
+
+    async def request_map(self) -> None:
+        """Request the current saved map through the Q10 multi-map protocol.
+
+        The list response arrives asynchronously on the subscribe stream.
+        ``_handle_message`` extracts its first map ID and follows up with the
+        matching ``get`` command; the resulting protocol-301 map packet is
+        routed to :attr:`map`.
+        """
+        self._map_list_requested = True
+        try:
+            await self.command.send(
+                B01_Q10_DP.COMMON,
+                {str(B01_Q10_DP.MULTI_MAP.code): {"op": "list"}},
+            )
+        except RoborockException:
+            self._map_list_requested = False
+            raise
 
     async def _subscribe_loop(self) -> None:
         """Persistent loop dispatching decoded messages to the read-model traits."""
         async for message in self._channel.subscribe_stream():
-            self._handle_message(message)
+            await self._handle_message(message)
 
-    def _handle_message(self, message: Q10Message) -> None:
+    async 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 read-model traits. More traits can be dispatched here below.
+        Map and trace packets arrive as protocol-301 ``MAP_RESPONSE`` pushes.
+        A ``dpMultiMap`` list response completes the asynchronous request flow
+        started by :meth:`request_map`; other DPS updates feed the read-model
+        traits.
         """
         if isinstance(message, Q10MapPacket):
             self.map.update_from_map_packet(message)
@@ -159,6 +199,32 @@ def _handle_message(self, message: Q10Message) -> None:
             # only updates the fields that it is responsible for.
             for trait in self._updatable_traits:
                 trait.update_from_dps(message.dps)
+            await self._request_map_from_list_response(message.dps)
+
+    async def _request_map_from_list_response(self, decoded_dps: dict[B01_Q10_DP, Any]) -> None:
+        """Request map content after receiving our pending map-list response."""
+        response = decoded_dps.get(B01_Q10_DP.MULTI_MAP)
+        if not self._map_list_requested or not isinstance(response, dict) or response.get("op") != "list":
+            return
+
+        self._map_list_requested = False
+        if (map_id := _map_id_from_list_response(response)) is None:
+            _LOGGER.debug("Q10 map list response did not contain a usable map ID")
+            return
+
+        try:
+            await self.command.send(
+                B01_Q10_DP.COMMON,
+                {
+                    str(B01_Q10_DP.MULTI_MAP.code): {
+                        "op": "get",
+                        "id": map_id,
+                    }
+                },
+            )
+        except RoborockException as ex:
+            # A failed follow-up must not kill the persistent subscribe loop.
+            _LOGGER.debug("Failed to request Q10 map content: %s", ex)
 
 
 def create(channel: B01Q10Channel) -> Q10PropertiesApi:

roborock/map/b01_q10_map_parser.py

@@ -1,7 +1,7 @@
 """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
+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:
 
 - ``01 01`` marker, then a ``u32be`` map id (bytes 2-5) and two consecutive
@@ -19,15 +19,15 @@
 https://github.com/v1b3c0d3x3r/roborock-qseries-map-bridge
 """
 
-import colorsys
 import io
 import math
 import statistics
 from dataclasses import dataclass, field, replace
 
 from PIL import Image
+from vacuum_map_parser_base.config.color import ColorsPalette, SupportedColor
 from vacuum_map_parser_base.config.image_config import ImageConfig
-from vacuum_map_parser_base.map_data import ImageData, MapData
+from vacuum_map_parser_base.map_data import ImageData, MapData, Point
 
 from roborock.exceptions import RoborockException
 
@@ -129,7 +129,8 @@ class Q10EraseZone:
 
     These are the app's *Erase* tool rectangles -- regions the user marked to be
     removed from the map (e.g. phantom floor the lidar mapped through windows).
-    Coordinates are world units (millimetres), same frame as the path/zones.
+    Coordinates are 5 mm world units, the same frame as restriction zones.
+    Trace points use a separate 2.5 mm scale.
 
     Confirmed by a controlled diff: removing the two erase zones on a live device
     dropped this section's count from 2 to 0 while the grid and the trailing
@@ -639,7 +640,12 @@ def parsed_from_packet(self, packet: Q10MapPacket) -> ParsedMapData:
             width=packet.width,
             image_config=ImageConfig(scale=self._config.map_scale),
             data=image,
-            img_transformation=lambda p: p,
+            # ImageDimensions uses V1's bottom-up map convention before
+            # projecting into the top-down PNG. Q10 points are already
+            # top-down grid pixels, so this adapter cancels that standard flip
+            # and lets Q10 use the shared V1 ImageGenerator without moving
+            # overlays vertically.
+            img_transformation=lambda p: Point(p.x, packet.height - p.y - 1, p.a),
         )
         room_names = {room.id: room.name for room in packet.rooms}
         if room_names:
@@ -655,12 +661,12 @@ def parsed_from_packet(self, packet: Q10MapPacket) -> ParsedMapData:
         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."""
+        """Render the Q10 grid with the V1 map palette."""
         palette = _build_palette(packet.grid)
-        rgb = bytearray()
+        rgba = bytearray()
         for value in packet.grid:
-            rgb.extend(palette[value])
-        img = Image.frombytes("RGB", (packet.width, packet.height), bytes(rgb))
+            rgba.extend(palette[value])
+        img = Image.frombytes("RGBA", (packet.width, packet.height), bytes(rgba))
         # The ss07 grid is stored top-down (row 0 = top of the home), so it is
         # rendered as-is -- unlike the V1/Q7 convention, no vertical flip.
         scale = self._config.map_scale
@@ -669,15 +675,22 @@ def _render(self, packet: Q10MapPacket) -> Image.Image:
         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))
+def _opaque(color: tuple[int, ...]) -> tuple[int, int, int, int]:
+    """Return a palette color as RGBA."""
+    return (color[0], color[1], color[2], color[3] if len(color) == 4 else 255)
+
+
+def _build_palette(grid: bytes) -> list[tuple[int, int, int, int]]:
+    """Map Q10 cells onto the same colors used by the V1 map renderer."""
+    colors = ColorsPalette()
+    outside = (0, 0, 0, 0)
+    palette = [outside] * 256
+    for value in {value for value in grid if 0 < value < _WALL_THRESHOLD}:
+        palette[value] = _opaque(colors.get_room_color(max(1, value // 4)))
+    wall = _opaque(colors.get_color(SupportedColor.GREY_WALL))
     for value in range(_WALL_THRESHOLD, 256):
-        palette[value] = (235, 235, 240)  # walls / borders
-    palette[0] = (28, 30, 38)
+        palette[value] = wall
+    palette[_UNSEGMENTED_FLOOR_VALUE] = _opaque(colors.get_color(SupportedColor.MAP_INSIDE))
+    palette[_BACKGROUND_VALUE] = outside
+    palette[0] = outside
     return palette

roborock/map/b01_q10_overlays.py

@@ -19,11 +19,12 @@
 zones (first wire word = x), confirmed against the app.  Provenance and the
 byte-level breakdown are in PR #850's review thread.
 
-Coordinates are in the device's world units (the same space as the cleaning
-path), so a :class:`~roborock.map.b01_grid_layers.GridCalibration` maps them to
-map pixels. ``type`` distinguishes the restriction kind (2 = no-mop, 3 = door
-threshold, anything else -- incl. 0 -- a no-go zone); it is preserved verbatim
-so callers can route polygons to the right ``MapData`` layer.
+Coordinates are in 5 mm device world units, the same space as erase polygons.
+Cleaning trace points use a separate 2.5 mm scale, so callers must not project
+both through the same resolution. ``type`` distinguishes the restriction kind
+(2 = no-mop, 3 = door threshold, anything else -- incl. 0 -- a no-go zone); it
+is preserved verbatim so callers can route polygons to the right ``MapData``
+layer.
 """
 
 import base64