python-roborock 7.6.0__tar.gz → 7.7.1__tar.gz

{python_roborock-7.6.0 → python_roborock-7.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-roborock
-Version: 7.6.0
+Version: 7.7.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.6.0 → python_roborock-7.7.1}/pyproject.toml

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

{python_roborock-7.6.0 → python_roborock-7.7.1}/roborock/data/b01_q10/b01_q10_code_mappings.py

@@ -101,13 +101,8 @@ class B01_Q10_DP(RoborockModeEnum):
     VOICE_VERSION = ("dpVoiceVersion", 108)
     ROBOT_COUNTRY_CODE = ("dpRobotCountryCode", 109)
     HEARTBEAT = ("dpHeartbeat", 110)
-    # NOTE: ss07 hardware also pushes data points 112 and 113 in its full status
-    # dump. They are absent from the official app's vacuum plugin and stayed 0
-    # across every observed state (docked/charging, segment cleaning, lifted-off-
-    # ground fault, returning to dock, dustbin removed), so their meaning is not
-    # yet known. They are intentionally left unmapped; ``decode_rpc_response``
-    # silently ignores unknown codes via ``from_code_optional``, so they do not
-    # produce "not a valid code" warnings. Map them here once identified.
+    UNKNOWN_112 = ("dpUnknown112", 112)
+    UNKNOWN_113 = ("dpUnknown113", 113)
     STATUS = ("dpStatus", 121)
     BATTERY = ("dpBattery", 122)
     FAN_LEVEL = ("dpFanLevel", 123)  # NOTE: typo "dpfunLevel" in source code

{python_roborock-7.6.0 → python_roborock-7.7.1}/roborock/data/b01_q10/b01_q10_containers.py

@@ -28,6 +28,62 @@ from .b01_q10_code_mappings import (
     YXWaterLevel,
 )
 
+_ROBOROCK_COORDINATE_OFFSET_MM = 25_500
+_Q10_TRACE_UNIT_MM = 2.5
+_Q10_VECTOR_UNIT_MM = 5
+
+
+@dataclass(frozen=True)
+class Q10RoborockPoint:
+    """A point in the common Roborock millimetre coordinate space.
+
+    Q10 trace and vector coordinates are firmware details. Public Q10 APIs use
+    this coordinate system, matching other Roborock devices and placing the dock
+    at ``(25500, 25500)``.
+    """
+
+    x: int
+    y: int
+
+    @classmethod
+    def from_trace(cls, x: int, y: int) -> "Q10RoborockPoint":
+        """Convert Q10 trace coordinates to common Roborock coordinates."""
+        for value in (x, y):
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise ValueError("trace coordinates must be integers")
+        return cls(
+            x=round(_ROBOROCK_COORDINATE_OFFSET_MM + x * _Q10_TRACE_UNIT_MM),
+            y=round(_ROBOROCK_COORDINATE_OFFSET_MM + y * _Q10_TRACE_UNIT_MM),
+        )
+
+    @classmethod
+    def from_vector(cls, x: int, y: int) -> "Q10RoborockPoint":
+        """Convert Q10 vector coordinates to common Roborock coordinates."""
+        for value in (x, y):
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise ValueError("vector coordinates must be integers")
+            if not -(2**15) <= value < 2**15:
+                raise ValueError("vector coordinates are outside the Q10 map range")
+        return cls(
+            x=_ROBOROCK_COORDINATE_OFFSET_MM + x * _Q10_VECTOR_UNIT_MM,
+            y=_ROBOROCK_COORDINATE_OFFSET_MM + y * _Q10_VECTOR_UNIT_MM,
+        )
+
+    def to_vector(self) -> tuple[int, int]:
+        """Convert common Roborock coordinates to the Q10 vector grid."""
+        coordinates: list[int] = []
+        for value in (self.x, self.y):
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise ValueError("coordinates must be integers")
+            relative_mm = value - _ROBOROCK_COORDINATE_OFFSET_MM
+            if relative_mm % _Q10_VECTOR_UNIT_MM:
+                raise ValueError("coordinates must align to the Q10 5 mm grid")
+            coordinate = relative_mm // _Q10_VECTOR_UNIT_MM
+            if not -(2**15) <= coordinate < 2**15:
+                raise ValueError("coordinates are outside the Q10 map range")
+            coordinates.append(coordinate)
+        return coordinates[0], coordinates[1]
+
 
 @dataclass
 class dpCleanRecord(RoborockBase):

{python_roborock-7.6.0 → python_roborock-7.7.1}/roborock/devices/traits/b01/q10/__init__.py

@@ -96,7 +96,6 @@ class Q10PropertiesApi(Trait):
         """Initialize the B01Props API."""
         self._channel = channel
         self.command = CommandTrait(channel)
-        self.vacuum = VacuumTrait(self.command)
         self.remote = RemoteTrait(self.command)
         self.status = StatusTrait()
         self.volume = SoundVolumeTrait(self.command)
@@ -109,6 +108,7 @@ class Q10PropertiesApi(Trait):
         self._map_dps = MapDpsTrait()
         self.maps = MapsTrait(self.command)
         self.map = MapContentTrait(self._map_dps, self.maps, self.command)
+        self.vacuum = VacuumTrait(self.command, self.status, self.map)
         self.clean_history = CleanHistoryTrait(self.command)
         # Read-model traits updated from the device's DPS push stream.
         self._updatable_traits = [
@@ -131,6 +131,7 @@ class Q10PropertiesApi(Trait):
 
     async def close(self) -> None:
         """Close any resources held by the trait."""
+        await self.vacuum.close()
         if self._subscribe_task is not None:
             self._subscribe_task.cancel()
             try:

python_roborock-7.7.1/roborock/devices/traits/b01/q10/goto.py

@@ -0,0 +1,158 @@
+"""State management for an emulated Q10 goto action."""
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import StrEnum
+from math import hypot
+
+from roborock.callbacks import CallbackList
+from roborock.data.b01_q10.b01_q10_code_mappings import YXDeviceCleanTask, YXDeviceState
+from roborock.data.b01_q10.b01_q10_containers import Q10RoborockPoint
+
+_LOGGER = logging.getLogger(__name__)
+_TERMINAL_STATES = {
+    YXDeviceState.IDLE,
+    YXDeviceState.PAUSED,
+    YXDeviceState.RETURNING_HOME,
+    YXDeviceState.CHARGING,
+}
+
+
+class GotoActionCommand(StrEnum):
+    """A command requested by a Q10 goto action."""
+
+    PAUSE = "pause"
+    STOP = "stop"
+    COMPLETE = "complete"
+
+
+@dataclass(frozen=True)
+class GotoSnapshot:
+    """Device state needed to advance a goto action."""
+
+    position: Q10RoborockPoint | None
+    trace_sequence: int | None
+    clean_task_type: YXDeviceCleanTask | None
+    status: YXDeviceState | None
+
+
+class GotoAction:
+    """Decide how one emulated goto should react to device updates.
+
+    The action owns no tasks and sends no device commands. ``VacuumTrait`` feeds
+    it push-derived snapshots and performs commands requested by its callbacks.
+    """
+
+    def __init__(
+        self,
+        target: Q10RoborockPoint,
+        previous_trace_sequence: int | None,
+        *,
+        tolerance: int,
+    ) -> None:
+        """Initialize a goto action waiting for a new trace session."""
+        self._target = target
+        self._previous_trace_sequence = previous_trace_sequence
+        self._tolerance = tolerance
+        self._owned_trace_sequence: int | None = None
+        self._owned_task_seen = False
+        self._command_pending = False
+        self._timeout_requested = False
+        self._finished = False
+        self._latest_snapshot: GotoSnapshot | None = None
+        self._callbacks: CallbackList[GotoActionCommand] = CallbackList(logger=_LOGGER)
+
+    def add_update_listener(self, callback: Callable[[GotoActionCommand], None]) -> Callable[[], None]:
+        """Register a callback for the next command requested by the action."""
+        return self._callbacks.add_callback(callback)
+
+    def update(self, snapshot: GotoSnapshot) -> None:
+        """Process the latest push-derived device state."""
+        self._latest_snapshot = snapshot
+        self._evaluate(snapshot)
+
+    def retry(self) -> None:
+        """Re-evaluate the latest state after a requested command failed."""
+        if self._finished or self._latest_snapshot is None:
+            return
+        self._command_pending = False
+        if self._timeout_requested:
+            self._evaluate_timeout(self._latest_snapshot)
+        else:
+            self._evaluate(self._latest_snapshot)
+
+    def timeout(self, snapshot: GotoSnapshot) -> None:
+        """Request a stop only if this action still owns the current zone task."""
+        if self._finished:
+            return
+        self._latest_snapshot = snapshot
+        self._timeout_requested = True
+        if self._command_pending:
+            return
+        self._evaluate_timeout(snapshot)
+
+    def _evaluate_timeout(self, snapshot: GotoSnapshot) -> None:
+        """Derive the safe timeout command from the latest device state."""
+        if self.owns(snapshot):
+            self._emit(GotoActionCommand.STOP)
+        else:
+            self._emit(GotoActionCommand.COMPLETE)
+
+    def complete(self) -> None:
+        """Mark the action complete after its requested command succeeds."""
+        self._finished = True
+        self._command_pending = False
+
+    def owns(self, snapshot: GotoSnapshot) -> bool:
+        """Return whether this action owns the current Q10 zone-clean session."""
+        return (
+            self._owned_trace_sequence is not None
+            and snapshot.trace_sequence == self._owned_trace_sequence
+            and snapshot.clean_task_type is YXDeviceCleanTask.DIVIDE_AREAS
+        )
+
+    def _evaluate(self, snapshot: GotoSnapshot) -> None:
+        """Derive the next command from the latest device state."""
+        if self._finished or self._command_pending:
+            return
+
+        if self._owned_trace_sequence is None:
+            if snapshot.trace_sequence is not None and snapshot.trace_sequence != self._previous_trace_sequence:
+                self._owned_trace_sequence = snapshot.trace_sequence
+        elif snapshot.trace_sequence != self._owned_trace_sequence:
+            _LOGGER.debug("Q10 goto task was replaced by another cleaning session")
+            self._emit(GotoActionCommand.COMPLETE)
+            return
+
+        if (
+            self._owned_trace_sequence is not None
+            and snapshot.clean_task_type is YXDeviceCleanTask.DIVIDE_AREAS
+            and snapshot.status not in _TERMINAL_STATES
+        ):
+            self._owned_task_seen = True
+
+        if self._owned_task_seen and (
+            snapshot.clean_task_type is not YXDeviceCleanTask.DIVIDE_AREAS or snapshot.status in _TERMINAL_STATES
+        ):
+            self._emit(GotoActionCommand.COMPLETE)
+            return
+
+        if (
+            self.owns(snapshot)
+            and snapshot.position is not None
+            and hypot(
+                snapshot.position.x - self._target.x,
+                snapshot.position.y - self._target.y,
+            )
+            <= self._tolerance
+        ):
+            self._emit(GotoActionCommand.PAUSE)
+
+    def _emit(self, command: GotoActionCommand) -> None:
+        """Publish a requested command once until it is handled."""
+        if command is GotoActionCommand.COMPLETE:
+            self._finished = True
+        else:
+            self._command_pending = True
+        self._callbacks(command)

{python_roborock-7.6.0 → python_roborock-7.7.1}/roborock/devices/traits/b01/q10/map.py

@@ -19,6 +19,7 @@ from typing import Any
 
 from roborock.data import RoborockBase
 from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP, YXDeviceState
+from roborock.data.b01_q10.b01_q10_containers import Q10RoborockPoint
 from roborock.devices.traits.common import DpsDataConverter, TraitUpdateListener
 from roborock.exceptions import RoborockException
 from roborock.map.b01_q10_map_parser import (
@@ -127,13 +128,20 @@ class MapContentTrait(TraitUpdateListener):
 
     @property
     def path(self) -> list[Q10Point]:
-        """Full path for live status and callers drawing their own map overlay."""
+        """Full path in the Q10 trace coordinate space used by the map renderer."""
         return self._trace_packet.points if self._trace_packet else []
 
     @property
-    def robot_position(self) -> Q10Point | None:
-        """Current position for live status and caller-rendered map overlays."""
-        return self._trace_packet.robot_position if self._trace_packet else None
+    def robot_position(self) -> Q10RoborockPoint | None:
+        """Current position in the common Roborock millimetre coordinate space."""
+        if self._trace_packet is None or (position := self._trace_packet.robot_position) is None:
+            return None
+        return position.to_roborock()
+
+    @property
+    def trace_sequence(self) -> int | None:
+        """Current cleaning-session sequence from the trace stream."""
+        return self._trace_packet.sequence if self._trace_packet else None
 
     @property
     def robot_heading(self) -> int | None:
@@ -181,7 +189,9 @@ class MapContentTrait(TraitUpdateListener):
         data = {
             "rooms": [room.as_dict() for room in self.rooms],
             "path": [point.as_dict() for point in self.path],
-            "robotPosition": self.robot_position.as_dict() if self.robot_position is not None else None,
+            "robotPosition": (
+                {"x": position.x, "y": position.y} if (position := self.robot_position) is not None else None
+            ),
             "robotHeading": self.robot_heading,
         }
         for key in exclude_set:

python_roborock-7.7.1/roborock/devices/traits/b01/q10/vacuum.py

@@ -0,0 +1,291 @@
+"""Traits for Q10 B01 devices."""
+
+import asyncio
+import logging
+from collections.abc import Callable
+from math import hypot
+
+from roborock.data.b01_q10.b01_q10_code_mappings import (
+    B01_Q10_DP,
+    YXCleanType,
+    YXDeviceCleanTask,
+    YXFanLevel,
+)
+from roborock.data.b01_q10.b01_q10_containers import Q10RoborockPoint
+from roborock.exceptions import RoborockException
+from roborock.protocols.b01_q10_protocol import CleanParams, encode_clean_params
+
+from .command import CommandTrait
+from .goto import GotoAction, GotoActionCommand, GotoSnapshot
+from .map import MapContentTrait
+from .status import StatusTrait
+
+_GOTO_HALF_ZONE_SIZE = 200
+_GOTO_TOLERANCE = 200
+_GOTO_TIMEOUT = 300
+_GOTO_RETRY_INTERVAL = 1
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class VacuumTrait:
+    """Trait for sending vacuum commands.
+
+    This is a wrapper around the CommandTrait for sending vacuum related
+    commands to Q10 devices.
+    """
+
+    def __init__(
+        self,
+        command: CommandTrait,
+        status: StatusTrait,
+        map_content: MapContentTrait,
+    ) -> None:
+        """Initialize the VacuumTrait."""
+        self._command = command
+        self._status = status
+        self._map = map_content
+        self._goto_action: GotoAction | None = None
+        self._goto_action_remove_listener: Callable[[], None] | None = None
+        self._goto_timeout_task: asyncio.Task[None] | None = None
+        self._goto_command_task: asyncio.Task[None] | None = None
+        self._remove_map_listener = self._map.add_update_listener(self._goto_source_updated)
+        self._remove_status_listener = self._status.add_update_listener(self._goto_source_updated)
+
+    async def close(self) -> None:
+        """Cancel background work owned by the trait."""
+        self.cancel_goto()
+        self._remove_map_listener()
+        self._remove_status_listener()
+
+    def cancel_goto(self) -> None:
+        """Cancel an emulated goto replaced by another command."""
+        if self._goto_action is not None:
+            self._goto_action.complete()
+            self._goto_action = None
+        if self._goto_action_remove_listener is not None:
+            self._goto_action_remove_listener()
+            self._goto_action_remove_listener = None
+        current_task = asyncio.current_task()
+        for task_name in ("_goto_timeout_task", "_goto_command_task"):
+            if (task := getattr(self, task_name)) is not None:
+                if task is not current_task:
+                    task.cancel()
+                setattr(self, task_name, None)
+
+    def _goto_snapshot(self) -> GotoSnapshot:
+        """Return the latest state used by an active goto action."""
+        return GotoSnapshot(
+            position=self._map.robot_position,
+            trace_sequence=self._map.trace_sequence,
+            clean_task_type=self._status.clean_task_type,
+            status=self._status.status,
+        )
+
+    def _goto_source_updated(self) -> None:
+        """Feed push-derived map or status state to the active goto action."""
+        if self._goto_action is not None:
+            self._goto_action.update(self._goto_snapshot())
+
+    def _goto_action_updated(self, action: GotoAction, command: GotoActionCommand) -> None:
+        """Schedule a device command requested by the active goto action."""
+        if action is not self._goto_action:
+            return
+        if command is GotoActionCommand.COMPLETE:
+            self.cancel_goto()
+            return
+        if self._goto_command_task is None:
+            self._goto_command_task = asyncio.create_task(
+                self._async_handle_goto_command(action, command),
+                name="roborock_q10_goto_command",
+            )
+
+    async def _async_handle_goto_command(self, action: GotoAction, command: GotoActionCommand) -> None:
+        """Perform a pause or stop requested by the active goto action."""
+        current_task = asyncio.current_task()
+        dp_command = B01_Q10_DP.PAUSE if command is GotoActionCommand.PAUSE else B01_Q10_DP.STOP
+        try:
+            await self._command.send(command=dp_command, params=0)
+        except RoborockException as err:
+            if command is GotoActionCommand.PAUSE:
+                _LOGGER.warning("Failed to pause completed Q10 goto task; retrying: %s", err)
+                await asyncio.sleep(_GOTO_RETRY_INTERVAL)
+                if action is self._goto_action:
+                    self._goto_command_task = None
+                    action.retry()
+                return
+            _LOGGER.warning("Failed to stop timed-out Q10 goto task: %s", err)
+        if action is self._goto_action:
+            action.complete()
+            self.cancel_goto()
+        if self._goto_command_task is current_task:
+            self._goto_command_task = None
+
+    async def _async_timeout_goto(self, action: GotoAction) -> None:
+        """Tell the active goto action when its safety timeout expires."""
+        try:
+            await asyncio.sleep(_GOTO_TIMEOUT)
+        except asyncio.CancelledError:
+            return
+        if action is self._goto_action:
+            action.timeout(self._goto_snapshot())
+
+    async def start_clean(self) -> None:
+        """Start a whole-home clean.
+
+        The ``dpStartClean`` (201) command selects a task by code: ``1`` =
+        whole-home, ``2`` = segment/room (see :meth:`clean_segments`), ``3`` =
+        zone, ``4`` = build map, ``5`` = spot. Whole-home and spot accept the
+        bare integer code; segment cleaning needs a room selection (an object
+        payload) instead.
+
+        Verified live against ss07 hardware: ``{"dps": {"201": 1}}`` starts a
+        whole-home clean (clean_task_type -> 1).
+        """
+        await self._command.send(command=B01_Q10_DP.START_CLEAN, params=1)
+        self.cancel_goto()
+
+    async def clean_segments(self, segment_ids: list[int]) -> None:
+        """Start a room / segment clean for the given segment (room) ids.
+
+        The ids are the same room ids the device reports on its map (see the Q10
+        ``MapContentTrait`` -- ``map.rooms``, each with an ``id``).
+
+        Unlike whole-home and spot, ``dpStartClean`` (201) carries the room
+        selection as an object: ``{"cmd": <task>, "clean_paramters": [<id>, ...]}``,
+        where ``cmd`` is the segment-clean task code.
+
+        Verified live against ss07 hardware: sending
+        ``{"dps": {"201": {"cmd": 2, "clean_paramters": [9]}}}`` starts cleaning
+        room 9 (clean_task_type -> 2 / electoral).
+        """
+        await self._command.send(
+            command=B01_Q10_DP.START_CLEAN,
+            # "clean_paramters" intentionally mirrors the device's misspelling of
+            # "parameters" -- the firmware only accepts that exact key.
+            params={"cmd": YXDeviceCleanTask.ELECTORAL.code, "clean_paramters": segment_ids},
+        )
+        self.cancel_goto()
+
+    async def clean_zone(
+        self,
+        first_corner: Q10RoborockPoint,
+        second_corner: Q10RoborockPoint,
+        *,
+        clean_count: int = 1,
+    ) -> None:
+        """Clean one rectangular zone in the common Roborock coordinate space."""
+        encoded_zone = encode_clean_params(CleanParams(first_corner, second_corner, clean_count))
+        await self._command.send(
+            command=B01_Q10_DP.START_CLEAN,
+            params={
+                "cmd": YXDeviceCleanTask.DIVIDE_AREAS.code,
+                # "clean_paramters" is the spelling required by the firmware.
+                "clean_paramters": encoded_zone,
+            },
+        )
+        self.cancel_goto()
+
+    async def goto_position(self, target: Q10RoborockPoint) -> None:
+        """Move to a coordinate using an owned 40 cm zone-clean task."""
+        target.to_vector()
+        snapshot = self._goto_snapshot()
+        if (position := snapshot.position) is not None and hypot(
+            position.x - target.x, position.y - target.y
+        ) <= _GOTO_TOLERANCE:
+            if self._goto_action is not None and self._goto_action.owns(snapshot):
+                await self._command.send(command=B01_Q10_DP.PAUSE, params=0)
+                self.cancel_goto()
+            return
+
+        encoded_zone = encode_clean_params(
+            CleanParams(
+                Q10RoborockPoint(
+                    target.x - _GOTO_HALF_ZONE_SIZE,
+                    target.y - _GOTO_HALF_ZONE_SIZE,
+                ),
+                Q10RoborockPoint(
+                    target.x + _GOTO_HALF_ZONE_SIZE,
+                    target.y + _GOTO_HALF_ZONE_SIZE,
+                ),
+            )
+        )
+        await self._command.send(
+            command=B01_Q10_DP.START_CLEAN,
+            params={
+                "cmd": YXDeviceCleanTask.DIVIDE_AREAS.code,
+                "clean_paramters": encoded_zone,
+            },
+        )
+        self.cancel_goto()
+        action = GotoAction(
+            target,
+            snapshot.trace_sequence,
+            tolerance=_GOTO_TOLERANCE,
+        )
+        self._goto_action = action
+        self._goto_action_remove_listener = action.add_update_listener(
+            lambda command: self._goto_action_updated(action, command)
+        )
+        self._goto_timeout_task = asyncio.create_task(
+            self._async_timeout_goto(action),
+            name="roborock_q10_goto_timeout",
+        )
+        action.update(self._goto_snapshot())
+
+    async def spot_clean(self) -> None:
+        """Start a spot / part clean around the robot's current position.
+
+        Verified live: ``{"dps": {"201": 5}}`` (clean_task_type -> 5).
+        """
+        await self._command.send(command=B01_Q10_DP.START_CLEAN, params=5)
+        self.cancel_goto()
+
+    async def pause_clean(self) -> None:
+        """Pause the current task. Verified live: ``{"dps": {"204": 0}}``."""
+        await self._command.send(command=B01_Q10_DP.PAUSE, params=0)
+        self.cancel_goto()
+
+    async def resume_clean(self) -> None:
+        """Resume a paused task. Verified live: ``{"dps": {"205": 0}}``."""
+        await self._command.send(command=B01_Q10_DP.RESUME, params=0)
+        self.cancel_goto()
+
+    async def stop_clean(self) -> None:
+        """Stop / cancel the current task. Verified live: ``{"dps": {"206": 0}}``."""
+        await self._command.send(command=B01_Q10_DP.STOP, params=0)
+        self.cancel_goto()
+
+    async def return_to_dock(self) -> None:
+        """Send the robot back to the dock to charge.
+
+        Uses ``dpStartBack`` (202) with the back-dock task code ``5`` (charge),
+        matching the official app. Verified live: ``{"dps": {"202": 5}}`` puts the
+        robot into the returning state. (The other back-dock codes are ``1`` =
+        wash mop en route and ``4`` = collect dust en route.)
+        """
+        await self._command.send(command=B01_Q10_DP.START_BACK, params=5)
+        self.cancel_goto()
+
+    async def empty_dustbin(self) -> None:
+        """Empty the dustbin at the dock.
+
+        Verified live: ``{"dps": {"203": 2}}`` triggers dust collection
+        (status -> emptying_the_bin). This is a dock task (``dpStartDockTask``),
+        distinct from the en-route collect-dust back-dock code.
+        """
+        await self._command.send(command=B01_Q10_DP.START_DOCK_TASK, params=2)
+
+    async def set_clean_mode(self, mode: YXCleanType) -> None:
+        """Set the cleaning mode (vacuum, mop, or both)."""
+        await self._command.send(
+            command=B01_Q10_DP.CLEAN_MODE,
+            params=mode.code,
+        )
+
+    async def set_fan_level(self, level: YXFanLevel) -> None:
+        """Set the fan suction level."""
+        await self._command.send(
+            command=B01_Q10_DP.FAN_LEVEL,
+            params=level.code,
+        )

{python_roborock-7.6.0 → python_roborock-7.7.1}/roborock/map/b01_q10_map_parser.py

@@ -29,6 +29,7 @@ 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, Point
 
+from roborock.data.b01_q10.b01_q10_containers import Q10RoborockPoint
 from roborock.data.containers import RoborockBase
 from roborock.exceptions import RoborockException
 
@@ -222,11 +223,15 @@ class Q10MapPacket:
 
 @dataclass
 class Q10Point(RoborockBase):
-    """A single point in Q10 map/trace coordinate space."""
+    """A point in the Q10 firmware's dock-relative trace coordinate space."""
 
     x: int
     y: int
 
+    def to_roborock(self) -> Q10RoborockPoint:
+        """Convert this trace point to common Roborock coordinates."""
+        return Q10RoborockPoint.from_trace(self.x, self.y)
+
 
 @dataclass
 class Q10TracePacket: