python-roborock 7.6.0__py3-none-any.whl → 7.7.0__py3-none-any.whl

{python_roborock-7.6.0.dist-info → python_roborock-7.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-roborock
-Version: 7.6.0
+Version: 7.7.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-7.6.0.dist-info → python_roborock-7.7.0.dist-info}/RECORD

@@ -17,7 +17,7 @@ roborock/data/code_mappings.py,sha256=j-ZZRtQQdIMJQAgEwDAxWKreNhD6U36oIhBKr_nLbi
 roborock/data/containers.py,sha256=ePz1tmhNY1QpgiVlyc8j6PH5kjU6fkZYtBByCFj2wzU,17896
 roborock/data/b01_q10/__init__.py,sha256=E4lwJcz4AI1z92FcYOJ-cY3fcfHSoXqvYVgfA-TgaRk,71
 roborock/data/b01_q10/b01_q10_code_mappings.py,sha256=UBFkxCWLYCGQatENmNwR0owkXrcB8AosnD-hICfS2AY,15203
-roborock/data/b01_q10/b01_q10_containers.py,sha256=HE1qAhYKDTz35oRgekYItNfD1iWTi7605-wpETcDzxU,11823
+roborock/data/b01_q10/b01_q10_containers.py,sha256=SOubDoxjNfCd-8JHjZ4GQKqWObJeYm0ouiUvWpjPWcY,14199
 roborock/data/b01_q7/__init__.py,sha256=D-Cd8eB0njf1PQPM6Exl_9A0AhpzIjrL0hapGOCEkkA,69
 roborock/data/b01_q7/b01_q7_code_mappings.py,sha256=S2KiBIpkUniEnw0hSSLeLWHZMZvq4Ld6RXzbaXO43Zk,11274
 roborock/data/b01_q7/b01_q7_containers.py,sha256=h01GNZM-M4OAMBO3aqE0LHgvmsrirssMmjR3YWdZMqo,10421
@@ -51,7 +51,7 @@ roborock/devices/traits/traits_mixin.py,sha256=7t15l_Ty1cN-3-fKNtRH1XR6-mfadPnTB
 roborock/devices/traits/a01/__init__.py,sha256=rRrdXgSsolyNC6MOCyYIfW8oaUmzt-p_uppuhzfYYIU,18375
 roborock/devices/traits/a01/device_feature.py,sha256=tO7u1dvnwerj9IVq9je-p7tzyEqTQR7i59DEj57eHZk,14117
 roborock/devices/traits/b01/__init__.py,sha256=pGN6wEocE6Fr2BTasG8Z_75crD6OdTwpju59Vw7eTDk,202
-roborock/devices/traits/b01/q10/__init__.py,sha256=BpeCO7vrM11ISy8JZwBiSkHsTs5-vp68c9YwnWKEIDk,6747
+roborock/devices/traits/b01/q10/__init__.py,sha256=fucVVugsvIHl09ypuVRnN5KeUgqFixngxMsm3ktxXts,6804
 roborock/devices/traits/b01/q10/button_light.py,sha256=_CCWSjFe_iZnnSXgBHOju31VUmwG1KKd_jGkmSpLew4,994
 roborock/devices/traits/b01/q10/child_lock.py,sha256=bTsbAMxn7AF1zpWteyZCkQm4jj3NiWD8ddZTM3tlG_0,1131
 roborock/devices/traits/b01/q10/clean_history.py,sha256=OsuzliXtWl2RDMAdKElCaebp9Pr2czVOex180k4jzVs,6672
@@ -60,12 +60,13 @@ roborock/devices/traits/b01/q10/common.py,sha256=Qxl3zBAUulqdrjFZJ0DPEFEIJLvlPqU
 roborock/devices/traits/b01/q10/consumable.py,sha256=MbtMgYKqzNdVn6M1iyOAqZPCYTbN_Q_Pr4h8EYGEiuY,669
 roborock/devices/traits/b01/q10/do_not_disturb.py,sha256=klyGQZ_nHyO6bhPlwBl8vElTnMwPf4A8VXwxkU8rMlM,1157
 roborock/devices/traits/b01/q10/dust_collection.py,sha256=LM-0YH4pMrEqLUCFP2g-DymhL5ZUQ4bHd-2EyKHmucY,1582
-roborock/devices/traits/b01/q10/map.py,sha256=xWODSaUo4LHOhmF89WLPHvxpLgBzlTt6pPmOVCP2Oyc,7276
+roborock/devices/traits/b01/q10/goto.py,sha256=ipSY08ZTwRr-2vKgzyE2eV1YrY2QRpYKDVych9lu_Sk,5690
+roborock/devices/traits/b01/q10/map.py,sha256=qy-V-sJ5bvAhjCpKZqBPU0NcOc9ZGqBudDvo4l-HA4o,7692
 roborock/devices/traits/b01/q10/maps.py,sha256=qWk1K47aIf3iJead3A2zQ3Lo0wZ1wcS2mo4qVfiiTDw,2101
 roborock/devices/traits/b01/q10/network_info.py,sha256=XiCr6YPu7xkvhgeaGwXli-_4SB88QW63ykiegyaau2k,656
 roborock/devices/traits/b01/q10/remote.py,sha256=8-fg4SA5M-tdMufHPeD9hIcax7y9Qh7pzcE7rBBVW_o,1267
 roborock/devices/traits/b01/q10/status.py,sha256=JAPixbsQ8jfN3OvI7o_NxISXFk8l7rGHFYcL4pH97Jk,859
-roborock/devices/traits/b01/q10/vacuum.py,sha256=w2FftNH5n-Tb-9drR3-5OiMy85FJfTDNmtt34LklC8w,4374
+roborock/devices/traits/b01/q10/vacuum.py,sha256=uVw11UgumzqEqqAUCe8LybFX810pqSIMloFiaoRsXAw,11651
 roborock/devices/traits/b01/q10/volume.py,sha256=UnT0yYDQntxYwnpv4_NVychm0FnGAYRAWA_FJR4yJag,1001
 roborock/devices/traits/b01/q7/__init__.py,sha256=tbsZSe2VojCN7uRdHPm74on8WrexJePzQ2ewTLcFjWo,9124
 roborock/devices/traits/b01/q7/clean_summary.py,sha256=M43iJVeYjrkBV6ZxXdHtn4Rd5Mx-KAK7WLU5fABiN8I,2742
@@ -101,7 +102,7 @@ roborock/devices/transport/mqtt_channel.py,sha256=dpL1mZIoI4Glk3hfUO9JweWFHG1tZW
 roborock/map/__init__.py,sha256=L3WHujuxUHCTTPaOElkJsTN_FkYhw01drfR-W4blgFc,146
 roborock/map/b01_grid_layers.py,sha256=b87MsGXslqLR_5H_4z4aj1wQqYgeTuULWqt4_txOF-M,12303
 roborock/map/b01_map_parser.py,sha256=y4Qlgiwre3bn5_UpL6R-ytjg8kQqwkbvhIYFOtpAM3s,14814
-roborock/map/b01_q10_map_parser.py,sha256=Pt-goedXV60hg-mwHOgOF0f4TQBQmQXe6otpWaa99ps,29996
+roborock/map/b01_q10_map_parser.py,sha256=i0jjQDb7pjlee3QCa1HlLKAv2t9_BtA-OYQUFT2g6RI,30262
 roborock/map/b01_q10_overlays.py,sha256=JmriUbT4-oe6NiE94VttMplFc1HHQrAGNQIiZHj5QKk,6640
 roborock/map/b01_q10_render.py,sha256=b7YUBr53WXxOJhXbfb5IVmgi82iGcC0lJ_j9Ef3kV7M,13502
 roborock/map/map_parser.py,sha256=EcJcz9yld_wu7d5QrmxR2BTfJ801F6SaEgJkbIIap4w,5111
@@ -115,7 +116,7 @@ roborock/mqtt/roborock_session.py,sha256=ir7HXs4gtoineiwlc6ixyAueBTCSPtNU8zPGgY9
 roborock/mqtt/session.py,sha256=eVW1o6PziXaRyNXviPgC_kIVuqhPSrloAWuP2RYj-uo,4096
 roborock/protocols/__init__.py,sha256=1ems3I1_KUQoMf2Hf6ZYDKFhu5Gnsc0PbfD-dkQJ7vA,82
 roborock/protocols/a01_protocol.py,sha256=nyUAn39CXH0xLqcRcr7JiORt2zFNgxP4F4ClVc3dvB4,2501
-roborock/protocols/b01_q10_protocol.py,sha256=Ac3_VHJ2DAwBiXFMPYOHExEV0prxS9Ju0djiC8nKtiI,4935
+roborock/protocols/b01_q10_protocol.py,sha256=FTki6nPGscelhq7HLvylmJZMqs-o9g_gbOEDVePb5OU,6971
 roborock/protocols/b01_q7_protocol.py,sha256=2dk6nbDOhb0O-Q_UPKeZHjzdazbS-MA3PIqpXvqRqoo,4657
 roborock/protocols/v1_protocol.py,sha256=ntFQoGn1IF7v_BwjiGow478SJHBSKr6jq6M2s01OdaI,12918
 roborock/testing/__init__.py,sha256=rji4a-JBIWC_I6SUTG9j4r2bGxfhYUoopdDAzYQ1tmA,5086
@@ -125,8 +126,8 @@ roborock/testing/channel.py,sha256=vjulT5MHBe8lAq6XITUqcxJVcCILWx7ZEcw5imTx0Tk,7
 roborock/testing/cloud.py,sha256=L2L0KlZDYaMuoV19KUQUoq5EAUDeNQ1lJ8Ew5YaOgjo,11946
 roborock/testing/simulator.py,sha256=g8ZUWVSjgAzuRRxWOCeOq-7deodyEItwUpqEw9RzCmQ,4347
 roborock/testing/v1_simulator.py,sha256=_LX_vsBMcB2Uu2QDt8QnQymgtVtbnwD5Xa7tmhiPAnY,14439
-python_roborock-7.6.0.dist-info/METADATA,sha256=K-sGLp5G2PZElinVEK18ggGArG4cdD7GKeYfTJFJsLQ,5278
-python_roborock-7.6.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-python_roborock-7.6.0.dist-info/entry_points.txt,sha256=EvC1nMqi9ZXKgZnqlNXA33v_3nzgPNjnM0mzWlrehnY,47
-python_roborock-7.6.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-python_roborock-7.6.0.dist-info/RECORD,,
+python_roborock-7.7.0.dist-info/METADATA,sha256=LuQWXmlZKWOMRGdAQWOrZqMm2Q9_5d3KtoxyN24BeaY,5278
+python_roborock-7.7.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+python_roborock-7.7.0.dist-info/entry_points.txt,sha256=EvC1nMqi9ZXKgZnqlNXA33v_3nzgPNjnM0mzWlrehnY,47
+python_roborock-7.7.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+python_roborock-7.7.0.dist-info/RECORD,,

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):

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:

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)

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:

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

@@ -1,13 +1,31 @@
 """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:
@@ -17,9 +35,100 @@ class VacuumTrait:
     commands to Q10 devices.
     """
 
-    def __init__(self, command: CommandTrait) -> None:
+    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.
@@ -34,6 +143,7 @@ class VacuumTrait:
         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.
@@ -55,6 +165,73 @@ class VacuumTrait:
             # "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.
@@ -62,18 +239,22 @@ class VacuumTrait:
         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.
@@ -84,6 +265,7 @@ class VacuumTrait:
         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.

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:

roborock/protocols/b01_q10_protocol.py

@@ -2,10 +2,13 @@
 
 import json
 import logging
+from base64 import b64encode
 from dataclasses import dataclass
+from struct import pack
 from typing import Any
 
 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 (
     Q10MapPacket,
@@ -24,6 +27,51 @@ _LOGGER = logging.getLogger(__name__)
 
 B01_VERSION = b"B01"
 ParamsType = list | dict | int | None
+_Q10_ZONE_NAME_FIELD_LENGTH = 19
+
+
+@dataclass(frozen=True)
+class CleanParams:
+    """Parameters for one rectangular Q10 zone-clean task."""
+
+    first_corner: Q10RoborockPoint
+    second_corner: Q10RoborockPoint
+    clean_count: int = 1
+
+    @property
+    def points(self) -> tuple[Q10RoborockPoint, ...]:
+        """Return rectangle vertices sorted into canonical wire order."""
+        min_x, max_x = sorted((self.first_corner.x, self.second_corner.x))
+        min_y, max_y = sorted((self.first_corner.y, self.second_corner.y))
+        return (
+            Q10RoborockPoint(min_x, min_y),
+            Q10RoborockPoint(max_x, min_y),
+            Q10RoborockPoint(max_x, max_y),
+            Q10RoborockPoint(min_x, max_y),
+        )
+
+
+def encode_clean_params(params: CleanParams) -> str:
+    """Encode Q10 zone-clean parameters for ``dpStartClean`` task type 3."""
+    if not isinstance(params, CleanParams):
+        raise ValueError("params must be CleanParams")
+    if not isinstance(params.first_corner, Q10RoborockPoint) or not isinstance(params.second_corner, Q10RoborockPoint):
+        raise ValueError("zone corners must be Q10RoborockPoint values")
+    if isinstance(params.clean_count, bool) or not 1 <= params.clean_count <= 3:
+        raise ValueError("clean_count must be between 1 and 3")
+    if params.first_corner.x == params.second_corner.x or params.first_corner.y == params.second_corner.y:
+        raise ValueError("zone corners must enclose an area")
+
+    points = params.points
+    payload = bytearray((1, params.clean_count, 1, len(points)))
+    for point in points:
+        payload.extend(pack(">hh", *point.to_vector()))
+
+    # The app protocol reserves a fixed 19-byte UTF-8 name field per zone. An
+    # unnamed zone is encoded as a zero length followed by zero padding.
+    payload.append(0)
+    payload.extend(bytes(_Q10_ZONE_NAME_FIELD_LENGTH))
+    return b64encode(payload).decode()
 
 
 def encode_mqtt_payload(command: B01_Q10_DP, params: ParamsType) -> RoborockMessage: