python-roborock 5.34.0__tar.gz → 5.36.0__tar.gz

{python_roborock-5.34.0 → python_roborock-5.36.0}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "5.34.0"
+version = "5.36.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.34.0 → python_roborock-5.36.0}/roborock/devices/rpc/a01_channel.py

@@ -7,6 +7,7 @@ from typing import Any, overload
 
 from roborock.devices.transport.mqtt_channel import MqttChannel
 from roborock.exceptions import RoborockException
+from roborock.mqtt.session import MqttQos
 from roborock.protocols.a01_protocol import (
     decode_rpc_response,
     encode_mqtt_payload,
@@ -30,6 +31,7 @@ async def send_decoded_command(
     mqtt_channel: MqttChannel,
     params: dict[RoborockDyadDataProtocol, Any],
     value_encoder: Callable[[Any], Any] | None = None,
+    qos: MqttQos = MqttQos.AT_MOST_ONCE,
 ) -> dict[RoborockDyadDataProtocol, Any]: ...
 
 
@@ -38,6 +40,7 @@ async def send_decoded_command(
     mqtt_channel: MqttChannel,
     params: dict[RoborockZeoProtocol, Any],
     value_encoder: Callable[[Any], Any] | None = None,
+    qos: MqttQos = MqttQos.AT_MOST_ONCE,
 ) -> dict[RoborockZeoProtocol, Any]: ...
 
 
@@ -45,8 +48,16 @@ async def send_decoded_command(
     mqtt_channel: MqttChannel,
     params: dict[RoborockDyadDataProtocol, Any] | dict[RoborockZeoProtocol, Any],
     value_encoder: Callable[[Any], Any] | None = None,
+    qos: MqttQos = MqttQos.AT_MOST_ONCE,
 ) -> dict[RoborockDyadDataProtocol, Any] | dict[RoborockZeoProtocol, Any]:
-    """Send a command on the MQTT channel and get a decoded response."""
+    """Send a command on the MQTT channel and get a decoded response.
+
+    Args:
+        mqtt_channel: The MQTT channel to send the command on.
+        params: The parameters to send.
+        value_encoder: A function to encode the values of the dictionary.
+        qos: The MQTT QoS level. Defaults to AT_MOST_ONCE.
+    """
     _LOGGER.debug("Sending MQTT command: %s", params)
     roborock_message = encode_mqtt_payload(params, value_encoder)
 
@@ -54,7 +65,7 @@ async def send_decoded_command(
     # block waiting for a response. Queries are handled below.
     param_values = {int(k): v for k, v in params.items()}
     if not (query_values := param_values.get(_ID_QUERY)):
-        await mqtt_channel.publish(roborock_message)
+        await mqtt_channel.publish(roborock_message, qos=qos)
         return {}
 
     # Merge any results together than contain the requested data. This

{python_roborock-5.34.0 → python_roborock-5.36.0}/roborock/devices/traits/b01/q10/__init__.py

@@ -16,7 +16,7 @@ from .command import CommandTrait
 from .consumable import ConsumableTrait
 from .do_not_disturb import DoNotDisturbTrait
 from .dust_collection import DustCollectionTrait
-from .map import MapContentTrait
+from .map import MapContentTrait, MapDpsTrait
 from .network_info import NetworkInfoTrait
 from .remote import RemoteTrait
 from .status import StatusTrait
@@ -77,7 +77,10 @@ class Q10PropertiesApi(Trait):
     """Trait exposing remaining life of consumables."""
 
     map: MapContentTrait
-    """Trait for fetching the current parsed map (image + rooms)."""
+    """Composed map image plus caller-facing map and trace data."""
+
+    _map_dps: MapDpsTrait
+    """Private source of restricted zones and virtual walls received through DPS."""
 
     clean_history: CleanHistoryTrait
     """Trait for fetching the device clean-record history (``dpCleanRecord``)."""
@@ -96,7 +99,8 @@ class Q10PropertiesApi(Trait):
         self.button_light = ButtonLightTrait(self.command)
         self.network_info = NetworkInfoTrait()
         self.consumable = ConsumableTrait()
-        self.map = MapContentTrait()
+        self._map_dps = MapDpsTrait()
+        self.map = MapContentTrait(self._map_dps)
         self.clean_history = CleanHistoryTrait(self.command)
         # Read-model traits updated from the device's DPS push stream.
         self._updatable_traits = [
@@ -108,6 +112,7 @@ class Q10PropertiesApi(Trait):
             self.network_info,
             self.consumable,
             self.clean_history,
+            self._map_dps,
         ]
         self._subscribe_task: asyncio.Task[None] | None = None
 

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

@@ -0,0 +1,151 @@
+"""Push-driven map traits for B01 Q10 devices.
+
+Map-related state arrives on three independent streams:
+
+* map packets are decoded from map-protocol responses;
+* trace packets are decoded from trace-protocol responses;
+* restricted zones and virtual walls arrive as ordinary DPS values.
+
+``MapDpsTrait`` owns the low-level DPS read model. ``MapContentTrait`` depends
+on it and combines that state with the latest map/trace packets through the pure
+functions in :mod:`roborock.map.b01_q10_render`. The high-level trait keeps only
+the latest value from each source and one replace-whole rendered image;
+calibration, path placement and overlay placement remain inside the renderer.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+from roborock.data import RoborockBase
+from roborock.data.b01_q10.b01_q10_code_mappings import B01_Q10_DP
+from roborock.devices.traits.common import DpsDataConverter, TraitUpdateListener
+from roborock.exceptions import RoborockException
+from roborock.map.b01_q10_map_parser import (
+    B01Q10MapParserConfig,
+    Q10MapPacket,
+    Q10Point,
+    Q10Room,
+    Q10TracePacket,
+)
+from roborock.map.b01_q10_overlays import parse_virtual_wall_blob, parse_zone_blob
+from roborock.map.b01_q10_render import Q10MapOverlays, render_q10_map
+
+from .common import UpdatableTrait
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class MapDps(RoborockBase):
+    """Low-level map values delivered in the Q10 DPS stream."""
+
+    restricted_zone_up: str | None = field(default=None, metadata={"dps": B01_Q10_DP.RESTRICTED_ZONE_UP})
+    virtual_wall_up: str | None = field(default=None, metadata={"dps": B01_Q10_DP.VIRTUAL_WALL_UP})
+
+
+class MapDpsTrait(MapDps, UpdatableTrait):
+    """Private read model for map-related DPS values and decoded overlays."""
+
+    _CONVERTER = DpsDataConverter.from_dataclass(MapDps)
+
+    def __init__(self) -> None:
+        MapDps.__init__(self)
+        UpdatableTrait.__init__(self, command=None, logger=_LOGGER)
+        self._overlays = Q10MapOverlays()
+
+    @property
+    def overlays(self) -> Q10MapOverlays:
+        """Overlays decoded once from the latest relevant DPS update."""
+        return self._overlays
+
+    def update_from_dps(self, decoded_dps: dict[B01_Q10_DP, Any]) -> None:
+        """Decode overlay blobs when they arrive, then notify dependents."""
+        if not self._CONVERTER.update_from_dps(self, decoded_dps):
+            return
+        self._overlays = Q10MapOverlays(
+            zones=tuple(parse_zone_blob(self.restricted_zone_up)),
+            virtual_walls=tuple(parse_virtual_wall_blob(self.virtual_wall_up)),
+        )
+        self._notify_update()
+
+
+class MapContentTrait(TraitUpdateListener):
+    """High-level composed Q10 map view.
+
+    The latest map and trace packets are combined with the injected
+    :class:`MapDpsTrait` whenever any of those three sources changes.
+    """
+
+    def __init__(
+        self,
+        map_dps: MapDpsTrait,
+        *,
+        map_parser_config: B01Q10MapParserConfig | None = None,
+    ) -> None:
+        TraitUpdateListener.__init__(self, logger=_LOGGER)
+        self._config = map_parser_config or B01Q10MapParserConfig()
+        self._map_dps = map_dps
+        self._map_packet: Q10MapPacket | None = None
+        self._trace_packet: Q10TracePacket | None = None
+        self._image_content: bytes | None = None
+        self._map_dps.add_update_listener(self._map_dps_updated)
+
+    @property
+    def image_content(self) -> bytes | None:
+        """The composed map PNG, if the latest map rendered successfully."""
+        return self._image_content
+
+    @property
+    def rooms(self) -> list[Q10Room]:
+        """Rooms reported by the device."""
+        return self._map_packet.rooms if self._map_packet else []
+
+    @property
+    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 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
+
+    @property
+    def robot_heading(self) -> int | None:
+        """Current heading for orienting a robot marker on a caller-rendered map."""
+        return self._trace_packet.heading if self._trace_packet else None
+
+    def update_from_map_packet(self, packet: Q10MapPacket) -> None:
+        """Store a map-protocol update and render the latest sources."""
+        self._map_packet = packet
+        self._render()
+        self._notify_update()
+
+    def update_from_trace_packet(self, packet: Q10TracePacket) -> None:
+        """Store a trace-protocol update and render the latest sources."""
+        self._trace_packet = packet
+        self._render()
+        self._notify_update()
+
+    def _map_dps_updated(self) -> None:
+        """Render after the low-level DPS source changes."""
+        if self._map_packet is None:
+            return
+        self._render()
+        self._notify_update()
+
+    def _render(self) -> None:
+        """Render the required map with the latest optional trace and overlays."""
+        if self._map_packet is None:
+            return
+        try:
+            self._image_content = render_q10_map(
+                self._map_packet,
+                self._trace_packet,
+                self._map_dps.overlays,
+                config=self._config,
+            )
+        except RoborockException as ex:
+            _LOGGER.debug("Failed to render Q10 map packet: %s", ex)
+            self._image_content = None

{python_roborock-5.34.0 → python_roborock-5.36.0}/roborock/devices/transport/mqtt_channel.py

@@ -8,7 +8,7 @@ from roborock.callbacks import decoder_callback
 from roborock.data import HomeDataDevice, RRiot, UserData
 from roborock.exceptions import RoborockException
 from roborock.mqtt.health_manager import HealthManager
-from roborock.mqtt.session import MqttParams, MqttSession, MqttSessionException
+from roborock.mqtt.session import MqttParams, MqttQos, MqttSession, MqttSessionException
 from roborock.protocol import create_mqtt_decoder, create_mqtt_encoder
 from roborock.roborock_message import RoborockMessage
 from roborock.util import RoborockLoggerAdapter
@@ -89,11 +89,15 @@ class MqttChannel(Channel):
         finally:
             unsub()
 
-    async def publish(self, message: RoborockMessage) -> None:
+    async def publish(self, message: RoborockMessage, qos: MqttQos = MqttQos.AT_MOST_ONCE) -> None:
         """Publish a command message.
 
         The caller is responsible for handling any responses and associating them
         with the incoming request.
+
+        Args:
+            message: The message to publish.
+            qos: The MQTT QoS level. Defaults to AT_MOST_ONCE.
         """
         try:
             encoded_msg = self._encoder(message)
@@ -101,7 +105,7 @@ class MqttChannel(Channel):
             self._logger.exception("Error encoding MQTT message: %s", e)
             raise RoborockException(f"Failed to encode MQTT message: {e}") from e
         try:
-            return await self._mqtt_session.publish(self._publish_topic, encoded_msg)
+            return await self._mqtt_session.publish(self._publish_topic, encoded_msg, qos=qos)
         except MqttSessionException as e:
             self._logger.debug("Error publishing MQTT message: %s", e)
             raise RoborockException(f"Failed to publish MQTT message: {e}") from e

{python_roborock-5.34.0 → python_roborock-5.36.0}/roborock/mqtt/roborock_session.py

@@ -22,7 +22,7 @@ from roborock.callbacks import CallbackMap
 from roborock.diagnostics import Diagnostics, redact_topic_name
 
 from .health_manager import HealthManager
-from .session import MqttParams, MqttSession, MqttSessionException, MqttSessionUnauthorized
+from .session import MqttParams, MqttQos, MqttSession, MqttSessionException, MqttSessionUnauthorized
 
 _LOGGER = logging.getLogger(__name__)
 _MQTT_LOGGER = logging.getLogger(f"{__name__}.aiomqtt")
@@ -361,8 +361,14 @@ class RoborockMqttSession(MqttSession):
 
         return delayed_unsub
 
-    async def publish(self, topic: str, message: bytes) -> None:
-        """Publish a message on the topic."""
+    async def publish(self, topic: str, message: bytes, qos: MqttQos = MqttQos.AT_MOST_ONCE) -> None:
+        """Publish a message on the topic.
+
+        Args:
+            topic: The MQTT topic to publish to.
+            message: The message payload.
+            qos: The MQTT QoS level. Defaults to AT_MOST_ONCE.
+        """
         _LOGGER.debug("Sending message to topic %s: %s", topic, message)
         client: aiomqtt.Client
         async with self._client_lock:
@@ -371,7 +377,7 @@ class RoborockMqttSession(MqttSession):
             client = self._client
         try:
             with self._diagnostics.timer("publish"):
-                await client.publish(topic, message)
+                await client.publish(topic, message, qos=qos)
         except MqttError as err:
             raise MqttSessionException(f"Error publishing message: {err}") from err
 
@@ -417,13 +423,13 @@ class LazyMqttSession(MqttSession):
         await self._maybe_start()
         return await self._session.subscribe(device_id, callback)
 
-    async def publish(self, topic: str, message: bytes) -> None:
+    async def publish(self, topic: str, message: bytes, qos: MqttQos = MqttQos.AT_MOST_ONCE) -> None:
         """Publish a message on the specified topic.
 
         This will raise an exception if the message could not be sent.
         """
         await self._maybe_start()
-        return await self._session.publish(topic, message)
+        return await self._session.publish(topic, message, qos=qos)
 
     async def close(self) -> None:
         """Cancels the mqtt loop.

{python_roborock-5.34.0 → python_roborock-5.36.0}/roborock/mqtt/session.py

@@ -3,6 +3,7 @@
 from abc import ABC, abstractmethod
 from collections.abc import Callable
 from dataclasses import dataclass, field
+from enum import IntEnum
 
 from roborock.diagnostics import Diagnostics
 from roborock.exceptions import RoborockException
@@ -10,6 +11,24 @@ from roborock.mqtt.health_manager import HealthManager
 
 DEFAULT_TIMEOUT = 30.0
 
+
+class MqttQos(IntEnum):
+    """MQTT Quality of Service levels.
+
+    A01 devices (Zeo, Dyad) require ``AT_LEAST_ONCE`` for DP200 (start)
+    commands. Other protocol versions use ``AT_MOST_ONCE``.
+    """
+
+    AT_MOST_ONCE = 0
+    """Fire-and-forget. No acknowledgment required."""
+
+    AT_LEAST_ONCE = 1
+    """Guaranteed delivery with possible duplicates. Broker sends PUBACK."""
+
+    EXACTLY_ONCE = 2
+    """Guaranteed delivery with no duplicates. Broker sends PUBREC/PUBREL/PUBCOMP."""
+
+
 SessionUnauthorizedHook = Callable[[], None]
 
 
@@ -76,10 +95,15 @@ class MqttSession(ABC):
         """
 
     @abstractmethod
-    async def publish(self, topic: str, message: bytes) -> None:
+    async def publish(self, topic: str, message: bytes, qos: MqttQos = MqttQos.AT_MOST_ONCE) -> None:
         """Publish a message on the specified topic.
 
         This will raise an exception if the message could not be sent.
+
+        Args:
+            topic: The MQTT topic to publish to.
+            message: The message payload.
+            qos: The MQTT QoS level. Defaults to AT_MOST_ONCE.
         """
 
     @abstractmethod

{python_roborock-5.34.0 → python_roborock-5.36.0}/roborock/protocols/a01_protocol.py

@@ -2,6 +2,7 @@
 
 import json
 import logging
+import time
 from collections.abc import Callable
 from typing import Any
 
@@ -42,7 +43,10 @@ def encode_mqtt_payload(
     """
     if value_encoder is None:
         value_encoder = _no_encode
-    dps_data = {"dps": {key: value_encoder(value) for key, value in data.items()}}
+    dps_data = {
+        "dps": {key: value_encoder(value) for key, value in data.items()},
+        "t": int(time.time()),
+    }
     payload = pad(json.dumps(dps_data).encode("utf-8"), AES.block_size)
     return RoborockMessage(
         protocol=RoborockMessageProtocol.RPC_REQUEST,

{python_roborock-5.34.0 → python_roborock-5.36.0}/roborock/testing/channel.py

@@ -12,6 +12,7 @@ from unittest.mock import AsyncMock, MagicMock
 
 from roborock.devices.transport.channel import Channel
 from roborock.mqtt.health_manager import HealthManager
+from roborock.mqtt.session import MqttQos
 from roborock.protocols.v1_protocol import LocalProtocolVersion
 from roborock.roborock_message import RoborockMessage
 
@@ -83,6 +84,7 @@ class FakeChannel(Channel):
         self.close = MagicMock(side_effect=self._close)
 
         self.protocol_version = LocalProtocolVersion.V1
+
         self.restart = AsyncMock()
         self.health_manager = HealthManager(self.restart)
 
@@ -102,10 +104,13 @@ class FakeChannel(Channel):
         """Return true if locally connected."""
         return self._is_connected and self._is_local
 
-    async def _publish(self, message: RoborockMessage) -> None:
+    async def _publish(self, message: RoborockMessage, qos: MqttQos = MqttQos.AT_MOST_ONCE) -> None:
         """Default publish implementation.
 
         Records the message in ``published_messages`` and executes ``publish_handler``.
+
+        The ``qos`` parameter is accepted for compatibility with
+        ``MqttChannel.publish`` but not simulated by the fake channel.
         """
         self.published_messages.append(message)
         if self.publish_side_effect:

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

@@ -1,110 +0,0 @@
-"""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()