|
| 1 | +"""Byte-level container helpers for Roborock V1 map blocks. |
| 2 | +
|
| 3 | +A V1 map file and the ``data`` / ``robot_data`` values returned by the dynamic |
| 4 | +map diff commands share one block framing. Every block begins with an |
| 5 | +eight-byte common header:: |
| 6 | +
|
| 7 | + offset 0, u16 block type |
| 8 | + offset 2, u16 header length H (including these eight bytes) |
| 9 | + offset 4, u32 payload length P |
| 10 | + offset 8 ..H type-specific header fields |
| 11 | + offset H ..H+P payload |
| 12 | +
|
| 13 | +The next block starts exactly ``H + P`` bytes after the current one. All |
| 14 | +multibyte fields are little-endian and unsigned. |
| 15 | +
|
| 16 | +This module only understands that framing. It can split a map file or a |
| 17 | +dynamic value into blocks, rebuild a map file from blocks, and decode the |
| 18 | +block 34 nonce table that identifies the base map and its dynamic elements. |
| 19 | +It deliberately knows nothing about the meaning of any block payload; that |
| 20 | +stays with the map parser (full maps) and the dynamic element merge logic. |
| 21 | +""" |
| 22 | + |
| 23 | +import struct |
| 24 | +from collections.abc import Iterable, Iterator |
| 25 | +from dataclasses import dataclass |
| 26 | +from typing import Self |
| 27 | + |
| 28 | +from roborock.exceptions import RoborockException |
| 29 | + |
| 30 | +# Marker at the start of a full V1 map file. |
| 31 | +MAP_FILE_MAGIC = b"rr" |
| 32 | + |
| 33 | +# Size of the block header fields shared by every block type. |
| 34 | +COMMON_HEADER_LEN = 8 |
| 35 | + |
| 36 | +# A dynamic ``data`` / ``robot_data`` value holds at most this many blocks. |
| 37 | +MAX_DYNAMIC_VALUE_BLOCKS = 4 |
| 38 | + |
| 39 | +# Block type of the nonce table carried inside a full map. |
| 40 | +NONCE_TABLE_BLOCK_TYPE = 34 |
| 41 | + |
| 42 | +# Entry identifier inside the nonce table that supplies the map nonce. |
| 43 | +MAP_NONCE_ENTRY_ID = 35 |
| 44 | + |
| 45 | +# Trailing digest block of a full map. New blocks are inserted before it. |
| 46 | +DIGEST_BLOCK_TYPE = 1024 |
| 47 | + |
| 48 | +_COMMON_HEADER = struct.Struct("<HHI") |
| 49 | +_NONCE_TABLE_NUM = struct.Struct("<I") |
| 50 | +_NONCE_ENTRY = struct.Struct("<BI") |
| 51 | +_NONCE_TABLE_MIN_HEADER_LEN = COMMON_HEADER_LEN + _NONCE_TABLE_NUM.size |
| 52 | +_MAP_FILE_HEADER_LEN = struct.Struct("<H") |
| 53 | + |
| 54 | + |
| 55 | +@dataclass(frozen=True) |
| 56 | +class MapBlock: |
| 57 | + """One framed block: its type, type-specific header fields, and payload. |
| 58 | +
|
| 59 | + ``extra_header`` holds the bytes between the common eight-byte header and |
| 60 | + the payload, so the common header is always regenerated from the lengths |
| 61 | + and can never disagree with the data it describes. |
| 62 | + """ |
| 63 | + |
| 64 | + block_type: int |
| 65 | + payload: bytes |
| 66 | + extra_header: bytes = b"" |
| 67 | + |
| 68 | + @property |
| 69 | + def header_length(self) -> int: |
| 70 | + """Total header length ``H`` written to the common header.""" |
| 71 | + return COMMON_HEADER_LEN + len(self.extra_header) |
| 72 | + |
| 73 | + def with_payload(self, payload: bytes) -> Self: |
| 74 | + """Return a copy carrying ``payload`` and the same type and header fields.""" |
| 75 | + return type(self)(self.block_type, payload, self.extra_header) |
| 76 | + |
| 77 | + def encode(self) -> bytes: |
| 78 | + """Serialize the block with a regenerated common header.""" |
| 79 | + common = _COMMON_HEADER.pack(self.block_type, self.header_length, len(self.payload)) |
| 80 | + return common + self.extra_header + self.payload |
| 81 | + |
| 82 | + |
| 83 | +def iter_blocks(data: bytes, start: int = 0) -> Iterator[MapBlock]: |
| 84 | + """Yield consecutive blocks from ``data`` beginning at byte ``start``. |
| 85 | +
|
| 86 | + The sequence must consume ``data`` exactly. A header shorter than eight |
| 87 | + bytes, a header or payload that runs past the end of ``data``, or a block |
| 88 | + that does not fit a complete common header is rejected. |
| 89 | + """ |
| 90 | + position = start |
| 91 | + end = len(data) |
| 92 | + while position < end: |
| 93 | + if end - position < COMMON_HEADER_LEN: |
| 94 | + raise RoborockException(f"Map block at offset {position} is shorter than its common header") |
| 95 | + block_type, header_length, payload_length = _COMMON_HEADER.unpack_from(data, position) |
| 96 | + if header_length < COMMON_HEADER_LEN: |
| 97 | + raise RoborockException(f"Map block at offset {position} declares header length {header_length} < 8") |
| 98 | + block_end = position + header_length + payload_length |
| 99 | + if block_end > end: |
| 100 | + raise RoborockException(f"Map block at offset {position} extends past the end of the data") |
| 101 | + header_end = position + header_length |
| 102 | + yield MapBlock( |
| 103 | + block_type=block_type, |
| 104 | + payload=data[header_end:block_end], |
| 105 | + extra_header=data[position + COMMON_HEADER_LEN : header_end], |
| 106 | + ) |
| 107 | + position = block_end |
| 108 | + |
| 109 | + |
| 110 | +def parse_dynamic_value(data: bytes) -> list[MapBlock]: |
| 111 | + """Split a decoded dynamic ``data`` / ``robot_data`` value into blocks. |
| 112 | +
|
| 113 | + A dynamic value is a bare block sequence: there is no ``rr`` file header |
| 114 | + and no digest. An empty value yields no blocks. A value that reaches a |
| 115 | + fifth block is rejected, so a non-empty value holds one to four blocks. |
| 116 | + """ |
| 117 | + blocks: list[MapBlock] = [] |
| 118 | + for block in iter_blocks(data): |
| 119 | + if len(blocks) == MAX_DYNAMIC_VALUE_BLOCKS: |
| 120 | + raise RoborockException(f"Dynamic map value holds more than {MAX_DYNAMIC_VALUE_BLOCKS} blocks") |
| 121 | + blocks.append(block) |
| 122 | + return blocks |
| 123 | + |
| 124 | + |
| 125 | +def encode_blocks(blocks: Iterable[MapBlock]) -> bytes: |
| 126 | + """Serialize a block sequence without any file header.""" |
| 127 | + return b"".join(block.encode() for block in blocks) |
| 128 | + |
| 129 | + |
| 130 | +@dataclass(frozen=True) |
| 131 | +class MapFile: |
| 132 | + """A full V1 map file split into its file header and framed blocks.""" |
| 133 | + |
| 134 | + header: bytes |
| 135 | + """The ``rr`` file header, kept verbatim so it round-trips unchanged.""" |
| 136 | + |
| 137 | + blocks: list[MapBlock] |
| 138 | + |
| 139 | + def encode(self) -> bytes: |
| 140 | + """Serialize the file header followed by every block.""" |
| 141 | + return self.header + encode_blocks(self.blocks) |
| 142 | + |
| 143 | + |
| 144 | +def split_map_file(map_bytes: bytes) -> MapFile: |
| 145 | + """Split a decompressed full map into its file header and blocks.""" |
| 146 | + if not map_bytes.startswith(MAP_FILE_MAGIC): |
| 147 | + raise RoborockException("Map file does not start with the 'rr' marker") |
| 148 | + if len(map_bytes) < _MAP_FILE_HEADER_LEN.size + 2: |
| 149 | + raise RoborockException("Map file is shorter than its header length field") |
| 150 | + (header_length,) = _MAP_FILE_HEADER_LEN.unpack_from(map_bytes, 2) |
| 151 | + if header_length < 4 or header_length > len(map_bytes): |
| 152 | + raise RoborockException(f"Map file declares an invalid header length {header_length}") |
| 153 | + return MapFile(header=map_bytes[:header_length], blocks=list(iter_blocks(map_bytes, header_length))) |
| 154 | + |
| 155 | + |
| 156 | +def find_block(blocks: Iterable[MapBlock], block_type: int) -> MapBlock | None: |
| 157 | + """Return the first block of ``block_type``, or ``None`` when absent.""" |
| 158 | + for block in blocks: |
| 159 | + if block.block_type == block_type: |
| 160 | + return block |
| 161 | + return None |
| 162 | + |
| 163 | + |
| 164 | +def replace_block(blocks: list[MapBlock], new_block: MapBlock) -> list[MapBlock]: |
| 165 | + """Return a new block list with ``new_block`` substituted for its type. |
| 166 | +
|
| 167 | + The first existing block of the same type is replaced in place, so the |
| 168 | + relative order the map parser depends on (for example mop flags after |
| 169 | + the path they describe) is preserved. When the type is not present the |
| 170 | + block is inserted before the trailing digest, or appended when there is |
| 171 | + no digest. |
| 172 | + """ |
| 173 | + for index, block in enumerate(blocks): |
| 174 | + if block.block_type == new_block.block_type: |
| 175 | + return [*blocks[:index], new_block, *blocks[index + 1 :]] |
| 176 | + for index, block in enumerate(blocks): |
| 177 | + if block.block_type == DIGEST_BLOCK_TYPE: |
| 178 | + return [*blocks[:index], new_block, *blocks[index:]] |
| 179 | + return [*blocks, new_block] |
| 180 | + |
| 181 | + |
| 182 | +@dataclass(frozen=True) |
| 183 | +class NonceTable: |
| 184 | + """Decoded block 34: identities of the base map and its dynamic elements. |
| 185 | +
|
| 186 | + Nonces are opaque 32-bit identities. Only equality is meaningful. They are |
| 187 | + decoded unsigned to preserve all 32 bits. JSON values may use a signed |
| 188 | + representation, as the app's binary reader does. Callers must normalize |
| 189 | + JSON nonces with ``value & 0xFFFFFFFF`` before comparing them to this table. |
| 190 | + """ |
| 191 | + |
| 192 | + map_nonce: int | None |
| 193 | + """Nonce of the base map (entry 35), or ``None`` when the table lacks it.""" |
| 194 | + |
| 195 | + element_nonces: dict[int, int] |
| 196 | + """Element nonce keyed by element id, excluding the map nonce entry.""" |
| 197 | + |
| 198 | + |
| 199 | +def decode_nonce_table(block: MapBlock) -> NonceTable: |
| 200 | + """Decode a block 34 nonce table. |
| 201 | +
|
| 202 | + The header carries ``num`` as a u32 at offset 8. The payload holds ``num`` |
| 203 | + five-byte entries, each a one-byte identifier followed by a u32 nonce. |
| 204 | + """ |
| 205 | + if block.block_type != NONCE_TABLE_BLOCK_TYPE: |
| 206 | + raise RoborockException(f"Block type {block.block_type} is not a nonce table") |
| 207 | + if block.header_length < _NONCE_TABLE_MIN_HEADER_LEN: |
| 208 | + raise RoborockException("Nonce table header is shorter than 12 bytes") |
| 209 | + (num,) = _NONCE_TABLE_NUM.unpack_from(block.extra_header, 0) |
| 210 | + if len(block.payload) < num * _NONCE_ENTRY.size: |
| 211 | + raise RoborockException(f"Nonce table declares {num} entries but the payload is too short") |
| 212 | + map_nonce: int | None = None |
| 213 | + element_nonces: dict[int, int] = {} |
| 214 | + for index in range(num): |
| 215 | + entry_id, nonce = _NONCE_ENTRY.unpack_from(block.payload, index * _NONCE_ENTRY.size) |
| 216 | + if entry_id == MAP_NONCE_ENTRY_ID: |
| 217 | + map_nonce = nonce |
| 218 | + else: |
| 219 | + element_nonces[entry_id] = nonce |
| 220 | + return NonceTable(map_nonce=map_nonce, element_nonces=element_nonces) |
0 commit comments