Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
b397491
Keep each robot's last-known state in a persistent store
virtitnerd Oct 22, 2026
44275cf
Feed the snapshot store from the MQTT proxy
virtitnerd Oct 22, 2026
bbbc516
Serve a robot's last-known state at /user/devices/{duid}/last_known
virtitnerd Oct 22, 2026
4902b81
Seed the snapshot store from the MQTT log on startup
virtitnerd Oct 23, 2026
dae1472
Keep each robot's room table in its snapshot and serve room names wit…
virtitnerd Oct 27, 2026
578bd2b
Document the last-known robot state
virtitnerd Nov 13, 2026
a4f2719
fix(plugin): resolve string product ids and serve the iOS app plugin
AlexanderBabel Oct 30, 2026
44ed228
Refresh the plugin catalogs from the cloud with the stored login
virtitnerd Nov 12, 2026
402702a
Add admin endpoints to refresh and list the plugin catalogs
virtitnerd Nov 12, 2026
47243da
Read a robot's firmware update from the cloud with the stored login
virtitnerd Nov 12, 2026
8883047
Answer the app's firmware calls from the cloud, and require its signa…
virtitnerd Nov 12, 2026
35c50c3
List firmware status for every robot on the account
virtitnerd Nov 12, 2026
b015aa3
Merge branch 'rebased/last-known-state' (without its last commit) int…
virtitnerd Nov 15, 2026
ade7386
Install firmware from the official app's Update button
virtitnerd Nov 13, 2026
90be75c
Show the firmware version a robot reports itself
virtitnerd Nov 13, 2026
39b05dc
Document firmware updates and the [ota] setting
virtitnerd Nov 13, 2026
6bb0481
Gate firmware packages on the version the robot reports
virtitnerd Nov 15, 2026
ba13a1e
Keep a catalog of every firmware package the server learns of
virtitnerd Nov 15, 2026
606e90a
Install an older or other catalog version when opted in
virtitnerd Nov 15, 2026
a06f6d7
Document the firmware catalog and installing another version
virtitnerd Nov 15, 2026
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
10 changes: 10 additions & 0 deletions config.example.toml
Original file line number Diff line number Diff line change
Expand Up @@ -74,3 +74,13 @@ 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
# Also lets LocalRock or the admin install another version from the firmware catalog, older ones included.
# Proven on one Qrevo Curv 2 Flow only; needs enable_install too.
allow_downgrade = false
# Keeps the package files from before and after an install (about 300 MB each) for a quick reinstall.
keep_previous_package = false
166 changes: 166 additions & 0 deletions docs/firmware_updates.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
# 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/<duid>/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.
- The install checks compare against the reported version too, so a package is only accepted for the version the
robot really runs or the version on offer.

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/<duid>/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/<duid>/fw?version=<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 the Update button only installs the version the cloud offers.
The package cache is cleared after a successful install and holds a single file otherwise, unless
`keep_previous_package` is on (see below).

## The firmware catalog

Roborock's cloud has no route that lists firmware versions. It only gives a package address for a version asked for
by name (`/user/devices/<duid>/fw?version=<version>`), and answers `{"url": null}` for versions that were never
released. The server therefore keeps its own catalog in `runtime/firmware_catalog.json`, keyed by robot model, and
never removes an entry. A version is added when the server learns of a real package:

- the version a robot reports just before an install (`robot_reported`),
- the package being installed (`install`),
- a version the cloud offers in an update check the server answers or the admin listing (`cloud_offer`).

Each entry has the model, version, package URL, MD5, size when known, the time it was first seen and the sources it
was learned from. An entry is never given a different MD5. The catalog also keeps, per robot, the version it ran
before its last install. `GET /admin/api/firmware/catalog` lists it, `?model=roborock.vacuum.a245` for one model.

## Installing another version

!!! warning
Installing an older version was proven on one robot only, a Qrevo Curv 2 Flow (a245), going from 02.35.52 back
to 02.33.48. It is untested on every other model.

This is off unless both are set:

```toml
[ota]
enable_install = true
allow_downgrade = true
```

With both on, any catalog version of the robot's model other than the one it reports can be installed, older ones
included. Without a version the one the robot ran before its last install is used. The install goes the same way as
an update: the same docked, idle, error-free and 80% battery checks, the same one-time URL and the same live status
for the app. The package is fetched from the address in the catalog and checked against its MD5; if that address no
longer works, a new one is asked for and accepted only with the same MD5.

- LocalRock: `POST /ota/device/<duid>/upgrade/version?version=<version>`. The path-style update check
(`GET /ota/firmware/<duid>/updatev2`) adds `downgradeAllowed`, `availableVersions` (each with `version`,
`current`, `installable`, `firstSeen`, `size`) and `previousVersion` when the robot ran another version before its
last install.
- Admin: `GET /admin/api/firmware/<duid>/versions` and `POST /admin/api/firmware/<duid>/install-version` with
`{"version": "02.33.48"}` (or no body for the previous version).

`keep_previous_package = true` keeps the package files from before and after each install in `runtime/ota_packages/`
(two files of about 300 MB), so going back needs no download. The catalog is kept either way.

The downgrade was done with a development debug endpoint that sends the same OTA command; the catalog route above
has not run against a robot yet. On the Curv 2 Flow the older package downloaded through the server in 36 seconds, the robot installed it, was offline
for about 30 seconds while it restarted and was idle again about 4 minutes after the start. Maps, rooms and settings
were unchanged, and the official app then showed 02.33.48 with the update to 02.35.52 on offer.

### 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/<duid>/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/<time>_<duid>.json` with the parameters sent to the robot (the one-time token
is hidden), the robot's state timeline, whether it went offline and came back, and the version it reports afterwards.
It is the place to look when an install did not behave.

### An example

A Qrevo Curv 2 Flow (a245) went from 02.33.48 to 02.35.52 this way. Download of the 283 MB package took 1 minute 24
seconds, the install 2 minutes 15 seconds, the robot was offline for 52 seconds while it restarted, and it reported
02.35.52 on reconnecting. The official app showed the update as successful about 4 minutes 36 seconds after the
button was pressed.

## How this was investigated

The behaviour above was found by asking a robot, step by step, what its OTA command accepts. Two tools were used and are
not part of the server:

- A dry run of the robot's local OTA command: an admin call that asks a docked, idle robot to download a file from
this server without installing it, first a random file and then a real package, and reports how the robot reacts.
It showed the header capitalisation requirement and the robot's state names.
- An explorer for candidate cloud OTA paths, read with the stored login, which located the package address route.

Both were admin-only debug endpoints on a development branch (`feat/ota-install-test` in the author's fork). They are
left out of the server because they let an admin drive a robot's firmware by hand. The robot's OTA commands are
`get_ota_state` (`idle`, `downloading`, `installing`, `wait_install`, `failed`), `get_ota_progress` (0 to 100, and 0
while installing) and `miIO.ota` with `{"mode": "normal", "install": "0" or "1", "app_url": ..., "file_md5": ...,
"proc": "dnld" or "dnld install"}`.

## Limits

- The cloud login stored at sign-in is required.
- The server does not update robots by itself. Nothing installs unless someone presses Update or asks for another version.
- Only robots paired to this server can be installed to; the robot has to be online and reachable over MQTT.
- Voice packages are downloaded by the robot the same way and need the same header handling. They are not covered here.
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 — 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), and the Update button can install it when `[ota] enable_install = true` (or `ROBOROCK_SERVER_OTA_ENABLE_INSTALL=true`). Off by default, the upgrade request is refused with an error. Installing an older version from the server's firmware catalog (`[ota] allow_downgrade = true`) was proven on one Qrevo Curv 2 Flow only and is untested on other models. See [Firmware updates](firmware_updates.md).
- 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.
29 changes: 29 additions & 0 deletions docs/last_known_state.md
Original file line number Diff line number Diff line change
@@ -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.
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
2 changes: 2 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,10 @@ nav:
- Integrations:
- Mobile App Options: roborock_app.md
- Camera (Live Video): camera.md
- Firmware Updates: firmware_updates.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
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 @@ -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
Expand Down Expand Up @@ -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),
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
Loading
Loading