Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/known_limitations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
20 changes: 20 additions & 0 deletions docs/roborock_app.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,26 @@ 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.

## 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)

[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.
Expand Down
4 changes: 4 additions & 0 deletions src/roborock_local_server/backend.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,9 @@ def _resolve_backend_path() -> Path:
_build_inventory,
_fetch_additional_web_cache,
_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,
Expand Down Expand Up @@ -52,7 +54,9 @@ def _resolve_backend_path() -> Path:
"_extract_inventory_vacuums",
"_fetch_additional_web_cache",
"_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",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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):
Expand All @@ -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,
Expand Down
Original file line number Diff line number Diff line change
@@ -1,23 +1,44 @@
from __future__ import annotations

import json
from typing import Any

from shared.context import ServerContext

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))

Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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))
Expand Down Expand Up @@ -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


Expand Down
13 changes: 13 additions & 0 deletions src/roborock_local_server/bundled_backend/shared/data_helpers.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down
Loading
Loading