python-roborock 5.0.0__tar.gz → 5.2.0__tar.gz

{python_roborock-5.0.0 → python_roborock-5.2.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: python-roborock
-Version: 5.0.0
+Version: 5.2.0
 Summary: A package to control Roborock vacuums.
-Project-URL: Repository, https://github.com/humbertogontijo/python-roborock
+Project-URL: Repository, https://github.com/python-roborock/python-roborock
 Project-URL: Documentation, https://python-roborock.readthedocs.io/
 Author: Lash-L, allenporter
 Author-email: humbertogontijo <humbertogontijo@users.noreply.github.com>
@@ -21,6 +21,7 @@ Requires-Dist: click-shell~=2.1
 Requires-Dist: click>=8
 Requires-Dist: construct<3,>=2.10.57
 Requires-Dist: paho-mqtt<3.0.0,>=1.6.1
+Requires-Dist: protobuf<7,>=5
 Requires-Dist: pycryptodomex~=3.18; sys_platform == 'darwin'
 Requires-Dist: pycryptodome~=3.18
 Requires-Dist: pyrate-limiter<5,>=4.0.0

{python_roborock-5.0.0 → python_roborock-5.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "5.0.0"
+version = "5.2.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"
@@ -25,6 +25,7 @@ dependencies = [
     "pycryptodomex~=3.18 ; sys_platform == 'darwin'",
     "paho-mqtt>=1.6.1,<3.0.0",
     "construct>=2.10.57,<3",
+    "protobuf>=5,<7",
     "vacuum-map-parser-roborock",
     "pyrate-limiter>=4.0.0,<5",
     "aiomqtt>=2.5.0,<3",
@@ -32,7 +33,7 @@ dependencies = [
 ]
 
 [project.urls]
-Repository = "https://github.com/humbertogontijo/python-roborock"
+Repository = "https://github.com/python-roborock/python-roborock"
 Documentation = "https://python-roborock.readthedocs.io/"
 
 [project.scripts]
@@ -97,9 +98,15 @@ major_tags= ["refactor"]
 lint.ignore = ["F403", "E741"]
 lint.select=["E", "F", "UP", "I"]
 line-length = 120
+extend-exclude = ["roborock/map/proto/*_pb2.py"]
 
 [tool.ruff.lint.per-file-ignores]
 "*/__init__.py" = ["F401"]
+"roborock/map/proto/*_pb2.py" = ["E501", "I001", "UP009"]
+
+[[tool.mypy.overrides]]
+module = ["roborock.map.proto.*"]
+ignore_errors = true
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/broadcast_protocol.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 import asyncio
 import hashlib
 import json

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/data/code_mappings.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 import logging
 from collections import namedtuple
 from enum import Enum, IntEnum, StrEnum
@@ -17,7 +15,7 @@ class RoborockEnum(IntEnum):
         return super().name.lower()
 
     @classmethod
-    def _missing_(cls: type[RoborockEnum], key) -> RoborockEnum:
+    def _missing_(cls: type[Self], key) -> Self:
         if hasattr(cls, "unknown"):
             warning = f"Missing {cls.__name__} code: {key} - defaulting to 'unknown'"
             if warning not in completed_warnings:
@@ -32,23 +30,23 @@ class RoborockEnum(IntEnum):
         return default_value
 
     @classmethod
-    def as_dict(cls: type[RoborockEnum]):
+    def as_dict(cls: type[Self]):
         return {i.name: i.value for i in cls if i.name != "missing"}
 
     @classmethod
-    def as_enum_dict(cls: type[RoborockEnum]):
+    def as_enum_dict(cls: type[Self]):
         return {i.value: i for i in cls if i.name != "missing"}
 
     @classmethod
-    def values(cls: type[RoborockEnum]) -> list[int]:
+    def values(cls: type[Self]) -> list[int]:
         return list(cls.as_dict().values())
 
     @classmethod
-    def keys(cls: type[RoborockEnum]) -> list[str]:
+    def keys(cls: type[Self]) -> list[str]:
         return list(cls.as_dict().keys())
 
     @classmethod
-    def items(cls: type[RoborockEnum]):
+    def items(cls: type[Self]):
         return cls.as_dict().items()
 
 

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/data/v1/v1_code_mappings.py

@@ -1,3 +1,5 @@
+from typing import Self
+
 from ..code_mappings import RoborockEnum
 
 
@@ -91,7 +93,7 @@ class RoborockStartType(RoborockEnum):
 
 class RoborockDssCodes(RoborockEnum):
     @classmethod
-    def _missing_(cls: type[RoborockEnum], key) -> RoborockEnum:
+    def _missing_(cls: type[Self], key) -> Self:
         # If the calculated value is not provided, then it should be viewed as okay.
         # As the math will sometimes result in you getting numbers that don't matter.
         return cls.okay  # type: ignore

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/device_features.py

@@ -1,8 +1,6 @@
-from __future__ import annotations
-
 from dataclasses import dataclass, field, fields
 from enum import IntEnum, StrEnum
-from typing import Any
+from typing import Any, Self
 
 from roborock.data.code_mappings import RoborockProductNickname
 from roborock.data.containers import RoborockBase
@@ -566,7 +564,7 @@ class DeviceFeatures(RoborockBase):
         new_feature_info_str: str,
         feature_info: list[int],
         product_nickname: RoborockProductNickname | None,
-    ) -> DeviceFeatures:
+    ) -> Self:
         """Creates a DeviceFeatures instance from raw feature flags.
         :param new_feature_info: A int from get_init_status (sometimes can be found in homedata, but it is not always)
         :param new_feature_info_str: A hex string from get_init_status or home_data.

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/devices/device_manager.py

@@ -251,7 +251,7 @@ async def create_device_manager(
                     trait = b01.q10.create(channel)
                 elif "sc" in model_part:
                     # Q7 devices start with 'sc' in their model naming.
-                    trait = b01.q7.create(channel)
+                    trait = b01.q7.create(product, device, channel)
                 else:
                     raise UnsupportedDeviceError(f"Device {device.name} has unsupported B01 model: {product.model}")
             case _:

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/devices/rpc/b01_q10_channel.py

@@ -1,7 +1,5 @@
 """Thin wrapper around the MQTT channel for Roborock B01 Q10 devices."""
 
-from __future__ import annotations
-
 import logging
 from collections.abc import AsyncGenerator
 from typing import Any

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/devices/rpc/b01_q7_channel.py

@@ -6,16 +6,24 @@ import asyncio
 import json
 import logging
 from collections.abc import Callable
-from typing import Any, TypeVar
+from typing import TypeAlias, TypeVar
 
 from roborock.devices.transport.mqtt_channel import MqttChannel
 from roborock.exceptions import RoborockException
-from roborock.protocols.b01_q7_protocol import B01_VERSION, Q7RequestMessage, decode_rpc_response, encode_mqtt_payload
+from roborock.protocols.b01_q7_protocol import (
+    B01_VERSION,
+    MapKey,
+    Q7RequestMessage,
+    decode_map_payload,
+    decode_rpc_response,
+    encode_mqtt_payload,
+)
 from roborock.roborock_message import RoborockMessage, RoborockMessageProtocol
 
 _LOGGER = logging.getLogger(__name__)
 _TIMEOUT = 10.0
 _T = TypeVar("_T")
+DecodedB01Response: TypeAlias = dict[str, object] | str
 
 
 def _matches_map_response(response_message: RoborockMessage, *, version: bytes | None) -> bytes | None:
@@ -61,11 +69,11 @@ async def _send_command(
 async def send_decoded_command(
     mqtt_channel: MqttChannel,
     request_message: Q7RequestMessage,
-) -> Any:
+) -> DecodedB01Response:
     """Send a command on the MQTT channel and get a decoded response."""
     _LOGGER.debug("Sending B01 MQTT command: %s", request_message)
 
-    def find_response(response_message: RoborockMessage) -> Any | None:
+    def find_response(response_message: RoborockMessage) -> DecodedB01Response | None:
         """Handle incoming messages and resolve the future."""
         try:
             decoded_dps = decode_rpc_response(response_message)
@@ -126,18 +134,32 @@ async def send_decoded_command(
         raise
 
 
-async def send_map_command(mqtt_channel: MqttChannel, request_message: Q7RequestMessage) -> bytes:
-    """Send map upload command and wait for MAP_RESPONSE payload bytes.
+class MapRpcChannel:
+    """RPC channel for map-related commands on B01/Q7 devices."""
 
-    This stays separate from ``send_decoded_command()`` because map uploads arrive as
-    raw ``MAP_RESPONSE`` payload bytes instead of a decoded RPC ``data`` payload.
-    """
+    def __init__(self, mqtt_channel: MqttChannel, map_key: MapKey) -> None:
+        self._mqtt_channel = mqtt_channel
+        self._map_key = map_key
 
-    try:
-        return await _send_command(
-            mqtt_channel,
-            request_message,
-            response_matcher=lambda response_message: _matches_map_response(response_message, version=B01_VERSION),
-        )
-    except TimeoutError as ex:
-        raise RoborockException(f"B01 map command timed out after {_TIMEOUT}s ({request_message})") from ex
+    async def send_map_command(self, request_message: Q7RequestMessage) -> bytes:
+        """Send a map upload command and return decoded SCMap bytes.
+
+        This publishes the request and waits for a matching ``MAP_RESPONSE`` message
+        with the correct protocol version. The raw ``MAP_RESPONSE`` payload bytes are
+        then decoded/inflated via :func:`decode_map_payload` using this channel's
+        ``map_key``, and the resulting SCMap bytes are returned.
+
+        The returned value is the decoded map data bytes suitable for passing to the
+        map parser library, not the raw MQTT ``MAP_RESPONSE`` payload bytes.
+        """
+
+        try:
+            raw_payload = await _send_command(
+                self._mqtt_channel,
+                request_message,
+                response_matcher=lambda response_message: _matches_map_response(response_message, version=B01_VERSION),
+            )
+        except TimeoutError as ex:
+            raise RoborockException(f"B01 map command timed out after {_TIMEOUT}s ({request_message})") from ex
+
+        return decode_map_payload(raw_payload, map_key=self._map_key)

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/devices/traits/b01/q7/__init__.py

@@ -1,10 +1,14 @@
 """Traits for Q7 B01 devices.
-Potentially other devices may fall into this category in the future."""
+
+Potentially other devices may fall into this category in the future.
+"""
+
+from __future__ import annotations
 
 from typing import Any
 
 from roborock import B01Props
-from roborock.data import Q7MapList, Q7MapListEntry
+from roborock.data import HomeDataDevice, HomeDataProduct, Q7MapList, Q7MapListEntry
 from roborock.data.b01_q7.b01_q7_code_mappings import (
     CleanPathPreferenceMapping,
     CleanRepeatMapping,
@@ -14,27 +18,30 @@ from roborock.data.b01_q7.b01_q7_code_mappings import (
     SCWindMapping,
     WaterLevelMapping,
 )
-from roborock.devices.rpc.b01_q7_channel import send_decoded_command
+from roborock.devices.rpc.b01_q7_channel import MapRpcChannel, send_decoded_command
 from roborock.devices.traits import Trait
 from roborock.devices.transport.mqtt_channel import MqttChannel
-from roborock.protocols.b01_q7_protocol import B01_Q7_DPS, CommandType, ParamsType, Q7RequestMessage
+from roborock.exceptions import RoborockException
+from roborock.protocols.b01_q7_protocol import B01_Q7_DPS, CommandType, ParamsType, Q7RequestMessage, create_map_key
 from roborock.roborock_message import RoborockB01Props
 from roborock.roborock_typing import RoborockB01Q7Methods
 
 from .clean_summary import CleanSummaryTrait
 from .map import MapTrait
+from .map_content import MapContentTrait
 
 __all__ = [
     "Q7PropertiesApi",
     "CleanSummaryTrait",
     "MapTrait",
+    "MapContentTrait",
     "Q7MapList",
     "Q7MapListEntry",
 ]
 
 
 class Q7PropertiesApi(Trait):
-    """API for interacting with B01 devices."""
+    """API for interacting with B01 Q7 devices."""
 
     clean_summary: CleanSummaryTrait
     """Trait for clean records / clean summary (Q7 `service.get_record_list`)."""
@@ -42,11 +49,27 @@ class Q7PropertiesApi(Trait):
     map: MapTrait
     """Trait for map list metadata + raw map payload retrieval."""
 
-    def __init__(self, channel: MqttChannel) -> None:
-        """Initialize the B01Props API."""
+    map_content: MapContentTrait
+    """Trait for fetching parsed current map content."""
+
+    def __init__(
+        self, channel: MqttChannel, map_rpc_channel: MapRpcChannel, device: HomeDataDevice, product: HomeDataProduct
+    ) -> None:
+        """Initialize the Q7 API."""
         self._channel = channel
+        self._map_rpc_channel = map_rpc_channel
+        self._device = device
+        self._product = product
+
+        if not device.sn or not product.model:
+            raise ValueError("B01 Q7 map content requires device serial number and product model metadata")
+
         self.clean_summary = CleanSummaryTrait(channel)
         self.map = MapTrait(channel)
+        self.map_content = MapContentTrait(
+            self._map_rpc_channel,
+            self.map,
+        )
 
     async def query_values(self, props: list[RoborockB01Props]) -> B01Props | None:
         """Query the device for the values of the given Q7 properties."""
@@ -151,6 +174,11 @@ class Q7PropertiesApi(Trait):
         )
 
 
-def create(channel: MqttChannel) -> Q7PropertiesApi:
-    """Create traits for B01 devices."""
-    return Q7PropertiesApi(channel)
+def create(product: HomeDataProduct, device: HomeDataDevice, channel: MqttChannel) -> Q7PropertiesApi:
+    """Create traits for B01 Q7 devices."""
+    if device.sn is None or product.model is None:
+        raise RoborockException(
+            f"Device serial number and product model are required (sn:: {device.sn}, model: {product.model})"
+        )
+    map_rpc_channel = MapRpcChannel(channel, map_key=create_map_key(serial=device.sn, model=product.model))
+    return Q7PropertiesApi(channel, device=device, product=product, map_rpc_channel=map_rpc_channel)

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/devices/traits/b01/q7/clean_summary.py

@@ -4,8 +4,6 @@ For B01/Q7, the Roborock app uses `service.get_record_list` which returns totals
 and a `record_list` whose items contain a JSON string in `detail`.
 """
 
-from __future__ import annotations
-
 import logging
 
 from roborock import CleanRecordDetail, CleanRecordList, CleanRecordSummary

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/devices/traits/b01/q7/map.py

@@ -1,9 +1,7 @@
 """Map trait for B01 Q7 devices."""
 
-import asyncio
-
 from roborock.data import Q7MapList
-from roborock.devices.rpc.b01_q7_channel import send_decoded_command, send_map_command
+from roborock.devices.rpc.b01_q7_channel import send_decoded_command
 from roborock.devices.traits import Trait
 from roborock.devices.transport.mqtt_channel import MqttChannel
 from roborock.exceptions import RoborockException
@@ -12,14 +10,15 @@ from roborock.roborock_typing import RoborockB01Q7Methods
 
 
 class MapTrait(Q7MapList, Trait):
-    """Map retrieval + map metadata helpers for Q7 devices."""
+    """Map trait for B01/Q7 devices, responsible for fetching and caching map list metadata.
+
+    The MapContent is fetched from the MapContent trait, which relies on this trait to determine the
+    current map ID to fetch.
+    """
 
     def __init__(self, channel: MqttChannel) -> None:
         super().__init__()
         self._channel = channel
-        # Map uploads are serialized per-device to avoid response cross-wiring.
-        self._map_command_lock = asyncio.Lock()
-        self._loaded = False
 
     async def refresh(self) -> None:
         """Refresh cached map list metadata from the device."""
@@ -36,24 +35,3 @@ class MapTrait(Q7MapList, Trait):
             raise RoborockException(f"Failed to decode map list response: {response!r}")
 
         self.map_list = parsed.map_list
-        self._loaded = True
-
-    async def _get_map_payload(self, *, map_id: int) -> bytes:
-        """Fetch raw map payload bytes for the given map id."""
-        request = Q7RequestMessage(
-            dps=B01_Q7_DPS,
-            command=RoborockB01Q7Methods.UPLOAD_BY_MAPID,
-            params={"map_id": map_id},
-        )
-        async with self._map_command_lock:
-            return await send_map_command(self._channel, request)
-
-    async def get_current_map_payload(self) -> bytes:
-        """Fetch raw map payload bytes for the currently selected map."""
-        if not self._loaded:
-            await self.refresh()
-
-        map_id = self.current_map_id
-        if map_id is None:
-            raise RoborockException(f"Unable to determine map_id from map list response: {self!r}")
-        return await self._get_map_payload(map_id=map_id)

python_roborock-5.2.0/roborock/devices/traits/b01/q7/map_content.py

@@ -0,0 +1,100 @@
+"""Trait for fetching parsed map content from B01/Q7 devices.
+
+This intentionally mirrors the v1 `MapContentTrait` contract:
+- `refresh()` performs I/O and populates cached fields
+- `parse_map_content()` reparses cached raw bytes without I/O
+- fields `image_content`, `map_data`, and `raw_api_response` are then readable
+
+For B01/Q7 devices, the underlying raw map payload is retrieved via `MapTrait`.
+"""
+
+import asyncio
+from dataclasses import dataclass
+
+from vacuum_map_parser_base.map_data import MapData
+
+from roborock.data import RoborockBase
+from roborock.devices.rpc.b01_q7_channel import MapRpcChannel
+from roborock.devices.traits import Trait
+from roborock.exceptions import RoborockException
+from roborock.map.b01_map_parser import B01MapParser, B01MapParserConfig
+from roborock.protocols.b01_q7_protocol import B01_Q7_DPS, Q7RequestMessage
+from roborock.roborock_typing import RoborockB01Q7Methods
+
+from .map import MapTrait
+
+_TRUNCATE_LENGTH = 20
+
+
+@dataclass
+class MapContent(RoborockBase):
+    """Dataclass representing map content."""
+
+    image_content: bytes | None = None
+    """The rendered image of the map in PNG format."""
+
+    map_data: MapData | None = None
+    """Parsed map data (metadata for points on the map)."""
+
+    raw_api_response: bytes | None = None
+    """Raw bytes of the map payload from the device.
+
+    This should be treated as an opaque blob used only internally by this
+    library to re-parse the map data when needed.
+    """
+
+    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}, map_data={self.map_data!r})"
+
+
+class MapContentTrait(MapContent, Trait):
+    """Trait for fetching parsed map content for Q7 devices."""
+
+    def __init__(
+        self,
+        map_rpc_channel: MapRpcChannel,
+        map_trait: MapTrait,
+        *,
+        map_parser_config: B01MapParserConfig | None = None,
+    ) -> None:
+        super().__init__()
+        self._map_rpc_channel = map_rpc_channel
+        self._map_trait = map_trait
+        self._map_parser = B01MapParser(map_parser_config)
+        # Map uploads are serialized per-device to avoid response cross-wiring.
+        self._map_command_lock = asyncio.Lock()
+
+    async def refresh(self) -> None:
+        """Fetch, decode, and parse the current map payload.
+
+        This relies on the Map Trait already having fetched the map list metadata
+        so it can determine the current map_id.
+        """
+        # Users must call first
+        if (map_id := self._map_trait.current_map_id) is None:
+            raise RoborockException("Unable to determine current map ID")
+
+        request = Q7RequestMessage(
+            dps=B01_Q7_DPS,
+            command=RoborockB01Q7Methods.UPLOAD_BY_MAPID,
+            params={"map_id": map_id},
+        )
+        async with self._map_command_lock:
+            raw_payload = await self._map_rpc_channel.send_map_command(request)
+
+        try:
+            parsed_data = self._map_parser.parse(raw_payload)
+        except RoborockException:
+            raise
+        except Exception as ex:
+            raise RoborockException("Failed to parse B01 map data") from ex
+
+        if parsed_data.image_content is None:
+            raise RoborockException("Failed to render B01 map image")
+
+        self.image_content = parsed_data.image_content
+        self.map_data = parsed_data.map_data
+        self.raw_api_response = raw_payload

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/devices/traits/v1/network_info.py

@@ -1,7 +1,5 @@
 """Trait for device network information."""
 
-from __future__ import annotations
-
 import logging
 
 from roborock.data import NetworkInfo

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/diagnostics.py

@@ -9,13 +9,11 @@ data is collected and exposed to clients via higher level APIs like the
 DeviceManager.
 """
 
-from __future__ import annotations
-
 import time
 from collections import Counter
 from collections.abc import Generator, Mapping
 from contextlib import contextmanager
-from typing import Any, TypeVar, cast
+from typing import Any, Self, TypeVar, cast
 
 
 class Diagnostics:
@@ -28,7 +26,7 @@ class Diagnostics:
     def __init__(self) -> None:
         """Initialize Diagnostics."""
         self._counter: Counter = Counter()
-        self._subkeys: dict[str, Diagnostics] = {}
+        self._subkeys: dict[str, Self] = {}
 
     def increment(self, key: str, count: int = 1) -> None:
         """Increment a counter for the specified key/event."""
@@ -49,7 +47,7 @@ class Diagnostics:
             data[k] = v
         return data
 
-    def subkey(self, key: str) -> Diagnostics:
+    def subkey(self, key: str) -> Self:
         """Return sub-Diagnostics object with the specified subkey.
 
         This will create a new Diagnostics object if one does not already exist
@@ -63,7 +61,7 @@ class Diagnostics:
             The Diagnostics object for the specified subkey.
         """
         if key not in self._subkeys:
-            self._subkeys[key] = Diagnostics()
+            self._subkeys[key] = type(self)()
         return self._subkeys[key]
 
     @contextmanager

{python_roborock-5.0.0 → python_roborock-5.2.0}/roborock/exceptions.py

@@ -1,7 +1,5 @@
 """Roborock exceptions."""
 
-from __future__ import annotations
-
 
 class RoborockException(Exception):
     """Class for Roborock exceptions."""