feat: render Q10 map obstacle markers

Author: hCoureau

roborock/devices/device_manager.py

@@ -266,7 +266,12 @@ def device_creator(home_data: HomeData, device: HomeDataDevice, product: HomeDat
                     trait = b01.q10.create(
                         channel,
                         map_parser_config=(
-                            B01Q10MapParserConfig(map_scale=map_parser_config.map_scale) if map_parser_config else None
+                            B01Q10MapParserConfig(
+                                map_scale=map_parser_config.map_scale,
+                                drawables=map_parser_config.drawables,
+                            )
+                            if map_parser_config
+                            else None
                         ),
                     )
                 elif "sc" in model_part:

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

@@ -28,6 +28,7 @@
     Q10HistoricalTracePacket,
     Q10MapPacket,
     Q10MapPacketKind,
+    Q10Obstacle,
     Q10Point,
 )
 from roborock.map.b01_q10_render import Q10MapOverlays, render_q10_map
@@ -200,6 +201,11 @@ def detail_path(self) -> list[Q10Point]:
         """Historical path points for the selected clean record."""
         return self.detail_trace.points if self.detail_trace else []
 
+    @property
+    def detail_obstacles(self) -> list[Q10Obstacle]:
+        """Obstacle markers embedded in the selected clean-record map."""
+        return list(self.detail_packet.obstacles) if self.detail_packet else []
+
     def update_from_dps(self, decoded_dps: dict[B01_Q10_DP, Any]) -> None:
         """Apply a ``dpCleanRecord`` push (a full list reply or a single notify)."""
         envelope = decoded_dps.get(B01_Q10_DP.CLEAN_RECORD)

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

@@ -25,6 +25,7 @@
     B01Q10MapParserConfig,
     Q10MapPacket,
     Q10MapPacketKind,
+    Q10Obstacle,
     Q10Point,
     Q10Room,
     Q10TracePacket,
@@ -139,6 +140,11 @@ def path(self) -> list[Q10Point]:
         """Full path for live status and callers drawing their own map overlay."""
         return self._trace_packet.points if self._trace_packet else []
 
+    @property
+    def obstacles(self) -> list[Q10Obstacle]:
+        """Position-only obstacle markers reported by the current map."""
+        return list(self._map_packet.obstacles) if self._map_packet else []
+
     @property
     def robot_position(self) -> Q10Point | None:
         """Current position for live status and caller-rendered map overlays."""
@@ -199,6 +205,7 @@ def as_dict(self, exclude: set[str] | None = None) -> dict[str, Any]:
         exclude_set = exclude or set()
         data = {
             "rooms": [room.as_dict() for room in self.rooms],
+            "obstacles": [obstacle.as_dict() for obstacle in self.obstacles],
             "path": [point.as_dict() for point in self.path],
             "robotPosition": self.robot_position.as_dict() if self.robot_position is not None else None,
             "robotHeading": self.robot_heading,

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

@@ -9,7 +9,12 @@
 from roborock.data.b01_q10.b01_q10_containers import Q10MapInfo, dpMultiMap
 from roborock.devices.traits.common import DpsDataConverter
 from roborock.exceptions import RoborockException
-from roborock.map.b01_q10_map_parser import B01Q10MapParserConfig, Q10MapPacket, Q10MapPacketKind
+from roborock.map.b01_q10_map_parser import (
+    B01Q10MapParserConfig,
+    Q10MapPacket,
+    Q10MapPacketKind,
+    Q10Obstacle,
+)
 from roborock.map.b01_q10_render import Q10MapOverlays, render_q10_map
 
 from .command import CommandTrait
@@ -64,6 +69,11 @@ def __init__(
         """Rendered saved-map detail image, if decoding succeeded."""
         self._pending_detail_map_id: str | None = None
 
+    @property
+    def detail_obstacles(self) -> list[Q10Obstacle]:
+        """Obstacle markers embedded in the selected saved-map preview."""
+        return list(self.detail_packet.obstacles) if self.detail_packet else []
+
     async def refresh(self) -> None:
         """Request a new saved-map list from the device."""
         await self._command.send(

roborock/map/b01_q10_map_parser.py

@@ -25,9 +25,11 @@
 import statistics
 import struct
 from dataclasses import dataclass, field, replace
+from typing import TypeVar
 
 from PIL import Image
 from vacuum_map_parser_base.config.color import ColorsPalette, SupportedColor
+from vacuum_map_parser_base.config.drawable import Drawable
 from vacuum_map_parser_base.config.image_config import ImageConfig
 from vacuum_map_parser_base.map_data import ImageData, MapData, Point
 
@@ -234,6 +236,10 @@ class Q10MapPacket:
     carpet (the value is the carpet kind). ``None`` if the packet carried none."""
     historical_trace: "Q10HistoricalTracePacket | None" = None
     """Cleaning path embedded in a clean-record detail packet, if present."""
+    obstacles: list["Q10Obstacle"] = field(default_factory=list)
+    """Obstacle markers embedded after the carpet block (50 raw units/pixel)."""
+    skip_cleaning_points: list["Q10Point"] = field(default_factory=list)
+    """Firmware skip-clean markers embedded after obstacles (10 raw units/pixel)."""
 
     @property
     def layers(self) -> GridLayers:
@@ -251,6 +257,19 @@ class Q10Point(RoborockBase):
     y: int
 
 
+@dataclass
+class Q10Obstacle(Q10Point):
+    """A Q10 map obstacle marker in its raw map-package coordinate frame.
+
+    The map package supplies positions only: there is no validated type,
+    confidence, or photo identifier on this model. Fifty raw units equal one
+    occupancy-grid pixel; placement is anchored by the map header origin.
+    """
+
+
+_PointType = TypeVar("_PointType", bound=Q10Point)
+
+
 @dataclass
 class Q10TracePacket:
     """Decoded contents of a Q10 ``02 01`` cleaning-path packet.
@@ -332,13 +351,12 @@ def robot_position(self) -> Q10Point | None:
 _TRACE_POINT_COUNT_OFFSET = 8
 _TRACE_HEADING_OFFSET = 10
 
-_HISTORICAL_TRACE_HEADER_LENGTH = 14
-_HISTORICAL_TRACE_PREFIX_LENGTH = 1
+_HISTORICAL_TRACE_HEADER_LENGTH = 13
 _HISTORICAL_TRACE_VERSION = 1
-_HISTORICAL_TRACE_OPAQUE_VALUE_OFFSET = 2
-_HISTORICAL_TRACE_POINT_COUNT_OFFSET = 6
-_HISTORICAL_TRACE_HEADING_OFFSET = 10
-_HISTORICAL_TRACE_RESERVED_OFFSET = 12
+_HISTORICAL_TRACE_OPAQUE_VALUE_OFFSET = 1
+_HISTORICAL_TRACE_POINT_COUNT_OFFSET = 5
+_HISTORICAL_TRACE_HEADING_OFFSET = 9
+_HISTORICAL_TRACE_RESERVED_OFFSET = 11
 
 # 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));
@@ -565,10 +583,18 @@ def parse_map_packet(payload: bytes) -> Q10MapPacket:
     tail = payload[layout_end:]
     erase_zones = _parse_erase_zones(tail)
     carpet_mask, carpet_end = _parse_carpet_block(tail, width, height)
-    if kind is Q10MapPacketKind.CLEAN_RECORD_DETAIL and carpet_end is not None:
-        historical_trace, _ = _parse_clean_record_trace(tail, carpet_end)
-    else:
-        historical_trace = None
+    obstacles: list[Q10Obstacle] = []
+    skip_cleaning_points: list[Q10Point] = []
+    historical_trace = None
+    if carpet_end is not None:
+        parsed_obstacles, obstacle_end = _parse_counted_points(tail, carpet_end, Q10Obstacle)
+        if obstacle_end is not None:
+            parsed_skip_points, skip_end = _parse_counted_points(tail, obstacle_end, Q10Point)
+            if skip_end is not None:
+                obstacles = parsed_obstacles
+                skip_cleaning_points = parsed_skip_points
+                if kind is Q10MapPacketKind.CLEAN_RECORD_DETAIL:
+                    historical_trace, _ = _parse_clean_record_trace(tail, skip_end)
     header_calibration = _parse_header_calibration(payload)
     return Q10MapPacket(
         kind=kind,
@@ -580,6 +606,8 @@ def parse_map_packet(payload: bytes) -> Q10MapPacket:
         erase_zones=erase_zones,
         header_calibration=header_calibration,
         carpet_mask=carpet_mask,
+        obstacles=obstacles,
+        skip_cleaning_points=skip_cleaning_points,
         historical_trace=historical_trace,
     )
 
@@ -701,6 +729,29 @@ def _parse_carpet_mask(tail: bytes, width: int, height: int) -> bytes | None:
     return _parse_carpet_block(tail, width, height)[0]
 
 
+def _parse_counted_points(
+    tail: bytes,
+    offset: int,
+    point_type: type[_PointType],
+) -> tuple[list[_PointType], int | None]:
+    """Decode one bounded ``u8 count`` + signed-BE ``(x, y)`` point table.
+
+    Obstacle and skip-clean sections use the same framing but different
+    coordinate scales. The caller owns those semantics; this helper only
+    validates and decodes the table atomically. A truncated table returns no
+    points and no end offset, preventing later sections from being misaligned.
+    """
+    if offset >= len(tail):
+        return [], None
+    count = tail[offset]
+    points_start = offset + 1
+    points_end = points_start + count * 4
+    if points_end > len(tail):
+        return [], None
+    coordinates = struct.iter_unpack(">hh", memoryview(tail)[points_start:points_end])
+    return ([point_type(x=x, y=y) for x, y in coordinates], points_end)
+
+
 def _parse_clean_record_trace(
     tail: bytes,
     offset: int,
@@ -709,20 +760,17 @@ def _parse_clean_record_trace(
 
     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.
+    corresponding live trace exactly. The caller first consumes the obstacle
+    and skip-clean point tables; ``offset`` therefore starts at the one-byte
+    path version. Any unsupported version, non-zero reserved word, or truncated
+    point table is left completely opaque. Bytes after the declared points are
+    deliberately not consumed: the observed invariant 12-byte suffix appears
+    structured, but controlled captures disprove it as per-clean obstacles.
     """
-    if offset >= len(tail) or tail[offset] != 0:
-        return None, None
-    offset += _HISTORICAL_TRACE_PREFIX_LENGTH
     header_end = offset + _HISTORICAL_TRACE_HEADER_LENGTH
     if header_end > len(tail):
         return None, None
-    version = int.from_bytes(tail[offset : offset + 2], "big")
+    version = tail[offset]
     reserved = int.from_bytes(
         tail[offset + _HISTORICAL_TRACE_RESERVED_OFFSET : offset + _HISTORICAL_TRACE_RESERVED_OFFSET + 2],
         "big",
@@ -778,6 +826,8 @@ class B01Q10MapParserConfig:
 
     map_scale: int = 4
     """Scale factor for the rendered map image."""
+    drawables: list[Drawable] | None = None
+    """Enabled map overlays, or ``None`` for the Q10 defaults."""
 
 
 class B01Q10MapParser:

roborock/map/b01_q10_render.py

@@ -20,7 +20,7 @@
 
 from vacuum_map_parser_base.config.drawable import Drawable
 from vacuum_map_parser_base.config.size import Size, Sizes
-from vacuum_map_parser_base.map_data import Area, MapData, Path, Point, Wall
+from vacuum_map_parser_base.map_data import Area, MapData, Obstacle, ObstacleDetails, Path, Point, Wall
 
 from roborock.exceptions import RoborockException
 
@@ -67,6 +67,7 @@
     Drawable.CHARGER,
     Drawable.NO_GO_AREAS,
     Drawable.NO_MOPPING_AREAS,
+    Drawable.OBSTACLES,
     Drawable.PATH,
     Drawable.VACUUM_POSITION,
     Drawable.VIRTUAL_WALLS,
@@ -114,7 +115,7 @@ def render_q10_map(
         raise RoborockException("Failed to render Q10 map image")
     map_data = parsed.map_data
 
-    has_drawables = False
+    has_drawables = _place_obstacles(map_data, packet)
     if trace_calibration is not None and trace is not None:
         charger_heading = packet.header_calibration.charger_phi if packet.header_calibration is not None else None
         _place_trace(map_data, trace_calibration, trace, charger_heading=charger_heading)
@@ -131,6 +132,30 @@ def render_q10_map(
     return parsed.image_content
 
 
+def _obstacle_calibration(packet: Q10MapPacket) -> GridCalibration | None:
+    """Build the obstacle-table transform from the map header.
+
+    Q10 obstacle positions use 50 raw units per occupancy-grid pixel, unlike
+    the 5 mm restriction vectors and 2.5 mm cleaning traces.
+    """
+    header = packet.header_calibration
+    if header is None or (origin := header.origin_pixels()) is None:
+        return None
+    return GridCalibration(resolution=50.0, origin_x=origin[0], origin_y=origin[1], y_sign=1)
+
+
+def _place_obstacles(map_data: MapData, packet: Q10MapPacket) -> bool:
+    """Project position-only Q10 obstacle markers into shared ``MapData``."""
+    calibration = _obstacle_calibration(packet)
+    if calibration is None or not packet.obstacles:
+        return False
+    map_data.obstacles = [
+        Obstacle(*calibration.world_to_pixel(obstacle.x, obstacle.y), ObstacleDetails())
+        for obstacle in packet.obstacles
+    ]
+    return True
+
+
 def solve_q10_calibration(
     packet: Q10MapPacket,
     trace: Q10TracePacket | Q10HistoricalTracePacket | None,
@@ -326,10 +351,10 @@ def _draw_map_content(
     """Draw Q10 content with the shared V1 image generator."""
     if map_data.image is None:
         raise RoborockException("Failed to render Q10 map image")
-    generator = _create_image_generator(
-        MapParserConfig(map_scale=config.map_scale),
-        drawables=_Q10_DRAWABLES,
+    drawables = (
+        _Q10_DRAWABLES if config.drawables is None else [d for d in config.drawables if d in _Q10_DRAWABLE_TYPES]
     )
+    generator = _create_image_generator(MapParserConfig(map_scale=config.map_scale), drawables=drawables)
     generator.draw_map(map_data)
     buffer = io.BytesIO()
     map_data.image.data.save(buffer, format="PNG")

tests/devices/test_device_manager.py

@@ -8,13 +8,16 @@
 
 import pytest
 import syrupy
+from vacuum_map_parser_base.config.drawable import Drawable
 
 from roborock.data import HomeData, UserData
 from roborock.data.containers import HomeDataDevice, HomeDataProduct, RoborockCategory
 from roborock.devices.cache import InMemoryCache
 from roborock.devices.device import RoborockDevice
 from roborock.devices.device_manager import UserParams, create_device_manager, create_web_api_wrapper
+from roborock.devices.traits.b01.q10 import create as create_q10
 from roborock.exceptions import RoborockException, RoborockInvalidCredentials
+from roborock.map.map_parser import MapParserConfig
 from roborock.testing import FakeRoborockCloud, Q10VacuumSimulator, V1VacuumSimulator
 from tests import mock_data
 
@@ -85,7 +88,12 @@ async def test_with_q10_device(cloud: FakeRoborockCloud, patch_device_manager: N
     )
     cloud.add_device(q10_sim)
 
-    device_manager = await create_device_manager(USER_PARAMS)
+    map_parser_config = MapParserConfig(drawables=[Drawable.OBSTACLES], map_scale=2)
+    with patch("roborock.devices.device_manager.b01.q10.create", wraps=create_q10) as q10_create:
+        device_manager = await create_device_manager(USER_PARAMS, map_parser_config=map_parser_config)
+    q10_config = q10_create.call_args.kwargs["map_parser_config"]
+    assert q10_config.map_scale == 2
+    assert q10_config.drawables == [Drawable.OBSTACLES]
     devices = await device_manager.get_devices()
 
     # The setup includes fake_device (V1) by default because of the fake_device fixture

tests/devices/traits/b01/q10/__snapshots__/test_status.ambr

@@ -24,6 +24,8 @@
       'dustSwitch': True,
     }),
     'map': dict({
+      'obstacles': list([
+      ]),
       'path': list([
       ]),
       'robotHeading': None,
@@ -404,6 +406,8 @@
         'dustSwitch': True,
       }),
       'map': dict({
+        'obstacles': list([
+        ]),
         'path': list([
         ]),
         'robotHeading': None,
@@ -480,6 +484,8 @@
     'dust_collection': dict({
     }),
     'map': dict({
+      'obstacles': list([
+      ]),
       'path': list([
       ]),
       'robotHeading': None,