python-roborock 4.26.3__tar.gz → 5.1.0__tar.gz

{python_roborock-4.26.3 → python_roborock-5.1.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: python-roborock
-Version: 4.26.3
+Version: 5.1.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-4.26.3 → python_roborock-5.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "4.26.3"
+version = "5.1.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-4.26.3 → python_roborock-5.1.0}/roborock/broadcast_protocol.py

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

{python_roborock-4.26.3 → python_roborock-5.1.0}/roborock/cli.py

@@ -1275,7 +1275,12 @@ async def q10_empty_dustbin(ctx: click.Context, device_id: str) -> None:
 
 @session.command()
 @click.option("--device_id", required=True, help="Device ID")
-@click.option("--mode", required=True, type=click.Choice(["bothwork", "onlysweep", "onlymop"]), help="Clean mode")
+@click.option(
+    "--mode",
+    required=True,
+    type=click.Choice(["vac_and_mop", "vacuum", "mop"], case_sensitive=False),
+    help='Clean mode (preferred: "vac_and_mop", "vacuum", "mop")',
+)
 @click.pass_context
 @async_command
 async def q10_set_clean_mode(ctx: click.Context, device_id: str, mode: str) -> None:

{python_roborock-4.26.3 → python_roborock-5.1.0}/roborock/data/b01_q10/b01_q10_code_mappings.py

@@ -136,9 +136,9 @@ class YXFanLevel(RoborockModeEnum):
 
 class YXWaterLevel(RoborockModeEnum):
     UNKNOWN = "unknown", -1
-    CLOSE = "close", 0
+    OFF = "off", 0  # close
     LOW = "low", 1
-    MIDDLE = "middle", 2
+    MEDIUM = "medium", 2  # middle
     HIGH = "high", 3
 
 
@@ -157,31 +157,31 @@ class YXRoomMaterial(RoborockModeEnum):
 
 class YXCleanType(RoborockModeEnum):
     UNKNOWN = "unknown", -1
-    BOTH_WORK = "bothwork", 1
-    ONLY_SWEEP = "onlysweep", 2
-    ONLY_MOP = "onlymop", 3
+    VAC_AND_MOP = "vac_and_mop", 1  # bothwork
+    VACUUM = "vacuum", 2  # onlysweep
+    MOP = "mop", 3  # onlymop
 
 
 class YXDeviceState(RoborockModeEnum):
     UNKNOWN = "unknown", -1
-    SLEEP_STATE = "sleeping", 2
-    STANDBY_STATE = "standby", 3
-    CLEANING_STATE = "cleaning", 5
-    TO_CHARGE_STATE = "going_to_charge", 6
-    REMOTEING_STATE = "remote_control", 7
-    CHARGING_STATE = "charging", 8
-    PAUSE_STATE = "paused", 10
-    FAULT_STATE = "fault", 12
-    UPGRADE_STATE = "updating", 14
-    DUSTING = "dusting", 22
-    CREATING_MAP_STATE = "creating_map", 29
-    MAP_SAVE_STATE = "saving_map", 99
-    RE_LOCATION_STATE = "relocating", 101
-    ROBOT_SWEEPING = "sweeping", 102
-    ROBOT_MOPING = "mopping", 103
-    ROBOT_SWEEP_AND_MOPING = "sweep_and_mop", 104
-    ROBOT_TRANSITIONING = "transitioning", 105
-    ROBOT_WAIT_CHARGE = "waiting_to_charge", 108
+    SLEEPING = "sleeping", 2  # sleepstate
+    IDLE = "idle", 3  # standbystate
+    CLEANING = "cleaning", 5  # cleaningstate
+    RETURNING_HOME = "returning_home", 6  # tochargestate
+    REMOTE_CONTROL_ACTIVE = "remote_control_active", 7  # remoteingstate
+    CHARGING = "charging", 8  # chargingstate
+    PAUSED = "paused", 10  # pausestate
+    ERROR = "error", 12  # faultstate
+    UPDATING = "updating", 14  # upgradestate
+    EMPTYING_THE_BIN = "emptying_the_bin", 22  # dusting
+    MAPPING = "mapping", 29  # creatingmapstate
+    SAVING_MAP = "saving_map", 99  # mapsavestate
+    RELOCATING = "relocating", 101  # relocationstate
+    SWEEPING = "sweeping", 102  # robotsweeping
+    MOPPING = "mopping", 103  # robotmoping
+    SWEEP_AND_MOP = "sweep_and_mop", 104  # robotsweepandmoping
+    TRANSITIONING = "transitioning", 105  # robottransitioning
+    WAITING_TO_CHARGE = "waiting_to_charge", 108  # robotwaitcharge
 
 
 class YXBackType(RoborockModeEnum):

{python_roborock-4.26.3 → python_roborock-5.1.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-4.26.3 → python_roborock-5.1.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-4.26.3 → python_roborock-5.1.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-4.26.3 → python_roborock-5.1.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-4.26.3 → python_roborock-5.1.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-4.26.3 → python_roborock-5.1.0}/roborock/devices/rpc/b01_q7_channel.py

@@ -6,7 +6,7 @@ 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
@@ -16,6 +16,7 @@ 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 +62,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)

{python_roborock-4.26.3 → python_roborock-5.1.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,
@@ -23,18 +27,20 @@ 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 +48,25 @@ 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, *, device: HomeDataDevice, product: HomeDataProduct) -> None:
+        """Initialize the Q7 API."""
         self._channel = 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,
+            serial=device.sn,
+            model=product.model,
+        )
 
     async def query_values(self, props: list[RoborockB01Props]) -> B01Props | None:
         """Query the device for the values of the given Q7 properties."""
@@ -151,6 +171,6 @@ 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."""
+    return Q7PropertiesApi(channel, device=device, product=product)

{python_roborock-4.26.3 → python_roborock-5.1.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.1.0/roborock/devices/traits/b01/q7/map_content.py

@@ -0,0 +1,98 @@
+"""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`.
+"""
+
+from dataclasses import dataclass
+
+from vacuum_map_parser_base.map_data import MapData
+
+from roborock.data import RoborockBase
+from roborock.devices.traits import Trait
+from roborock.exceptions import RoborockException
+from roborock.map.b01_map_parser import B01MapParser, B01MapParserConfig
+
+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_trait: MapTrait,
+        *,
+        serial: str,
+        model: str,
+        map_parser_config: B01MapParserConfig | None = None,
+    ) -> None:
+        super().__init__()
+        self._map_trait = map_trait
+        self._serial = serial
+        self._model = model
+        self._map_parser = B01MapParser(map_parser_config)
+
+    async def refresh(self) -> None:
+        """Fetch, decode, and parse the current map payload."""
+        raw_payload = await self._map_trait.get_current_map_payload()
+        parsed = self.parse_map_content(raw_payload)
+        self.image_content = parsed.image_content
+        self.map_data = parsed.map_data
+        self.raw_api_response = parsed.raw_api_response
+
+    def parse_map_content(self, response: bytes) -> MapContent:
+        """Parse map content from raw bytes.
+
+        This mirrors the v1 trait behavior so cached map payload bytes can be
+        reparsed without going back to the device.
+        """
+        try:
+            parsed_data = self._map_parser.parse(
+                response,
+                serial=self._serial,
+                model=self._model,
+            )
+        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")
+
+        return MapContent(
+            image_content=parsed_data.image_content,
+            map_data=parsed_data.map_data,
+            raw_api_response=response,
+        )

{python_roborock-4.26.3 → python_roborock-5.1.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-4.26.3 → python_roborock-5.1.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-4.26.3 → python_roborock-5.1.0}/roborock/exceptions.py

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

python_roborock-5.1.0/roborock/map/b01_map_parser.py

@@ -0,0 +1,178 @@
+"""Module for parsing B01/Q7 map content.
+
+Observed Q7 `MAP_RESPONSE` payloads follow this decode pipeline:
+- base64-encoded ASCII
+- AES-ECB encrypted with the derived map key
+- PKCS7 padded
+- ASCII hex for a zlib-compressed SCMap payload
+
+The inner SCMap blob is parsed with protobuf messages generated from
+`roborock/map/proto/b01_scmap.proto`.
+"""
+
+import base64
+import binascii
+import hashlib
+import io
+import zlib
+from dataclasses import dataclass
+
+from Crypto.Cipher import AES
+from google.protobuf.message import DecodeError, Message
+from PIL import Image
+from vacuum_map_parser_base.config.image_config import ImageConfig
+from vacuum_map_parser_base.map_data import ImageData, MapData
+
+from roborock.exceptions import RoborockException
+from roborock.map.proto.b01_scmap_pb2 import RobotMap  # type: ignore[attr-defined]
+from roborock.protocol import Utils
+
+from .map_parser import ParsedMapData
+
+_MAP_FILE_FORMAT = "PNG"
+
+
+@dataclass
+class B01MapParserConfig:
+    """Configuration for the B01/Q7 map parser."""
+
+    map_scale: int = 4
+    """Scale factor for the rendered map image."""
+
+
+class B01MapParser:
+    """Decoder/parser for B01/Q7 SCMap payloads."""
+
+    def __init__(self, config: B01MapParserConfig | None = None) -> None:
+        self._config = config or B01MapParserConfig()
+
+    def parse(self, raw_payload: bytes, *, serial: str, model: str) -> ParsedMapData:
+        """Parse a raw MAP_RESPONSE payload and return a PNG + MapData."""
+        inflated = _decode_b01_map_payload(raw_payload, serial=serial, model=model)
+        parsed = _parse_scmap_payload(inflated)
+        size_x, size_y, grid = _extract_grid(parsed)
+        room_names = _extract_room_names(parsed)
+
+        image = _render_occupancy_image(grid, size_x=size_x, size_y=size_y, scale=self._config.map_scale)
+
+        map_data = MapData()
+        map_data.image = ImageData(
+            size=size_x * size_y,
+            top=0,
+            left=0,
+            height=size_y,
+            width=size_x,
+            image_config=ImageConfig(scale=self._config.map_scale),
+            data=image,
+            img_transformation=lambda p: p,
+        )
+        if room_names:
+            map_data.additional_parameters["room_names"] = room_names
+
+        image_bytes = io.BytesIO()
+        image.save(image_bytes, format=_MAP_FILE_FORMAT)
+
+        return ParsedMapData(
+            image_content=image_bytes.getvalue(),
+            map_data=map_data,
+        )
+
+
+def _derive_map_key(serial: str, model: str) -> bytes:
+    """Derive the B01/Q7 map decrypt key from serial + model."""
+    model_suffix = model.split(".")[-1]
+    model_key = (model_suffix + "0" * 16)[:16].encode()
+    material = f"{serial}+{model_suffix}+{serial}".encode()
+    encrypted = Utils.encrypt_ecb(material, model_key)
+    md5 = hashlib.md5(base64.b64encode(encrypted), usedforsecurity=False).hexdigest()
+    return md5[8:24].encode()
+
+
+def _decode_base64_payload(raw_payload: bytes) -> bytes:
+    blob = raw_payload.strip()
+    padded = blob + b"=" * (-len(blob) % 4)
+    try:
+        return base64.b64decode(padded, validate=True)
+    except binascii.Error as err:
+        raise RoborockException("Failed to decode B01 map payload") from err
+
+
+def _decode_b01_map_payload(raw_payload: bytes, *, serial: str, model: str) -> bytes:
+    """Decode raw B01 `MAP_RESPONSE` payload into inflated SCMap bytes."""
+    # TODO: Move this lower-level B01 transport decode under `roborock.protocols`
+    # so this module only handles SCMap parsing/rendering.
+    encrypted_payload = _decode_base64_payload(raw_payload)
+    if len(encrypted_payload) % AES.block_size != 0:
+        raise RoborockException("Unexpected encrypted B01 map payload length")
+
+    map_key = _derive_map_key(serial, model)
+
+    try:
+        compressed_hex = Utils.decrypt_ecb(encrypted_payload, map_key).decode("ascii")
+        compressed_payload = bytes.fromhex(compressed_hex)
+        return zlib.decompress(compressed_payload)
+    except (ValueError, UnicodeDecodeError, zlib.error) as err:
+        raise RoborockException("Failed to decode B01 map payload") from err
+
+
+def _parse_proto(blob: bytes, message: Message, *, context: str) -> None:
+    try:
+        message.ParseFromString(blob)
+    except DecodeError as err:
+        raise RoborockException(f"Failed to parse {context}") from err
+
+
+def _parse_scmap_payload(payload: bytes) -> RobotMap:
+    """Parse inflated SCMap bytes into a generated protobuf message."""
+    parsed = RobotMap()
+    _parse_proto(payload, parsed, context="B01 SCMap")
+    return parsed
+
+
+def _extract_grid(parsed: RobotMap) -> tuple[int, int, bytes]:
+    if not parsed.HasField("mapHead") or not parsed.HasField("mapData"):
+        raise RoborockException("Failed to parse B01 map header/grid")
+
+    size_x = parsed.mapHead.sizeX if parsed.mapHead.HasField("sizeX") else 0
+    size_y = parsed.mapHead.sizeY if parsed.mapHead.HasField("sizeY") else 0
+    if not size_x or not size_y or not parsed.mapData.HasField("mapData"):
+        raise RoborockException("Failed to parse B01 map header/grid")
+
+    map_data = parsed.mapData.mapData
+    expected_len = size_x * size_y
+    if len(map_data) < expected_len:
+        raise RoborockException("B01 map data shorter than expected dimensions")
+
+    return size_x, size_y, map_data[:expected_len]
+
+
+def _extract_room_names(parsed: RobotMap) -> dict[int, str]:
+    # Expose room id/name mapping without inventing room geometry/polygons.
+    room_names: dict[int, str] = {}
+    for room in parsed.roomDataInfo:
+        if room.HasField("roomId"):
+            room_id = room.roomId
+            room_names[room_id] = room.roomName if room.HasField("roomName") else f"Room {room_id}"
+    return room_names
+
+
+def _render_occupancy_image(grid: bytes, *, size_x: int, size_y: int, scale: int) -> Image.Image:
+    """Render the B01 occupancy grid into a simple image."""
+
+    # The observed occupancy grid contains only:
+    # - 0: outside/unknown
+    # - 127: wall/obstacle
+    # - 128: floor/free
+    table = bytearray(range(256))
+    table[0] = 0
+    table[127] = 180
+    table[128] = 255
+
+    mapped = grid.translate(bytes(table))
+    img = Image.frombytes("L", (size_x, size_y), mapped)
+    img = img.transpose(Image.Transpose.FLIP_TOP_BOTTOM).convert("RGB")
+
+    if scale > 1:
+        img = img.resize((size_x * scale, size_y * scale), resample=Image.Resampling.NEAREST)
+
+    return img

python_roborock-5.1.0/roborock/map/proto/__init__.py

@@ -0,0 +1 @@
+"""Generated protobuf modules for Roborock map payloads."""

python_roborock-5.1.0/roborock/map/proto/b01_scmap.proto

@@ -0,0 +1,70 @@
+// Checked-in B01/Q7 SCMap schema for the generated runtime protobuf module.
+// Regenerate the checked-in Python module after edits with:
+//   python -m grpc_tools.protoc -I./roborock/map/proto --python_out=./roborock/map/proto roborock/map/proto/b01_scmap.proto
+// The generated file `b01_scmap_pb2.py` is checked in for runtime use and should
+// not be edited by hand.
+syntax = "proto2";
+
+package b01.scmap;
+
+message DevicePointInfo {
+  optional float x = 1;
+  optional float y = 2;
+}
+
+message MapBoundaryInfo {
+  optional string mapMd5 = 1;
+  optional uint32 vMinX = 2;
+  optional uint32 vMaxX = 3;
+  optional uint32 vMinY = 4;
+  optional uint32 vMaxY = 5;
+}
+
+message MapExtInfo {
+  optional uint32 taskBeginDate = 1;
+  optional uint32 mapUploadDate = 2;
+  optional uint32 mapValid = 3;
+  optional uint32 radian = 4;
+  optional uint32 force = 5;
+  optional uint32 cleanPath = 6;
+  optional MapBoundaryInfo boudaryInfo = 7;
+  optional uint32 mapVersion = 8;
+  optional uint32 mapValueType = 9;
+}
+
+message MapHeadInfo {
+  optional uint32 mapHeadId = 1;
+  optional uint32 sizeX = 2;
+  optional uint32 sizeY = 3;
+  optional float minX = 4;
+  optional float minY = 5;
+  optional float maxX = 6;
+  optional float maxY = 7;
+  optional float resolution = 8;
+}
+
+message MapDataInfo {
+  optional bytes mapData = 1;
+}
+
+message RoomDataInfo {
+  optional uint32 roomId = 1;
+  optional string roomName = 2;
+  optional uint32 roomTypeId = 3;
+  optional uint32 meterialId = 4;
+  optional uint32 cleanState = 5;
+  optional uint32 roomClean = 6;
+  optional uint32 roomCleanIndex = 7;
+  optional DevicePointInfo roomNamePost = 8;
+  optional uint32 colorId = 10;
+  optional uint32 floor_direction = 11;
+  optional uint32 global_seq = 12;
+}
+
+message RobotMap {
+  optional uint32 mapType = 1;
+  optional MapExtInfo mapExtInfo = 2;
+  optional MapHeadInfo mapHead = 3;
+  optional MapDataInfo mapData = 4;
+  repeated RoomDataInfo roomDataInfo = 12;
+}

python_roborock-5.1.0/roborock/map/proto/b01_scmap_pb2.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: roborock/map/proto/b01_scmap.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'roborock/map/proto/b01_scmap.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\"roborock/map/proto/b01_scmap.proto\x12\tb01.scmap\"\'\n\x0f\x44\x65vicePointInfo\x12\t\n\x01x\x18\x01 \x01(\x02\x12\t\n\x01y\x18\x02 \x01(\x02\"]\n\x0fMapBoundaryInfo\x12\x0e\n\x06mapMd5\x18\x01 \x01(\t\x12\r\n\x05vMinX\x18\x02 \x01(\r\x12\r\n\x05vMaxX\x18\x03 \x01(\r\x12\r\n\x05vMinY\x18\x04 \x01(\r\x12\r\n\x05vMaxY\x18\x05 \x01(\r\"\xd9\x01\n\nMapExtInfo\x12\x15\n\rtaskBeginDate\x18\x01 \x01(\r\x12\x15\n\rmapUploadDate\x18\x02 \x01(\r\x12\x10\n\x08mapValid\x18\x03 \x01(\r\x12\x0e\n\x06radian\x18\x04 \x01(\r\x12\r\n\x05\x66orce\x18\x05 \x01(\r\x12\x11\n\tcleanPath\x18\x06 \x01(\r\x12/\n\x0b\x62oudaryInfo\x18\x07 \x01(\x0b\x32\x1a.b01.scmap.MapBoundaryInfo\x12\x12\n\nmapVersion\x18\x08 \x01(\r\x12\x14\n\x0cmapValueType\x18\t \x01(\r\"\x8a\x01\n\x0bMapHeadInfo\x12\x11\n\tmapHeadId\x18\x01 \x01(\r\x12\r\n\x05sizeX\x18\x02 \x01(\r\x12\r\n\x05sizeY\x18\x03 \x01(\r\x12\x0c\n\x04minX\x18\x04 \x01(\x02\x12\x0c\n\x04minY\x18\x05 \x01(\x02\x12\x0c\n\x04maxX\x18\x06 \x01(\x02\x12\x0c\n\x04maxY\x18\x07 \x01(\x02\x12\x12\n\nresolution\x18\x08 \x01(\x02\"\x1e\n\x0bMapDataInfo\x12\x0f\n\x07mapData\x18\x01 \x01(\x0c\"\x87\x02\n\x0cRoomDataInfo\x12\x0e\n\x06roomId\x18\x01 \x01(\r\x12\x10\n\x08roomName\x18\x02 \x01(\t\x12\x12\n\nroomTypeId\x18\x03 \x01(\r\x12\x12\n\nmeterialId\x18\x04 \x01(\r\x12\x12\n\ncleanState\x18\x05 \x01(\r\x12\x11\n\troomClean\x18\x06 \x01(\r\x12\x16\n\x0eroomCleanIndex\x18\x07 \x01(\r\x12\x30\n\x0croomNamePost\x18\x08 \x01(\x0b\x32\x1a.b01.scmap.DevicePointInfo\x12\x0f\n\x07\x63olorId\x18\n \x01(\r\x12\x17\n\x0f\x66loor_direction\x18\x0b \x01(\r\x12\x12\n\nglobal_seq\x18\x0c \x01(\r\"\xc7\x01\n\x08RobotMap\x12\x0f\n\x07mapType\x18\x01 \x01(\r\x12)\n\nmapExtInfo\x18\x02 \x01(\x0b\x32\x15.b01.scmap.MapExtInfo\x12\'\n\x07mapHead\x18\x03 \x01(\x0b\x32\x16.b01.scmap.MapHeadInfo\x12\'\n\x07mapData\x18\x04 \x01(\x0b\x32\x16.b01.scmap.MapDataInfo\x12-\n\x0croomDataInfo\x18\x0c \x03(\x0b\x32\x17.b01.scmap.RoomDataInfo')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'roborock.map.proto.b01_scmap_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_DEVICEPOINTINFO']._serialized_start=49
+  _globals['_DEVICEPOINTINFO']._serialized_end=88
+  _globals['_MAPBOUNDARYINFO']._serialized_start=90
+  _globals['_MAPBOUNDARYINFO']._serialized_end=183
+  _globals['_MAPEXTINFO']._serialized_start=186
+  _globals['_MAPEXTINFO']._serialized_end=403
+  _globals['_MAPHEADINFO']._serialized_start=406
+  _globals['_MAPHEADINFO']._serialized_end=544
+  _globals['_MAPDATAINFO']._serialized_start=546
+  _globals['_MAPDATAINFO']._serialized_end=576
+  _globals['_ROOMDATAINFO']._serialized_start=579
+  _globals['_ROOMDATAINFO']._serialized_end=842
+  _globals['_ROBOTMAP']._serialized_start=845
+  _globals['_ROBOTMAP']._serialized_end=1044
+# @@protoc_insertion_point(module_scope)

{python_roborock-4.26.3 → python_roborock-5.1.0}/roborock/protocol.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 import binascii
 import gzip
 import hashlib

{python_roborock-4.26.3 → python_roborock-5.1.0}/roborock/roborock_message.py

@@ -1,7 +1,6 @@
-from __future__ import annotations
-
 from dataclasses import dataclass, field
 from enum import StrEnum
+from typing import Self
 
 from roborock import RoborockEnum
 from roborock.util import get_next_int, get_timestamp
@@ -37,8 +36,8 @@ class RoborockDataProtocol(RoborockEnum):
     OFFLINE_STATUS = 135
 
     @classmethod
-    def _missing_(cls: type[RoborockEnum], key) -> RoborockEnum:
-        raise ValueError("%s not a valid key for Data Protocol", key)
+    def _missing_(cls: type[Self], key) -> Self:
+        raise ValueError(f"{key} not a valid key for Data Protocol")
 
 
 class RoborockDyadDataProtocol(RoborockEnum):

{python_roborock-4.26.3 → python_roborock-5.1.0}/roborock/roborock_typing.py

@@ -1,7 +1,6 @@
-from __future__ import annotations
-
 from dataclasses import dataclass, field
 from enum import Enum, StrEnum
+from typing import Self
 
 from .data import (
     CleanRecord,
@@ -368,7 +367,7 @@ class DeviceProp(RoborockBase):
         ):
             self.dust_collection_mode_name = self.dock_summary.dust_collection_mode.mode.name
 
-    def update(self, device_prop: DeviceProp) -> None:
+    def update(self, device_prop: Self) -> None:
         if device_prop.status:
             self.status = device_prop.status
         if device_prop.clean_summary:

{python_roborock-4.26.3 → python_roborock-5.1.0}/roborock/util.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 import logging
 import math
 import time

{python_roborock-4.26.3 → python_roborock-5.1.0}/roborock/web_api.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 import base64
 import hashlib
 import hmac