python-roborock 7.13.0__tar.gz → 7.14.0__tar.gz

{python_roborock-7.13.0 → python_roborock-7.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-roborock
-Version: 7.13.0
+Version: 7.14.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.13.0 → python_roborock-7.14.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-roborock"
-version = "7.13.0"
+version = "7.14.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-7.13.0 → python_roborock-7.14.0}/roborock/cli.py

@@ -34,7 +34,7 @@ import threading
 from collections.abc import Callable
 from dataclasses import asdict, dataclass
 from pathlib import Path
-from typing import Any, cast
+from typing import Any, TextIO, cast
 
 try:
     import click
@@ -50,7 +50,7 @@ except ImportError as err:
     ) from err
 
 from roborock import RoborockCommand
-from roborock.data import RoborockBase, UserData
+from roborock.data import HomeDataSchedule, RoborockBase, UserData
 from roborock.data.b01_q10.b01_q10_code_mappings import (
     B01_Q10_DP,
     YXCleanType,
@@ -428,6 +428,33 @@ async def execute_scene(ctx, scene_id):
     await client.execute_scene(connection_cache.user_data, scene_id)
 
 
+@click.command()
+@click.option("--device_id", required=True)
+@click.option(
+    "--job-file",
+    required=True,
+    type=click.File("r", encoding="utf-8"),
+    help="JSON file containing the schedule to update.",
+)
+@click.pass_context
+@async_command
+async def update_job(ctx: click.Context, device_id: str, job_file: TextIO) -> None:
+    """Replace a cloud job using a complete schedule JSON file.
+
+    Include all existing settings in the file, including unchanged cleaning parameters.
+    """
+    context: RoborockContext = ctx.obj
+    try:
+        job = HomeDataSchedule.from_dict(json.load(job_file))
+        connection_cache = context.connection_cache()
+        client = RoborockApiClient(connection_cache.email)
+        await client.update_job(connection_cache.user_data, device_id, job)
+    except Exception as err:
+        click.echo(f"Error: {err}", err=True)
+        raise SystemExit(1) from err
+    click.echo(f"Updated job {job.id} for device {device_id}")
+
+
 async def _v1_trait(context: RoborockContext, device_id: str, display_func: Callable[[], V1TraitMixin]) -> Trait:
     device_manager = await context.get_device_manager()
     device = await device_manager.get_device(device_id)
@@ -1366,6 +1393,7 @@ cli.add_command(discover)
 cli.add_command(list_devices)
 cli.add_command(list_scenes)
 cli.add_command(execute_scene)
+cli.add_command(update_job)
 cli.add_command(status)
 cli.add_command(command)
 cli.add_command(parser)

python_roborock-7.14.0/roborock/map/dynamic_blocks.py

@@ -0,0 +1,220 @@
+"""Byte-level container helpers for Roborock V1 map blocks.
+
+A V1 map file and the ``data`` / ``robot_data`` values returned by the dynamic
+map diff commands share one block framing. Every block begins with an
+eight-byte common header::
+
+    offset 0, u16  block type
+    offset 2, u16  header length H (including these eight bytes)
+    offset 4, u32  payload length P
+    offset 8 ..H   type-specific header fields
+    offset H ..H+P payload
+
+The next block starts exactly ``H + P`` bytes after the current one. All
+multibyte fields are little-endian and unsigned.
+
+This module only understands that framing. It can split a map file or a
+dynamic value into blocks, rebuild a map file from blocks, and decode the
+block 34 nonce table that identifies the base map and its dynamic elements.
+It deliberately knows nothing about the meaning of any block payload; that
+stays with the map parser (full maps) and the dynamic element merge logic.
+"""
+
+import struct
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from typing import Self
+
+from roborock.exceptions import RoborockException
+
+# Marker at the start of a full V1 map file.
+MAP_FILE_MAGIC = b"rr"
+
+# Size of the block header fields shared by every block type.
+COMMON_HEADER_LEN = 8
+
+# A dynamic ``data`` / ``robot_data`` value holds at most this many blocks.
+MAX_DYNAMIC_VALUE_BLOCKS = 4
+
+# Block type of the nonce table carried inside a full map.
+NONCE_TABLE_BLOCK_TYPE = 34
+
+# Entry identifier inside the nonce table that supplies the map nonce.
+MAP_NONCE_ENTRY_ID = 35
+
+# Trailing digest block of a full map. New blocks are inserted before it.
+DIGEST_BLOCK_TYPE = 1024
+
+_COMMON_HEADER = struct.Struct("<HHI")
+_NONCE_TABLE_NUM = struct.Struct("<I")
+_NONCE_ENTRY = struct.Struct("<BI")
+_NONCE_TABLE_MIN_HEADER_LEN = COMMON_HEADER_LEN + _NONCE_TABLE_NUM.size
+_MAP_FILE_HEADER_LEN = struct.Struct("<H")
+
+
+@dataclass(frozen=True)
+class MapBlock:
+    """One framed block: its type, type-specific header fields, and payload.
+
+    ``extra_header`` holds the bytes between the common eight-byte header and
+    the payload, so the common header is always regenerated from the lengths
+    and can never disagree with the data it describes.
+    """
+
+    block_type: int
+    payload: bytes
+    extra_header: bytes = b""
+
+    @property
+    def header_length(self) -> int:
+        """Total header length ``H`` written to the common header."""
+        return COMMON_HEADER_LEN + len(self.extra_header)
+
+    def with_payload(self, payload: bytes) -> Self:
+        """Return a copy carrying ``payload`` and the same type and header fields."""
+        return type(self)(self.block_type, payload, self.extra_header)
+
+    def encode(self) -> bytes:
+        """Serialize the block with a regenerated common header."""
+        common = _COMMON_HEADER.pack(self.block_type, self.header_length, len(self.payload))
+        return common + self.extra_header + self.payload
+
+
+def iter_blocks(data: bytes, start: int = 0) -> Iterator[MapBlock]:
+    """Yield consecutive blocks from ``data`` beginning at byte ``start``.
+
+    The sequence must consume ``data`` exactly. A header shorter than eight
+    bytes, a header or payload that runs past the end of ``data``, or a block
+    that does not fit a complete common header is rejected.
+    """
+    position = start
+    end = len(data)
+    while position < end:
+        if end - position < COMMON_HEADER_LEN:
+            raise RoborockException(f"Map block at offset {position} is shorter than its common header")
+        block_type, header_length, payload_length = _COMMON_HEADER.unpack_from(data, position)
+        if header_length < COMMON_HEADER_LEN:
+            raise RoborockException(f"Map block at offset {position} declares header length {header_length} < 8")
+        block_end = position + header_length + payload_length
+        if block_end > end:
+            raise RoborockException(f"Map block at offset {position} extends past the end of the data")
+        header_end = position + header_length
+        yield MapBlock(
+            block_type=block_type,
+            payload=data[header_end:block_end],
+            extra_header=data[position + COMMON_HEADER_LEN : header_end],
+        )
+        position = block_end
+
+
+def parse_dynamic_value(data: bytes) -> list[MapBlock]:
+    """Split a decoded dynamic ``data`` / ``robot_data`` value into blocks.
+
+    A dynamic value is a bare block sequence: there is no ``rr`` file header
+    and no digest. An empty value yields no blocks. A value that reaches a
+    fifth block is rejected, so a non-empty value holds one to four blocks.
+    """
+    blocks: list[MapBlock] = []
+    for block in iter_blocks(data):
+        if len(blocks) == MAX_DYNAMIC_VALUE_BLOCKS:
+            raise RoborockException(f"Dynamic map value holds more than {MAX_DYNAMIC_VALUE_BLOCKS} blocks")
+        blocks.append(block)
+    return blocks
+
+
+def encode_blocks(blocks: Iterable[MapBlock]) -> bytes:
+    """Serialize a block sequence without any file header."""
+    return b"".join(block.encode() for block in blocks)
+
+
+@dataclass(frozen=True)
+class MapFile:
+    """A full V1 map file split into its file header and framed blocks."""
+
+    header: bytes
+    """The ``rr`` file header, kept verbatim so it round-trips unchanged."""
+
+    blocks: list[MapBlock]
+
+    def encode(self) -> bytes:
+        """Serialize the file header followed by every block."""
+        return self.header + encode_blocks(self.blocks)
+
+
+def split_map_file(map_bytes: bytes) -> MapFile:
+    """Split a decompressed full map into its file header and blocks."""
+    if not map_bytes.startswith(MAP_FILE_MAGIC):
+        raise RoborockException("Map file does not start with the 'rr' marker")
+    if len(map_bytes) < _MAP_FILE_HEADER_LEN.size + 2:
+        raise RoborockException("Map file is shorter than its header length field")
+    (header_length,) = _MAP_FILE_HEADER_LEN.unpack_from(map_bytes, 2)
+    if header_length < 4 or header_length > len(map_bytes):
+        raise RoborockException(f"Map file declares an invalid header length {header_length}")
+    return MapFile(header=map_bytes[:header_length], blocks=list(iter_blocks(map_bytes, header_length)))
+
+
+def find_block(blocks: Iterable[MapBlock], block_type: int) -> MapBlock | None:
+    """Return the first block of ``block_type``, or ``None`` when absent."""
+    for block in blocks:
+        if block.block_type == block_type:
+            return block
+    return None
+
+
+def replace_block(blocks: list[MapBlock], new_block: MapBlock) -> list[MapBlock]:
+    """Return a new block list with ``new_block`` substituted for its type.
+
+    The first existing block of the same type is replaced in place, so the
+    relative order the map parser depends on (for example mop flags after
+    the path they describe) is preserved. When the type is not present the
+    block is inserted before the trailing digest, or appended when there is
+    no digest.
+    """
+    for index, block in enumerate(blocks):
+        if block.block_type == new_block.block_type:
+            return [*blocks[:index], new_block, *blocks[index + 1 :]]
+    for index, block in enumerate(blocks):
+        if block.block_type == DIGEST_BLOCK_TYPE:
+            return [*blocks[:index], new_block, *blocks[index:]]
+    return [*blocks, new_block]
+
+
+@dataclass(frozen=True)
+class NonceTable:
+    """Decoded block 34: identities of the base map and its dynamic elements.
+
+    Nonces are opaque 32-bit identities. Only equality is meaningful. They are
+    decoded unsigned to preserve all 32 bits. JSON values may use a signed
+    representation, as the app's binary reader does. Callers must normalize
+    JSON nonces with ``value & 0xFFFFFFFF`` before comparing them to this table.
+    """
+
+    map_nonce: int | None
+    """Nonce of the base map (entry 35), or ``None`` when the table lacks it."""
+
+    element_nonces: dict[int, int]
+    """Element nonce keyed by element id, excluding the map nonce entry."""
+
+
+def decode_nonce_table(block: MapBlock) -> NonceTable:
+    """Decode a block 34 nonce table.
+
+    The header carries ``num`` as a u32 at offset 8. The payload holds ``num``
+    five-byte entries, each a one-byte identifier followed by a u32 nonce.
+    """
+    if block.block_type != NONCE_TABLE_BLOCK_TYPE:
+        raise RoborockException(f"Block type {block.block_type} is not a nonce table")
+    if block.header_length < _NONCE_TABLE_MIN_HEADER_LEN:
+        raise RoborockException("Nonce table header is shorter than 12 bytes")
+    (num,) = _NONCE_TABLE_NUM.unpack_from(block.extra_header, 0)
+    if len(block.payload) < num * _NONCE_ENTRY.size:
+        raise RoborockException(f"Nonce table declares {num} entries but the payload is too short")
+    map_nonce: int | None = None
+    element_nonces: dict[int, int] = {}
+    for index in range(num):
+        entry_id, nonce = _NONCE_ENTRY.unpack_from(block.payload, index * _NONCE_ENTRY.size)
+        if entry_id == MAP_NONCE_ENTRY_ID:
+            map_nonce = nonce
+        else:
+            element_nonces[entry_id] = nonce
+    return NonceTable(map_nonce=map_nonce, element_nonces=element_nonces)

{python_roborock-7.13.0 → python_roborock-7.14.0}/roborock/testing/v1_simulator.py

@@ -4,8 +4,11 @@ This module provides `V1VacuumSimulator` which simulates the firmware state
 machine and JSON RPC commands for V1 vacuum cleaners.
 """
 
+import gzip
+import hashlib
 import json
 import logging
+import struct
 import time
 from collections.abc import Callable
 from dataclasses import asdict, replace
@@ -37,6 +40,7 @@ from roborock.data.v1.v1_containers import (
 )
 from roborock.devices.cache import DeviceCache, InMemoryCache
 from roborock.devices.rpc.v1_channel import V1Channel
+from roborock.protocol import Utils
 from roborock.protocols.v1_protocol import SecurityData
 from roborock.roborock_message import RoborockDataProtocol, RoborockMessage, RoborockMessageProtocol
 from roborock.testing.channel import FakeChannel
@@ -165,6 +169,33 @@ DEFAULT_LAST_CLEAN_RECORD = CleanRecord(
 )
 
 
+# Eight character endpoint, matching the width of the map response header field.
+MAP_ENDPOINT = "fakeendp"
+
+# Minimum side length in cells of the simulated map image.
+MAP_IMAGE_SIZE = 32
+
+_MAP_FILE_HEADER_LEN = 20
+_MAP_CELL_SIZE_MM = 50
+_MAP_IMAGE_PADDING = 2
+_IMAGE_BLOCK_TYPE = 2
+_PATH_BLOCK_TYPE = 3
+_POSE_BLOCK_TYPE = 8
+_MOP_BLOCK_TYPE = 18
+_DIGEST_BLOCK_TYPE = 1024
+_MAP_INSIDE = 0xFF
+
+
+def _path_point(index: int) -> bytes:
+    """A deterministic path point, so tests can assert on exact bytes."""
+    return struct.pack("<HH", 20000 + index * 10, 21000 + index * 7)
+
+
+def _block(block_type: int, payload: bytes, extra_header: bytes = b"") -> bytes:
+    """Frame one map block: type, header length, payload length, header, payload."""
+    return struct.pack("<HHI", block_type, 8 + len(extra_header), len(payload)) + extra_header + payload
+
+
 class V1VacuumSimulator(RoborockDeviceSimulator):
     """Firmware simulator for a V1/L01 vacuum device.
 
@@ -219,10 +250,18 @@ class V1VacuumSimulator(RoborockDeviceSimulator):
             "reset_consumable": self._handle_reset_consumable,
             "app_get_init_status": self._handle_app_get_init_status,
             "get_network_info": self._handle_get_network_info,
+            "get_map_v1": lambda params: self.build_map_bytes(),
         }
 
+        # The simulated robot's own view of its map. Tests extend the path
+        # with advance_path() and move the robot via robot_position.
+        self.path_length = 0
+        self.robot_position = (25000, 24000, 90)
+
         self.device_cache = DeviceCache(self.duid, InMemoryCache())
-        self.security_data = SecurityData(endpoint="fake_endpoint", nonce=b"fake_nonce_16bytes")
+        # The endpoint must fit the eight byte map response header field and the
+        # nonce must be a valid sixteen byte AES key for map responses to decode.
+        self.security_data = SecurityData(endpoint=MAP_ENDPOINT, nonce=b"fake_nonce_16byt")
         local_session = Mock(return_value=self.local_channel)
 
         self._v1_channel = V1Channel(
@@ -333,6 +372,56 @@ class V1VacuumSimulator(RoborockDeviceSimulator):
     def _handle_get_network_info(self, params: Any) -> dict[str, Any]:
         return _serialize_dataclass(self.network_info)
 
+    # --- Simulated map -------------------------------------------------
+
+    def advance_path(self, count: int) -> None:
+        """Extend the current path, as the robot does while it cleans."""
+        self.path_length += count
+
+    def path_payload(self, start: int, count: int) -> bytes:
+        """The point records for a range of the current path."""
+        return b"".join(_path_point(i) for i in range(start, start + count))
+
+    def mop_payload(self, start: int, count: int) -> bytes:
+        """The mop flags for a range of the current path, alternating per point."""
+        return bytes(i % 2 for i in range(start, start + count))
+
+    def _pose_block(self) -> bytes:
+        return _block(_POSE_BLOCK_TYPE, struct.pack("<iii", *self.robot_position))
+
+    def _path_blocks(self, start: int, count: int) -> bytes:
+        """Blocks 3 and 18 for a range of the path, as both a map and a page carry them."""
+        return _block(_PATH_BLOCK_TYPE, self.path_payload(start, count), struct.pack("<III", count, 4, 0)) + _block(
+            _MOP_BLOCK_TYPE, self.mop_payload(start, count)
+        )
+
+    def build_map_bytes(self) -> bytes:
+        """Build a decompressed map file reflecting the current robot state."""
+        # Full-map image offsets are cells; path and robot coordinates are millimetres.
+        points = [self.robot_position[:2], *struct.iter_unpack("<HH", self.path_payload(0, self.path_length))]
+        xs = [x // _MAP_CELL_SIZE_MM for x, _ in points]
+        ys = [y // _MAP_CELL_SIZE_MM for _, y in points]
+        left = max(0, min(xs) - _MAP_IMAGE_PADDING)
+        top = max(0, min(ys) - _MAP_IMAGE_PADDING)
+        width = max(MAP_IMAGE_SIZE, max(xs) - left + _MAP_IMAGE_PADDING + 1)
+        height = max(MAP_IMAGE_SIZE, max(ys) - top + _MAP_IMAGE_PADDING + 1)
+        image = _block(
+            _IMAGE_BLOCK_TYPE,
+            bytes([_MAP_INSIDE]) * (width * height),
+            struct.pack("<Iiiii", 0, top, left, height, width),
+        )
+        body = image + self._path_blocks(0, self.path_length) + self._pose_block()
+        digest_header = struct.pack("<HHI", _DIGEST_BLOCK_TYPE, 8, 20)
+        header = struct.pack("<2sHIHHII", b"rr", _MAP_FILE_HEADER_LEN, len(body) + len(digest_header) + 20, 1, 0, 0, 0)
+        data = header + body + digest_header
+        return data + hashlib.sha1(data, usedforsecurity=False).digest()
+
+    def _map_response_message(self, request_id: int, map_bytes: bytes) -> RoborockMessage:
+        """Frame the map as the encrypted binary response the device sends."""
+        body = Utils.encrypt_cbc(gzip.compress(map_bytes), self.security_data.nonce)
+        header = struct.pack("<8s8sH6s", self.security_data.endpoint.encode(), bytes(8), request_id & 0xFFFF, bytes(6))
+        return RoborockMessage(protocol=RoborockMessageProtocol.MAP_RESPONSE, payload=header + body)
+
     async def _handle_publish(self, message: RoborockMessage, channel: FakeChannel) -> None:
         if not message.payload:
             return
@@ -364,6 +453,11 @@ class V1VacuumSimulator(RoborockDeviceSimulator):
         else:
             result = "ok"
 
+        if method == "get_map_v1" and error is None and isinstance(result, bytes):
+            # Custom handlers return decompressed map bytes, just like the default.
+            channel.notify_subscribers(self._map_response_message(msg_id, result))
+            return
+
         response_data = {
             "dps": {"102": json.dumps({"id": msg_id, "result": result, "error": error})},
             "t": int(time.time()),

{python_roborock-7.13.0 → python_roborock-7.14.0}/roborock/web_api.py

@@ -768,6 +768,31 @@ class RoborockApiClient:
             raise RoborockException(response)
         return response
 
+    async def update_job(self, user_data: UserData, device_id: str, job: HomeDataSchedule) -> None:
+        """Replace an existing cloud job with the full supplied schedule.
+
+        Pass a schedule returned by :meth:`get_schedules` with the desired changes.
+        The job ID identifies the URL; all other fields are sent as the replacement body.
+        """
+        rriot = user_data.rriot
+        if rriot is None:
+            raise RoborockException("rriot is none")
+        if rriot.r.a is None:
+            raise RoborockException("Missing field 'a' in rriot reference")
+        path = f"/user/devices/{device_id}/jobs/{job.id}"
+        body = job.as_dict(exclude={"id"})
+        job_request = PreparedRequest(
+            rriot.r.a,
+            self.session,
+            {
+                "Authorization": _get_hawk_authentication(rriot, path, body=body),
+                "Content-Type": "application/json",
+            },
+        )
+        response = await job_request.request("put", path, data=_compact_json(body).encode())
+        if not response or not response.get("success"):
+            raise RoborockException(response)
+
     async def get_products(self, user_data: UserData) -> ProductResponse:
         """Gets all products and their schemas, good for determining status codes and model numbers."""
         base_url = await self.base_url