From 7272d2ff2ef130abe9d7fbd8bcda3cc1b4fb8d52 Mon Sep 17 00:00:00 2001 From: Alex Babel Date: Fri, 30 Oct 2026 21:17:17 +0100 Subject: [PATCH 1/6] 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 b79dfd0..84259a2 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 53b46b86021b916b833f9224e6823fcd239c16d6 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 2/6] 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 a5f4c29f154e447629883d92580f9aafc2151fb7 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 3/6] 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 05b9873c631a0e496f4e7ec34374ab569d2eb1e7 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 4/6] 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 0d82e5dbda28fe203e462854a24c940038881372 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 5/6] 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 d81d24b..f5fad0f 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 — supported with a TURN relay and a short camera bootstrap hostname; see [camera.md](camera.md). Verified on the Saros 10R and Qrevo MaxV; other camera models may bootstrap differently and need validation. -- 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 do not work outside of China. Their firmware checks the region they are used in (via `rrcheck`), and after local onboarding they reject ordinary commands such as `get_status` with `-10002 / rrcheck access denied`. See [#81](https://github.com/Python-roborock/local_roborock_server/issues/81). - Some users have gotten China-market vacuums working outside China on the official cloud by routing the robot's traffic through a VPN that exits in China (the robot's WAN IP is what matters, not the phone's). See [this comment](https://github.com/iobroker-community-adapters/ioBroker.mihome-vacuum/issues/842#issuecomment-1736230673). This has not been tested with this local server yet, so it may or may not help. 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 c876583..ee27533 100644 --- a/src/roborock_local_server/bundled_backend/shared/protocol_auth.py +++ b/src/roborock_local_server/bundled_backend/shared/protocol_auth.py @@ -553,7 +553,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 @@ -604,6 +607,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 105a2aa..9d5e12f 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("/") @@ -789,6 +838,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 @@ -1233,6 +1285,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" @@ -1351,14 +1404,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 599781f1ca2a83119b8a2ddb949729bf199ccae5 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 6/6] 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"]