Skip to content

Commit aa9ce28

Browse files
authored
feat(map): add V1 map block container helpers (#1001)
* feat: add v1 map block container helpers for dynamic map diffs Add byte-level helpers for the block framing shared by V1 map files and the data values returned by get_dynamic_map_diff / get_dynamic_data: splitting and re-encoding block sequences, the bounded dynamic-value validator, block substitution that preserves parser-relevant ordering, and the block 34 nonce table decoder. * docs(map): clarify normalization of JSON nonces * fix(map): use typing.Self and cover absent find_block case
1 parent 4c0586d commit aa9ce28

2 files changed

Lines changed: 404 additions & 0 deletions

File tree

‎roborock/map/dynamic_blocks.py‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
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

Comments
 (0)