From b397491acddda30c4fe06a81be073bfd9878cec6 Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Wed, 21 Oct 2026 23:27:29 -0400 Subject: [PATCH 01/19] Keep each robot's last-known state in a persistent store The last status, battery and error a robot sent, its last position and the map it was on, and when it last spoke or went offline, written under device_snapshots/ so it survives a restart. A robot that dies or loses Wi-Fi stops answering; this is what is left to say where it was. Co-Authored-By: Claude Sonnet 5.5 --- .../bundled_backend/shared/context.py | 2 + .../shared/device_snapshot_store.py | 276 ++++++++++++++++++ src/roborock_local_server/server.py | 3 + tests/test_device_snapshot_store.py | 133 +++++++++ 4 files changed, 414 insertions(+) create mode 100644 src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py create mode 100644 tests/test_device_snapshot_store.py diff --git a/src/roborock_local_server/bundled_backend/shared/context.py b/src/roborock_local_server/bundled_backend/shared/context.py index 69dc72c..e91cf4e 100644 --- a/src/roborock_local_server/bundled_backend/shared/context.py +++ b/src/roborock_local_server/bundled_backend/shared/context.py @@ -15,6 +15,7 @@ from .http_helpers import pick_first from .runtime_credentials import RuntimeCredentialsStore from .runtime_state import RuntimeState +from .device_snapshot_store import DeviceSnapshotStore from .zone_ranges_store import ZoneRangesStore _DEVICE_ID_KEYS = ("did", "d", "duid", "device_id", "deviceId", "device_did", "deviceDid") @@ -70,6 +71,7 @@ class ServerContext: runtime_state: RuntimeState | None = None runtime_credentials: RuntimeCredentialsStore | None = None zone_ranges_store: ZoneRangesStore | None = None + snapshot_store: DeviceSnapshotStore | None = None timezone: str | None = None # TURN/STUN advertised to the robot for camera sessions (see routes/fw/createca.py). turn_enabled: bool = False diff --git a/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py b/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py new file mode 100644 index 0000000..6f6d01c --- /dev/null +++ b/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py @@ -0,0 +1,276 @@ +"""Persistent last-known state of each robot the server manages. + +A robot that dies, loses Wi-Fi or gets stuck stops answering, and from then on nothing +can say where it was or what it last reported. This store keeps, per device, the last +status, battery and error the robot sent, its last position on the map and the map it +was drawn on, and when it last spoke or went offline. It survives a server restart. + +It is fed from the MQTT proxy: status pushes (``dps`` 120/121/122), ``get_status`` +answers, and the ``get_map_v1`` reply, which is decrypted with the nonce of the request +that asked for it. Position needs that map; nothing else in the protocol carries it. +""" + +from __future__ import annotations + +import base64 +import json +import logging +import re +import struct +import threading +import time +from pathlib import Path +from typing import Any + +from .data_helpers import utcnow_iso + +logger = logging.getLogger(__name__) + +_DIR_NAME = "device_snapshots" +_MAX_NONCES_PER_DEVICE = 16 +_SAFE_DUID = re.compile(r"^[A-Za-z0-9_-]+$") + +# dps keys the robot pushes on its own. +_DPS_ERROR = "120" +_DPS_STATE = "121" +_DPS_BATTERY = "122" + +_SECURITY_RE = re.compile(r'"endpoint\\?":\s*\\?"(\w+)\\?",\s*\\?"nonce\\?":\s*\\?"([0-9a-fA-F]+)') + + +def _int_or_none(value: Any) -> int | None: + if isinstance(value, bool): + return None + if isinstance(value, int): + return value + if isinstance(value, float) and value.is_integer(): + return int(value) + return None + + +def _point(point: Any) -> dict[str, int] | None: + if point is None: + return None + try: + return {"x": int(point.x), "y": int(point.y), "angle": int(getattr(point, "a", 0) or 0)} + except (AttributeError, TypeError, ValueError): + return None + + +def _parse_map(map_bytes: bytes) -> tuple[dict[str, int] | None, dict[str, int] | None]: + """(robot position, charger position) in robot millimetres, or Nones if it will not parse.""" + from roborock.map.map_parser import MapParser, MapParserConfig + + parsed = MapParser(MapParserConfig()).parse(map_bytes) + map_data = parsed.map_data if parsed is not None else None + if map_data is None: + return None, None + return _point(map_data.vacuum_position), _point(map_data.charger) + + +class DeviceSnapshotStore: + """Thread-safe, file-backed last-known state per device, keyed by duid.""" + + def __init__(self, directory: Path, *, flush_interval_s: float = 30.0, map_interval_s: float = 60.0) -> None: + self._dir = directory / _DIR_NAME + self._flush_interval_s = flush_interval_s + self._map_interval_s = map_interval_s + self._lock = threading.RLock() + self._data: dict[str, dict[str, Any]] = {} + self._maps: dict[str, bytes] = {} + self._nonces: dict[str, dict[str, str]] = {} + self._dirty: set[str] = set() + self._dirty_maps: set[str] = set() + self._last_flush = 0.0 + self._last_map_at: dict[str, float] = {} + self._load() + + # ---- persistence ------------------------------------------------------------- + + def _load(self) -> None: + try: + files = sorted(self._dir.glob("*.json")) + except OSError: + return + for path in files: + try: + raw = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + continue + duid = str(raw.get("duid") or path.stem) if isinstance(raw, dict) else "" + if not isinstance(raw, dict) or not duid or not _SAFE_DUID.match(duid): + continue + self._data[duid] = raw + map_path = self._dir / f"{duid}.map" + if map_path.exists(): + try: + self._maps[duid] = map_path.read_bytes() + except OSError: + pass + + def flush(self) -> None: + """Write everything changed since the last flush.""" + with self._lock: + dirty, dirty_maps = set(self._dirty), set(self._dirty_maps) + if not dirty and not dirty_maps: + return + try: + self._dir.mkdir(parents=True, exist_ok=True) + except OSError: + return + for duid in dirty: + self._write(self._dir / f"{duid}.json", json.dumps(self._data[duid], separators=(",", ":")).encode()) + for duid in dirty_maps: + if duid in self._maps: + self._write(self._dir / f"{duid}.map", self._maps[duid]) + self._dirty.clear() + self._dirty_maps.clear() + self._last_flush = time.monotonic() + + @staticmethod + def _write(path: Path, content: bytes) -> None: + tmp = path.with_suffix(path.suffix + ".tmp") + try: + tmp.write_bytes(content) + tmp.replace(path) + except OSError: + logger.warning("Could not write %s", path) + + def _touch(self, duid: str, *, force_flush: bool = False) -> None: + self._dirty.add(duid) + if force_flush or time.monotonic() - self._last_flush >= self._flush_interval_s: + self.flush() + + # ---- recording --------------------------------------------------------------- + + def _entry(self, duid: str) -> dict[str, Any]: + entry = self._data.get(duid) + if entry is None: + entry = {"duid": duid, "last_seen_at": None, "offline_at": None, "status": {}, "position": None} + self._data[duid] = entry + return entry + + def mark_seen(self, duid: str) -> None: + """The robot spoke: it is online, so any earlier offline mark is cleared.""" + if not _SAFE_DUID.match(duid or ""): + return + with self._lock: + entry = self._entry(duid) + entry["last_seen_at"] = utcnow_iso() + if entry.get("offline_at"): + entry["offline_at"] = None + self._touch(duid, force_flush=True) + else: + self._touch(duid) + + def mark_offline(self, duid: str) -> None: + """The robot's connection closed. Written at once, since the next restart may lose the rest.""" + if not _SAFE_DUID.match(duid or ""): + return + with self._lock: + entry = self._entry(duid) + if not entry.get("offline_at"): + entry["offline_at"] = utcnow_iso() + self._touch(duid, force_flush=True) + + def record_dps(self, duid: str, payload_utf8: str | None) -> None: + """A status push, ``{"dps": {"122": 5}}``.""" + if not payload_utf8 or not _SAFE_DUID.match(duid or ""): + return + try: + payload = json.loads(payload_utf8) + except (TypeError, json.JSONDecodeError): + return + dps = payload.get("dps") if isinstance(payload, dict) else None + if not isinstance(dps, dict): + return + update: dict[str, int] = {} + for key, name in ((_DPS_STATE, "state"), (_DPS_BATTERY, "battery"), (_DPS_ERROR, "error_code")): + value = _int_or_none(dps.get(key)) + if value is not None: + update[name] = value + if update: + self._update_status(duid, update) + + def record_status_result(self, duid: str, result: Any) -> None: + """The answer to ``get_status``: a one-item list holding the status object.""" + status = result[0] if isinstance(result, list) and result else result + if not isinstance(status, dict) or not _SAFE_DUID.match(duid or ""): + return + update: dict[str, int] = {} + for key in ("state", "battery", "error_code", "clean_percent"): + value = _int_or_none(status.get(key)) + if value is not None: + update[key] = value + if update: + self._update_status(duid, update) + + def _update_status(self, duid: str, update: dict[str, int]) -> None: + with self._lock: + entry = self._entry(duid) + status = entry.setdefault("status", {}) + status.update(update) + status["updated_at"] = utcnow_iso() + self._touch(duid) + + def note_request(self, duid: str, payload_utf8: str | None) -> None: + """Remember the nonce a client sent with a request, so its map reply can be decrypted.""" + if not payload_utf8 or "security" not in payload_utf8 or not _SAFE_DUID.match(duid or ""): + return + found = _SECURITY_RE.search(payload_utf8) + if found is None: + return + endpoint, nonce = found.group(1), found.group(2) + with self._lock: + nonces = self._nonces.setdefault(duid, {}) + nonces.pop(endpoint, None) + nonces[endpoint] = nonce + while len(nonces) > _MAX_NONCES_PER_DEVICE: + nonces.pop(next(iter(nonces))) + + def record_map(self, duid: str, payload: bytes) -> None: + """A ``get_map_v1`` reply (protocol 301): decrypt, keep the map, and read the robot's position.""" + if not payload or len(payload) < 24 or not _SAFE_DUID.match(duid or ""): + return + now = time.monotonic() + with self._lock: + if now - self._last_map_at.get(duid, 0.0) < self._map_interval_s: + return + endpoint = struct.unpack("<8s", payload[:8])[0].decode("ascii", "replace") + nonce = self._nonces.get(duid, {}).get(endpoint) + if nonce is None: + return + try: + from roborock.protocol import Utils + + # 24-byte header (endpoint, request id), then the gzipped map encrypted with the nonce. + map_bytes = Utils.decompress(Utils.decrypt_cbc(payload[24:], bytes.fromhex(nonce))) + position, charger = _parse_map(map_bytes) + except Exception: + logger.debug("Could not decode a map reply for %s", duid, exc_info=True) + return + with self._lock: + self._last_map_at[duid] = now + entry = self._entry(duid) + self._maps[duid] = map_bytes + self._dirty_maps.add(duid) + entry["position"] = { + "robot": position, + "charger": charger, + "map_updated_at": utcnow_iso(), + } + self._touch(duid) + + # ---- reading ----------------------------------------------------------------- + + def get(self, duid: str, *, include_map: bool = False) -> dict[str, Any] | None: + with self._lock: + entry = self._data.get(duid) + if entry is None: + return None + result = json.loads(json.dumps(entry)) + map_bytes = self._maps.get(duid) + result["has_map"] = map_bytes is not None + if include_map and map_bytes is not None: + result["map"] = base64.b64encode(map_bytes).decode("ascii") + return result diff --git a/src/roborock_local_server/server.py b/src/roborock_local_server/server.py index c0412ef..0cadd67 100644 --- a/src/roborock_local_server/server.py +++ b/src/roborock_local_server/server.py @@ -61,6 +61,7 @@ load_cloud_full_snapshot, with_current_server_urls, ) +from .bundled_backend.shared.device_snapshot_store import DeviceSnapshotStore from .bundled_backend.shared.zone_ranges_store import ZoneRangesStore from .security import AdminSessionManager, verify_password @@ -475,6 +476,7 @@ def __init__( runtime_state=self.runtime_state, runtime_credentials=self.runtime_credentials, zone_ranges_store=zone_ranges_store, + snapshot_store=DeviceSnapshotStore(self.paths.http_jsonl_path.parent), timezone=self.config.network.timezone or None, turn_enabled=self.config.turn.mode != "disabled", turn_host=self.config.turn.host or self.config.network.stack_fqdn, @@ -1904,6 +1906,7 @@ def _start_mqtt_proxy(self) -> None: runtime_state=self.runtime_state, runtime_credentials=self.runtime_credentials, zone_ranges_store=self.context.zone_ranges_store, + snapshot_store=self.context.snapshot_store, tls_enabled=self._uses_local_tls(), on_onboarding_credentials_learned=self.persist_active_onboarding_device, ) diff --git a/tests/test_device_snapshot_store.py b/tests/test_device_snapshot_store.py new file mode 100644 index 0000000..1741734 --- /dev/null +++ b/tests/test_device_snapshot_store.py @@ -0,0 +1,133 @@ +from __future__ import annotations + +import base64 +import gzip +import json +from pathlib import Path + +import pytest + +from roborock_local_server.bundled_backend.shared.device_snapshot_store import DeviceSnapshotStore + +DUID = "2e2txkqKqxVifcIdyOT1lY" + + +def _store(tmp_path: Path) -> DeviceSnapshotStore: + return DeviceSnapshotStore(tmp_path, flush_interval_s=0.0, map_interval_s=0.0) + + +def test_unknown_device_has_no_snapshot(tmp_path: Path) -> None: + assert _store(tmp_path).get(DUID) is None + + +def test_status_push_records_battery_state_and_error(tmp_path: Path) -> None: + store = _store(tmp_path) + store.record_dps(DUID, json.dumps({"t": 1, "dps": {"122": 5}})) + store.record_dps(DUID, json.dumps({"t": 2, "dps": {"121": 12, "120": 4}})) + + status = store.get(DUID)["status"] + + assert (status["battery"], status["state"], status["error_code"]) == (5, 12, 4) + assert status["updated_at"] + + +def test_get_status_answer_is_read_from_the_one_item_list(tmp_path: Path) -> None: + store = _store(tmp_path) + store.record_status_result(DUID, [{"state": 8, "battery": 100, "error_code": 0, "ignored": "x"}]) + + status = store.get(DUID)["status"] + + assert (status["state"], status["battery"], status["error_code"]) == (8, 100, 0) + assert "ignored" not in status + + +def test_dps_ignores_unrelated_or_malformed_payloads(tmp_path: Path) -> None: + store = _store(tmp_path) + store.record_dps(DUID, "not json") + store.record_dps(DUID, json.dumps({"dps": {"101": "{}"}})) + store.record_dps(DUID, json.dumps({"dps": {"122": True}})) + + assert store.get(DUID) is None + + +def test_offline_is_marked_and_cleared_when_the_robot_speaks_again(tmp_path: Path) -> None: + store = _store(tmp_path) + store.mark_seen(DUID) + store.mark_offline(DUID) + assert store.get(DUID)["offline_at"] + + store.mark_seen(DUID) + assert store.get(DUID)["offline_at"] is None + + +def test_state_survives_a_restart(tmp_path: Path) -> None: + store = _store(tmp_path) + store.record_dps(DUID, json.dumps({"dps": {"122": 5}})) + store.mark_offline(DUID) + store.flush() + + reopened = _store(tmp_path).get(DUID) + + assert reopened["status"]["battery"] == 5 + assert reopened["offline_at"] + + +def test_unsafe_device_ids_are_refused(tmp_path: Path) -> None: + store = _store(tmp_path) + for bad in ("", "../x", "a/b", "a b"): + store.mark_seen(bad) + store.mark_offline(bad) + store.record_dps(bad, json.dumps({"dps": {"122": 5}})) + + assert not (tmp_path / "device_snapshots").exists() + + +def test_request_nonce_is_found_in_the_escaped_rpc_payload(tmp_path: Path) -> None: + store = _store(tmp_path) + payload = ( + '{"dps":{"101":"{\\"id\\":29755,\\"method\\":\\"get_map_v1\\",\\"params\\":[],' + '\\"security\\":{\\"endpoint\\":\\"w5Mpv215\\",\\"nonce\\":\\"0fd7440a89d9e25af17aa00493c29025\\"}}"},"t":1}' + ) + + store.note_request(DUID, payload) + + assert store._nonces[DUID] == {"w5Mpv215": "0fd7440a89d9e25af17aa00493c29025"} + + +def test_map_reply_without_a_known_nonce_is_ignored(tmp_path: Path) -> None: + store = _store(tmp_path) + + store.record_map(DUID, b"w5Mpv215" + b"\x00" * 64) + + assert store.get(DUID) is None + + +def test_map_reply_is_decrypted_and_its_position_stored(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + from roborock.protocol import Utils + + from roborock_local_server.bundled_backend.shared import device_snapshot_store as module + + class Point: + def __init__(self, x: int, y: int, a: int) -> None: + self.x, self.y, self.a = x, y, a + + map_bytes = b"fake map bytes" + nonce = bytes(range(16)) + header = b"w5Mpv215" + b"\x00" * 8 + b"\x01\x00" + b"\x00" * 6 + body = Utils.encrypt_cbc(gzip.compress(map_bytes), nonce) + monkeypatch.setattr(module, "_parse_map", lambda data: (module._point(Point(24343, 38108, 170)), module._point(Point(26306, 25598, -177))) if data == map_bytes else (None, None)) + + store = _store(tmp_path) + store.note_request( + DUID, + '{"dps":{"101":"{\\"security\\":{\\"endpoint\\":\\"w5Mpv215\\",\\"nonce\\":\\"%s\\"}}"}}' % nonce.hex(), + ) + store.record_map(DUID, header + body) + + snapshot = store.get(DUID, include_map=True) + + assert snapshot["position"]["robot"] == {"x": 24343, "y": 38108, "angle": 170} + assert snapshot["position"]["charger"] == {"x": 26306, "y": 25598, "angle": -177} + assert base64.b64decode(snapshot["map"]) == map_bytes + assert snapshot["has_map"] is True + assert "map" not in store.get(DUID) From 44275cf4f872ffe313df42ec70de598d12490649 Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Wed, 21 Oct 2026 23:27:30 -0400 Subject: [PATCH 02/19] Feed the snapshot store from the MQTT proxy Robot-originated frames update the store: status pushes (dps 120/121/122), get_status answers, and the map reply, which is decrypted with the nonce of whichever client's request asked for it. A closing robot connection marks the device offline at once. Co-Authored-By: Claude Sonnet 5.5 --- .../mqtt_tls_proxy_server/server.py | 57 ++++++++++++++ tests/test_mqtt_tls_proxy.py | 75 +++++++++++++++++++ 2 files changed, 132 insertions(+) diff --git a/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py b/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py index e497909..afd85b7 100644 --- a/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py +++ b/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py @@ -19,6 +19,7 @@ from shared.protocol_auth import ProtocolAuthStore from shared.runtime_credentials import RuntimeCredentialsStore, parse_mqtt_connect_packet from shared.runtime_state import RuntimeState +from shared.device_snapshot_store import DeviceSnapshotStore from shared.zone_ranges_store import ZoneRangesStore from .command_handlers import RpcCommandRegistry @@ -46,6 +47,7 @@ def __init__( runtime_state: RuntimeState | None = None, runtime_credentials: RuntimeCredentialsStore | None = None, zone_ranges_store: ZoneRangesStore | None = None, + snapshot_store: DeviceSnapshotStore | None = None, tls_enabled: bool = True, on_onboarding_credentials_learned: Callable[[], None] | None = None, ) -> None: @@ -65,6 +67,8 @@ def __init__( self.runtime_state = runtime_state self.runtime_credentials = runtime_credentials self.zone_ranges_store = zone_ranges_store + self.snapshot_store = snapshot_store + self._conn_duids: dict[str, set[str]] = {} self._on_onboarding_credentials_learned = on_onboarding_credentials_learned self._server_socket: socket.socket | None = None self._running = False @@ -521,6 +525,54 @@ def _parse_v1_rpc_payload(payload_utf8: str | None, protocol_value: int) -> dict parsed["error"] = rpc_obj.get("error") return parsed + def _duid_for_topic(self, topic: str) -> str: + parts = topic.split("/") + if topic.startswith("rr/m/") and len(parts) >= 6: + return parts[5] + if topic.startswith("rr/d/") and len(parts) >= 5 and self.runtime_credentials is not None: + device = self.runtime_credentials.resolve_device(did=parts[3]) + return str(device.get("duid") or "") if device else "" + return "" + + def _observe_snapshot( + self, + conn_id: str, + direction: str, + topic: str, + proto_value: int, + decoded_entry: dict[str, Any], + payload_bytes: bytes, + ) -> None: + """Feed what the robot says into the last-known-state store.""" + if self.snapshot_store is None: + return + try: + duid = self._duid_for_topic(topic) + if not duid: + return + payload_utf8 = decoded_entry.get("payload_utf8") + payload_utf8 = payload_utf8 if isinstance(payload_utf8, str) else None + if proto_value == 101: + # Any client's request: the nonce in it is what decrypts the map reply it gets. + self.snapshot_store.note_request(duid, payload_utf8) + return + if not (topic.startswith("rr/d/i/") and direction == "c2b"): + return + with self._lock: + self._conn_duids.setdefault(conn_id, set()).add(duid) + self.snapshot_store.mark_seen(duid) + if proto_value == 301: + self.snapshot_store.record_map(duid, payload_bytes) + elif proto_value == 102: + response_to = decoded_entry.get("response_to") + if isinstance(response_to, dict): + if response_to.get("request_method") == "get_status" and response_to.get("error") is None: + self.snapshot_store.record_status_result(duid, response_to.get("result")) + else: + self.snapshot_store.record_dps(duid, payload_utf8) + except Exception: + self.logger.exception("[conn %s] snapshot update failed", conn_id) + def _trace_packet(self, conn_id: str, direction: str, packet: bytes) -> None: packet_type = packet[0] >> 4 if packet_type in (12, 13): # PINGREQ, PINGRESP @@ -661,6 +713,7 @@ def _trace_packet(self, conn_id: str, direction: str, packet: bytes) -> None: response_to.get("request_method"), response_to.get("error"), ) + self._observe_snapshot(conn_id, direction, topic, proto_value, decoded_entry, payload_bytes) decoded_messages.append(decoded_entry) self.logger.info( "[conn %s %s] PUBLISH topic=%s proto=%s(%d) ver=%s seq=%s key_source=%s payload=%s", @@ -815,6 +868,10 @@ def _handle_client(self, tls_conn: socket.socket | ssl.SSLSocket, addr: tuple[st self.runtime_state.record_mqtt_disconnect(conn_id=conn_id) with self._lock: self._conn_protocol_levels.pop(conn_id, None) + gone_duids = self._conn_duids.pop(conn_id, set()) + if self.snapshot_store is not None: + for duid in gone_duids: + self.snapshot_store.mark_offline(duid) self.logger.info("[conn %s] closed", conn_id) def start(self) -> threading.Thread: diff --git a/tests/test_mqtt_tls_proxy.py b/tests/test_mqtt_tls_proxy.py index 61d7e33..07866c5 100644 --- a/tests/test_mqtt_tls_proxy.py +++ b/tests/test_mqtt_tls_proxy.py @@ -1195,3 +1195,78 @@ def test_stalled_tls_handshake_is_closed_after_timeout(start_tls_proxy) -> None: proxy = start_tls_proxy(handshake_timeout_seconds=0.5) with socket.create_connection(("127.0.0.1", proxy.listen_port), timeout=5) as stalled: assert stalled.recv(1) == b"" + + +class _FakeCredentials: + def resolve_device(self, *, did: str = "", duid: str = "", model: str = "") -> dict[str, str] | None: + return {"duid": "DUID1"} if did == "1103829226788" else None + + +def _snapshot_proxy(tmp_path): + from roborock_local_server.bundled_backend.shared.device_snapshot_store import DeviceSnapshotStore + + store = DeviceSnapshotStore(tmp_path, flush_interval_s=0.0, map_interval_s=0.0) + proxy = MqttTlsProxy( + cert_file=tmp_path / "fullchain.pem", + key_file=tmp_path / "privkey.pem", + listen_host="127.0.0.1", + listen_port=8883, + backend_host="127.0.0.1", + backend_port=1883, + localkey="test-local-key", + logger=logging.getLogger("test.mqtt_tls_proxy"), + decoded_jsonl=tmp_path / "decoded.jsonl", + runtime_credentials=_FakeCredentials(), + snapshot_store=store, + ) + return proxy, store + + +def test_robot_status_push_updates_the_snapshot_and_remembers_the_connection(tmp_path) -> None: + proxy, store = _snapshot_proxy(tmp_path) + + proxy._observe_snapshot( + "7", "c2b", "rr/d/i/1103829226788/abc", 102, {"payload_utf8": '{"t":1,"dps":{"122":5}}'}, b"", + ) + + assert store.get("DUID1")["status"]["battery"] == 5 + assert proxy._conn_duids["7"] == {"DUID1"} + + +def test_get_status_answer_updates_the_snapshot(tmp_path) -> None: + proxy, store = _snapshot_proxy(tmp_path) + + proxy._observe_snapshot( + "7", + "c2b", + "rr/d/i/1103829226788/abc", + 102, + {"response_to": {"request_method": "get_status", "error": None, "result": [{"state": 8, "battery": 100}]}}, + b"", + ) + + assert store.get("DUID1")["status"]["state"] == 8 + + +def test_frames_that_are_not_from_the_robot_do_not_mark_it_seen(tmp_path) -> None: + proxy, store = _snapshot_proxy(tmp_path) + + # An app's request travels on rr/m/i; the broker's copy toward the robot is rr/d/o. + proxy._observe_snapshot( + "9", "c2b", "rr/m/i/user/abcd1234/DUID1", 102, {"payload_utf8": '{"dps":{"122":5}}'}, b"", + ) + proxy._observe_snapshot( + "9", "b2c", "rr/d/o/1103829226788/abc", 102, {"payload_utf8": '{"dps":{"122":5}}'}, b"", + ) + + assert store.get("DUID1") is None + assert "9" not in proxy._conn_duids + + +def test_a_request_with_a_nonce_is_remembered_for_its_map_reply(tmp_path) -> None: + proxy, store = _snapshot_proxy(tmp_path) + payload = '{"dps":{"101":"{\\"security\\":{\\"endpoint\\":\\"w5Mpv215\\",\\"nonce\\":\\"00ff\\"}}"}}' + + proxy._observe_snapshot("9", "c2b", "rr/m/i/user/abcd1234/DUID1", 101, {"payload_utf8": payload}, b"") + + assert store._nonces["DUID1"] == {"w5Mpv215": "00ff"} From bbbc516d408aab7026d464b713a65adbc84e31ee Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Wed, 21 Oct 2026 23:27:30 -0400 Subject: [PATCH 03/19] Serve a robot's last-known state at /user/devices/{duid}/last_known Returns status, position, last_seen_at and offline_at; ?map=1 adds the last map the robot sent so a client can draw it while the robot cannot be asked. Co-Authored-By: Claude Sonnet 5.5 --- .../https_server/endpoint_rules.py | 3 ++ .../routes/user/devices/last_known.py | 35 +++++++++++++++++++ tests/test_admin_api.py | 28 +++++++++++++++ 3 files changed, 66 insertions(+) create mode 100644 src/roborock_local_server/bundled_backend/https_server/routes/user/devices/last_known.py diff --git a/src/roborock_local_server/bundled_backend/https_server/endpoint_rules.py b/src/roborock_local_server/bundled_backend/https_server/endpoint_rules.py index f2f2dcf..e5ad7dc 100644 --- a/src/roborock_local_server/bundled_backend/https_server/endpoint_rules.py +++ b/src/roborock_local_server/bundled_backend/https_server/endpoint_rules.py @@ -121,6 +121,8 @@ from .routes.user.deviceshare import match_rooms as _match_get_shared_device_rooms from .routes.user.devices.jobs import build as _build_get_schedules from .routes.user.devices.jobs import match as _match_get_schedules +from .routes.user.devices.last_known import build as _build_last_known +from .routes.user.devices.last_known import match as _match_last_known from .routes.user.devices.newadd import build as _build_add_device from .routes.user.devices.newadd import match as _match_add_device from .routes.user.homes.item import build as _build_get_home_data @@ -609,6 +611,7 @@ def default_endpoint_rules() -> Sequence[EndpointRule]: EndpointRule("get_device", _match_get_device, _build_get_device), EndpointRule("get_device_extra", _match_get_device_extra, _build_get_device_extra), EndpointRule("get_schedules", _match_get_schedules, _build_get_schedules), + EndpointRule("get_device_last_known", _match_last_known, _build_last_known), EndpointRule("post_app_info", _match_post_app_info, _build_post_app_info), EndpointRule("get_inbox_latest", _match_get_inbox_latest, _build_get_inbox_latest), EndpointRule("get_products_v4", _match_get_products_v4, _build_get_products_v4), diff --git a/src/roborock_local_server/bundled_backend/https_server/routes/user/devices/last_known.py b/src/roborock_local_server/bundled_backend/https_server/routes/user/devices/last_known.py new file mode 100644 index 0000000..c2023b4 --- /dev/null +++ b/src/roborock_local_server/bundled_backend/https_server/routes/user/devices/last_known.py @@ -0,0 +1,35 @@ +from __future__ import annotations + +import re +from typing import Any + +from shared.context import ServerContext +from shared.http_helpers import wrap_response + + +def match(path: str) -> bool: + clean = path.rstrip("/") + return bool(re.fullmatch(r"/user/devices/[^/]+/last_known", clean)) + + +def build( + ctx: ServerContext, + query_params: dict[str, list[str]], + _body_params: dict[str, list[str]], + clean_path: str, +) -> dict[str, Any]: + """The robot's last-known state: status, position, and when it last spoke or went offline. + + ``?map=1`` adds the last map the robot sent (base64 of the same bytes ``get_map_v1`` returns + once decrypted and decompressed), so a client can draw it while the robot cannot be asked. + """ + parts = [part for part in clean_path.rstrip("/").split("/") if part] + duid = parts[-2] if len(parts) >= 2 else "" + store = ctx.snapshot_store + snapshot = None + if store is not None: + include_map = (query_params.get("map") or [""])[0] in ("1", "true") + snapshot = store.get(duid, include_map=include_map) + if snapshot is None: + return wrap_response({"duid": duid, "known": False}) + return wrap_response({**snapshot, "known": True}) diff --git a/tests/test_admin_api.py b/tests/test_admin_api.py index 13341a3..a59cc11 100644 --- a/tests/test_admin_api.py +++ b/tests/test_admin_api.py @@ -1602,3 +1602,31 @@ def test_create_room_returns_bare_id_in_result_and_object_in_data(tmp_path: Path assert body["data"]["id"] == body["result"] assert body["data"]["name"] == "Study" assert body["data"]["created"] is True + + +def test_last_known_route_returns_the_stored_snapshot(tmp_path: Path) -> None: + config_file = write_release_config(tmp_path) + config = load_config(config_file) + paths = resolve_paths(config_file, config) + _seed_protocol_snapshot(paths.cloud_snapshot_path) + supervisor = ReleaseSupervisor(config=config, paths=paths) + client = TestClient(supervisor.app) + device_id = "6HL2zfniaoYYV01CkVuhkO" + path = f"/user/devices/{device_id}/last_known" + + from https_server.routes.user.devices.last_known import build as build_last_known + + assert build_last_known(supervisor.context, {}, {}, path)["data"] == {"duid": device_id, "known": False} + + store = supervisor.context.snapshot_store + store.record_dps(device_id, json.dumps({"dps": {"122": 5, "121": 12}})) + store.mark_offline(device_id) + + known = client.get(path, headers=_hawk_headers(paths.cloud_snapshot_path, path)) + assert known.status_code == 200 + data = known.json()["data"] + assert data["known"] is True + assert data["status"]["battery"] == 5 + assert data["offline_at"] + assert data["has_map"] is False + assert "map" not in data From 4902b811c9bdb055fb47b714b87feac8eae78cea Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Thu, 22 Oct 2026 20:02:09 -0400 Subject: [PATCH 04/19] Seed the snapshot store from the MQTT log on startup A robot that went quiet before the store existed still has its last status, battery and map in the decoded MQTT log. On startup, in a background thread, devices the store has no snapshot for are filled in from that log: last time heard, last status, and the last map decoded with the nonce of the request that asked for it. Devices that already have a snapshot are left alone. Co-Authored-By: Claude Sonnet 5.5 --- .../shared/device_snapshot_store.py | 206 +++++++++++++++--- src/roborock_local_server/server.py | 20 +- tests/test_device_snapshot_store.py | 88 ++++++++ 3 files changed, 278 insertions(+), 36 deletions(-) diff --git a/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py b/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py index 6f6d01c..3a85224 100644 --- a/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py +++ b/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py @@ -20,8 +20,11 @@ import threading import time from pathlib import Path +from collections.abc import Callable from typing import Any +from roborock_local_server.log_retention import iter_log_lines + from .data_helpers import utcnow_iso logger = logging.getLogger(__name__) @@ -38,6 +41,15 @@ _SECURITY_RE = re.compile(r'"endpoint\\?":\s*\\?"(\w+)\\?",\s*\\?"nonce\\?":\s*\\?"([0-9a-fA-F]+)') +def _bytes_from_hex(value: Any) -> bytes | None: + if not isinstance(value, str): + return None + try: + return bytes.fromhex(value) + except ValueError: + return None + + def _int_or_none(value: Any) -> int | None: if isinstance(value, bool): return None @@ -68,6 +80,56 @@ def _parse_map(map_bytes: bytes) -> tuple[dict[str, int] | None, dict[str, int] return _point(map_data.vacuum_position), _point(map_data.charger) +def _dps_update(payload_utf8: str | None) -> dict[str, int]: + """The status a push carries: ``{"dps": {"122": 5}}`` -> ``{"battery": 5}``.""" + if not payload_utf8: + return {} + try: + payload = json.loads(payload_utf8) + except (TypeError, json.JSONDecodeError): + return {} + dps = payload.get("dps") if isinstance(payload, dict) else None + if not isinstance(dps, dict): + return {} + update: dict[str, int] = {} + for key, name in ((_DPS_STATE, "state"), (_DPS_BATTERY, "battery"), (_DPS_ERROR, "error_code")): + value = _int_or_none(dps.get(key)) + if value is not None: + update[name] = value + return update + + +def _status_update(result: Any) -> dict[str, int]: + """The status a ``get_status`` answer carries: a one-item list holding the status object.""" + status = result[0] if isinstance(result, list) and result else result + if not isinstance(status, dict): + return {} + update: dict[str, int] = {} + for key in ("state", "battery", "error_code", "clean_percent"): + value = _int_or_none(status.get(key)) + if value is not None: + update[key] = value + return update + + +def _security_of(payload_utf8: str | None) -> tuple[str, str] | None: + """(endpoint, nonce) from a request that asked for a map, or None.""" + if not payload_utf8 or "security" not in payload_utf8: + return None + found = _SECURITY_RE.search(payload_utf8) + return (found.group(1), found.group(2)) if found else None + + +def _decode_map(payload: bytes, nonce: str) -> tuple[bytes, dict[str, int] | None, dict[str, int] | None]: + """Decrypt a map reply: (the map bytes, robot position, charger position).""" + from roborock.protocol import Utils + + # 24-byte header (endpoint, request id), then the gzipped map encrypted with the nonce. + map_bytes = Utils.decompress(Utils.decrypt_cbc(payload[24:], bytes.fromhex(nonce))) + position, charger = _parse_map(map_bytes) + return map_bytes, position, charger + + class DeviceSnapshotStore: """Thread-safe, file-backed last-known state per device, keyed by duid.""" @@ -175,34 +237,14 @@ def mark_offline(self, duid: str) -> None: def record_dps(self, duid: str, payload_utf8: str | None) -> None: """A status push, ``{"dps": {"122": 5}}``.""" - if not payload_utf8 or not _SAFE_DUID.match(duid or ""): - return - try: - payload = json.loads(payload_utf8) - except (TypeError, json.JSONDecodeError): - return - dps = payload.get("dps") if isinstance(payload, dict) else None - if not isinstance(dps, dict): - return - update: dict[str, int] = {} - for key, name in ((_DPS_STATE, "state"), (_DPS_BATTERY, "battery"), (_DPS_ERROR, "error_code")): - value = _int_or_none(dps.get(key)) - if value is not None: - update[name] = value - if update: + update = _dps_update(payload_utf8) + if update and _SAFE_DUID.match(duid or ""): self._update_status(duid, update) def record_status_result(self, duid: str, result: Any) -> None: - """The answer to ``get_status``: a one-item list holding the status object.""" - status = result[0] if isinstance(result, list) and result else result - if not isinstance(status, dict) or not _SAFE_DUID.match(duid or ""): - return - update: dict[str, int] = {} - for key in ("state", "battery", "error_code", "clean_percent"): - value = _int_or_none(status.get(key)) - if value is not None: - update[key] = value - if update: + """The answer to ``get_status``.""" + update = _status_update(result) + if update and _SAFE_DUID.match(duid or ""): self._update_status(duid, update) def _update_status(self, duid: str, update: dict[str, int]) -> None: @@ -215,12 +257,10 @@ def _update_status(self, duid: str, update: dict[str, int]) -> None: def note_request(self, duid: str, payload_utf8: str | None) -> None: """Remember the nonce a client sent with a request, so its map reply can be decrypted.""" - if not payload_utf8 or "security" not in payload_utf8 or not _SAFE_DUID.match(duid or ""): + security = _security_of(payload_utf8) + if security is None or not _SAFE_DUID.match(duid or ""): return - found = _SECURITY_RE.search(payload_utf8) - if found is None: - return - endpoint, nonce = found.group(1), found.group(2) + endpoint, nonce = security with self._lock: nonces = self._nonces.setdefault(duid, {}) nonces.pop(endpoint, None) @@ -241,11 +281,7 @@ def record_map(self, duid: str, payload: bytes) -> None: if nonce is None: return try: - from roborock.protocol import Utils - - # 24-byte header (endpoint, request id), then the gzipped map encrypted with the nonce. - map_bytes = Utils.decompress(Utils.decrypt_cbc(payload[24:], bytes.fromhex(nonce))) - position, charger = _parse_map(map_bytes) + map_bytes, position, charger = _decode_map(payload, nonce) except Exception: logger.debug("Could not decode a map reply for %s", duid, exc_info=True) return @@ -261,6 +297,106 @@ def record_map(self, duid: str, payload: bytes) -> None: } self._touch(duid) + # ---- backfill ---------------------------------------------------------------- + + @staticmethod + def _duid_in_topic(topic: str, resolve_duid: Callable[[str], str]) -> str: + parts = topic.split("/") + if topic.startswith("rr/m/") and len(parts) >= 6: + return parts[5] + if topic.startswith("rr/d/") and len(parts) >= 5: + return resolve_duid(parts[3]) + return "" + + def seed_from_mqtt_jsonl(self, mqtt_jsonl: Path, resolve_duid: Callable[[str], str]) -> int: + """Fill in devices the store knows nothing about from the decoded MQTT log. + + The log holds what each robot last said, so a robot that stopped answering before this + store existed still gets its last status and map. A device that already has a snapshot is + left alone. ``resolve_duid`` turns the short id in a robot's topic into its duid. Returns + how many devices were added; it can take a while on a large log, so run it off the main + thread. + """ + with self._lock: + known = set(self._data) + nonces: dict[str, dict[str, str]] = {} + seen: dict[str, dict[str, Any]] = {} + for line in iter_log_lines(mqtt_jsonl): + # Most lines are neither a robot's own frame nor a map request; skip them unparsed. + if "rr/d/i/" not in line and "security" not in line: + continue + try: + entry = json.loads(line) + except json.JSONDecodeError: + continue + if not isinstance(entry, dict): + continue + topic = str(entry.get("topic") or "") + at = str(entry.get("time") or "") + duid = self._duid_in_topic(topic, resolve_duid) + if not duid or duid in known or not _SAFE_DUID.match(duid): + continue + from_robot = topic.startswith("rr/d/i/") and entry.get("direction") == "c2b" + for message in entry.get("decoded_messages") or []: + if not isinstance(message, dict): + continue + payload_utf8 = message.get("payload_utf8") + payload_utf8 = payload_utf8 if isinstance(payload_utf8, str) else None + proto = message.get("protocol_value") + if proto == 101: + security = _security_of(payload_utf8) + if security is not None: + nonces.setdefault(duid, {})[security[0]] = security[1] + continue + if not from_robot: + continue + acc = seen.setdefault(duid, {"status": {}, "status_at": None, "map": None}) + acc["last_seen_at"] = at + if proto == 301: + raw = _bytes_from_hex(message.get("payload_hex")) + if raw is not None and len(raw) >= 24: + nonce = nonces.get(duid, {}).get(raw[:8].decode("ascii", "replace")) + if nonce: + acc["map"] = (at, raw, nonce) + elif proto == 102: + response_to = message.get("response_to") + if isinstance(response_to, dict): + update = ( + _status_update(response_to.get("result")) + if response_to.get("request_method") == "get_status" and response_to.get("error") is None + else {} + ) + else: + update = _dps_update(payload_utf8) + if update: + acc["status"].update(update) + acc["status_at"] = at + + added = 0 + for duid, acc in seen.items(): + map_bytes = position = charger = None + if acc["map"] is not None: + try: + map_bytes, position, charger = _decode_map(acc["map"][1], acc["map"][2]) + except Exception: + logger.debug("Could not decode the last logged map for %s", duid, exc_info=True) + with self._lock: + if duid in self._data: + continue + entry = self._entry(duid) + entry["last_seen_at"] = acc.get("last_seen_at") + if acc["status"]: + entry["status"] = {**acc["status"], "updated_at": acc["status_at"]} + if map_bytes is not None: + self._maps[duid] = map_bytes + self._dirty_maps.add(duid) + entry["position"] = {"robot": position, "charger": charger, "map_updated_at": acc["map"][0]} + self._dirty.add(duid) + added += 1 + if added: + self.flush() + return added + # ---- reading ----------------------------------------------------------------- def get(self, duid: str, *, include_map: bool = False) -> dict[str, Any] | None: diff --git a/src/roborock_local_server/server.py b/src/roborock_local_server/server.py index 0cadd67..6e4322c 100644 --- a/src/roborock_local_server/server.py +++ b/src/roborock_local_server/server.py @@ -455,6 +455,7 @@ def __init__( backup_count=self.config.logging.backup_count, ) + snapshot_store = DeviceSnapshotStore(self.paths.http_jsonl_path.parent) self.context = ServerContext( api_host=self.config.network.stack_fqdn, mqtt_host=self.config.network.stack_fqdn, @@ -476,7 +477,7 @@ def __init__( runtime_state=self.runtime_state, runtime_credentials=self.runtime_credentials, zone_ranges_store=zone_ranges_store, - snapshot_store=DeviceSnapshotStore(self.paths.http_jsonl_path.parent), + snapshot_store=snapshot_store, timezone=self.config.network.timezone or None, turn_enabled=self.config.turn.mode != "disabled", turn_host=self.config.turn.host or self.config.network.stack_fqdn, @@ -486,9 +487,26 @@ def __init__( turn_realm=self.config.turn.realm or self.config.turn.host or self.config.network.stack_fqdn, turn_ttl=self.config.turn.ttl, ) + # A robot that went quiet before this store existed still has its last words in the MQTT log. + threading.Thread( + target=self._seed_snapshots, args=(snapshot_store,), daemon=True, name="snapshot-seed", + ).start() self.endpoint_rules = default_endpoint_rules() self.app = self._create_app() + def _seed_snapshots(self, store: DeviceSnapshotStore) -> None: + def resolve_duid(did: str) -> str: + device = self.runtime_credentials.resolve_device(did=did) + return str(device.get("duid") or "") if device else "" + + try: + added = store.seed_from_mqtt_jsonl(self.paths.mqtt_jsonl_path, resolve_duid) + except Exception: + self.root_logger.exception("Could not seed last-known device state from the MQTT log") + return + if added: + self.root_logger.info("Seeded last-known state for %d device(s) from the MQTT log", added) + def _init_zone_ranges_store(self) -> ZoneRangesStore: store = ZoneRangesStore(self.paths.http_jsonl_path.parent) if not store._data: diff --git a/tests/test_device_snapshot_store.py b/tests/test_device_snapshot_store.py index 1741734..1b585fa 100644 --- a/tests/test_device_snapshot_store.py +++ b/tests/test_device_snapshot_store.py @@ -131,3 +131,91 @@ def __init__(self, x: int, y: int, a: int) -> None: assert base64.b64decode(snapshot["map"]) == map_bytes assert snapshot["has_map"] is True assert "map" not in store.get(DUID) + + +def _log_line(time: str, direction: str, topic: str, *messages: dict) -> str: + return json.dumps({"time": time, "direction": direction, "topic": topic, "decoded_messages": list(messages)}) + "\n" + + +def _seed_log(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, map_bytes: bytes = b"last map bytes") -> Path: + from roborock.protocol import Utils + + from roborock_local_server.bundled_backend.shared import device_snapshot_store as module + + class Point: + def __init__(self, x: int, y: int, a: int) -> None: + self.x, self.y, self.a = x, y, a + + monkeypatch.setattr( + module, + "_parse_map", + lambda data: (module._point(Point(24343, 38108, 170)), module._point(Point(26306, 25598, -177))) + if data == map_bytes + else (None, None), + ) + nonce = bytes(range(16)) + header = b"w5Mpv215" + b"\x00" * 8 + b"\x01\x00" + b"\x00" * 6 + reply = header + Utils.encrypt_cbc(gzip.compress(map_bytes), nonce) + request = '{"dps":{"101":"{\\"security\\":{\\"endpoint\\":\\"w5Mpv215\\",\\"nonce\\":\\"%s\\"}}"}}' % nonce.hex() + robot = "rr/d/i/1103829226788/abc" + path = tmp_path / "decoded.jsonl" + path.write_text( + _log_line("2026-10-22T00:20:00+00:00", "c2b", f"rr/m/i/user/abcd1234/{DUID}", {"protocol_value": 101, "payload_utf8": request}) + + _log_line("2026-10-22T00:24:17+00:00", "c2b", robot, {"protocol_value": 102, "payload_utf8": '{"dps":{"122":7}}'}) + + _log_line("2026-10-22T00:25:00+00:00", "c2b", robot, {"protocol_value": 301, "payload_hex": reply.hex()}) + + _log_line( + "2026-10-22T00:30:00+00:00", "c2b", robot, + {"protocol_value": 102, "response_to": {"request_method": "get_status", "error": None, "result": [{"state": 2, "battery": 6}]}}, + ) + + _log_line("2026-10-22T00:33:57+00:00", "c2b", robot, {"protocol_value": 102, "payload_utf8": '{"dps":{"122":5}}'}) + # An app's own traffic and unrelated lines must not count as the robot speaking. + + _log_line("2026-10-22T03:00:00+00:00", "b2c", "rr/d/o/1103829226788/abc", {"protocol_value": 102, "payload_utf8": '{"dps":{"122":99}}'}) + + "not json at all\n", + encoding="utf-8", + ) + return path + + +def test_seed_recovers_the_last_status_map_and_time_from_the_log(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + log = _seed_log(tmp_path, monkeypatch) + store = _store(tmp_path / "state") + + added = store.seed_from_mqtt_jsonl(log, lambda did: DUID if did == "1103829226788" else "") + + snapshot = store.get(DUID, include_map=True) + assert added == 1 + assert snapshot["last_seen_at"] == "2026-10-22T00:33:57+00:00" + assert snapshot["status"]["battery"] == 5 + assert snapshot["status"]["state"] == 2 + assert snapshot["position"]["robot"] == {"x": 24343, "y": 38108, "angle": 170} + assert snapshot["position"]["map_updated_at"] == "2026-10-22T00:25:00+00:00" + assert base64.b64decode(snapshot["map"]) == b"last map bytes" + + +def test_seed_persists_so_a_restart_keeps_it(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + log = _seed_log(tmp_path, monkeypatch) + _store(tmp_path / "state").seed_from_mqtt_jsonl(log, lambda did: DUID) + + reopened = _store(tmp_path / "state").get(DUID) + + assert reopened["status"]["battery"] == 5 + assert reopened["position"]["robot"]["x"] == 24343 + + +def test_seed_leaves_a_device_that_already_has_a_snapshot_alone(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + log = _seed_log(tmp_path, monkeypatch) + store = _store(tmp_path / "state") + store.record_dps(DUID, json.dumps({"dps": {"122": 80}})) + + added = store.seed_from_mqtt_jsonl(log, lambda did: DUID) + + assert added == 0 + assert store.get(DUID)["status"]["battery"] == 80 + + +def test_seed_skips_robots_it_cannot_name_and_missing_logs(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + log = _seed_log(tmp_path, monkeypatch) + store = _store(tmp_path / "state") + + assert store.seed_from_mqtt_jsonl(log, lambda did: "") == 0 + assert store.seed_from_mqtt_jsonl(tmp_path / "missing.jsonl", lambda did: DUID) == 0 From dae14722f7c1d18ec828bbff47cb59cc0a28d804 Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Tue, 27 Oct 2026 17:19:09 -0400 Subject: [PATCH 05/19] Keep each robot's room table in its snapshot and serve room names with it The snapshot had the last map but not which segment is which room, so an offline map could only show generic labels. The proxy now records each get_room_mapping answer, the startup seed reads it from the MQTT log, and /last_known adds each room's name from the home data. Co-Authored-By: Claude Sonnet 5.5 Co-Authored-By: Claude Opus 5.5 --- .../routes/user/devices/last_known.py | 6 ++++ .../mqtt_tls_proxy_server/server.py | 2 ++ .../shared/device_snapshot_store.py | 33 ++++++++++++++++++- tests/test_admin_api.py | 25 ++++++++++++++ tests/test_device_snapshot_store.py | 23 +++++++++++++ 5 files changed, 88 insertions(+), 1 deletion(-) diff --git a/src/roborock_local_server/bundled_backend/https_server/routes/user/devices/last_known.py b/src/roborock_local_server/bundled_backend/https_server/routes/user/devices/last_known.py index c2023b4..c4fe2f4 100644 --- a/src/roborock_local_server/bundled_backend/https_server/routes/user/devices/last_known.py +++ b/src/roborock_local_server/bundled_backend/https_server/routes/user/devices/last_known.py @@ -6,6 +6,8 @@ from shared.context import ServerContext from shared.http_helpers import wrap_response +from ..homes.service import home_rooms_payload + def match(path: str) -> bool: clean = path.rstrip("/") @@ -32,4 +34,8 @@ def build( snapshot = store.get(duid, include_map=include_map) if snapshot is None: return wrap_response({"duid": duid, "known": False}) + # The robot's room table says which segment is which room; the home data knows the names. + names = {str(room.get("id")): room.get("name") for room in home_rooms_payload(ctx) if isinstance(room, dict)} + for room in snapshot.get("rooms") or []: + room["name"] = names.get(str(room.get("iot_id"))) return wrap_response({**snapshot, "known": True}) diff --git a/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py b/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py index afd85b7..c900cad 100644 --- a/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py +++ b/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py @@ -568,6 +568,8 @@ def _observe_snapshot( if isinstance(response_to, dict): if response_to.get("request_method") == "get_status" and response_to.get("error") is None: self.snapshot_store.record_status_result(duid, response_to.get("result")) + elif response_to.get("request_method") == "get_room_mapping" and response_to.get("error") is None: + self.snapshot_store.record_room_mapping(duid, response_to.get("result")) else: self.snapshot_store.record_dps(duid, payload_utf8) except Exception: diff --git a/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py b/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py index 3a85224..2e37c30 100644 --- a/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py +++ b/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py @@ -112,6 +112,19 @@ def _status_update(result: Any) -> dict[str, int]: return update +def _room_table(result: Any) -> list[dict[str, Any]]: + """The rows of a ``get_room_mapping`` answer, ``[segment, iot room id, type tag]``, as dicts.""" + rows: list[dict[str, Any]] = [] + for row in result if isinstance(result, list) else []: + if not isinstance(row, (list, tuple)) or len(row) < 2: + continue + segment = _int_or_none(row[0]) + if segment is None or row[1] in (None, ""): + continue + rows.append({"segment": segment, "iot_id": str(row[1]), "tag": _int_or_none(row[2]) if len(row) > 2 else None}) + return rows + + def _security_of(payload_utf8: str | None) -> tuple[str, str] | None: """(endpoint, nonce) from a request that asked for a map, or None.""" if not payload_utf8 or "security" not in payload_utf8: @@ -247,6 +260,17 @@ def record_status_result(self, duid: str, result: Any) -> None: if update and _SAFE_DUID.match(duid or ""): self._update_status(duid, update) + def record_room_mapping(self, duid: str, result: Any) -> None: + """The answer to ``get_room_mapping``: which room each map segment is, and its type.""" + rooms = _room_table(result) + if not rooms or not _SAFE_DUID.match(duid or ""): + return + with self._lock: + entry = self._entry(duid) + if entry.get("rooms") != rooms: + entry["rooms"] = rooms + self._touch(duid) + def _update_status(self, duid: str, update: dict[str, int]) -> None: with self._lock: entry = self._entry(duid) @@ -350,7 +374,7 @@ def seed_from_mqtt_jsonl(self, mqtt_jsonl: Path, resolve_duid: Callable[[str], s continue if not from_robot: continue - acc = seen.setdefault(duid, {"status": {}, "status_at": None, "map": None}) + acc = seen.setdefault(duid, {"status": {}, "status_at": None, "map": None, "rooms": []}) acc["last_seen_at"] = at if proto == 301: raw = _bytes_from_hex(message.get("payload_hex")) @@ -360,6 +384,11 @@ def seed_from_mqtt_jsonl(self, mqtt_jsonl: Path, resolve_duid: Callable[[str], s acc["map"] = (at, raw, nonce) elif proto == 102: response_to = message.get("response_to") + if isinstance(response_to, dict) and response_to.get("request_method") == "get_room_mapping": + rooms = _room_table(response_to.get("result")) if response_to.get("error") is None else [] + if rooms: + acc["rooms"] = rooms + continue if isinstance(response_to, dict): update = ( _status_update(response_to.get("result")) @@ -387,6 +416,8 @@ def seed_from_mqtt_jsonl(self, mqtt_jsonl: Path, resolve_duid: Callable[[str], s entry["last_seen_at"] = acc.get("last_seen_at") if acc["status"]: entry["status"] = {**acc["status"], "updated_at": acc["status_at"]} + if acc["rooms"]: + entry["rooms"] = acc["rooms"] if map_bytes is not None: self._maps[duid] = map_bytes self._dirty_maps.add(duid) diff --git a/tests/test_admin_api.py b/tests/test_admin_api.py index a59cc11..3a4a55b 100644 --- a/tests/test_admin_api.py +++ b/tests/test_admin_api.py @@ -1630,3 +1630,28 @@ def test_last_known_route_returns_the_stored_snapshot(tmp_path: Path) -> None: assert data["offline_at"] assert data["has_map"] is False assert "map" not in data + + +def test_last_known_route_names_each_room_of_the_robots_room_table(tmp_path: Path, monkeypatch) -> None: + config_file = write_release_config(tmp_path) + config = load_config(config_file) + paths = resolve_paths(config_file, config) + _seed_protocol_snapshot(paths.cloud_snapshot_path) + supervisor = ReleaseSupervisor(config=config, paths=paths) + device_id = "6HL2zfniaoYYV01CkVuhkO" + path = f"/user/devices/{device_id}/last_known" + + from https_server.routes.user.devices import last_known as route + + monkeypatch.setattr(route, "home_rooms_payload", lambda ctx: [{"id": 1, "name": "Living Room"}, {"id": 4, "name": "Kitchen"}]) + store = supervisor.context.snapshot_store + store.record_dps(device_id, json.dumps({"dps": {"122": 5}})) + store.record_room_mapping(device_id, [[21, "1", 6], [19, "4", 14], [18, "999", 1]]) + + rooms = route.build(supervisor.context, {}, {}, path)["data"]["rooms"] + + assert rooms == [ + {"segment": 21, "iot_id": "1", "tag": 6, "name": "Living Room"}, + {"segment": 19, "iot_id": "4", "tag": 14, "name": "Kitchen"}, + {"segment": 18, "iot_id": "999", "tag": 1, "name": None}, + ] diff --git a/tests/test_device_snapshot_store.py b/tests/test_device_snapshot_store.py index 1b585fa..3e8f486 100644 --- a/tests/test_device_snapshot_store.py +++ b/tests/test_device_snapshot_store.py @@ -219,3 +219,26 @@ def test_seed_skips_robots_it_cannot_name_and_missing_logs(tmp_path: Path, monke assert store.seed_from_mqtt_jsonl(log, lambda did: "") == 0 assert store.seed_from_mqtt_jsonl(tmp_path / "missing.jsonl", lambda did: DUID) == 0 + + +def test_room_mapping_answer_is_kept_and_survives_a_restart(tmp_path: Path) -> None: + store = _store(tmp_path) + store.record_room_mapping(DUID, [[21, "1001", 6], [16, "1002", 8], [18, "1003"]]) + store.flush() + + rooms = _store(tmp_path).get(DUID)["rooms"] + + assert rooms == [ + {"segment": 21, "iot_id": "1001", "tag": 6}, + {"segment": 16, "iot_id": "1002", "tag": 8}, + {"segment": 18, "iot_id": "1003", "tag": None}, + ] + + +def test_room_mapping_ignores_empty_and_malformed_answers(tmp_path: Path) -> None: + store = _store(tmp_path) + store.record_room_mapping(DUID, []) + store.record_room_mapping(DUID, "nope") + store.record_room_mapping(DUID, [["x", "1"], [3], [4, None]]) + + assert store.get(DUID) is None From 578bd2b1f0f14c670d6072e0ee470c304530de52 Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:00:24 -0500 Subject: [PATCH 06/19] Document the last-known robot state Co-Authored-By: Claude Sonnet 5.5 Co-Authored-By: Claude Opus 5.5 --- docs/last_known_state.md | 29 +++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 30 insertions(+) create mode 100644 docs/last_known_state.md diff --git a/docs/last_known_state.md b/docs/last_known_state.md new file mode 100644 index 0000000..4405574 --- /dev/null +++ b/docs/last_known_state.md @@ -0,0 +1,29 @@ +# Last-known robot state + +A robot that loses Wi-Fi, gets stuck or is switched off stops answering, and from then on nothing says where +it was or what it last reported. The server keeps that for every robot it manages, so a client can show the last +known picture instead of an empty screen. + +## What is kept + +Per robot, in `last_known/` under the data directory (it survives a restart): + +- When the robot last spoke, and when its connection last closed. +- The last status it sent: state, battery and error code. +- Its last position on the map and the map it was drawn on. +- Its room table (which map segment is which room), with the room names from the home data. + +It is fed from the MQTT proxy: status pushes (`dps` 120, 121 and 122), the answers to `get_status` and +`get_room_mapping`, and the `get_map_v1` reply, which is decrypted with the nonce of the request that asked for +it. On startup the store is seeded from the existing MQTT log, so a freshly updated server does not begin empty. + +## Reading it + +```text +GET /user/devices/{duid}/last_known +GET /user/devices/{duid}/last_known?map=1 +``` + +The answer is the usual `{"code": 200, "data": {...}}` envelope. `data.known` is `false` for a robot the server has +never heard from, which is how a client tells "never paired" from "paired and currently offline". With `?map=1` the +last map is included as base64 of the same bytes `get_map_v1` returns once decrypted and decompressed. diff --git a/mkdocs.yml b/mkdocs.yml index 7dd2153..be7c8d6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -59,6 +59,7 @@ nav: - Camera (Live Video): camera.md - Reference: - Log Retention: logging.md + - Last-Known State: last_known_state.md - Known Limitations: known_limitations.md - Scene Validity Reports: scene_validity.md - Tested Vacuums: tested_vacuums.md From a4f2719d754328b6ba255e854d0daa6758a83df1 Mon Sep 17 00:00:00 2001 From: Alex Babel Date: Fri, 30 Oct 2026 21:17:17 +0100 Subject: [PATCH 07/19] fix(plugin): resolve string product ids and serve the iOS app plugin The cloud lists newer models (e.g. roborock.vacuum.a226) under a string product id, so the import never fetched their app plugin and /api/v5/product answered with a hashed id that matches no plugin. The app then fails with "device initialization failed". The import now fetches the cloud's /api/v5/product to map models to their numeric id, and fetches /api/v1/appplugin for both type 2 (Android) and type 1 (iOS), which get different zips. The appplugin route answers iOS requests from the iOS catalog, falling back to the existing one. Fixes #221 --- .../routes/api/product_service.py | 10 +++- .../https_server/routes/api/v1/appplugin.py | 25 ++++++++- .../https_server/routes/plugin/common.py | 4 ++ .../import_web_inventory_from_cloud.py | 41 ++++++++------ .../bundled_backend/shared/data_helpers.py | 13 +++++ tests/test_cloud_plugin_catalogs.py | 53 +++++++++++++++++++ tests/test_plugin_routes.py | 41 ++++++++++++++ tests/test_product_response.py | 30 +++++++++++ 8 files changed, 196 insertions(+), 21 deletions(-) create mode 100644 tests/test_cloud_plugin_catalogs.py diff --git a/src/roborock_local_server/bundled_backend/https_server/routes/api/product_service.py b/src/roborock_local_server/bundled_backend/https_server/routes/api/product_service.py index 0c0d2c6..e450d8e 100644 --- a/src/roborock_local_server/bundled_backend/https_server/routes/api/product_service.py +++ b/src/roborock_local_server/bundled_backend/https_server/routes/api/product_service.py @@ -4,7 +4,9 @@ from shared.constants import MODEL_PRODUCT_ID_OVERRIDES from shared.context import ServerContext -from shared.data_helpers import as_int, default_product_name, stable_int +from shared.data_helpers import as_int, default_product_name, model_product_ids, stable_int + +from ..plugin.common import snapshot_plugin_catalog_data from ..user.homes.service import home_payload @@ -13,6 +15,7 @@ def build_product_response(ctx: ServerContext) -> dict[str, Any]: home_data = home_payload(ctx) products_value = home_data.get("products") products = products_value if isinstance(products_value, list) else [] + cloud_product_ids = model_product_ids(snapshot_plugin_catalog_data(ctx, "product")) categories: dict[str, dict[str, Any]] = {} for product in products: if not isinstance(product, dict): @@ -34,9 +37,12 @@ def build_product_response(ctx: ServerContext) -> dict[str, Any]: } model = str(product.get("model") or "roborock.vacuum.a117") model_key = model.strip().lower() + # String product ids (e.g. a226) take the cloud's numeric id for the model; + # plugins are keyed by it, so a hashed id gets the app no device plugin. product_id = MODEL_PRODUCT_ID_OVERRIDES.get( model_key, - as_int(raw_product_id, stable_int(raw_product_id or category_name) % 1_000_000), + cloud_product_ids.get(model_key) + or as_int(raw_product_id, stable_int(raw_product_id or category_name) % 1_000_000), ) product_entry = { "id": product_id, diff --git a/src/roborock_local_server/bundled_backend/https_server/routes/api/v1/appplugin.py b/src/roborock_local_server/bundled_backend/https_server/routes/api/v1/appplugin.py index b4a4edc..6f1b74a 100644 --- a/src/roborock_local_server/bundled_backend/https_server/routes/api/v1/appplugin.py +++ b/src/roborock_local_server/bundled_backend/https_server/routes/api/v1/appplugin.py @@ -1,5 +1,6 @@ from __future__ import annotations +import json from typing import Any from shared.context import ServerContext @@ -7,17 +8,37 @@ from ...auth.service import ok from ...plugin.common import APPPLUGIN_LIST, plugin_records_with_snapshot_fallback, proxied_plugin_records +# Request "type" of the iOS app; Android sends 2. +IOS_APP_TYPE = 1 + def match(path: str) -> bool: return path.rstrip("/") == "/api/v1/appplugin" +def _request_app_type(body_params: dict[str, list[str]]) -> int | None: + for raw in body_params.get("__json") or []: + try: + body = json.loads(raw) + except (TypeError, json.JSONDecodeError): + continue + if isinstance(body, dict): + try: + return int(body.get("type")) + except (TypeError, ValueError): + return None + return None + + def build( ctx: ServerContext, _query_params: dict[str, list[str]], - _body_params: dict[str, list[str]], + body_params: dict[str, list[str]], _clean_path: str, ) -> dict[str, Any]: records = plugin_records_with_snapshot_fallback(ctx, "appplugin", APPPLUGIN_LIST) + if _request_app_type(body_params) == IOS_APP_TYPE: + # Same plugin version, different zip: the iOS app cannot load the Android + # one. Imports from before the iOS catalog existed fall back to Android. + records = plugin_records_with_snapshot_fallback(ctx, "appplugin_ios", records) return ok(proxied_plugin_records(ctx, records)) - diff --git a/src/roborock_local_server/bundled_backend/https_server/routes/plugin/common.py b/src/roborock_local_server/bundled_backend/https_server/routes/plugin/common.py index 8a50285..1783813 100644 --- a/src/roborock_local_server/bundled_backend/https_server/routes/plugin/common.py +++ b/src/roborock_local_server/bundled_backend/https_server/routes/plugin/common.py @@ -156,6 +156,10 @@ def _dict_records(value: Any) -> list[dict[str, Any]]: return [dict(item) for item in value if isinstance(item, dict)] +def snapshot_plugin_catalog_data(ctx: ServerContext, catalog_name: str) -> Any: + return _catalog_data(_snapshot_plugin_catalogs(ctx), catalog_name) + + def snapshot_plugin_records( ctx: ServerContext, catalog_name: str, diff --git a/src/roborock_local_server/bundled_backend/import_web_inventory_from_cloud.py b/src/roborock_local_server/bundled_backend/import_web_inventory_from_cloud.py index ede4b30..ca09504 100644 --- a/src/roborock_local_server/bundled_backend/import_web_inventory_from_cloud.py +++ b/src/roborock_local_server/bundled_backend/import_web_inventory_from_cloud.py @@ -20,6 +20,8 @@ from roborock.exceptions import RoborockRateLimit from roborock.web_api import PreparedRequest, RoborockApiClient, _get_hawk_authentication +from shared.data_helpers import model_product_ids + def _find_repo_root() -> Path: current = Path(__file__).resolve().parent @@ -376,13 +378,18 @@ async def _request_cloud_api_data( return response.get("data") -def _plugin_product_ids(home_data: HomeData) -> list[int]: +def _plugin_product_ids(home_data: HomeData, cloud_products: Any = None) -> list[int]: + # Newer models (e.g. roborock.vacuum.a226) carry a string product id in home + # data; the numeric id the plugin catalog is keyed by comes from /api/v5/product. + ids_by_model = model_product_ids(cloud_products) product_ids: set[int] = set() for product in home_data.products or []: try: product_ids.add(int(product.id)) except (TypeError, ValueError): - continue + model_id = ids_by_model.get(str(product.model or "").strip().lower()) + if model_id: + product_ids.add(model_id) for device in _all_home_devices(home_data): try: product_ids.add(int(getattr(device, "product_id", 0) or 0)) @@ -442,21 +449,21 @@ async def fetch_catalog( "/api/v1/plugins", params={"type": 2, "apiLevel": 10043}, ) - product_ids = _plugin_product_ids(home_data) - if product_ids: - await fetch_catalog( - "appplugin", - "/api/v1/appplugin", - method="post", - json_body={"type": 2, "apilevel": 10043, "productids": product_ids}, - ) - else: - catalogs["appplugin"] = { - "path": "/api/v1/appplugin", - "method": "POST", - "json": {"type": 2, "apilevel": 10043, "productids": []}, - "error": "no product ids available", - } + await fetch_catalog("product", "/api/v5/product") + product_ids = _plugin_product_ids(home_data, catalogs["product"].get("data")) + # The cloud serves a separate zip per platform for the same plugin version: + # type 2 is Android, type 1 is iOS. + for name, app_type in (("appplugin", 2), ("appplugin_ios", 1)): + json_body = {"type": app_type, "apilevel": 10043, "productids": product_ids} + if product_ids: + await fetch_catalog(name, "/api/v1/appplugin", method="post", json_body=json_body) + else: + catalogs[name] = { + "path": "/api/v1/appplugin", + "method": "POST", + "json": json_body, + "error": "no product ids available", + } return catalogs diff --git a/src/roborock_local_server/bundled_backend/shared/data_helpers.py b/src/roborock_local_server/bundled_backend/shared/data_helpers.py index 836b808..b0b9062 100644 --- a/src/roborock_local_server/bundled_backend/shared/data_helpers.py +++ b/src/roborock_local_server/bundled_backend/shared/data_helpers.py @@ -44,6 +44,19 @@ def stable_int(seed: str) -> int: return int(hashlib.sha256(seed.encode("utf-8")).hexdigest()[:12], 16) +def model_product_ids(cloud_products: Any) -> dict[str, int]: + """Map model -> numeric product id from a cloud /api/v5/product payload.""" + ids: dict[str, int] = {} + category_details = cloud_products.get("categoryDetailList") if isinstance(cloud_products, dict) else None + for category_detail in category_details or []: + for product in (category_detail or {}).get("productList") or []: + model = str(product.get("model") or "").strip().lower() + product_id = as_int(product.get("id"), 0) + if model and product_id > 0: + ids[model] = product_id + return ids + + def default_home_id(ctx: ServerContext) -> int: return stable_int(f"{ctx.duid}:home") diff --git a/tests/test_cloud_plugin_catalogs.py b/tests/test_cloud_plugin_catalogs.py new file mode 100644 index 0000000..8f8a169 --- /dev/null +++ b/tests/test_cloud_plugin_catalogs.py @@ -0,0 +1,53 @@ +import asyncio +from typing import Any + +from roborock.data import HomeData + +import roborock_local_server.backend # noqa: F401 (puts the bundled backend on sys.path) +import import_web_inventory_from_cloud as importer + + +CLOUD_PRODUCTS = { + "categoryDetailList": [ + { + "category": {"id": 1, "code": "robot.vacuum.cleaner"}, + "productList": [{"id": 199, "model": "roborock.vacuum.a226"}], + } + ] +} + + +def _home_data() -> HomeData: + # Home data lists newer models under a string product id on both the product + # and the device. + return HomeData.from_dict( + { + "id": 1, + "name": "Home", + "products": [{"id": "30uADinyLKa3Qpga60B1Ke", "name": "Qrevo Curv 2 Pro", "model": "roborock.vacuum.a226", "category": "robot.vacuum.cleaner"}], + "devices": [{"duid": "duid-1", "name": "Vacuum", "productId": "30uADinyLKa3Qpga60B1Ke", "localKey": "key"}], + } + ) + + +def test_plugin_catalogs_resolve_string_product_ids_and_fetch_both_platforms(monkeypatch) -> None: + requests: list[tuple[str, dict[str, Any] | None]] = [] + + async def fake_request(_api, _user_data, path, *, method="get", params=None, json_body=None): + requests.append((path, json_body)) + if path == "/api/v5/product": + return CLOUD_PRODUCTS + if path == "/api/v1/appplugin": + return [{"productid": 199, "url": f"https://app-files.roborock.com/iot/plugin/type{json_body['type']}.zip"}] + return {} + + monkeypatch.setattr(importer, "_request_cloud_api_data", fake_request) + + catalogs = asyncio.run(importer._fetch_plugin_catalogs(None, None, _home_data())) + + assert catalogs["product"]["data"] == CLOUD_PRODUCTS + app_plugin_bodies = [body for path, body in requests if path == "/api/v1/appplugin"] + assert sorted(body["type"] for body in app_plugin_bodies) == [1, 2] + assert all(body["productids"] == [199] for body in app_plugin_bodies) + assert catalogs["appplugin"]["data"][0]["url"].endswith("/type2.zip") + assert catalogs["appplugin_ios"]["data"][0]["url"].endswith("/type1.zip") diff --git a/tests/test_plugin_routes.py b/tests/test_plugin_routes.py index 2d42ae9..686a59e 100644 --- a/tests/test_plugin_routes.py +++ b/tests/test_plugin_routes.py @@ -247,3 +247,44 @@ def test_download_plugin_zip_still_rejects_oversized_payload(monkeypatch) -> Non with pytest.raises(RuntimeError, match="plugin too large"): asyncio.run(plugin_common.download_plugin_zip("https://files.roborock.com/plugin.zip")) + + +def _write_app_plugin_snapshot(supervisor: ReleaseSupervisor, catalogs: dict) -> None: + snapshot = {"web_api_cache": {"plugin_catalogs": catalogs}} + supervisor.paths.cloud_snapshot_path.write_text(json.dumps(snapshot) + "\n", encoding="utf-8") + + +def _app_plugin_catalog(url: str) -> dict: + return {"data": [{"version": 6846, "url": url, "pluginLevel": 3002, "productid": 199, "apilevel": 10030}]} + + +ANDROID_ZIP = "https://app-files.roborock.com/iot/plugin/android.zip" +IOS_ZIP = "https://app-files.roborock.com/iot/plugin/ios.zip" + + +@pytest.mark.parametrize(("app_type", "expected"), [(1, IOS_ZIP), (2, ANDROID_ZIP)]) +def test_app_plugin_answers_per_platform_type(tmp_path: Path, app_type: int, expected: str) -> None: + # The cloud serves a different zip for the same plugin version to iOS (type 1) + # and Android (type 2); the iOS app cannot load the Android one. + supervisor = _build_supervisor(tmp_path) + _write_app_plugin_snapshot( + supervisor, + {"appplugin": _app_plugin_catalog(ANDROID_ZIP), "appplugin_ios": _app_plugin_catalog(IOS_ZIP)}, + ) + client = TestClient(supervisor.app) + + response = client.post("/api/v1/appplugin", json={"type": app_type, "apilevel": "40740", "productids": [199]}) + + [record] = response.json()["data"] + assert _source_from_proxied_url(record["url"]) == expected + + +def test_app_plugin_ios_falls_back_to_android_catalog_from_older_imports(tmp_path: Path) -> None: + supervisor = _build_supervisor(tmp_path) + _write_app_plugin_snapshot(supervisor, {"appplugin": _app_plugin_catalog(ANDROID_ZIP)}) + client = TestClient(supervisor.app) + + response = client.post("/api/v1/appplugin", json={"type": 1, "productids": [199]}) + + [record] = response.json()["data"] + assert _source_from_proxied_url(record["url"]) == ANDROID_ZIP diff --git a/tests/test_product_response.py b/tests/test_product_response.py index 09f8b8d..35c05eb 100644 --- a/tests/test_product_response.py +++ b/tests/test_product_response.py @@ -111,3 +111,33 @@ def test_product_picture_fields_use_app_json_names(tmp_path: Path) -> None: assert product["picurl"] == "https://images.example.com/vacuum.png" assert product["cardpicurl"] == "https://images.example.com/vacuum.png" assert "cardPicUrl" not in product + + +def test_string_product_id_uses_cloud_numeric_id_by_model(tmp_path: Path) -> None: + # The cloud lists newer models (e.g. a226) under a string product id in home + # data. The numeric id the app requests plugins with comes from the cloud's + # /api/v5/product, which the import stores in the snapshot. + snapshot = { + "web_api_cache": { + "plugin_catalogs": { + "product": { + "data": { + "categoryDetailList": [ + { + "category": {"id": 1, "code": "robot.vacuum.cleaner"}, + "productList": [{"id": 199, "model": "roborock.vacuum.a226"}], + } + ] + } + } + } + } + } + (tmp_path / "web_api_inventory_full_snapshot.json").write_text(json.dumps(snapshot), encoding="utf-8") + device = dict(_DEVICE, model="roborock.vacuum.a226", product_id="30uADinyLKa3Qpga60B1Ke") + + data = _products_v5(tmp_path, [device]) + + [product] = data["categoryDetailList"][0]["productList"] + assert product["id"] == 199 + assert product["rriotid"] == "30uADinyLKa3Qpga60B1Ke" From 44ed228d8a731644ed67a3f235b4c9a46af85ee3 Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Thu, 12 Nov 2026 00:00:55 -0500 Subject: [PATCH 08/19] Refresh the plugin catalogs from the cloud with the stored login The snapshot keeps the cloud login and the plugin catalogs fetched at sign-in, and the plugin routes serve those. Newer robots can need newer plugins than the snapshot holds, so CloudImportManager.refresh_plugin_catalogs asks the cloud again with the stored login and replaces only the catalogs. The sign-in now also stores the device identifier the cloud ties the login to. A rejected login or an empty answer leaves the snapshot as it was. Co-Authored-By: Claude Sonnet 5.5 Co-Authored-By: Claude Opus 5.5 --- src/roborock_local_server/backend.py | 2 + src/roborock_local_server/cloud.py | 79 +++++++++++++++++++ tests/test_cloud.py | 109 +++++++++++++++++++++++++++ 3 files changed, 190 insertions(+) diff --git a/src/roborock_local_server/backend.py b/src/roborock_local_server/backend.py index 526d7a9..008e04f 100644 --- a/src/roborock_local_server/backend.py +++ b/src/roborock_local_server/backend.py @@ -24,6 +24,7 @@ def _resolve_backend_path() -> Path: _build_inventory, _fetch_additional_web_cache, _fetch_cloud_home_data_with_api, + _fetch_plugin_catalogs, _flatten_device_scenes, _load_existing_inventory_for_merge, _merge_existing_inventory_mutations, @@ -52,6 +53,7 @@ def _resolve_backend_path() -> Path: "_extract_inventory_vacuums", "_fetch_additional_web_cache", "_fetch_cloud_home_data_with_api", + "_fetch_plugin_catalogs", "_flatten_device_scenes", "_load_existing_inventory_for_merge", "_load_inventory", diff --git a/src/roborock_local_server/cloud.py b/src/roborock_local_server/cloud.py index b0c96c9..ac7bcaf 100644 --- a/src/roborock_local_server/cloud.py +++ b/src/roborock_local_server/cloud.py @@ -12,12 +12,14 @@ from typing import Any, Literal import aiohttp +from roborock.data import UserData from roborock.web_api import RoborockApiClient from .backend import ( _build_inventory, _fetch_additional_web_cache, _fetch_cloud_home_data_with_api, + _fetch_plugin_catalogs, _flatten_device_scenes, _load_existing_inventory_for_merge, _merge_existing_inventory_mutations, @@ -30,6 +32,27 @@ from shared.inventory_io import atomic_write_inventory, inventory_transaction +def summarize_plugin_catalogs(catalogs: dict[str, Any]) -> dict[str, Any]: + """The plugin catalogs reduced to what picks a plugin: versions, levels and download URLs.""" + keep = ("version", "apiLevel", "apilevel", "pluginLevel", "productid", "categoryId", "category", "moduleType", "url", "id", "model") + summary: dict[str, Any] = {"fetched_at_utc": catalogs.get("fetched_at_utc")} + for name, catalog in catalogs.items(): + if not isinstance(catalog, dict): + continue + entry: dict[str, Any] = {"params": catalog.get("params") or catalog.get("json") or {}} + if "error" in catalog: + entry["error"] = catalog["error"] + data = catalog.get("data") + if isinstance(data, dict): + data = data.get("categoryPluginList") + records = data if isinstance(data, list) else [] + entry["plugins"] = [ + {key: record[key] for key in keep if key in record} for record in records if isinstance(record, dict) + ] + summary[name] = entry + return summary + + def _to_jsonable(value: Any) -> Any: if value is None or isinstance(value, (str, int, float, bool)): return value @@ -127,6 +150,61 @@ async def request_code(self, *, email: str, base_url: str = "") -> dict[str, Any "expires_at": datetime.fromtimestamp(expires_at_ts, tz=timezone.utc).isoformat(), } + def _read_snapshot(self) -> dict[str, Any]: + try: + parsed = json.loads(self.snapshot_path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return {} + return parsed if isinstance(parsed, dict) else {} + + def plugin_catalogs(self) -> dict[str, Any]: + """The stored plugin catalogs, summarized, without any cloud request.""" + web_cache = self._read_snapshot().get("web_api_cache") + catalogs = web_cache.get("plugin_catalogs") if isinstance(web_cache, dict) else None + return summarize_plugin_catalogs(catalogs) if isinstance(catalogs, dict) else {} + + async def refresh_plugin_catalogs(self) -> dict[str, Any]: + """Re-reads the plugin catalogs from the cloud with the login the snapshot already holds. + + Only the plugin catalogs in the snapshot change; the inventory is left alone. A rejected + login needs the email-code sign-in again, which stores a fresh one. + """ + snapshot = self._read_snapshot() + meta = snapshot.get("meta") if isinstance(snapshot.get("meta"), dict) else {} + try: + user_data = UserData.from_dict(snapshot.get("user_data")) + except (TypeError, ValueError, KeyError): + user_data = None + email = str(meta.get("username") or "") + if user_data is None or not user_data.token or not email: + raise ValueError("No cloud login is stored. Request a code and sign in first.") + + timeout = aiohttp.ClientTimeout(total=120) + async with aiohttp.ClientSession(timeout=timeout) as session: + api = RoborockApiClient(username=email, base_url=str(meta.get("base_url") or "") or None, session=session) + if meta.get("device_identifier"): + setattr(api, "_device_identifier", str(meta["device_identifier"])) + try: + home_data = await _fetch_cloud_home_data_with_api(api, user_data) + catalogs = await _fetch_plugin_catalogs(api, user_data, home_data) + except Exception as exc: # noqa: BLE001 + raise ValueError( + f"The cloud rejected the stored login ({exc}). Request a code and sign in again." + ) from exc + + failed = [name for name, item in catalogs.items() if isinstance(item, dict) and "error" in item] + if failed and len(failed) == sum(1 for item in catalogs.values() if isinstance(item, dict)): + errors = "; ".join(str(catalogs[name]["error"]) for name in failed) + raise ValueError(f"The cloud returned no plugin catalogs ({errors}). Request a code and sign in again.") + + web_cache = snapshot.get("web_api_cache") + if not isinstance(web_cache, dict): + web_cache = {} + snapshot["web_api_cache"] = web_cache + web_cache["plugin_catalogs"] = _to_jsonable(catalogs) + self.snapshot_path.write_text(json.dumps(snapshot, indent=2) + "\n", encoding="utf-8") + return {"success": True, "step": "plugins_refreshed", **summarize_plugin_catalogs(catalogs)} + async def submit_code(self, *, session_id: str, code: str) -> dict[str, Any]: normalized_session_id = session_id.strip() normalized_code = code.strip() @@ -180,6 +258,7 @@ async def submit_code(self, *, session_id: str, code: str) -> dict[str, Any]: "generated_at_utc": datetime.now(timezone.utc).isoformat(), "username": session_data.email, "base_url": session_data.base_url, + "device_identifier": session_data.device_identifier, "source": "admin_email_code_login", }, "user_data": _to_jsonable(user_data), diff --git a/tests/test_cloud.py b/tests/test_cloud.py index 98be0b2..9944e74 100644 --- a/tests/test_cloud.py +++ b/tests/test_cloud.py @@ -265,3 +265,112 @@ def test_submit_code_expired_session_raises_value_error(tmp_path, monkeypatch) - with pytest.raises(ValueError): asyncio.run(manager.submit_code(session_id=request_result["session_id"], code="123456")) + + +_STORED_USER_DATA = { + "rriot": {"u": "u", "s": "s", "h": "h", "k": "k", "r": {"r": "EU", "a": "https://api", "m": "ssl://mqtt", "l": "https://l"}}, + "uid": 1, + "token": "stored-token", +} +_NEW_CATALOGS = { + "fetched_at_utc": "2026-11-11T00:00:00+00:00", + "plugins": { + "path": "/api/v1/plugins", + "params": {"type": 2, "apiLevel": 10043}, + "data": {"categoryPluginList": [{"categoryId": 1, "category": "robot.vacuum.cleaner", "version": 7006, "url": "https://files.roborock.com/p.zip", "md5": None}]}, + }, + "appplugin": { + "path": "/api/v1/appplugin", + "json": {"type": 2, "apilevel": 10043, "productids": [110]}, + "data": [{"productid": 110, "version": 7006, "apilevel": 10043, "url": "https://files.roborock.com/a.zip"}], + }, +} + + +def _write_snapshot(manager: CloudImportManager, **overrides) -> None: + snapshot = { + "meta": {"username": "user@example.com", "base_url": "https://euiot.roborock.com", "device_identifier": "dev-9"}, + "user_data": _STORED_USER_DATA, + "web_api_cache": {"rooms": [1, 2], "plugin_catalogs": {"fetched_at_utc": "old"}}, + } + snapshot.update(overrides) + manager.snapshot_path.write_text(json.dumps(snapshot), encoding="utf-8") + + +def _patch_plugin_fetch(monkeypatch: pytest.MonkeyPatch, catalogs: dict, seen: dict | None = None) -> None: + async def fake_catalogs(api, user_data, home_data): + if seen is not None: + seen.update(token=user_data.token, device_identifier=api._device_identifier) + return catalogs + + monkeypatch.setattr(cloud_module, "RoborockApiClient", _FakeRoborockApiClientV4) + monkeypatch.setattr(cloud_module, "_fetch_cloud_home_data_with_api", _fake_fetch_cloud_home_data_with_api) + monkeypatch.setattr(cloud_module, "_fetch_plugin_catalogs", fake_catalogs) + + +def test_refresh_plugin_catalogs_replaces_only_the_catalogs(tmp_path, monkeypatch) -> None: + manager = _make_manager(tmp_path) + _write_snapshot(manager) + seen: dict = {} + _patch_plugin_fetch(monkeypatch, _NEW_CATALOGS, seen) + + result = asyncio.run(manager.refresh_plugin_catalogs()) + + assert seen == {"token": "stored-token", "device_identifier": "dev-9"} + assert result["success"] is True + assert result["plugins"]["plugins"] == [ + {"version": 7006, "url": "https://files.roborock.com/p.zip", "categoryId": 1, "category": "robot.vacuum.cleaner"} + ] + assert result["appplugin"]["plugins"][0]["url"] == "https://files.roborock.com/a.zip" + stored = json.loads(manager.snapshot_path.read_text(encoding="utf-8")) + assert stored["web_api_cache"]["rooms"] == [1, 2] + assert stored["web_api_cache"]["plugin_catalogs"]["plugins"]["data"]["categoryPluginList"][0]["version"] == 7006 + assert manager.plugin_catalogs()["appplugin"]["plugins"][0]["version"] == 7006 + + +def test_refresh_plugin_catalogs_needs_a_stored_login(tmp_path, monkeypatch) -> None: + manager = _make_manager(tmp_path) + _patch_plugin_fetch(monkeypatch, _NEW_CATALOGS) + + with pytest.raises(ValueError, match="No cloud login"): + asyncio.run(manager.refresh_plugin_catalogs()) + _write_snapshot(manager, user_data={}) + with pytest.raises(ValueError, match="No cloud login"): + asyncio.run(manager.refresh_plugin_catalogs()) + + +def test_refresh_plugin_catalogs_keeps_the_snapshot_when_the_cloud_gives_nothing(tmp_path, monkeypatch) -> None: + manager = _make_manager(tmp_path) + _write_snapshot(manager) + before = manager.snapshot_path.read_text(encoding="utf-8") + failing = {"fetched_at_utc": "now", "plugins": {"path": "/p", "error": "code 2010"}, "appplugin": {"path": "/a", "error": "code 2010"}} + _patch_plugin_fetch(monkeypatch, failing) + + with pytest.raises(ValueError, match="no plugin catalogs"): + asyncio.run(manager.refresh_plugin_catalogs()) + assert manager.snapshot_path.read_text(encoding="utf-8") == before + + +def test_refresh_plugin_catalogs_reports_a_rejected_login(tmp_path, monkeypatch) -> None: + manager = _make_manager(tmp_path) + _write_snapshot(manager) + _patch_plugin_fetch(monkeypatch, _NEW_CATALOGS) + + async def rejected(api, user_data): + raise RuntimeError("invalid token") + + monkeypatch.setattr(cloud_module, "_fetch_cloud_home_data_with_api", rejected) + with pytest.raises(ValueError, match="sign in again"): + asyncio.run(manager.refresh_plugin_catalogs()) + + +def test_submit_code_stores_the_device_identifier(tmp_path, monkeypatch) -> None: + monkeypatch.setattr(cloud_module, "RoborockApiClient", _FakeRoborockApiClientV4) + _patch_backend_calls(monkeypatch) + manager = _make_manager(tmp_path) + + request_result = asyncio.run(manager.request_code(email="user@example.com")) + asyncio.run(manager.submit_code(session_id=request_result["session_id"], code="123456")) + + stored = json.loads(manager.snapshot_path.read_text(encoding="utf-8")) + assert stored["meta"]["device_identifier"] == _fake_client_instances[0]._device_identifier From 402702a959cb741336e9fca3868f80960495087d Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Thu, 12 Nov 2026 00:00:57 -0500 Subject: [PATCH 09/19] Add admin endpoints to refresh and list the plugin catalogs POST /admin/api/cloud/refresh-plugins re-reads them with the stored login, taking an optional platform type. GET /admin/api/cloud/plugins shows what is stored without a cloud request. Both return each plugin's version, API level and download URL. Co-Authored-By: Claude Sonnet 5.5 Co-Authored-By: Claude Opus 5.5 --- docs/roborock_app.md | 16 +++++++++ src/roborock_local_server/standalone_admin.py | 15 ++++++++ tests/test_admin_api.py | 34 +++++++++++++++++++ 3 files changed, 65 insertions(+) diff --git a/docs/roborock_app.md b/docs/roborock_app.md index 5775efb..0c969a9 100644 --- a/docs/roborock_app.md +++ b/docs/roborock_app.md @@ -170,6 +170,22 @@ During `JNI_OnLoad`, `librrcodec.so` calls a verification function that retrieve --- +## Refreshing the Plugin List + +The official app downloads each device's screens as plugins, and the server hands it the list it saved from the cloud when you signed in. Newer robots can need newer plugins than that saved list holds. Refresh it without signing in again: + +```sh +curl -c jar -X POST https://your-server/admin/api/login -H 'Content-Type: application/json' -d '{"password": "..."}' +curl -b jar -X POST https://your-server/admin/api/cloud/refresh-plugins +curl -b jar https://your-server/admin/api/cloud/plugins +``` + +The refresh reuses the login stored by the email-code sign-in and only replaces the plugin catalogs, with the product ids of every device on the account. The reply lists each plugin's version, API level and download URL. `GET /admin/api/cloud/plugins` shows what is stored now without asking the cloud. + +If the cloud rejects the stored login, or the snapshot predates this feature and has none, sign in again with the email code; that stores a login the refresh can use. + +--- + ## LocalRock (Third-Party App) [LocalRock](https://github.com/DonSidro/LocalRock) is an open-source app created by **Sidon Kodraliu** ([@DonSidro](https://github.com/DonSidro)) that connects directly to the local Roborock server. diff --git a/src/roborock_local_server/standalone_admin.py b/src/roborock_local_server/standalone_admin.py index e1c24dd..b83ad68 100644 --- a/src/roborock_local_server/standalone_admin.py +++ b/src/roborock_local_server/standalone_admin.py @@ -478,3 +478,18 @@ async def admin_cloud_submit_code(request: Request) -> JSONResponse: result = {"success": False, "step": "code_submit_failed", "error": str(exc)} supervisor.runtime_state.record_cloud_request(result) return JSONResponse(result, status_code=200 if result.get("success") else 400) + + @app.get("/admin/api/cloud/plugins") + async def admin_cloud_plugins(request: Request) -> JSONResponse: + supervisor._require_admin(request) + return JSONResponse({"success": True, **supervisor.cloud_manager.plugin_catalogs()}) + + @app.post("/admin/api/cloud/refresh-plugins") + async def admin_cloud_refresh_plugins(request: Request) -> JSONResponse: + supervisor._require_admin(request) + try: + result = await supervisor.cloud_manager.refresh_plugin_catalogs() + except Exception as exc: # noqa: BLE001 + result = {"success": False, "step": "plugin_refresh_failed", "error": str(exc)} + supervisor.runtime_state.record_cloud_request(result) + return JSONResponse(result, status_code=200 if result.get("success") else 400) diff --git a/tests/test_admin_api.py b/tests/test_admin_api.py index 13341a3..935306e 100644 --- a/tests/test_admin_api.py +++ b/tests/test_admin_api.py @@ -1602,3 +1602,37 @@ def test_create_room_returns_bare_id_in_result_and_object_in_data(tmp_path: Path assert body["data"]["id"] == body["result"] assert body["data"]["name"] == "Study" assert body["data"]["created"] is True + + +def test_admin_plugin_catalog_endpoints_require_auth_and_report_the_snapshot(tmp_path: Path) -> None: + config_file = write_release_config(tmp_path) + config = load_config(config_file) + paths = resolve_paths(config_file, config) + supervisor = ReleaseSupervisor(config=config, paths=paths) + client = TestClient(supervisor.app) + + assert client.get("/admin/api/cloud/plugins").status_code == 401 + assert client.post("/admin/api/cloud/refresh-plugins", json={}).status_code == 401 + + assert client.post("/admin/api/login", json={"password": "correct horse battery staple"}).status_code == 200 + assert client.get("/admin/api/cloud/plugins").json() == {"success": True} + + paths.cloud_snapshot_path.write_text( + json.dumps( + { + "web_api_cache": { + "plugin_catalogs": { + "appplugin": {"json": {"type": 2}, "data": [{"productid": 110, "version": 7006, "url": "https://files.roborock.com/a.zip"}]}, + } + } + } + ), + encoding="utf-8", + ) + stored = client.get("/admin/api/cloud/plugins").json() + assert stored["appplugin"]["plugins"] == [{"productid": 110, "version": 7006, "url": "https://files.roborock.com/a.zip"}] + + refused = client.post("/admin/api/cloud/refresh-plugins", json={}) + assert refused.status_code == 400 + assert refused.json()["step"] == "plugin_refresh_failed" + assert "No cloud login" in refused.json()["error"] From 47243da7277bfa2d3c77be6185dd2ee30773a451 Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Thu, 12 Nov 2026 09:02:08 -0500 Subject: [PATCH 10/19] Read a robot's firmware update from the cloud with the stored login The firmware check is a Hawk-signed IoT call, so it uses the rriot credentials the sign-in stored. The refresh and the check now share one helper for loading that login. Co-Authored-By: Claude Sonnet 5.5 Co-Authored-By: Claude Opus 5.5 --- src/roborock_local_server/backend.py | 2 ++ src/roborock_local_server/cloud.py | 43 ++++++++++++++++++++-------- tests/test_cloud.py | 26 +++++++++++++++++ 3 files changed, 59 insertions(+), 12 deletions(-) diff --git a/src/roborock_local_server/backend.py b/src/roborock_local_server/backend.py index 008e04f..84442cc 100644 --- a/src/roborock_local_server/backend.py +++ b/src/roborock_local_server/backend.py @@ -26,6 +26,7 @@ def _resolve_backend_path() -> Path: _fetch_cloud_home_data_with_api, _fetch_plugin_catalogs, _flatten_device_scenes, + _hawk_get_result, _load_existing_inventory_for_merge, _merge_existing_inventory_mutations, _normalize_dict_list, @@ -55,6 +56,7 @@ def _resolve_backend_path() -> Path: "_fetch_cloud_home_data_with_api", "_fetch_plugin_catalogs", "_flatten_device_scenes", + "_hawk_get_result", "_load_existing_inventory_for_merge", "_load_inventory", "_merge_existing_inventory_mutations", diff --git a/src/roborock_local_server/cloud.py b/src/roborock_local_server/cloud.py index ac7bcaf..fa1a53c 100644 --- a/src/roborock_local_server/cloud.py +++ b/src/roborock_local_server/cloud.py @@ -21,6 +21,7 @@ _fetch_cloud_home_data_with_api, _fetch_plugin_catalogs, _flatten_device_scenes, + _hawk_get_result, _load_existing_inventory_for_merge, _merge_existing_inventory_mutations, _normalize_dict_list, @@ -157,6 +158,34 @@ def _read_snapshot(self) -> dict[str, Any]: return {} return parsed if isinstance(parsed, dict) else {} + def _stored_cloud_login(self) -> tuple[dict[str, Any], dict[str, Any], UserData, str]: + """The snapshot, its meta, and the login the last sign-in stored.""" + snapshot = self._read_snapshot() + meta = snapshot.get("meta") if isinstance(snapshot.get("meta"), dict) else {} + try: + user_data = UserData.from_dict(snapshot.get("user_data")) + except (TypeError, ValueError, KeyError): + user_data = None + email = str(meta.get("username") or "") + if user_data is None or not user_data.token or not email: + raise ValueError("No cloud login is stored. Request a code and sign in first.") + return snapshot, meta, user_data, email + + @staticmethod + def _cloud_client(session: aiohttp.ClientSession, meta: dict[str, Any], email: str) -> RoborockApiClient: + api = RoborockApiClient(username=email, base_url=str(meta.get("base_url") or "") or None, session=session) + if meta.get("device_identifier"): + setattr(api, "_device_identifier", str(meta["device_identifier"])) + return api + + async def firmware_update_info(self, duid: str, *, lang: str = "en") -> Any: + """What the cloud says about a robot's firmware update, read with the stored login.""" + _, meta, user_data, email = self._stored_cloud_login() + timeout = aiohttp.ClientTimeout(total=30) + async with aiohttp.ClientSession(timeout=timeout) as session: + api = self._cloud_client(session, meta, email) + return await _hawk_get_result(api, user_data, f"/ota/firmware/{duid}/updatev2", params={"lang": lang}) + def plugin_catalogs(self) -> dict[str, Any]: """The stored plugin catalogs, summarized, without any cloud request.""" web_cache = self._read_snapshot().get("web_api_cache") @@ -169,21 +198,11 @@ async def refresh_plugin_catalogs(self) -> dict[str, Any]: Only the plugin catalogs in the snapshot change; the inventory is left alone. A rejected login needs the email-code sign-in again, which stores a fresh one. """ - snapshot = self._read_snapshot() - meta = snapshot.get("meta") if isinstance(snapshot.get("meta"), dict) else {} - try: - user_data = UserData.from_dict(snapshot.get("user_data")) - except (TypeError, ValueError, KeyError): - user_data = None - email = str(meta.get("username") or "") - if user_data is None or not user_data.token or not email: - raise ValueError("No cloud login is stored. Request a code and sign in first.") + snapshot, meta, user_data, email = self._stored_cloud_login() timeout = aiohttp.ClientTimeout(total=120) async with aiohttp.ClientSession(timeout=timeout) as session: - api = RoborockApiClient(username=email, base_url=str(meta.get("base_url") or "") or None, session=session) - if meta.get("device_identifier"): - setattr(api, "_device_identifier", str(meta["device_identifier"])) + api = self._cloud_client(session, meta, email) try: home_data = await _fetch_cloud_home_data_with_api(api, user_data) catalogs = await _fetch_plugin_catalogs(api, user_data, home_data) diff --git a/tests/test_cloud.py b/tests/test_cloud.py index 9944e74..1958c73 100644 --- a/tests/test_cloud.py +++ b/tests/test_cloud.py @@ -374,3 +374,29 @@ def test_submit_code_stores_the_device_identifier(tmp_path, monkeypatch) -> None stored = json.loads(manager.snapshot_path.read_text(encoding="utf-8")) assert stored["meta"]["device_identifier"] == _fake_client_instances[0]._device_identifier + + +def test_firmware_update_info_is_read_with_the_stored_login(tmp_path, monkeypatch) -> None: + manager = _make_manager(tmp_path) + _write_snapshot(manager) + seen: dict = {} + + async def fake_hawk(api, user_data, path, *, params=None): + seen.update(path=path, params=params, token=user_data.token, device_identifier=api._device_identifier) + return {"version": "02.45.78", "updatable": True} + + monkeypatch.setattr(cloud_module, "RoborockApiClient", _FakeRoborockApiClientV4) + monkeypatch.setattr(cloud_module, "_hawk_get_result", fake_hawk) + + result = asyncio.run(manager.firmware_update_info("duid-1", lang="de")) + + assert result == {"version": "02.45.78", "updatable": True} + assert seen == { + "path": "/ota/firmware/duid-1/updatev2", "params": {"lang": "de"}, + "token": "stored-token", "device_identifier": "dev-9", + } + + +def test_firmware_update_info_needs_a_stored_login(tmp_path) -> None: + with pytest.raises(ValueError, match="No cloud login"): + asyncio.run(_make_manager(tmp_path).firmware_update_info("duid-1")) From 88830474b2a4ea3e6e92f80e3e05cc326e277a48 Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Thu, 12 Nov 2026 09:24:56 -0500 Subject: [PATCH 11/19] Answer the app's firmware calls from the cloud, and require its signature The app checks with GET /ota/firmware/updatev2?duids=...&lang=..., reads progress from /ota/firmware/upgrade/status?duids=..., and installs with POST /ota/device//upgrade (or /upgrade/latest-stable). The check and the progress are now read from the cloud, so the official app and LocalRock can show an available update and its notes, and the older path-style GET /ota/firmware//updatev2 still works. Both upgrade forms used to answer success and do nothing; they are now refused with a clear error, since installing a firmware needs the command the cloud pushes to the robot. These routes answer from the stored cloud login, so they need the same Hawk signature as the /user/ routes instead of being open. The app sends the check and the progress read within milliseconds of each other with the same timestamp and nonce, so for these read-only GETs the signature and its age are verified but the repeated-nonce refusal is skipped. Everything else, including the upgrade POST, keeps it. Co-Authored-By: Claude Sonnet 5.5 Co-Authored-By: Claude Opus 5.5 --- docs/known_limitations.md | 2 +- .../bundled_backend/shared/protocol_auth.py | 5 + src/roborock_local_server/cloud.py | 10 +- src/roborock_local_server/server.py | 73 ++++++++-- tests/test_ota_firmware.py | 132 ++++++++++++++++++ 5 files changed, 210 insertions(+), 12 deletions(-) create mode 100644 tests/test_ota_firmware.py diff --git a/docs/known_limitations.md b/docs/known_limitations.md index b7b8c59..874ad72 100644 --- a/docs/known_limitations.md +++ b/docs/known_limitations.md @@ -3,7 +3,7 @@ I have tried to copy over most functionality into this server, but some is not 100% completed. There are a few features I know are not currently working - Vacuum camera live streaming — available; see the [model-specific results](camera.md#reported-camera-results). Bootstrap, activation and audio support vary by firmware, and some reports require custom builds. -- Firmware Updates +- Firmware updates: the app can see whether an update is available (the server asks Roborock's cloud with the login stored at sign-in, so it needs one email-code sign-in first), but installing it is not supported. The upgrade request is refused with an error instead of pretending to start. - Schedules (Routines/Scenes do work though) - China-market devices have model/firmware-specific region and access-renewal restrictions. Unresolved a143/a146/a96 reports reject ordinary commands with `-10002 / rrcheck access denied` after local onboarding. See [known failures](tested_vacuums.md#known-failures). Factory-firmware a184 success was reported with custom interception and compromised-intermediate certificates; it does not establish support through the standard setup or resolve those other reports. - Some users report success with the official cloud through a China-exit VPN; see [this comment](https://github.com/iobroker-community-adapters/ioBroker.mihome-vacuum/issues/842#issuecomment-1736230673). A China VPN did not resolve the G30 local-server report [#161](https://github.com/Python-roborock/local_roborock_server/issues/161), so it is not an established general workaround here. diff --git a/src/roborock_local_server/bundled_backend/shared/protocol_auth.py b/src/roborock_local_server/bundled_backend/shared/protocol_auth.py index 31e9860..230e003 100644 --- a/src/roborock_local_server/bundled_backend/shared/protocol_auth.py +++ b/src/roborock_local_server/bundled_backend/shared/protocol_auth.py @@ -561,7 +561,10 @@ def verify_hawk( headers: Mapping[str, str], raw_body: bytes | None = None, now_ts: float | None = None, + allow_replay: bool = False, ) -> tuple[bool, str]: + """Checks the signature and its age. A repeated nonce is refused unless [allow_replay] is set, which + is for read-only requests the app is known to resend with the same signature.""" availability = self.availability() if not availability.users: return False, availability.reason @@ -612,6 +615,8 @@ def verify_hawk( ) if not hmac.compare_digest(_clean_str(hawk.get("mac")), expected_mac): return False, "invalid_hawk_mac" + if allow_replay: + return True, "ok" nonce_key = f"{user.hawk_id}:{user.hawk_session}:{timestamp}:{nonce}" expires_at = float(current_ts + self.hawk_nonce_ttl_seconds) diff --git a/src/roborock_local_server/cloud.py b/src/roborock_local_server/cloud.py index fa1a53c..0f8395c 100644 --- a/src/roborock_local_server/cloud.py +++ b/src/roborock_local_server/cloud.py @@ -178,13 +178,17 @@ def _cloud_client(session: aiohttp.ClientSession, meta: dict[str, Any], email: s setattr(api, "_device_identifier", str(meta["device_identifier"])) return api - async def firmware_update_info(self, duid: str, *, lang: str = "en") -> Any: - """What the cloud says about a robot's firmware update, read with the stored login.""" + async def iot_get(self, path: str, params: dict[str, Any] | None = None) -> Any: + """A signed read of Roborock's IoT API with the stored login; returns the reply's `result`.""" _, meta, user_data, email = self._stored_cloud_login() timeout = aiohttp.ClientTimeout(total=30) async with aiohttp.ClientSession(timeout=timeout) as session: api = self._cloud_client(session, meta, email) - return await _hawk_get_result(api, user_data, f"/ota/firmware/{duid}/updatev2", params={"lang": lang}) + return await _hawk_get_result(api, user_data, path, params=params) + + async def firmware_update_info(self, duid: str, *, lang: str = "en") -> Any: + """What the cloud says about a robot's firmware update, read with the stored login.""" + return await self.iot_get(f"/ota/firmware/{duid}/updatev2", {"lang": lang}) def plugin_catalogs(self) -> dict[str, Any]: """The stored plugin catalogs, summarized, without any cloud request.""" diff --git a/src/roborock_local_server/server.py b/src/roborock_local_server/server.py index c0412ef..bdbadcc 100644 --- a/src/roborock_local_server/server.py +++ b/src/roborock_local_server/server.py @@ -9,6 +9,7 @@ import hashlib import json import logging +import re from pathlib import Path import secrets import signal @@ -624,6 +625,54 @@ def _protocol_login_identity(self) -> dict[str, Any]: return patched_user_data return self._local_protocol_identity() + # The app asks with the duid as a query value; older clients put it in the path. + _OTA_CHECK = re.compile(r"^/ota/firmware/([^/]+)/updatev2/?$") + _OTA_CHECK_QUERY = re.compile(r"^/ota/firmware/updatev2/?$") + _OTA_STATUS = re.compile(r"^/ota/firmware/upgrade/status/?$") + _OTA_UPGRADE = re.compile(r"^/ota/device/([^/]+)/upgrade(/latest-stable)?/?$") + + def _is_firmware_read(self, clean_path: str) -> bool: + return bool( + self._OTA_CHECK.match(clean_path) + or self._OTA_CHECK_QUERY.match(clean_path) + or self._OTA_STATUS.match(clean_path) + ) + + async def _firmware_ota_response( + self, clean_path: str, method: str, query_params: dict[str, list[str]], + ) -> tuple[str, dict[str, Any]] | None: + """Answers the app's firmware calls: the check and its progress are read from the cloud, the upgrade is refused.""" + def first(name: str, default: str = "") -> str: + return ((query_params.get(name) or [default])[0] or default).strip() + + route_name = "ota_firmware_check" + read: tuple[str, dict[str, str]] | None = None + if method == "GET": + if (check := self._OTA_CHECK.match(clean_path)) is not None: + read = (f"/ota/firmware/{check.group(1)}/updatev2", {"lang": first("lang", "en")}) + elif self._OTA_CHECK_QUERY.match(clean_path): + read = ("/ota/firmware/updatev2", {"duids": first("duids"), "lang": first("lang", "en")}) + elif self._OTA_STATUS.match(clean_path): + route_name = "ota_firmware_status" + read = ("/ota/firmware/upgrade/status", {"duids": first("duids")}) + if read is not None: + try: + result = await self.cloud_manager.iot_get(read[0], read[1]) + except Exception as exc: # noqa: BLE001 + logging.getLogger("real_stack").warning("Firmware request %s failed: %s", clean_path, exc) + return route_name, { + "success": False, "code": 502, "msg": "firmware_check_unavailable", "data": {"error": str(exc)}, + } + return route_name, {"success": True, "code": 200, "msg": "success", "data": result, "result": result} + if self._OTA_UPGRADE.match(clean_path) and method == "POST": + return "ota_upgrade_unsupported", { + "success": False, + "code": 501, + "msg": "firmware_upgrade_not_supported", + "data": {"error": "Installing firmware is not supported by the local server yet."}, + } + return None + @staticmethod def _normalized_path(path: str) -> str: normalized = str(path or "").rstrip("/") @@ -790,6 +839,9 @@ def _required_protocol_auth(cls, clean_path: str) -> str | None: return None if normalized.startswith(("/user/", "/v2/user/", "/v3/user/", "/v4/user/")): return "hawk" + # The firmware routes answer from the stored cloud login, so they are app-only like /user/. + if normalized.startswith(("/ota/firmware/", "/ota/device/")): + return "hawk" if normalized.startswith("/api/"): return "token" return None @@ -1234,6 +1286,7 @@ async def _handle_roborock_request(self, request: Request) -> Response: body_params=body_params, headers=request.headers, raw_body=raw_body, + allow_replay=request.method == "GET" and self._is_firmware_read(clean_path), ) if not authenticated: route_name = f"{required_auth}_auth_failed" @@ -1352,14 +1405,18 @@ async def _handle_roborock_request(self, request: Request) -> Response: ) return response - route_name, response_payload = resolve_route( - rules=self.endpoint_rules, - context=self.context, - clean_path=clean_path, - query_params=query_params, - body_params=body_params, - method=request.method, - ) + ota_response = await self._firmware_ota_response(clean_path, request.method, query_params) + if ota_response is not None: + route_name, response_payload = ota_response + else: + route_name, response_payload = resolve_route( + rules=self.endpoint_rules, + context=self.context, + clean_path=clean_path, + query_params=query_params, + body_params=body_params, + method=request.method, + ) entry["route"] = route_name if route_name == "fw_createca": # Persist metadata, but retain the exact credential response sent to firmware. diff --git a/tests/test_ota_firmware.py b/tests/test_ota_firmware.py new file mode 100644 index 0000000..ee0d322 --- /dev/null +++ b/tests/test_ota_firmware.py @@ -0,0 +1,132 @@ +from pathlib import Path + +from fastapi.testclient import TestClient + +from conftest import write_release_config +from roborock_local_server.config import load_config, resolve_paths +from roborock_local_server.server import ReleaseSupervisor +from shared.protocol_auth import ProtocolAuthStore, build_hawk_authorization +from test_admin_api import _hawk_headers, _seed_protocol_snapshot + +CHECK = "/ota/firmware/updatev2" +CHECK_BY_PATH = "/ota/firmware/duid-1/updatev2" +STATUS = "/ota/firmware/upgrade/status" +UPGRADE = "/ota/device/duid-1/upgrade" +LATEST_STABLE = "/ota/device/duid-1/upgrade/latest-stable" +INFO = {"version": "02.45.78", "currentVersion": "02.43.62", "updatable": True, "desc": "Fixes"} + + +def _client(tmp_path: Path) -> tuple[TestClient, ReleaseSupervisor, Path]: + config_file = write_release_config(tmp_path) + config = load_config(config_file) + paths = resolve_paths(config_file, config) + _seed_protocol_snapshot(paths.cloud_snapshot_path) + supervisor = ReleaseSupervisor(config=config, paths=paths) + return TestClient(supervisor.app), supervisor, paths.cloud_snapshot_path + + +def _signed(snapshot: Path, path: str, **query: str) -> dict[str, str]: + user = ProtocolAuthStore(snapshot).availability().user + assert user is not None + return {"Authorization": build_hawk_authorization( + user=user, path=path, query_values=query or None, nonce="n-" + path.replace("/", "-"), + )} + + +def _record_reads(supervisor, monkeypatch, result=INFO, error=None) -> list: + calls: list = [] + + async def fake(path, params=None): + calls.append((path, params)) + if error: + raise error + return result + + monkeypatch.setattr(supervisor.cloud_manager, "iot_get", fake) + return calls + + +def test_the_apps_check_is_read_from_the_cloud(tmp_path, monkeypatch) -> None: + client, supervisor, snapshot = _client(tmp_path) + calls = _record_reads(supervisor, monkeypatch, result=[INFO]) + + body = client.get(CHECK, params={"duids": "duid-1", "lang": "de"}, headers=_signed(snapshot, CHECK, duids="duid-1", lang="de")).json() + + assert calls == [("/ota/firmware/updatev2", {"duids": "duid-1", "lang": "de"})] + assert body["success"] is True and body["result"] == [INFO] and body["data"] == [INFO] + + +def test_the_older_path_style_check_is_read_from_the_cloud(tmp_path, monkeypatch) -> None: + client, supervisor, snapshot = _client(tmp_path) + calls = _record_reads(supervisor, monkeypatch) + + body = client.get(CHECK_BY_PATH, headers=_signed(snapshot, CHECK_BY_PATH)).json() + + assert calls == [("/ota/firmware/duid-1/updatev2", {"lang": "en"})] + assert body["result"] == INFO + + +def test_upgrade_progress_is_read_from_the_cloud(tmp_path, monkeypatch) -> None: + client, supervisor, snapshot = _client(tmp_path) + calls = _record_reads(supervisor, monkeypatch, result={"status": "idle"}) + + body = client.get(STATUS, params={"duids": "duid-1"}, headers=_signed(snapshot, STATUS, duids="duid-1")).json() + + assert calls == [("/ota/firmware/upgrade/status", {"duids": "duid-1"})] + assert body["result"] == {"status": "idle"} + + +def test_a_failed_read_reports_why(tmp_path, monkeypatch) -> None: + client, supervisor, snapshot = _client(tmp_path) + _record_reads(supervisor, monkeypatch, error=ValueError("No cloud login is stored. Request a code and sign in first.")) + + body = client.get(CHECK, params={"duids": "duid-1"}, headers=_signed(snapshot, CHECK, duids="duid-1")).json() + + assert body["success"] is False and body["code"] == 502 + assert "No cloud login" in body["data"]["error"] + + +def test_upgrades_are_refused_instead_of_pretending(tmp_path) -> None: + client, _, snapshot = _client(tmp_path) + for path in (UPGRADE, LATEST_STABLE): + body = client.post(path, json={}, headers=_hawk_headers(snapshot, path, json_values={})).json() + assert body["success"] is False and body["code"] == 501 + assert body["msg"] == "firmware_upgrade_not_supported" + + +def test_firmware_routes_need_the_app_signature(tmp_path, monkeypatch) -> None: + client, supervisor, _ = _client(tmp_path) + calls = _record_reads(supervisor, monkeypatch) + + assert client.get(CHECK, params={"duids": "duid-1"}).status_code == 401 + assert client.get(STATUS, params={"duids": "duid-1"}).status_code == 401 + assert client.post(UPGRADE, json={}).status_code == 401 + assert calls == [] + + +def test_a_resent_firmware_read_is_not_refused_as_a_replay(tmp_path, monkeypatch) -> None: + client, supervisor, snapshot = _client(tmp_path) + _record_reads(supervisor, monkeypatch, result={"status": "idle"}) + headers = _signed(snapshot, STATUS, duids="duid-1") + + first = client.get(STATUS, params={"duids": "duid-1"}, headers=headers) + again = client.get(STATUS, params={"duids": "duid-1"}, headers=headers) + + assert first.json()["success"] is True and again.json()["success"] is True + + +def test_a_tampered_firmware_read_is_still_refused(tmp_path, monkeypatch) -> None: + client, supervisor, snapshot = _client(tmp_path) + calls = _record_reads(supervisor, monkeypatch) + headers = _signed(snapshot, STATUS, duids="duid-1") + + assert client.get(STATUS, params={"duids": "duid-2"}, headers=headers).status_code == 401 + assert calls == [] + + +def test_an_upgrade_post_is_still_refused_as_a_replay(tmp_path) -> None: + client, _, snapshot = _client(tmp_path) + headers = _hawk_headers(snapshot, UPGRADE, json_values={}) + + assert client.post(UPGRADE, json={}, headers=headers).json()["code"] == 501 + assert client.post(UPGRADE, json={}, headers=headers).status_code == 401 From 35c50c357a7aababf4cdd271999c900b1d53f190 Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Thu, 12 Nov 2026 09:37:34 -0500 Subject: [PATCH 12/19] List firmware status for every robot on the account GET /admin/api/cloud/firmware asks the cloud about each robot in the home data the sign-in stored, including robots that are not paired to this server, so an available update can be seen before pairing. A failure for one robot is reported on its row without hiding the rest. Co-Authored-By: Claude Sonnet 5.5 Co-Authored-By: Claude Opus 5.5 --- docs/roborock_app.md | 4 ++ src/roborock_local_server/cloud.py | 31 +++++++++++++ src/roborock_local_server/standalone_admin.py | 9 ++++ tests/test_cloud.py | 44 +++++++++++++++++++ tests/test_ota_firmware.py | 23 ++++++++++ 5 files changed, 111 insertions(+) diff --git a/docs/roborock_app.md b/docs/roborock_app.md index 0c969a9..2e6187c 100644 --- a/docs/roborock_app.md +++ b/docs/roborock_app.md @@ -184,6 +184,10 @@ The refresh reuses the login stored by the email-code sign-in and only replaces If the cloud rejects the stored login, or the snapshot predates this feature and has none, sign in again with the email code; that stores a login the refresh can use. +## Firmware Status for Every Robot + +`GET /admin/api/cloud/firmware` (signed in as admin, for example in a browser tab) asks the cloud about each robot on the account, including ones that are not paired to this server, and lists its model, the firmware the cloud last saw, and the available update. It uses the same stored login. + --- ## LocalRock (Third-Party App) diff --git a/src/roborock_local_server/cloud.py b/src/roborock_local_server/cloud.py index 0f8395c..346a551 100644 --- a/src/roborock_local_server/cloud.py +++ b/src/roborock_local_server/cloud.py @@ -190,6 +190,37 @@ async def firmware_update_info(self, duid: str, *, lang: str = "en") -> Any: """What the cloud says about a robot's firmware update, read with the stored login.""" return await self.iot_get(f"/ota/firmware/{duid}/updatev2", {"lang": lang}) + def firmware_devices(self) -> list[dict[str, Any]]: + """Every robot on the signed-in account, from the home data the sign-in stored.""" + home = self._read_snapshot().get("home_data") + home = home if isinstance(home, dict) else {} + models = { + str(product.get("id")): product.get("model") + for product in home.get("products") or [] if isinstance(product, dict) + } + rows: list[dict[str, Any]] = [] + for device in [*(home.get("devices") or []), *(home.get("received_devices") or [])]: + if isinstance(device, dict) and device.get("duid"): + rows.append({ + "duid": device["duid"], "name": device.get("name"), + "model": models.get(str(device.get("product_id"))), + "cloud_firmware": device.get("fv"), "online": device.get("online"), + }) + return rows + + async def firmware_status(self, *, lang: str = "en") -> list[dict[str, Any]]: + """Each account robot with the cloud's firmware update answer; one failure does not hide the rest.""" + self._stored_cloud_login() + rows = self.firmware_devices() + if not rows: + raise ValueError("No devices are stored. Sign in with an email code to import them.") + for row in rows: + try: + row["update"] = await self.iot_get("/ota/firmware/updatev2", {"duids": row["duid"], "lang": lang}) + except Exception as exc: # noqa: BLE001 + row["error"] = str(exc) + return rows + def plugin_catalogs(self) -> dict[str, Any]: """The stored plugin catalogs, summarized, without any cloud request.""" web_cache = self._read_snapshot().get("web_api_cache") diff --git a/src/roborock_local_server/standalone_admin.py b/src/roborock_local_server/standalone_admin.py index b83ad68..901aef4 100644 --- a/src/roborock_local_server/standalone_admin.py +++ b/src/roborock_local_server/standalone_admin.py @@ -484,6 +484,15 @@ async def admin_cloud_plugins(request: Request) -> JSONResponse: supervisor._require_admin(request) return JSONResponse({"success": True, **supervisor.cloud_manager.plugin_catalogs()}) + @app.get("/admin/api/cloud/firmware") + async def admin_cloud_firmware(request: Request) -> JSONResponse: + supervisor._require_admin(request) + try: + devices = await supervisor.cloud_manager.firmware_status() + except Exception as exc: # noqa: BLE001 + return JSONResponse({"success": False, "step": "firmware_status_failed", "error": str(exc)}, status_code=400) + return JSONResponse({"success": True, "devices": devices}) + @app.post("/admin/api/cloud/refresh-plugins") async def admin_cloud_refresh_plugins(request: Request) -> JSONResponse: supervisor._require_admin(request) diff --git a/tests/test_cloud.py b/tests/test_cloud.py index 1958c73..e556d3a 100644 --- a/tests/test_cloud.py +++ b/tests/test_cloud.py @@ -400,3 +400,47 @@ async def fake_hawk(api, user_data, path, *, params=None): def test_firmware_update_info_needs_a_stored_login(tmp_path) -> None: with pytest.raises(ValueError, match="No cloud login"): asyncio.run(_make_manager(tmp_path).firmware_update_info("duid-1")) + + +_HOME = { + "products": [{"id": "p116", "model": "roborock.vacuum.a101"}, {"id": "p223", "model": "roborock.vacuum.a245"}], + "devices": [ + {"duid": "pro", "name": "Quevo", "product_id": "p116", "fv": "02.15.26", "online": True}, + {"duid": "flow", "name": "Curv", "product_id": "p223", "fv": "02.40.00", "online": False}, + ], + "received_devices": [], +} + + +def test_firmware_status_lists_every_account_robot_and_isolates_failures(tmp_path, monkeypatch) -> None: + manager = _make_manager(tmp_path) + _write_snapshot(manager, home_data=_HOME) + asked: list = [] + + async def fake_iot_get(path, params=None): + asked.append((path, params)) + if params["duids"] == "pro": + raise RuntimeError("boom") + return [{"version": "02.45.78", "updatable": True}] + + monkeypatch.setattr(manager, "iot_get", fake_iot_get) + rows = asyncio.run(manager.firmware_status(lang="de")) + + assert asked == [ + ("/ota/firmware/updatev2", {"duids": "pro", "lang": "de"}), + ("/ota/firmware/updatev2", {"duids": "flow", "lang": "de"}), + ] + assert [(r["name"], r["model"], r["cloud_firmware"]) for r in rows] == [ + ("Quevo", "roborock.vacuum.a101", "02.15.26"), ("Curv", "roborock.vacuum.a245", "02.40.00"), + ] + assert rows[0]["error"] == "boom" and "update" not in rows[0] + assert rows[1]["update"] == [{"version": "02.45.78", "updatable": True}] + + +def test_firmware_status_needs_a_login_and_devices(tmp_path) -> None: + manager = _make_manager(tmp_path) + with pytest.raises(ValueError, match="No cloud login"): + asyncio.run(manager.firmware_status()) + _write_snapshot(manager) + with pytest.raises(ValueError, match="No devices are stored"): + asyncio.run(manager.firmware_status()) diff --git a/tests/test_ota_firmware.py b/tests/test_ota_firmware.py index ee0d322..32345c3 100644 --- a/tests/test_ota_firmware.py +++ b/tests/test_ota_firmware.py @@ -130,3 +130,26 @@ def test_an_upgrade_post_is_still_refused_as_a_replay(tmp_path) -> None: assert client.post(UPGRADE, json={}, headers=headers).json()["code"] == 501 assert client.post(UPGRADE, json={}, headers=headers).status_code == 401 + + +def test_admin_firmware_listing_needs_the_admin_login(tmp_path, monkeypatch) -> None: + client, supervisor, _ = _client(tmp_path) + + async def fake(): + return [{"duid": "flow", "name": "Curv", "update": [INFO]}] + + monkeypatch.setattr(supervisor.cloud_manager, "firmware_status", fake) + + assert client.get("/admin/api/cloud/firmware").status_code == 401 + assert client.post("/admin/api/login", json={"password": "correct horse battery staple"}).status_code == 200 + assert client.get("/admin/api/cloud/firmware").json() == {"success": True, "devices": [{"duid": "flow", "name": "Curv", "update": [INFO]}]} + + +def test_admin_firmware_listing_reports_why_it_failed(tmp_path) -> None: + client, _, _ = _client(tmp_path) + client.post("/admin/api/login", json={"password": "correct horse battery staple"}) + + response = client.get("/admin/api/cloud/firmware") + + assert response.status_code == 400 + assert response.json()["success"] is False and "No cloud login" in response.json()["error"] From ade7386961fa265702641997a8e3ade2d8f07ea3 Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:15:18 -0500 Subject: [PATCH 13/19] Install firmware from the official app's Update button With [ota] enable_install = true (or ROBOROCK_SERVER_OTA_ENABLE_INSTALL=true), the Update button's POST /ota/device//upgrade downloads the package the cloud offers, checks it against the MD5 in its address, serves it to the robot from this server and sends the robot's own OTA command. The robot has to be docked, idle and at 80% battery or more. While it runs, the app's status polls are answered from the robot's real state, since the cloud would answer them with an error that the app reads as a failed update. Co-Authored-By: Claude Sonnet 5.5 Co-Authored-By: Claude Opus 5.5 --- src/roborock_local_server/config.py | 21 + .../firmware_versions.py | 61 +++ src/roborock_local_server/ota_dry_run.py | 372 ++++++++++++++++++ src/roborock_local_server/ota_install.py | 137 +++++++ src/roborock_local_server/server.py | 45 ++- tests/test_ota_dry_run.py | 165 ++++++++ tests/test_ota_install.py | 104 +++++ tests/test_ota_package_dry_run.py | 206 ++++++++++ tests/test_ota_upgrade_button.py | 194 +++++++++ tests/test_reported_firmware.py | 42 ++ 10 files changed, 1346 insertions(+), 1 deletion(-) create mode 100644 src/roborock_local_server/firmware_versions.py create mode 100644 src/roborock_local_server/ota_dry_run.py create mode 100644 src/roborock_local_server/ota_install.py create mode 100644 tests/test_ota_dry_run.py create mode 100644 tests/test_ota_install.py create mode 100644 tests/test_ota_package_dry_run.py create mode 100644 tests/test_ota_upgrade_button.py create mode 100644 tests/test_reported_firmware.py diff --git a/src/roborock_local_server/config.py b/src/roborock_local_server/config.py index 1469631..484c597 100644 --- a/src/roborock_local_server/config.py +++ b/src/roborock_local_server/config.py @@ -4,6 +4,7 @@ from dataclasses import dataclass import ipaddress +import os from pathlib import Path import re import tomllib @@ -104,6 +105,13 @@ class TurnConfig: ttl: int = 86400 +@dataclass(frozen=True) +class OtaConfig: + """Firmware installs from the official app's Update button; off until the owner opts in.""" + + enable_install: bool = False + + @dataclass(frozen=True) class AppConfig: network: NetworkConfig @@ -113,6 +121,7 @@ class AppConfig: admin: AdminConfig turn: TurnConfig = TurnConfig() logging: LoggingConfig = LoggingConfig() + ota: OtaConfig = OtaConfig() @dataclass(frozen=True) @@ -249,6 +258,16 @@ def _as_bool(value: object, default: bool) -> bool: return bool(value) +def _ota_install_enabled(from_file: bool) -> bool: + """The env var wins when set, so installs can also be switched on for a config.toml that already exists.""" + override = os.environ.get("ROBOROCK_SERVER_OTA_ENABLE_INSTALL", "").strip().lower() + if override in {"1", "true", "yes", "on"}: + return True + if override in {"0", "false", "no", "off"}: + return False + return from_file + + def load_config(path: str | Path) -> AppConfig: config_path = Path(path).resolve() parsed = tomllib.loads(config_path.read_text(encoding="utf-8")) @@ -260,6 +279,7 @@ def load_config(path: str | Path) -> AppConfig: tls = _get_section(parsed, "tls") admin = _get_section(parsed, "admin") turn = _get_section(parsed, "turn") + ota = _get_section(parsed, "ota") turn_mode = str(turn.get("mode", "external" if _as_bool(turn.get("enabled"), False) else "disabled")).strip().lower() broker_mode = str(broker.get("mode", "embedded")).strip().lower() if broker_mode not in {"embedded", "external"}: @@ -347,6 +367,7 @@ def load_config(path: str | Path) -> AppConfig: cert_file=str(tls.get("cert_file", "")).strip(), key_file=str(tls.get("key_file", "")).strip(), ), + ota=OtaConfig(enable_install=_ota_install_enabled(_as_bool(ota.get("enable_install"), False))), admin=AdminConfig( password_hash=_require_non_empty(admin.get("password_hash"), "admin.password_hash"), session_secret=_require_non_empty(admin.get("session_secret"), "admin.session_secret"), diff --git a/src/roborock_local_server/firmware_versions.py b/src/roborock_local_server/firmware_versions.py new file mode 100644 index 0000000..60cd4f6 --- /dev/null +++ b/src/roborock_local_server/firmware_versions.py @@ -0,0 +1,61 @@ +"""The firmware version a robot says it runs, against what the cloud still believes. + +The cloud learns a robot's version from the robot's own connection to it. A robot paired to this server never +reports there, so after a local update the cloud keeps offering the update. The robot's own report (protocol 203, +sent each time it connects) is the truth, and the answers the apps read are corrected with it. +""" + +from __future__ import annotations + +from typing import Any + + +def parse(version: str) -> tuple[int, ...] | None: + try: + return tuple(int(part) for part in str(version).strip().split(".")) + except ValueError: + return None + + +def at_least(reported: str, offered: str) -> bool: + """True when the version the robot reports is the offered one or newer.""" + have, want = parse(reported), parse(offered) + if have is None or want is None: + return bool(reported) and reported == offered + return have >= want + + +def reported_version(snapshot_store: Any, duid: str) -> str: + """The version the robot last reported, or an empty string when it has not.""" + if snapshot_store is None or not duid: + return "" + try: + entry = snapshot_store.get(duid) + except Exception: # noqa: BLE001 + return "" + value = (entry or {}).get("firmware_version") + return value if isinstance(value, str) else "" + + +def reconcile(info: Any, duid: str, snapshot_store: Any) -> Any: + """An update answer for one robot with the robot's own version applied.""" + reported = reported_version(snapshot_store, duid) + if not reported or not isinstance(info, dict): + return info + fixed = dict(info) + fixed["currentVersion"] = reported + if at_least(reported, str(fixed.get("version") or "")): + fixed["updatable"] = False + return fixed + + +def reconcile_result(result: Any, duid: str, snapshot_store: Any) -> Any: + """Either answer shape: one robot's dict (the path style) or the list of per-robot rows (the query style).""" + if isinstance(result, list): + rows = [] + for row in result: + if isinstance(row, dict) and isinstance(row.get("firmwareUpdateResponse"), dict): + row = {**row, "firmwareUpdateResponse": reconcile(row["firmwareUpdateResponse"], str(row.get("duid") or ""), snapshot_store)} + rows.append(row) + return rows + return reconcile(result, duid, snapshot_store) diff --git a/src/roborock_local_server/ota_dry_run.py b/src/roborock_local_server/ota_dry_run.py new file mode 100644 index 0000000..a5b0782 --- /dev/null +++ b/src/roborock_local_server/ota_dry_run.py @@ -0,0 +1,372 @@ +"""A bounded dry run of a robot's local OTA command: it is asked to download, never to install. + +Random mode serves a throwaway file that is not a firmware, so nothing could be flashed even if +install were on. Package mode uses the robot's own CURRENT firmware package, resolved from the +cloud and checked against its checksum, with install off. Either way the file is served from a +one-time URL on this server, or the CDN address is given directly when asked. +""" + +from __future__ import annotations + +import asyncio +import hashlib +import os +import re +import secrets +import time +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any + +from fastapi.responses import Response, StreamingResponse + +FILE_BYTES = 64 * 1024 +TOKEN_TTL_SECONDS = 600 +WATCH_SECONDS = 60 +PACKAGE_WATCH_SECONDS = 240 +# An install: the robot reboots and is briefly unreachable, so the watch is long and tolerates silence. +INSTALL_WATCH_SECONDS = 900 +INSTALL_TOKEN_TTL_SECONDS = 1800 +INSTALL_MIN_BATTERY = 80 +WAIT_INSTALL_STUCK_SECONDS = 60 +MAX_PACKAGE_BYTES = 400 * 1024 * 1024 +CHUNK_BYTES = 64 * 1024 +# CDN response headers that are not replayed: this server sets its own length, ranges and connection handling. +_NOT_MIRRORED = {"content-length", "transfer-encoding", "connection", "keep-alive", "date", "content-encoding", "accept-ranges"} +POLL_SECONDS = 2 +# Charging states of the robot: 8 charging, 100 fully charged. +DOCKED_STATES = {8, 100} +# A robot asleep on its dock reports state 2 (charger disconnected) while charge_status says it is on the charger. +SLEEPING_ON_DOCK_STATE = 2 +# States a new attempt may start from: wait_install is a package a dry run staged earlier, replaced by the new one. +STARTABLE_STATES = ("idle", "failed", "wait_install") +_PACKAGE_MD5 = re.compile(r"\.([0-9a-f]{32})\.signed\.pkg$") +_PATH = re.compile(r"^/ota_test/([A-Za-z0-9_-]{16,})(?:/([A-Za-z0-9._-]{1,200})|\.bin)$") +_RANGE = re.compile(r"^bytes=(\d*)-(\d*)$") +_HEADERS_KEPT = ("user-agent", "range", "accept", "host", "connection", "if-none-match", "if-range") + + +class _CasedResponse(StreamingResponse): + """A streamed response that sends header names exactly as given. + + Starlette lowercases header names, which a minimal embedded HTTP client may not accept; uvicorn's h11 + keeps the case it is handed, so names like Content-Length reach the wire as written. + """ + + def init_headers(self, headers: Any = None) -> None: + self.raw_headers = [(name.encode("latin-1"), value.encode("latin-1")) for name, value in (headers or {}).items()] + + +def _size(data: bytes | Path) -> int: + return data.stat().st_size if isinstance(data, Path) else len(data) + + +def _chunks(data: bytes | Path, start: int, end: int): + """The bytes from start to end (inclusive) in chunks, read from memory or from the cached file.""" + if isinstance(data, Path): + with data.open("rb") as handle: + handle.seek(start) + left = end - start + 1 + while left > 0: + chunk = handle.read(min(CHUNK_BYTES, left)) + if not chunk: + break + left -= len(chunk) + yield chunk + return + for offset in range(start, end + 1, CHUNK_BYTES): + yield data[offset:min(offset + CHUNK_BYTES, end + 1)] + + +@dataclass +class _Active: + token: str + data: bytes | Path + md5: str + expires_at: float + filename: str = "" + headers: dict[str, str] = field(default_factory=dict) + variant: dict[str, bool] = field(default_factory=dict) + hits: list[dict[str, Any]] = field(default_factory=list) + + +class OtaDryRun: + def __init__(self) -> None: + self._active: _Active | None = None + + def file_response(self, clean_path: str, method: str, headers: Any, remote: str) -> Response | None: + """The test file for its one-time URL, or None when the path is not a dry-run path.""" + match = _PATH.match(clean_path) + if match is None: + return None + active = self._active + asked_name = match.group(2) + if ( + active is None or not secrets.compare_digest(active.token, match.group(1)) or time.time() > active.expires_at + or (asked_name is not None and asked_name != active.filename) + ): + return Response(status_code=404) + hit: dict[str, Any] = { + "time": time.time(), "method": method, "remote": remote, + "headers": {key: headers.get(key) for key in _HEADERS_KEPT if headers.get(key) is not None}, + } + active.hits.append(hit) + total = _size(active.data) + status, start, end, extra = 200, 0, total - 1, {"Accept-Ranges": "bytes", **active.headers} + requested = _RANGE.match(str(headers.get("range") or "")) + if requested: + start_text, end_text = requested.groups() + first = int(start_text) if start_text else max(0, total - int(end_text or 0)) + last = min(int(end_text), total - 1) if end_text and start_text else total - 1 + if 0 <= first <= last < total: + status, start, end = 206, first, last + extra["Content-Range"] = f"bytes {start}-{end}/{total}" + length = max(0, end - start + 1) + if method == "HEAD": + return Response(content=b"", status_code=status, media_type="application/octet-stream", + headers={**extra, "Content-Length": str(length)}) + variant = active.variant + body = self._counted(active.data, start, end, total, hit) + # Robots only accept the file when header names are capitalised (Content-Length), as the CDN sends them. + if variant.get("title_case", True): + headers_out = {"Content-Type": "application/octet-stream", "Content-Length": str(length), **extra} + if variant.get("connection_close"): + headers_out["Connection"] = "close" + return _CasedResponse(body, status_code=status, headers=headers_out) + return StreamingResponse( + body, status_code=status, media_type="application/octet-stream", + headers={**extra, "Content-Length": str(length), **({"Connection": "close"} if variant.get("connection_close") else {})}, + ) + + @staticmethod + async def _counted(data: bytes | Path, start: int, end: int, total: int, hit: dict[str, Any]): + """Sends the file in chunks and records how much the robot took and whether it took all of it.""" + sent, started = 0, time.monotonic() + try: + for chunk in _chunks(data, start, end): + yield chunk + sent += len(chunk) + hit["completed"] = True + finally: + hit.setdefault("completed", False) + hit["bytes_sent"], hit["of_bytes"], hit["seconds"] = sent, total, round(time.monotonic() - started, 2) + + async def run( + self, client: Any, api_url: str, package: dict[str, Any] | None = None, variant: dict[str, bool] | None = None, + install: bool = False, on_state: Any = None, + ) -> dict[str, Any]: + """Checks the robot is docked and idle, asks it to download the file, and watches its OTA state. + + [package] is {"url", "md5", "data"}: the robot's current firmware, with its bytes when this server + should serve it, or None for data when the robot should fetch the url directly. Without a package + a random file is used. With [install] the robot is asked to download AND install the package. + """ + refusal = await self._refusal(client, INSTALL_MIN_BATTERY if install else 30) + if refusal: + return {"ran": False, "reason": refusal} + + direct_url, filename, headers = None, "", {} + if package is None: + data = os.urandom(FILE_BYTES) + md5 = hashlib.md5(data).hexdigest() # noqa: S324 + else: + data, md5 = package.get("data") or b"", package["md5"] + if package.get("data") is None: + direct_url = package["url"] + else: + filename, headers = package.get("filename", ""), package.get("headers", {}) + ttl = INSTALL_TOKEN_TTL_SECONDS if install else TOKEN_TTL_SECONDS + active = _Active(secrets.token_urlsafe(18), data, md5, time.time() + ttl, filename, headers, dict(variant or {})) + self._active = active + served = f"{api_url}/ota_test/{active.token}/{filename}" if filename else f"{api_url}/ota_test/{active.token}.bin" + params = { + "mode": "normal", "install": "1" if install else "0", "app_url": direct_url or served, + "file_md5": md5, "proc": "dnld install" if install else "dnld", + } + seconds = INSTALL_WATCH_SECONDS if install else (PACKAGE_WATCH_SECONDS if package else WATCH_SECONDS) + try: + reply = await self._ask(client, "miIO.ota", params) + trace = await self._watch(client, seconds, install=install, on_state=on_state) + finally: + self._active = None + states = [step["state"] for step in trace] + return { + "ran": True, "package": package is not None, "variant": active.variant, "install": install, + "saw_offline": None in states, + "stuck_in_wait_install": install and bool(trace) and trace[-1]["state"] == "wait_install", + "params": {**params, "app_url": params["app_url"].replace(active.token, "")}, + "ota_reply": reply, "file_fetched": bool(active.hits), "hits": active.hits, "trace": trace, + "final_state": trace[-1]["state"] if trace else None, + } + + @staticmethod + async def _ask(client: Any, method: str, params: Any) -> Any: + try: + return await client.send_command(method, params) + except Exception as exc: # noqa: BLE001 + return {"error": str(exc)} + + async def _refusal(self, client: Any, min_battery: int = 30) -> str: + status = await self._ask(client, "get_status", []) + first = status[0] if isinstance(status, list) and status and isinstance(status[0], dict) else None + if first is None: + return f"Could not read the robot's status: {status}" + state = first.get("state") + docked = state in DOCKED_STATES or (state == SLEEPING_ON_DOCK_STATE and first.get("charge_status") == 1) + if not docked or first.get("in_cleaning") or first.get("error_code"): + return f"The robot must be docked, idle and error-free (state={first.get('state')}, error={first.get('error_code')})" + if int(first.get("battery") or 0) < min_battery: + return f"The battery is too low ({first.get('battery')}%)" + ota = await self._ask(client, "get_ota_state", []) + state = ota.get("ota_state") if isinstance(ota, dict) else None + if state not in STARTABLE_STATES: + # failed only records that the last attempt ended, and wait_install is a package an earlier dry run + # staged; a new attempt replaces either. + return f"The robot's OTA state is {state!r}, so an update may be in progress" + return "" + + async def _watch( + self, client: Any, seconds: float = WATCH_SECONDS, install: bool = False, on_state: Any = None, + ) -> list[dict[str, Any]]: + """Polls the robot's OTA state. In install mode wait_install is not a resting place, so the watch goes on + through it (the robot may pass through it on the way to installing) unless it sits there too long.""" + resting = ("idle", "failed") if install else ("idle", "failed", "wait_install") + trace: list[dict[str, Any]] = [] + started = time.monotonic() + left_idle = False + settled_at: float | None = None + waiting_since: float | None = None + while time.monotonic() - started < seconds: + ota = await self._ask(client, "get_ota_state", []) + progress = await self._ask(client, "get_ota_progress", []) + state = ota.get("ota_state") if isinstance(ota, dict) else ota + trace.append({ + "t": round(time.monotonic() - started, 1), "state": state, + "progress": progress.get("ota_progress") if isinstance(progress, dict) else progress, + "raw": ota, + }) + if on_state is not None: + on_state(state, trace[-1]["progress"]) + if state not in (None,) + resting: + left_idle, settled_at = True, None + if install and state == "wait_install": + waiting_since = waiting_since or time.monotonic() + if time.monotonic() - waiting_since > WAIT_INSTALL_STUCK_SECONDS: + break + elif state is not None: + waiting_since = None + if left_idle and state in resting: + settled_at = settled_at or time.monotonic() + if time.monotonic() - settled_at > 4: + break + await asyncio.sleep(POLL_SECONDS) + return trace + + +class PackageRefused(Exception): + """The firmware package could not be used safely; the message says why.""" + + +async def _download_to_file(url: str, target: Path) -> tuple[str, dict[str, str]]: + """Streams the package to [target] and returns its md5 and the CDN's response headers.""" + import aiohttp + + digest, size = hashlib.md5(), 0 # noqa: S324 + timeout = aiohttp.ClientTimeout(total=1800) + target.parent.mkdir(parents=True, exist_ok=True) + partial = target.with_name(target.name + ".part") + try: + async with aiohttp.ClientSession(timeout=timeout) as session: + async with session.get(url) as response: + if response.status != 200: + raise PackageRefused(f"The package server answered HTTP {response.status}") + headers = dict(response.headers) + with partial.open("wb") as handle: + async for chunk in response.content.iter_chunked(1024 * 1024): + size += len(chunk) + if size > MAX_PACKAGE_BYTES: + raise PackageRefused("The package is larger than the limit") + digest.update(chunk) + handle.write(chunk) + partial.replace(target) + finally: + partial.unlink(missing_ok=True) + return digest.hexdigest(), headers + + +def _file_md5(path: Path) -> str: + digest = hashlib.md5() # noqa: S324 + with path.open("rb") as handle: + for block in iter(lambda: handle.read(1024 * 1024), b""): + digest.update(block) + return digest.hexdigest() + + +def clean_package_cache(cache_dir: Path, keep: str = "") -> None: + """Removes cached packages (and half-downloaded ones) other than the one named [keep].""" + for path in cache_dir.glob("*.pkg*") if cache_dir.is_dir() else (): + if path.name != keep: + path.unlink(missing_ok=True) + + +async def _download(url: str) -> tuple[bytes, dict[str, str]]: + """The package bytes and the CDN's response headers.""" + import aiohttp + + timeout = aiohttp.ClientTimeout(total=600) + async with aiohttp.ClientSession(timeout=timeout) as session: + async with session.get(url) as response: + if response.status != 200: + raise PackageRefused(f"The package server answered HTTP {response.status}") + if int(response.headers.get("Content-Length") or 0) > MAX_PACKAGE_BYTES: + raise PackageRefused("The package is larger than the limit") + return await response.read(), dict(response.headers) + + +async def resolve_package( + cloud: Any, duid: str, version: str, *, serve: bool, allow_update: bool = False, cache_dir: Path | None = None, +) -> dict[str, Any]: + """The robot's current firmware package: its address from the cloud, and its checksum verified. + + Only the version the cloud says the robot runs is accepted, so a dry run can never change the + firmware. With [serve] the bytes are fetched here and checked against the checksum in the file + name; the robot then downloads them from this server instead of the CDN. + """ + info = await cloud.firmware_update_info(duid) + current = info.get("currentVersion") if isinstance(info, dict) else None + offered = info.get("version") if isinstance(info, dict) and info.get("updatable") is True else None + if not version or (current != version and not (allow_update and offered == version)): + raise PackageRefused(f"Only the robot's current version can be used (the cloud says {current!r}, asked for {version!r})") + reply = await cloud.iot_get(f"/user/devices/{duid}/fw", {"version": version}) + url = reply.get("url") if isinstance(reply, dict) else None + match = _PACKAGE_MD5.search(str(url or "")) + if not url or not str(url).startswith("https://") or match is None: + raise PackageRefused(f"The cloud's package address is not in the expected form: {url!r}") + md5 = match.group(1) + if not serve: + return {"url": url, "md5": md5, "data": None} + if cache_dir is not None: + name = f"{md5}.pkg" + path = cache_dir / name + clean_package_cache(cache_dir, keep=name) + loop = asyncio.get_running_loop() + if path.is_file() and await loop.run_in_executor(None, _file_md5, path) == md5: + cdn_headers: dict[str, str] = {} + else: + path.unlink(missing_ok=True) + got, cdn_headers = await _download_to_file(str(url), path) + if got != md5: + path.unlink(missing_ok=True) + raise PackageRefused("The downloaded package does not match the checksum in its address") + return { + "url": url, "md5": md5, "data": path, "filename": str(url).rsplit("/", 1)[-1], + "headers": {key: value for key, value in cdn_headers.items() if key.lower() not in _NOT_MIRRORED}, + } + data, cdn_headers = await _download(url) + if hashlib.md5(data).hexdigest() != md5: # noqa: S324 + raise PackageRefused("The downloaded package does not match the checksum in its address") + # Served under its real file name and with the CDN's own response headers, as the robot may rely on either. + return { + "url": url, "md5": md5, "data": data, "filename": str(url).rsplit("/", 1)[-1], + "headers": {key: value for key, value in cdn_headers.items() if key.lower() not in _NOT_MIRRORED}, + } diff --git a/src/roborock_local_server/ota_install.py b/src/roborock_local_server/ota_install.py new file mode 100644 index 0000000..b8890cb --- /dev/null +++ b/src/roborock_local_server/ota_install.py @@ -0,0 +1,137 @@ +"""Installs firmware when the official app's Update button is pressed. + +The cloud says which version is on offer; the package is fetched, checked against the checksum in its +address and served to the robot from this server, which then downloads, installs and reboots. +""" + +from __future__ import annotations + +import asyncio +import json +import logging +import time +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + +from .bundled_backend.shared.routine_runner import _RoutineMqttClient +from .ota_dry_run import PackageRefused, clean_package_cache, resolve_package + +# A child logger: only real_stack. loggers have an output handler, plain real_stack drops INFO. +logger = logging.getLogger("real_stack.api") + + +class OtaInstaller: + def __init__(self, supervisor: Any) -> None: + self._supervisor = supervisor + self._running: dict[str, asyncio.Task[None]] = {} + self.results: dict[str, dict[str, Any]] = {} + # What the official app reads while an install runs: the cloud knows nothing of a local install, so + # the app's status polls are answered from here. The app treats IDLE as success and an error as failure. + self._live: dict[str, dict[str, Any]] = {} + + @property + def cache_dir(self) -> Path: + return self._supervisor.paths.runtime_dir / "ota_packages" + + async def start(self, duid: str) -> dict[str, Any]: + """Begins an install in the background, or says why not. One install runs at a time.""" + supervisor = self._supervisor + if any(not task.done() for task in self._running.values()): + return {"started": False, "reason": "Another firmware install is already running"} + vacuum = next((v for v in supervisor._vacuums_payload()["vacuums"] if str(v.get("duid") or "") == duid), None) + if vacuum is None: + return {"started": False, "reason": f"Unknown device {duid!r}"} + try: + info = await supervisor.cloud_manager.firmware_update_info(duid) + except Exception as exc: # noqa: BLE001 + return {"started": False, "reason": f"Could not ask the cloud about updates: {exc}"} + version = info.get("version") if isinstance(info, dict) else None + if not isinstance(info, dict) or info.get("updatable") is not True or not version: + return {"started": False, "reason": "The cloud offers no update for this robot"} + try: + package = await resolve_package(supervisor.cloud_manager, duid, str(version), serve=True, allow_update=True, cache_dir=self.cache_dir, + ) + except PackageRefused as exc: + return {"started": False, "reason": str(exc)} + except Exception as exc: # noqa: BLE001 + return {"started": False, "reason": f"Could not fetch the package: {exc}"} + device = {"duid": duid, "localkey": str(vacuum.get("local_key") or "")} + self.results.pop(duid, None) + self._set_live(duid, "START") + self._running[duid] = asyncio.create_task(self._install(device, package, str(version))) + return {"started": True, "version": str(version)} + + _APP_STATES = {"downloading": "DOWNLOADING", "installing": "INSTALLING", "wait_install": "WAIT_INSTALL"} + LIVE_SECONDS = 1800 + + def _set_live(self, duid: str, status: str, progress: str = "", err_msg: str = "", err_code: int = 0) -> None: + self._live[duid] = { + "status": status, "progress": progress, "errCode": err_code, "errMsg": err_msg, "at": time.monotonic(), + } + + def _robot_state(self, duid: str, state: Any, progress: Any) -> None: + """Mirrors the robot's own OTA state. A robot that is idle or silent keeps its last status; IDLE and FAILED + are only set at the end, since the app reads IDLE as the update being done.""" + status = self._APP_STATES.get(str(state)) + if status is None: + return + text = "" if progress is None else str(progress) + previous = self._live.get(duid) + if status == "INSTALLING": + # The robot reports no progress of its own while installing (its query answers 0 even though its + # messages said 100 at the end of the download), so keep the download's last number. + text = "100" + elif previous is not None and previous["status"] == status and previous["progress"] not in ("", "0"): + # The robot sometimes does not answer the progress query, or answers 0; keep the last real number + # so the app's percentage does not fall back to 0 and climb again. + if text in ("", "0"): + text = previous["progress"] + self._set_live(duid, status, text) + + def _write_record(self, duid: str, record: dict[str, Any]) -> None: + """Keeps the whole install (state timeline, what the robot downloaded, the version it reports afterwards) + in the data volume, since it is otherwise lost when the container restarts.""" + try: + folder = self._supervisor.paths.runtime_dir / "ota_results" + folder.mkdir(parents=True, exist_ok=True) + stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + (folder / f"{stamp}_{duid}.json").write_text(json.dumps(record, indent=2, default=str), encoding="utf-8") + except Exception as exc: # noqa: BLE001 + logger.warning("Could not write the firmware install record: %s", exc) + + def live_status(self, duid: str) -> dict[str, Any] | None: + """The status for the app's poll, or None when no local install ran in the last half hour.""" + entry = self._live.get(duid) + if entry is None or time.monotonic() - entry["at"] > self.LIVE_SECONDS: + return None + return {key: value for key, value in entry.items() if key != "at"} + + async def _install(self, device: dict[str, str], package: dict[str, Any], version: str) -> None: + supervisor = self._supervisor + duid = device["duid"] + client = _RoutineMqttClient(supervisor.context, device, logger) + try: + await client.connect() + result = await supervisor.ota_dry_run.run( + client, supervisor.context.api_url(), package, None, True, + on_state=lambda state, progress: self._robot_state(duid, state, progress), + ) + except Exception as exc: # noqa: BLE001 + result = {"ran": False, "reason": str(exc)} + finally: + await client.close() + snapshot = supervisor.context.snapshot_store.get(duid) if supervisor.context.snapshot_store else None + reported = (snapshot or {}).get("firmware_version") + self.results[duid] = {**result, "version": version, "firmware_version_reported": reported} + self._write_record(duid, self.results[duid]) + succeeded = bool(result.get("ran")) and result.get("final_state") == "idle" and bool(result.get("saw_offline")) + if succeeded: + self._set_live(duid, "IDLE", "100") + else: + self._set_live(duid, "FAILED", err_msg=str(result.get("reason") or "The robot did not finish the update"), err_code=1) + if reported != version: + logger.warning("After the install the robot %s reports firmware %r, not %s", duid, reported, version) + if result.get("ran") and result.get("final_state") == "idle" and result.get("saw_offline"): + clean_package_cache(self.cache_dir) + logger.info("Firmware install of %s on %s finished: ran=%s final=%s", version, duid, result.get("ran"), result.get("final_state")) diff --git a/src/roborock_local_server/server.py b/src/roborock_local_server/server.py index f6191e9..3674da7 100644 --- a/src/roborock_local_server/server.py +++ b/src/roborock_local_server/server.py @@ -30,8 +30,11 @@ from .product_registry import resolve_product_metadata from .bundled_backend.shared.runtime_state import ONBOARDING_STEP_LABELS, REQUIRED_ONBOARDING_STEPS from .cloud import CloudImportManager +from . import firmware_versions from .config import AppConfig, AppPaths, load_config, resolve_paths from .log_retention import configure_jsonl_logging +from .ota_dry_run import OtaDryRun +from .ota_install import OtaInstaller from .turn_relay import EmbeddedTurnRelay from .standalone_admin import register_standalone_admin_routes from .backend import ( @@ -375,6 +378,8 @@ def __init__( inventory_path=self.paths.inventory_path, snapshot_path=self.paths.cloud_snapshot_path, ) + self.ota_dry_run = OtaDryRun() + self.ota_installer = OtaInstaller(self) self.protocol_auth = ProtocolAuthStore( self.paths.cloud_snapshot_path, session_store_path=self.paths.protocol_auth_sessions_path, @@ -649,6 +654,7 @@ def _protocol_login_identity(self) -> dict[str, Any]: _OTA_CHECK = re.compile(r"^/ota/firmware/([^/]+)/updatev2/?$") _OTA_CHECK_QUERY = re.compile(r"^/ota/firmware/updatev2/?$") _OTA_STATUS = re.compile(r"^/ota/firmware/upgrade/status/?$") + _OTA_STATUS_PATH = re.compile(r"^/ota/firmware/([^/]+)/upgrade/status/?$") _OTA_UPGRADE = re.compile(r"^/ota/device/([^/]+)/upgrade(/latest-stable)?/?$") def _is_firmware_read(self, clean_path: str) -> bool: @@ -656,8 +662,23 @@ def _is_firmware_read(self, clean_path: str) -> bool: self._OTA_CHECK.match(clean_path) or self._OTA_CHECK_QUERY.match(clean_path) or self._OTA_STATUS.match(clean_path) + or self._OTA_STATUS_PATH.match(clean_path) ) + def _local_ota_status(self, clean_path: str, duids: str) -> Any: + """The status of an install this server is running, in the shape the app reads, or None to ask the cloud.""" + by_path = self._OTA_STATUS_PATH.match(clean_path) + if by_path is not None: + return self.ota_installer.live_status(by_path.group(1)) + if self._OTA_STATUS.match(clean_path): + rows = [] + for duid in [part for part in duids.split(",") if part]: + status = self.ota_installer.live_status(duid) + if status is not None: + rows.append({"duid": duid, **status}) + return rows or None + return None + async def _firmware_ota_response( self, clean_path: str, method: str, query_params: dict[str, list[str]], ) -> tuple[str, dict[str, Any]] | None: @@ -668,6 +689,9 @@ def first(name: str, default: str = "") -> str: route_name = "ota_firmware_check" read: tuple[str, dict[str, str]] | None = None if method == "GET": + local = self._local_ota_status(clean_path, first("duids")) + if local is not None: + return "ota_firmware_status_local", {"success": True, "code": 200, "msg": "success", "data": local, "result": local} if (check := self._OTA_CHECK.match(clean_path)) is not None: read = (f"/ota/firmware/{check.group(1)}/updatev2", {"lang": first("lang", "en")}) elif self._OTA_CHECK_QUERY.match(clean_path): @@ -678,13 +702,22 @@ def first(name: str, default: str = "") -> str: if read is not None: try: result = await self.cloud_manager.iot_get(read[0], read[1]) + if route_name == "ota_firmware_check": + path_duid = check.group(1) if (check := self._OTA_CHECK.match(clean_path)) else "" + result = firmware_versions.reconcile_result(result, path_duid, self.context.snapshot_store) except Exception as exc: # noqa: BLE001 logging.getLogger("real_stack").warning("Firmware request %s failed: %s", clean_path, exc) return route_name, { "success": False, "code": 502, "msg": "firmware_check_unavailable", "data": {"error": str(exc)}, } return route_name, {"success": True, "code": 200, "msg": "success", "data": result, "result": result} - if self._OTA_UPGRADE.match(clean_path) and method == "POST": + upgrade = self._OTA_UPGRADE.match(clean_path) + if upgrade and method == "POST" and not upgrade.group(2) and self.config.ota.enable_install: + started = await self.ota_installer.start(upgrade.group(1)) + if started["started"]: + return "ota_upgrade_started", {"success": True, "code": 200, "msg": "success", "data": started, "result": started} + return "ota_upgrade_refused", {"success": False, "code": 409, "msg": "firmware_upgrade_refused", "data": started} + if upgrade and method == "POST": return "ota_upgrade_unsupported", { "success": False, "code": 501, @@ -1344,6 +1377,16 @@ async def _handle_roborock_request(self, request: Request) -> Response: ) return JSONResponse(response_payload, status_code=status_code) + dry_run_file = self.ota_dry_run.file_response( + clean_path, request.method, request.headers, str(entry["remote"]), + ) + if dry_run_file is not None: + entry["route"] = "ota_dry_run_file" + entry["response_meta"] = {"status_code": dry_run_file.status_code} + append_jsonl(self.context.http_jsonl, entry) + logger.info("%s %s host=%s route=ota_dry_run_file status=%d", request.method, clean_path, host or "-", dry_run_file.status_code) + return dry_run_file + try: plugin_dispatch = await dispatch_plugin_zip_request( clean_path=clean_path, diff --git a/tests/test_ota_dry_run.py b/tests/test_ota_dry_run.py new file mode 100644 index 0000000..6863db7 --- /dev/null +++ b/tests/test_ota_dry_run.py @@ -0,0 +1,165 @@ +import asyncio +import hashlib + +from roborock_local_server import ota_dry_run +from roborock_local_server.ota_dry_run import OtaDryRun + +DOCKED = [{"state": 8, "battery": 100, "in_cleaning": 0, "error_code": 0}] + + +class FakeRobot: + """Plays the robot: answers the reads, and 'downloads' the file when asked to.""" + + def __init__(self, dry_run: OtaDryRun, states, status=None, fetch=True): + self.dry_run, self.states, self.status = dry_run, list(states), status or DOCKED + self.fetch, self.asked, self.fetched = fetch, [], None + + async def send_command(self, method, params): + self.asked.append((method, params)) + if method == "get_status": + return self.status + if method == "get_ota_state": + state = self.states.pop(0) if len(self.states) > 1 else self.states[0] + return {"ota_state": state, "ts": 1} + if method == "get_ota_progress": + return {"ota_progress": 0} + if method == "miIO.ota": + if self.fetch: + path = "/" + params["app_url"].split("/", 3)[3] + self.fetched = self.dry_run.file_response(path, "GET", {"user-agent": "robot/1"}, "10.0.0.5") + return ["ok"] + raise AssertionError(method) + + +async def _body(response): + """The bytes of a streamed response.""" + return b"".join([chunk async for chunk in response.body_iterator]) + + +def _fast(monkeypatch): + monkeypatch.setattr(ota_dry_run, "POLL_SECONDS", 0) + monkeypatch.setattr(ota_dry_run, "WATCH_SECONDS", 2) + + +def test_the_robot_is_asked_to_download_without_installing_and_the_file_is_served(monkeypatch) -> None: + _fast(monkeypatch) + dry_run = OtaDryRun() + robot = FakeRobot(dry_run, ["idle", "idle", "downloading", "failed", "failed", "failed"]) + + result = asyncio.run(dry_run.run(robot, "https://srv:555")) + + ota_call = next(params for method, params in robot.asked if method == "miIO.ota") + assert (ota_call["mode"], ota_call["install"], ota_call["proc"]) == ("normal", "0", "dnld") + assert ota_call["app_url"].startswith("https://srv:555/ota_test/") + assert result["ran"] is True and result["file_fetched"] is True + assert result["hits"][0]["headers"] == {"user-agent": "robot/1"} + assert [step["state"] for step in result["trace"]][:3] == ["idle", "downloading", "failed"] + assert result["final_state"] == "failed" + assert "" in result["params"]["app_url"] and ota_call["app_url"] not in str(result) + served = robot.fetched + assert served.status_code == 200 and hashlib.md5(asyncio.run(_body(served))).hexdigest() == ota_call["file_md5"] # noqa: S324 + + +def test_the_url_stops_working_after_the_run(monkeypatch) -> None: + _fast(monkeypatch) + dry_run = OtaDryRun() + robot = FakeRobot(dry_run, ["idle"]) + asyncio.run(dry_run.run(robot, "https://srv:555")) + + token_path = "/" + next(p for m, p in robot.asked if m == "miIO.ota")["app_url"].split("/", 3)[3] + assert dry_run.file_response(token_path, "GET", {}, "x").status_code == 404 + assert dry_run.file_response("/ota_test/not-a-real-token-at-all.bin", "GET", {}, "x").status_code == 404 + assert dry_run.file_response("/something/else", "GET", {}, "x") is None + + +def test_a_robot_that_is_not_docked_idle_and_healthy_is_left_alone(monkeypatch) -> None: + _fast(monkeypatch) + for status in ([{"state": 5, "battery": 90, "in_cleaning": 1, "error_code": 0}], + [{"state": 8, "battery": 10, "in_cleaning": 0, "error_code": 0}], + [{"state": 8, "battery": 90, "in_cleaning": 0, "error_code": 12}]): + dry_run = OtaDryRun() + robot = FakeRobot(dry_run, ["idle"], status=status) + result = asyncio.run(dry_run.run(robot, "https://srv:555")) + assert result["ran"] is False + assert all(method != "miIO.ota" for method, _ in robot.asked) + + +def test_a_robot_already_updating_is_left_alone(monkeypatch) -> None: + _fast(monkeypatch) + dry_run = OtaDryRun() + robot = FakeRobot(dry_run, ["downloading"]) + result = asyncio.run(dry_run.run(robot, "https://srv:555")) + assert result["ran"] is False and "downloading" in result["reason"] + assert all(method != "miIO.ota" for method, _ in robot.asked) + + +def test_range_and_head_requests_are_answered(monkeypatch) -> None: + _fast(monkeypatch) + dry_run = OtaDryRun() + robot = FakeRobot(dry_run, ["idle"], fetch=False) + + async def go(): + # Keep the URL alive for the requests by starting a run and reading the token mid-way. + original = robot.send_command + + async def spy(method, params): + if method == "miIO.ota": + path = "/" + params["app_url"].split("/", 3)[3] + robot.part = dry_run.file_response(path, "GET", {"range": "bytes=0-9"}, "x") + robot.head = dry_run.file_response(path, "HEAD", {}, "x") + return await original(method, params) + + robot.send_command = spy + return await dry_run.run(robot, "https://srv:555") + + asyncio.run(go()) + assert robot.part.status_code == 206 and dict((k.lower(), v) for k, v in robot.part.raw_headers)[b"content-length"] == b"10" + assert dict((k.lower(), v) for k, v in robot.part.raw_headers)[b"content-range"].startswith(b"bytes 0-9/") + assert robot.head.status_code == 200 and robot.head.body == b"" + assert robot.head.headers["content-length"] == str(ota_dry_run.FILE_BYTES) + + +def test_a_robot_still_showing_a_failed_attempt_can_start_a_new_one(monkeypatch) -> None: + _fast(monkeypatch) + dry_run = OtaDryRun() + # It starts as "failed", then really downloads, then settles: the watch must not stop at the first reading. + robot = FakeRobot(dry_run, ["failed", "failed", "downloading", "downloading", "idle", "idle", "idle"]) + + result = asyncio.run(dry_run.run(robot, "https://srv:555")) + + assert result["ran"] is True + assert "downloading" in [step["state"] for step in result["trace"]] + assert result["final_state"] == "idle" + + +def test_a_robot_that_is_updating_is_still_left_alone(monkeypatch) -> None: + _fast(monkeypatch) + for state in ("downloading", "installing"): + robot = FakeRobot(OtaDryRun(), [state]) + result = asyncio.run(OtaDryRun().run(robot, "https://srv:555")) + assert result["ran"] is False and "in progress" in result["reason"] + + +def test_the_file_route_records_how_much_the_robot_took() -> None: + dry_run = OtaDryRun() + active = dry_run._active = ota_dry_run._Active("t" * 24, b"x" * (3 * ota_dry_run.CHUNK_BYTES), "md5", 9e12) + path = "/ota_test/" + "t" * 24 + ".bin" + + async def take_all(): + response = dry_run.file_response(path, "GET", {}, "robot") + return await _body(response) + + assert len(asyncio.run(take_all())) == 3 * ota_dry_run.CHUNK_BYTES + assert active.hits[0]["completed"] is True + assert (active.hits[0]["bytes_sent"], active.hits[0]["of_bytes"]) == (3 * ota_dry_run.CHUNK_BYTES, 3 * ota_dry_run.CHUNK_BYTES) + + async def take_some(): + response = dry_run.file_response(path, "GET", {}, "robot") + iterator = response.body_iterator + await iterator.__anext__() + await iterator.__anext__() + await iterator.aclose() + + asyncio.run(take_some()) + assert active.hits[1]["completed"] is False + assert active.hits[1]["bytes_sent"] == ota_dry_run.CHUNK_BYTES and active.hits[1]["of_bytes"] == 3 * ota_dry_run.CHUNK_BYTES diff --git a/tests/test_ota_install.py b/tests/test_ota_install.py new file mode 100644 index 0000000..9fbb719 --- /dev/null +++ b/tests/test_ota_install.py @@ -0,0 +1,104 @@ +import asyncio + +import pytest + +from roborock_local_server import ota_dry_run +from roborock_local_server.ota_dry_run import OtaDryRun +from test_ota_package_dry_run import MD5, PACKAGE, URL, FakeCloud, _no_network # noqa: F401 + +PACKAGE_INFO = {"url": URL, "md5": MD5, "data": PACKAGE, "filename": f"pearl-s_1526_fullos.{MD5}.signed.pkg", "headers": {}} + + +class Robot: + """A robot whose OTA state follows a script; None means it did not answer (rebooting).""" + + def __init__(self, states, battery=100): + self.states, self.battery, self.asked = list(states), battery, [] + + status_extra: dict = {} + + async def send_command(self, method, params): + self.asked.append((method, params)) + if method == "get_status": + return [{"state": 8, "battery": self.battery, "in_cleaning": 0, "error_code": 0, **self.status_extra}] + if method == "get_ota_state": + state = self.states.pop(0) if len(self.states) > 1 else self.states[0] + if state is None: + raise TimeoutError("no answer") + return {"ota_state": state} + if method == "get_ota_progress": + return {"ota_progress": 0} + if method == "miIO.ota": + return ["ok"] + raise AssertionError(method) + + +@pytest.fixture(autouse=True) +def _fast(monkeypatch): + monkeypatch.setattr(ota_dry_run, "POLL_SECONDS", 0) + monkeypatch.setattr(ota_dry_run, "INSTALL_WATCH_SECONDS", 2) + monkeypatch.setattr(ota_dry_run, "WAIT_INSTALL_STUCK_SECONDS", 0.3) + + +def _ota_call(robot): + return next(params for method, params in robot.asked if method == "miIO.ota") + + +def test_an_install_asks_for_download_and_install() -> None: + robot = Robot(["idle", "downloading", "installing", "idle"]) + result = asyncio.run(OtaDryRun().run(robot, "https://srv:555", dict(PACKAGE_INFO), None, install=True)) + + sent = _ota_call(robot) + assert (sent["install"], sent["proc"], sent["file_md5"], sent["mode"]) == ("1", "dnld install", MD5, "normal") + assert sent["app_url"].endswith(f"/pearl-s_1526_fullos.{MD5}.signed.pkg") + assert result["install"] is True + + +def test_a_dry_run_still_only_downloads() -> None: + robot = Robot(["idle", "downloading", "wait_install"]) + result = asyncio.run(OtaDryRun().run(robot, "https://srv:555", dict(PACKAGE_INFO))) + + sent = _ota_call(robot) + assert (sent["install"], sent["proc"]) == ("0", "dnld") + assert result["install"] is False + + +def test_an_install_needs_a_well_charged_robot_but_a_dry_run_does_not() -> None: + result = asyncio.run(OtaDryRun().run(Robot(["idle"], battery=70), "https://srv:555", dict(PACKAGE_INFO), None, install=True)) + assert result["ran"] is False and "battery" in result["reason"] + + result = asyncio.run(OtaDryRun().run(Robot(["idle", "wait_install"], battery=70), "https://srv:555", dict(PACKAGE_INFO))) + assert result["ran"] is True + + +def test_the_watch_goes_through_wait_install_and_a_reboot() -> None: + robot = Robot(["idle", "downloading", "wait_install", "installing", "installing", None, None, "idle"]) + result = asyncio.run(OtaDryRun().run(robot, "https://srv:555", dict(PACKAGE_INFO), None, install=True)) + + states = [step["state"] for step in result["trace"]] + assert "installing" in states and None in states + assert states.index("installing") > states.index("wait_install") + assert result["saw_offline"] is True + assert result["final_state"] == "idle" + assert result["stuck_in_wait_install"] is False + + +def test_a_robot_that_stays_in_wait_install_is_reported_as_not_installing() -> None: + robot = Robot(["idle", "downloading", "wait_install"]) + result = asyncio.run(OtaDryRun().run(robot, "https://srv:555", dict(PACKAGE_INFO), None, install=True)) + + assert result["stuck_in_wait_install"] is True + assert result["final_state"] == "wait_install" + assert result["saw_offline"] is False + + +def test_a_robot_asleep_on_its_dock_counts_as_docked() -> None: + sleeping = Robot(["idle", "downloading", "installing", "idle"]) + sleeping.status_extra = {"state": 2, "charge_status": 1} + result = asyncio.run(OtaDryRun().run(sleeping, "https://srv:555", dict(PACKAGE_INFO), None, install=True)) + assert result["ran"] is True + + off_dock = Robot(["idle"]) + off_dock.status_extra = {"state": 2, "charge_status": 0} + result = asyncio.run(OtaDryRun().run(off_dock, "https://srv:555", dict(PACKAGE_INFO), None, install=True)) + assert result["ran"] is False and "docked" in result["reason"] diff --git a/tests/test_ota_package_dry_run.py b/tests/test_ota_package_dry_run.py new file mode 100644 index 0000000..15a8ab3 --- /dev/null +++ b/tests/test_ota_package_dry_run.py @@ -0,0 +1,206 @@ +import asyncio +import hashlib + +import pytest + +from roborock_local_server import ota_dry_run +from roborock_local_server.ota_dry_run import OtaDryRun, PackageRefused, resolve_package + +PACKAGE = b"not really a firmware, but it has bytes" * 100 +MD5 = hashlib.md5(PACKAGE).hexdigest() # noqa: S324 +URL = f"https://cdn.example.com/rriotpkg/a101/pearl-s_1526_fullos.{MD5}.signed.pkg" +DOCKED = [{"state": 8, "battery": 100, "in_cleaning": 0, "error_code": 0}] + + +class FakeCloud: + def __init__(self, current="02.15.26", url=URL): + self.current, self.url, self.asked = current, url, [] + + async def firmware_update_info(self, duid, *, lang="en"): + return {"currentVersion": self.current, "version": self.current, "updatable": False} + + async def iot_get(self, path, params=None): + self.asked.append((path, params)) + return {"url": self.url} + + +CDN_HEADERS = { + "Server": "Byte-nginx", "Content-Type": "application/octet-stream", "Content-Length": "999", "Content-Md5": MD5, + "Etag": f'"{MD5}"', "X-Xiaomi-Meta-Content-Length": str(len(PACKAGE)), "Last-Modified": "Sat, 26 Jul 2025 09:03:30 GMT", + "Connection": "keep-alive", "Date": "now", "Accept-Ranges": "bytes", +} + + +@pytest.fixture(autouse=True) +def _no_network(monkeypatch): + async def fake_download(url): + return PACKAGE, dict(CDN_HEADERS) + + monkeypatch.setattr(ota_dry_run, "_download", fake_download) + monkeypatch.setattr(ota_dry_run, "POLL_SECONDS", 0) + monkeypatch.setattr(ota_dry_run, "PACKAGE_WATCH_SECONDS", 2) + + +async def _body(response): + return b"".join([chunk async for chunk in response.body_iterator]) + + +def test_only_the_current_version_can_be_used() -> None: + cloud = FakeCloud(current="02.15.26") + for asked in ("02.99.99", "", "02.15.27"): + with pytest.raises(PackageRefused, match="current version"): + asyncio.run(resolve_package(cloud, "duid", asked, serve=True)) + assert cloud.asked == [] + + +def test_an_unexpected_package_address_is_refused() -> None: + for url in ("http://cdn.example.com/x.%s.signed.pkg" % MD5, "https://cdn.example.com/no-checksum.pkg", None): + with pytest.raises(PackageRefused, match="not in the expected form"): + asyncio.run(resolve_package(FakeCloud(url=url), "duid", "02.15.26", serve=True)) + + +def test_a_download_that_does_not_match_its_checksum_is_refused(monkeypatch) -> None: + async def corrupted(url): + return PACKAGE + b"!", dict(CDN_HEADERS) + + monkeypatch.setattr(ota_dry_run, "_download", corrupted) + with pytest.raises(PackageRefused, match="does not match"): + asyncio.run(resolve_package(FakeCloud(), "duid", "02.15.26", serve=True)) + + +def test_the_address_comes_from_the_cloud_route_with_the_version() -> None: + cloud = FakeCloud() + package = asyncio.run(resolve_package(cloud, "duid", "02.15.26", serve=True)) + + assert cloud.asked == [("/user/devices/duid/fw", {"version": "02.15.26"})] + assert (package["url"], package["md5"], package["data"]) == (URL, MD5, PACKAGE) + assert package["filename"] == f"pearl-s_1526_fullos.{MD5}.signed.pkg" + assert package["headers"] == { + "Server": "Byte-nginx", "Content-Type": "application/octet-stream", "Content-Md5": MD5, "Etag": f'"{MD5}"', + "X-Xiaomi-Meta-Content-Length": str(len(PACKAGE)), "Last-Modified": "Sat, 26 Jul 2025 09:03:30 GMT", + } + + +def test_direct_mode_does_not_download_anything(monkeypatch) -> None: + async def forbidden(url): + raise AssertionError("must not download") + + monkeypatch.setattr(ota_dry_run, "_download", forbidden) + package = asyncio.run(resolve_package(FakeCloud(), "duid", "02.15.26", serve=False)) + assert package == {"url": URL, "md5": MD5, "data": None} + + +class FakeRobot: + def __init__(self, dry_run, states): + self.dry_run, self.states, self.asked, self.fetched = dry_run, list(states), [], None + + async def send_command(self, method, params): + self.asked.append((method, params)) + if method == "get_status": + return DOCKED + if method == "get_ota_state": + return {"ota_state": self.states.pop(0) if len(self.states) > 1 else self.states[0]} + if method == "get_ota_progress": + return {"ota_progress": 0} + if method == "miIO.ota" and params["app_url"].startswith("https://srv"): + self.fetched = self.dry_run.file_response("/" + params["app_url"].split("/", 3)[3], "GET", {}, "robot") + return ["ok"] + + +def test_a_served_package_is_sent_download_only_from_this_server() -> None: + dry_run = OtaDryRun() + robot = FakeRobot(dry_run, ["idle", "downloading", "idle"]) + package = {"url": URL, "md5": MD5, "data": PACKAGE} + + result = asyncio.run(dry_run.run(robot, "https://srv:555", package)) + + sent = next(params for method, params in robot.asked if method == "miIO.ota") + assert (sent["install"], sent["proc"], sent["file_md5"]) == ("0", "dnld", MD5) + assert sent["app_url"].startswith("https://srv:555/ota_test/") + assert result["package"] is True and result["file_fetched"] is True + assert asyncio.run(_body(robot.fetched)) == PACKAGE + + +def test_a_direct_package_gives_the_robot_the_cdn_address_and_serves_nothing() -> None: + dry_run = OtaDryRun() + robot = FakeRobot(dry_run, ["idle"]) + + result = asyncio.run(dry_run.run(robot, "https://srv:555", {"url": URL, "md5": MD5, "data": None})) + + sent = next(params for method, params in robot.asked if method == "miIO.ota") + assert (sent["app_url"], sent["install"], sent["proc"]) == (URL, "0", "dnld") + assert result["file_fetched"] is False + + +def test_the_package_is_served_under_its_real_file_name_with_the_cdn_headers() -> None: + dry_run = OtaDryRun() + robot = FakeRobot(dry_run, ["idle", "downloading", "idle"]) + package = asyncio.run(resolve_package(FakeCloud(), "duid", "02.15.26", serve=True)) + + asyncio.run(dry_run.run(robot, "https://srv:555", package)) + + sent = next(params for method, params in robot.asked if method == "miIO.ota") + assert sent["app_url"].endswith(f"/pearl-s_1526_fullos.{MD5}.signed.pkg") + sent = {name.decode().lower(): value.decode() for name, value in robot.fetched.raw_headers} + assert sent["etag"] == f'"{MD5}"' and sent["content-md5"] == MD5 + assert sent["x-xiaomi-meta-content-length"] == str(len(PACKAGE)) + assert sent["content-length"] == str(len(PACKAGE)) # this server's own, not the CDN's + + +def test_only_the_real_file_name_is_served() -> None: + dry_run = OtaDryRun() + active = dry_run._active = ota_dry_run._Active("t" * 24, PACKAGE, MD5, 9e12, filename="right.signed.pkg") + assert dry_run.file_response("/ota_test/" + "t" * 24 + "/right.signed.pkg", "GET", {}, "x").status_code == 200 + assert dry_run.file_response("/ota_test/" + "t" * 24 + "/wrong.signed.pkg", "GET", {}, "x").status_code == 404 + assert len(active.hits) == 1 + + +def test_a_robot_holding_a_staged_package_can_start_another_attempt() -> None: + dry_run = OtaDryRun() + robot = FakeRobot(dry_run, ["wait_install", "downloading", "wait_install", "wait_install", "wait_install"]) + package = {"url": URL, "md5": MD5, "data": None} + + result = asyncio.run(dry_run.run(robot, "https://srv:555", package)) + + assert result["ran"] is True + assert result["final_state"] == "wait_install" + + +def _wire_names(response): + return [name.decode() for name, _ in response.raw_headers] + + +def test_the_title_case_variant_sends_header_names_as_written() -> None: + dry_run = OtaDryRun() + dry_run._active = ota_dry_run._Active( + "t" * 24, PACKAGE, MD5, 9e12, filename="f.signed.pkg", headers={"Etag": f'"{MD5}"'}, variant={"title_case": True}, + ) + response = dry_run.file_response("/ota_test/" + "t" * 24 + "/f.signed.pkg", "GET", {}, "x") + + assert _wire_names(response) == ["Content-Type", "Content-Length", "Accept-Ranges", "Etag"] + assert dict(response.raw_headers)[b"Content-Length"] == str(len(PACKAGE)).encode() + + +def test_names_are_capitalised_by_default_and_close_is_optional() -> None: + dry_run = OtaDryRun() + path = "/ota_test/" + "t" * 24 + "/f.signed.pkg" + dry_run._active = ota_dry_run._Active("t" * 24, PACKAGE, MD5, 9e12, filename="f.signed.pkg") + assert "Content-Length" in _wire_names(dry_run.file_response(path, "GET", {}, "x")) # capitalised by default + + dry_run._active = ota_dry_run._Active("t" * 24, PACKAGE, MD5, 9e12, filename="f.signed.pkg", variant={"title_case": False}) + assert all(name == name.lower() for name in _wire_names(dry_run.file_response(path, "GET", {}, "x"))) + + dry_run._active = ota_dry_run._Active("t" * 24, PACKAGE, MD5, 9e12, filename="f.signed.pkg", variant={"title_case": True, "connection_close": True}) + assert "Connection" in _wire_names(dry_run.file_response(path, "GET", {}, "x")) + dry_run._active = ota_dry_run._Active("t" * 24, PACKAGE, MD5, 9e12, filename="f.signed.pkg", variant={"connection_close": True}) + assert b"close" in dict(dry_run.file_response(path, "GET", {}, "x").raw_headers).values() + + +def test_the_variant_is_recorded_in_the_result() -> None: + dry_run = OtaDryRun() + robot = FakeRobot(dry_run, ["idle", "downloading", "idle"]) + package = {"url": URL, "md5": MD5, "data": PACKAGE, "filename": "x.signed.pkg", "headers": {}} + + result = asyncio.run(dry_run.run(robot, "https://srv:555", package, {"title_case": True})) + + assert result["variant"] == {"title_case": True} diff --git a/tests/test_ota_upgrade_button.py b/tests/test_ota_upgrade_button.py new file mode 100644 index 0000000..4e4f9c6 --- /dev/null +++ b/tests/test_ota_upgrade_button.py @@ -0,0 +1,194 @@ +import asyncio + +from fastapi.testclient import TestClient + +import roborock_local_server.ota_install as ota_install +from conftest import write_release_config +from roborock_local_server import ota_dry_run +from roborock_local_server.config import load_config, resolve_paths +from roborock_local_server.server import ReleaseSupervisor +from test_ota_install import Robot +from test_ota_package_dry_run import MD5, PACKAGE, FakeCloud, _no_network # noqa: F401 + + +class UpdatableCloud(FakeCloud): + async def firmware_update_info(self, duid, *, lang="en"): + return {"currentVersion": "02.15.26", "version": "02.16.00", "updatable": True} + + +def _supervisor(tmp_path, monkeypatch, enable): + config_file = write_release_config(tmp_path) + if enable: + config_file.write_text(config_file.read_text(encoding="utf-8") + "\n[ota]\nenable_install = true\n", encoding="utf-8") + config = load_config(config_file) + supervisor = ReleaseSupervisor(config=config, paths=resolve_paths(config_file, config)) + monkeypatch.setattr(supervisor, "_vacuums_payload", lambda: {"vacuums": [{"duid": "robot", "local_key": "k"}]}) + monkeypatch.setattr(supervisor, "cloud_manager", UpdatableCloud(current="02.16.00")) + return supervisor + + +def test_the_config_default_is_off(tmp_path) -> None: + config_file = write_release_config(tmp_path) + assert load_config(config_file).ota.enable_install is False + + +def test_the_update_button_is_refused_unless_enabled(tmp_path, monkeypatch) -> None: + supervisor = _supervisor(tmp_path, monkeypatch, enable=False) + result = asyncio.run(supervisor._firmware_ota_response("/ota/device/robot/upgrade", "POST", {})) + assert result[1]["code"] == 501 + + +def test_the_update_button_starts_an_install_of_the_offered_version(tmp_path, monkeypatch) -> None: + supervisor = _supervisor(tmp_path, monkeypatch, enable=True) + robot = Robot(["idle", "downloading", "installing", "idle"]) + + class FakeClient: + def __init__(self, *args): + pass + + async def connect(self): + pass + + async def send_command(self, method, params): + return await robot.send_command(method, params) + + async def close(self): + pass + + monkeypatch.setattr(ota_install, "_RoutineMqttClient", FakeClient) + + async def fake_to_file(url, target): + target.parent.mkdir(parents=True, exist_ok=True) + target.write_bytes(PACKAGE) + return MD5, {} + + monkeypatch.setattr(ota_dry_run, "_download_to_file", fake_to_file) + monkeypatch.setattr(ota_dry_run, "POLL_SECONDS", 0) + monkeypatch.setattr(ota_dry_run, "INSTALL_WATCH_SECONDS", 2) + + async def go(): + route, body = await supervisor._firmware_ota_response("/ota/device/robot/upgrade", "POST", {}) + assert body["success"] is True and body["data"]["version"] == "02.16.00" + again = await supervisor.ota_installer.start("robot") + assert again["started"] is False + await asyncio.gather(*supervisor.ota_installer._running.values()) + + asyncio.run(go()) + sent = next(params for method, params in robot.asked if method == "miIO.ota") + assert sent["install"] == "1" and sent["proc"] == "dnld install" + assert supervisor.ota_installer.results["robot"]["ran"] is True + + +def test_latest_stable_is_still_refused(tmp_path, monkeypatch) -> None: + supervisor = _supervisor(tmp_path, monkeypatch, enable=True) + result = asyncio.run(supervisor._firmware_ota_response("/ota/device/robot/upgrade/latest-stable", "POST", {})) + assert result[1]["code"] == 501 + + +def test_the_package_cache_keeps_one_file_and_is_cleared_after_a_good_install(tmp_path, monkeypatch) -> None: + cache = tmp_path / "ota_packages" + cache.mkdir() + (cache / "stale.pkg").write_bytes(b"old") + (cache / "half.pkg.part").write_bytes(b"x") + (cache / MD5_NAME).write_bytes(b"keep") + ota_dry_run.clean_package_cache(cache, keep=MD5_NAME) + assert [p.name for p in cache.iterdir()] == [MD5_NAME] + + +MD5_NAME = "keep.pkg" + + +def test_the_env_var_overrides_the_config_file(tmp_path, monkeypatch) -> None: + config_file = write_release_config(tmp_path) + monkeypatch.setenv("ROBOROCK_SERVER_OTA_ENABLE_INSTALL", "true") + assert load_config(config_file).ota.enable_install is True + monkeypatch.setenv("ROBOROCK_SERVER_OTA_ENABLE_INSTALL", "false") + assert load_config(config_file).ota.enable_install is False + + +def test_the_app_polls_the_local_status_during_an_install(tmp_path, monkeypatch) -> None: + supervisor = _supervisor(tmp_path, monkeypatch, enable=True) + installer = supervisor.ota_installer + assert installer.live_status("robot") is None + + async def ask(path, query=None): + return await supervisor._firmware_ota_response(path, "GET", query or {}) + + # Nothing running here: the question goes to the cloud (which the fake cloud answers as an error). + assert supervisor._local_ota_status("/ota/firmware/robot/upgrade/status", "") is None + + installer._set_live("robot", "START") + installer._robot_state("robot", "downloading", 42) + route, body = asyncio.run(ask("/ota/firmware/robot/upgrade/status")) + assert route == "ota_firmware_status_local" + assert body["result"]["status"] == "DOWNLOADING" and body["result"]["progress"] == "42" + + installer._robot_state("robot", "installing", 0) + installer._robot_state("robot", "idle", 0) # an idle robot mid-install must not look like success + assert installer.live_status("robot")["status"] == "INSTALLING" + + route, body = asyncio.run(ask("/ota/firmware/upgrade/status", {"duids": ["robot"]})) + assert body["result"] == [{"duid": "robot", "status": "INSTALLING", "progress": "100", "errCode": 0, "errMsg": ""}] + + installer._set_live("robot", "FAILED", err_msg="The robot did not finish", err_code=1) + assert installer.live_status("robot")["errMsg"] == "The robot did not finish" + + +def test_a_finished_install_reports_idle_and_a_failed_one_reports_the_reason(tmp_path, monkeypatch) -> None: + supervisor = _supervisor(tmp_path, monkeypatch, enable=True) + robot = Robot(["idle", "downloading", "installing", None, "idle"]) + + class FakeClient: + def __init__(self, *args): + pass + + async def connect(self): + pass + + async def send_command(self, method, params): + return await robot.send_command(method, params) + + async def close(self): + pass + + async def fake_to_file(url, target): + target.parent.mkdir(parents=True, exist_ok=True) + target.write_bytes(PACKAGE) + return MD5, {} + + monkeypatch.setattr(ota_install, "_RoutineMqttClient", FakeClient) + monkeypatch.setattr(ota_dry_run, "_download_to_file", fake_to_file) + monkeypatch.setattr(ota_dry_run, "POLL_SECONDS", 0) + monkeypatch.setattr(ota_dry_run, "INSTALL_WATCH_SECONDS", 2) + + async def go(): + await supervisor.ota_installer.start("robot") + assert supervisor.ota_installer.live_status("robot")["status"] in {"START", "DOWNLOADING", "INSTALLING"} + await asyncio.gather(*supervisor.ota_installer._running.values()) + + asyncio.run(go()) + assert supervisor.ota_installer.live_status("robot")["status"] == "IDLE" + records = list((supervisor.paths.runtime_dir / "ota_results").glob("*_robot.json")) + assert len(records) == 1 and "trace" in records[0].read_text(encoding="utf-8") + + +def test_the_progress_does_not_fall_back_to_zero_within_a_phase(tmp_path, monkeypatch) -> None: + installer = _supervisor(tmp_path, monkeypatch, enable=True).ota_installer + installer._robot_state("robot", "downloading", 40) + installer._robot_state("robot", "downloading", None) + installer._robot_state("robot", "downloading", 0) + assert installer.live_status("robot")["progress"] == "40" + installer._robot_state("robot", "downloading", 55) + assert installer.live_status("robot")["progress"] == "55" + installer._robot_state("robot", "installing", 0) # the robot's query answers 0 while installing + assert installer.live_status("robot")["progress"] == "100" + + +def test_the_install_logger_is_one_that_has_a_handler() -> None: + assert ota_install.logger.name == "real_stack.api" + + +def test_an_unknown_package_path_is_a_404_not_the_generic_ok(tmp_path, monkeypatch) -> None: + supervisor = _supervisor(tmp_path, monkeypatch, enable=False) + client = TestClient(supervisor.app) + assert client.get("/ota_test/abcdefghijklmnopqrstuvwxyz/pkg.signed.pkg").status_code == 404 diff --git a/tests/test_reported_firmware.py b/tests/test_reported_firmware.py new file mode 100644 index 0000000..24c2dda --- /dev/null +++ b/tests/test_reported_firmware.py @@ -0,0 +1,42 @@ +from roborock_local_server import firmware_versions as fw + + +class Store: + def __init__(self, versions): + self.versions = versions + + def get(self, duid, include_map=False): + version = self.versions.get(duid) + return {"firmware_version": version} if version else None + + +INFO = {"version": "02.35.52", "updatable": True, "currentVersion": "02.33.48", "forceUpdate": False} + + +def test_a_robot_on_the_offered_version_is_not_offered_it_again() -> None: + fixed = fw.reconcile(INFO, "robot", Store({"robot": "02.35.52"})) + assert fixed["updatable"] is False and fixed["currentVersion"] == "02.35.52" + assert INFO["updatable"] is True + + +def test_an_older_report_keeps_the_update_offered_but_shows_the_real_version() -> None: + fixed = fw.reconcile(INFO, "robot", Store({"robot": "02.33.48"})) + assert fixed["updatable"] is True and fixed["currentVersion"] == "02.33.48" + + +def test_numbers_are_compared_not_text() -> None: + assert fw.at_least("02.100.1", "02.35.52") is True + assert fw.at_least("02.9.0", "02.35.52") is False + + +def test_nothing_changes_when_the_robot_has_not_reported() -> None: + assert fw.reconcile(INFO, "robot", Store({})) == INFO + assert fw.reconcile(INFO, "robot", None) == INFO + + +def test_both_answer_shapes_are_corrected() -> None: + store = Store({"a": "02.35.52"}) + rows = [{"duid": "a", "firmwareUpdateResponse": dict(INFO)}, {"duid": "b", "firmwareUpdateResponse": dict(INFO)}] + fixed = fw.reconcile_result(rows, "", store) + assert fixed[0]["firmwareUpdateResponse"]["updatable"] is False and fixed[1]["firmwareUpdateResponse"]["updatable"] is True + assert fw.reconcile_result(dict(INFO), "a", store)["updatable"] is False From 90be75c700bb114241ffeaadd4073c85545255f4 Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:15:18 -0500 Subject: [PATCH 14/19] Show the firmware version a robot reports itself The cloud only learns a robot's version from the robot's own connection to it, so after a local update it keeps offering the update and showing the old version. The robot reports its version (protocol 203) each time it connects; the server now keeps it and uses it for the update check and for the device list. Co-Authored-By: Claude Sonnet 5.5 Co-Authored-By: Claude Opus 5.5 --- .../routes/user/devices/service.py | 38 +++++++++++++++++-- .../mqtt_tls_proxy_server/server.py | 2 + .../shared/device_snapshot_store.py | 11 ++++++ tests/test_device_snapshot_store.py | 7 ++++ 4 files changed, 54 insertions(+), 4 deletions(-) diff --git a/src/roborock_local_server/bundled_backend/https_server/routes/user/devices/service.py b/src/roborock_local_server/bundled_backend/https_server/routes/user/devices/service.py index aaa8051..7ee8a77 100644 --- a/src/roborock_local_server/bundled_backend/https_server/routes/user/devices/service.py +++ b/src/roborock_local_server/bundled_backend/https_server/routes/user/devices/service.py @@ -360,6 +360,35 @@ def _runtime_device_for_record( return {} +def _apply_reported_firmware(ctx: ServerContext, home_data: dict[str, Any]) -> dict[str, Any]: + """Shows the firmware version a robot reported itself (it can differ from the cloud's record after an update).""" + store = getattr(ctx, "snapshot_store", None) + if store is None: + return home_data + enriched = dict(home_data) + for key in ("devices", "receivedDevices", "received_devices"): + devices = home_data.get(key) + if not isinstance(devices, list): + continue + updated = [] + for device in devices: + if isinstance(device, dict): + reported = _reported_firmware(store, str(device.get("duid") or "")) + device = {**device, "fv": reported} if reported else device + updated.append(device) + enriched[key] = updated + return enriched + + +def _reported_firmware(store: Any, duid: str) -> str: + try: + entry = store.get(duid) if duid else None + except Exception: # noqa: BLE001 + return "" + value = (entry or {}).get("firmware_version") + return value if isinstance(value, str) else "" + + def _apply_runtime_online_status(ctx: ServerContext, home_data: dict[str, Any]) -> dict[str, Any]: runtime_device_map, any_runtime_connected = _runtime_device_identity_map(ctx) if not any_runtime_connected: @@ -389,7 +418,7 @@ def _apply_runtime_online_status(ctx: ServerContext, home_data: dict[str, Any]) def enrich_home_data_with_cloud_snapshot(ctx: ServerContext, home_data: dict[str, Any]) -> dict[str, Any]: cloud_home_data = _load_cloud_home_data(ctx) or {} if not cloud_home_data: - return _apply_device_overrides(ctx, home_data) + return _apply_reported_firmware(ctx, _apply_device_overrides(ctx, home_data)) enriched_home = dict(home_data) @@ -464,7 +493,7 @@ def enrich_home_data_with_cloud_snapshot(ctx: ServerContext, home_data: dict[str if enriched_devices: enriched_home[collection_key] = enriched_devices - return _apply_device_overrides(ctx, enriched_home) + return _apply_reported_firmware(ctx, _apply_device_overrides(ctx, enriched_home)) def _home_data(ctx: ServerContext) -> dict[str, Any]: @@ -502,7 +531,7 @@ def _home_data(ctx: ServerContext) -> dict[str, Any]: home["id"] = resolve_home_id(home, cloud_home_data, default=0) home["name"] = str(get_value(home, "name", "home_name", default="Local Home")) - return _apply_runtime_online_status(ctx, _apply_device_overrides(ctx, home)) + return _apply_reported_firmware(ctx, _apply_runtime_online_status(ctx, _apply_device_overrides(ctx, home))) def device_detail_payload(ctx: ServerContext, device_id: str) -> dict[str, Any]: @@ -610,7 +639,8 @@ def device_detail_payload(ctx: ServerContext, device_id: str) -> dict[str, Any]: ) ), "productId": product_id, - "fv": str(get_value(raw_device, "fv", default=get_value(normalized_device, "fv", default=""))), + "fv": _reported_firmware(getattr(ctx, "snapshot_store", None), device_id) + or str(get_value(raw_device, "fv", default=get_value(normalized_device, "fv", default=""))), "pv": str(get_value(raw_device, "pv", default=get_value(normalized_device, "pv", default=""))), "activeTime": as_int( get_value( diff --git a/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py b/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py index c900cad..40865cb 100644 --- a/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py +++ b/src/roborock_local_server/bundled_backend/mqtt_tls_proxy_server/server.py @@ -563,6 +563,8 @@ def _observe_snapshot( self.snapshot_store.mark_seen(duid) if proto_value == 301: self.snapshot_store.record_map(duid, payload_bytes) + elif proto_value == 203: + self.snapshot_store.record_firmware_version(duid, payload_utf8) elif proto_value == 102: response_to = decoded_entry.get("response_to") if isinstance(response_to, dict): diff --git a/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py b/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py index 2e37c30..a82ec55 100644 --- a/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py +++ b/src/roborock_local_server/bundled_backend/shared/device_snapshot_store.py @@ -254,6 +254,17 @@ def record_dps(self, duid: str, payload_utf8: str | None) -> None: if update and _SAFE_DUID.match(duid or ""): self._update_status(duid, update) + def record_firmware_version(self, duid: str, payload_utf8: str | None) -> None: + """The robot's firmware report (protocol 203), sent each time it connects: ``{"mqttOtaData": {"mqttOtaFirmwareVersion": {"version": ...}}}``.""" + try: + version = json.loads(payload_utf8 or "")["mqttOtaData"]["mqttOtaFirmwareVersion"]["version"] + except (ValueError, KeyError, TypeError): + return + if isinstance(version, str) and version and _SAFE_DUID.match(duid or ""): + with self._lock: + self._entry(duid)["firmware_version"] = version + self._touch(duid, force_flush=True) + def record_status_result(self, duid: str, result: Any) -> None: """The answer to ``get_status``.""" update = _status_update(result) diff --git a/tests/test_device_snapshot_store.py b/tests/test_device_snapshot_store.py index 3e8f486..217d391 100644 --- a/tests/test_device_snapshot_store.py +++ b/tests/test_device_snapshot_store.py @@ -242,3 +242,10 @@ def test_room_mapping_ignores_empty_and_malformed_answers(tmp_path: Path) -> Non store.record_room_mapping(DUID, [["x", "1"], [3], [4, None]]) assert store.get(DUID) is None + + +def test_the_firmware_report_is_remembered(tmp_path: Path) -> None: + store = DeviceSnapshotStore(tmp_path) + store.record_firmware_version("robot1", '{"mqttOtaData":{"mqttOtaFirmwareVersion":{"version":"02.35.52"}}}') + store.record_firmware_version("robot1", "not json") + assert store.get("robot1")["firmware_version"] == "02.35.52" From 39b05dc084b47375406d85ae7db1511784ad2104 Mon Sep 17 00:00:00 2001 From: Colin Haven <10933733+virtitnerd@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:15:18 -0500 Subject: [PATCH 15/19] Document firmware updates and the [ota] setting Co-Authored-By: Claude Sonnet 5.5 Co-Authored-By: Claude Opus 5.5 --- config.example.toml | 5 ++ docs/firmware_updates.md | 113 ++++++++++++++++++++++++++++++++++++++ docs/known_limitations.md | 2 +- mkdocs.yml | 1 + 4 files changed, 120 insertions(+), 1 deletion(-) create mode 100644 docs/firmware_updates.md diff --git a/config.example.toml b/config.example.toml index 0230287..ad14878 100644 --- a/config.example.toml +++ b/config.example.toml @@ -74,3 +74,8 @@ username = "" password = "" realm = "api-roborock.example.com" ttl = 86400 + +# Lets the official app's Update button install firmware (docked, 80%+ battery, idle robots only). +# The package comes from Roborock's CDN, is checked against its checksum, and is served to the robot from here. +[ota] +enable_install = false diff --git a/docs/firmware_updates.md b/docs/firmware_updates.md new file mode 100644 index 0000000..91a9abf --- /dev/null +++ b/docs/firmware_updates.md @@ -0,0 +1,113 @@ +# Firmware updates + +A robot that is paired to this server never talks to Roborock's cloud, so it never learns about a new firmware +and the official app cannot install one on its own. The server closes that gap in two steps. It reads the update +information from Roborock with the login stored at sign-in, and, when you opt in, it installs the update itself +through the app's own Update button. + +!!! note + Everything here needs the cloud login the server stored when you signed in (one email-code sign-in). Without it + the update check is unavailable and the Update button is refused. + +## Checking for an update + +The official app asks the server `GET /ota/firmware//updatev2` (or `/ota/firmware/updatev2?duids=...`). The +server asks Roborock's cloud and returns its answer, so the app shows the real version and release notes. Both calls +need the app's signature, like the rest of the protocol, and are never refused as replayed. + +`GET /admin/api/cloud/firmware` lists the update status of every robot on the account in one call, for scripts. + +### The version a robot reports + +Roborock's cloud learns a robot's version from the robot's own connection to it. A robot paired here never makes +one, so after a local update the cloud would keep saying the old version and offering the same update. The robot +reports its firmware version itself (protocol 203) each time it connects. The server keeps that version and uses it +in place of the cloud's: + +- `currentVersion` in the update check is the version the robot reports. +- `updatable` is `false` when that version is the offered one or newer. Versions are compared as numbers. +- The `fv` field the apps read from the device list and device detail is the reported version. + +A robot that has not reported yet is left as the cloud describes it. + +## Installing an update + +Installing is off by default. Switch it on with either: + +```toml +[ota] +enable_install = true +``` + +or the environment variable `ROBOROCK_SERVER_OTA_ENABLE_INSTALL=true`. The variable wins when it is set, so it also +works for a `config.toml` that already exists. + +With it on, pressing Update in the official app (`POST /ota/device//upgrade`) does the following: + +1. The server asks the cloud for the offered version and refuses if there is none. +2. It asks the cloud for the package address (`/user/devices//fw?version=`). The file name carries the + package's MD5. The server downloads the package to `runtime/ota_packages/` and checks it against that MD5. +3. It checks the robot: docked (charging, fully charged, or asleep on the charger), idle, not cleaning, no error, at + least 80% battery, and no other install running. Otherwise it answers with the reason and changes nothing. +4. It serves the package to the robot from a one-time URL on this server and sends the robot's own OTA command + (`miIO.ota`, `proc: "dnld install"`). +5. It follows the robot through download, install and reboot, and returns once the robot is idle again. + +The `latest-stable` upgrade call is still refused, and only the version the cloud offers can be installed. The +package cache is cleared after a successful install and holds a single file otherwise. + +### What the robot needs + +The robot's downloader only accepts HTTP responses whose header names are capitalised (`Content-Length`), as its +CDN sends them. The server serves packages that way, with range requests and from disk. Anything else a robot +downloads from this server has to be served the same way. + +### What the app sees + +The cloud knows nothing about an install that runs here, and it answers the app's status poll +(`GET /ota/firmware//upgrade/status`, or `/ota/firmware/upgrade/status?duids=...`) with an error. The official +app treats an error from that poll as a failed update, and polls it whenever the robot's own status messages go +quiet for 90 seconds, which the reboot does. While an install runs, the server therefore answers that poll itself +with the robot's real state: `DOWNLOADING`, `INSTALLING` or `WAIT_INSTALL` with the progress, `IDLE` only once the +robot has rebooted and is idle again (the app reads `IDLE` as success), and `FAILED` with the reason when the install +did not finish. The answer is kept for 30 minutes. + +During the install the robot's own status messages reach the app as usual: `P201` carries the status +(`DOWNLOADING`, `INSTALLING`, `IDLE`), `P200` the download progress from 0 to 100, and `P203` the new version when +the robot reconnects. + +### The install record + +Each install writes `runtime/ota_results/