Skip to content

Show firmware updates in the official app and install them from its Update button (install is opt-in) - #255

Open
virtitnerd wants to merge 20 commits into
Python-roborock:mainfrom
virtitnerd:pr/firmware-install
Open

virtitnerd wants to merge 20 commits into
Python-roborock:mainfrom
virtitnerd:pr/firmware-install

Conversation

@virtitnerd

@virtitnerd virtitnerd commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Replaces #254. This PR now carries both the update check (from #254) and the install.

Depends on: #251 (last-known state) and #253 (plugin catalog refresh, which itself sits on #224). The branch is
built on those, so until they land the diff also shows their commits. The commits that are new here are:

  • Read a robot's firmware update from the cloud with the stored login
  • Answer the app's firmware calls from the cloud, and require its signature
  • List firmware status for every robot on the account
  • Install firmware from the official app's Update button
  • Show the firmware version a robot reports itself
  • Document firmware updates and the [ota] setting

Why

A robot paired to the local server never talks to Roborock's cloud, so it never learns about new firmware and the
official app cannot install it. The server also answered the app's firmware calls with a generic success, so the app
could never even see that an update existed. Keeping a robot out of the cloud should not mean never updating it.
People in #158, #150 and #36 describe updating before moving to the local server for this reason.

What

Update check

The routes the app really uses are GET /ota/firmware/<duid>/updatev2, GET /ota/firmware/updatev2?duids=... and
GET /ota/firmware/upgrade/status?duids=.... The server reads the update information from Roborock's cloud with the
login it stored at sign-in and returns it, so the app shows the real version and release notes. These routes require
the app's signature, and a read is never refused as a replayed signature (the app repeats them).
GET /admin/api/cloud/firmware lists every robot's status on the account for scripts. Without the stored cloud login
the check is reported as unavailable.

Install (off by default)

Turn it on with [ota] enable_install = true or ROBOROCK_SERVER_OTA_ENABLE_INSTALL=true (the variable wins). With
it off, the upgrade call is refused with an error instead of pretending to start.

With it on, the Update button (POST /ota/device/<duid>/upgrade):

  1. asks the cloud for the offered version and the package address (/user/devices/<duid>/fw?version=...; the file
    name carries the MD5);
  2. downloads the package to the data volume, checks the MD5, and serves it to the robot from a one-time URL;
  3. refuses unless the robot is docked (or asleep on its charger), idle, not cleaning, error free and at 80% battery
    or more, with no other install running;
  4. sends the robot's own OTA command (miIO.ota, download and install) and follows it through the reboot.

Two things that were not obvious and are handled:

  • The robot's downloader only accepts capitalised header names (Content-Length). Starlette lowercases them, so
    packages are served with the names kept as written.
  • The cloud answers the app's status poll with an error when it knows of no update. The official app reads an error
    from that poll as a failed update, and polls it whenever the robot is silent for 90 seconds, which the reboot
    causes. While an install runs the server answers that poll itself from the robot's real state (and IDLE, which
    the app reads as success, only after the robot is back).

Reported version

The robot reports its version (protocol 203) on every connect. The server keeps it in the last-known state store and
uses it for the update check and the device list, because the cloud never learns the new version and would keep
offering the same update.

Security

Installs are opt-in. Only the version the cloud offers can be installed, and the package is checked against the MD5
in the address the cloud returns. The robot verifies the firmware's signature itself. The latest-stable call stays
refused.

Testing

  • tests/test_ota_firmware.py covers both URL styles, the signature requirement and the replay case with a fake
    cloud, plus unit tests for each part of the install. Full suite on this branch: 550 passed.
  • The iOS app shows the real version for a Qrevo Pro and a Qrevo Curv 2 Flow.
  • On hardware, a Qrevo Curv 2 Flow went from 02.33.48 to 02.35.52 through the iOS app's Update button: 283 MB
    downloaded in 1m24s, installed in 2m15s, offline for 52s, and the robot reported 02.35.52 when it reconnected. The
    app showed success. An earlier install of a Qrevo Pro's current package confirmed the delivery path.

Not included

The development tools used to find this (an admin dry run of the robot's OTA command and a cloud path explorer) are
not part of this PR. They are described in docs/firmware_updates.md.

Related

#158, #150, #36 (context). There is no open issue for firmware updates; happy to open one if you prefer.

@Hoeze

Hoeze commented Nov 14, 2026

Copy link
Copy Markdown

Hey @virtitnerd, is there a way to downgrade the robot firmware if needed?

virtitnerd added a commit to virtitnerd/local_roborock_server that referenced this pull request Nov 14, 2026
ROBOROCK_SERVER_OTA_ENABLE_INSTALL already updates the key in an existing
config.toml; a freshly generated file now carries the [ota] section too,
off unless the variable turns it on. The installation guide lists the
variable with the other commonly set ones. The section is read by the
firmware install change (Python-roborock#255); without that change the key is ignored.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@virtitnerd virtitnerd changed the title Install firmware from the official app's Update button (opt-in) Show firmware updates in the official app and install them from its Update button (install is opt-in) Nov 15, 2026
@virtitnerd
virtitnerd marked this pull request as ready for review November 15, 2026 15:22
@Lash-L Lash-L added blocked Waiting on an explicit dependency or maintainer hold; record the blocker. feature PR adding capability; under this two-type scheme also covers additive documentation. labels Nov 15, 2026
virtitnerd and others added 16 commits November 15, 2026 16:15
The last status, battery and error a robot sent, its last position and the map it was on,
and when it last spoke or went offline, written under device_snapshots/ so it survives a
restart. A robot that dies or loses Wi-Fi stops answering; this is what is left to say
where it was.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Robot-originated frames update the store: status pushes (dps 120/121/122), get_status
answers, and the map reply, which is decrypted with the nonce of whichever client's
request asked for it. A closing robot connection marks the device offline at once.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Returns status, position, last_seen_at and offline_at; ?map=1 adds the last map the robot
sent so a client can draw it while the robot cannot be asked.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A robot that went quiet before the store existed still has its last status, battery and map
in the decoded MQTT log. On startup, in a background thread, devices the store has no snapshot
for are filled in from that log: last time heard, last status, and the last map decoded with
the nonce of the request that asked for it. Devices that already have a snapshot are left alone.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…h it

The snapshot had the last map but not which segment is which room, so an
offline map could only show generic labels. The proxy now records each
get_room_mapping answer, the startup seed reads it from the MQTT log, and
/last_known adds each room's name from the home data.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 Python-roborock#221
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 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ture

The app checks with GET /ota/firmware/updatev2?duids=...&lang=..., reads progress from
/ota/firmware/upgrade/status?duids=..., and installs with POST /ota/device/<duid>/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/<duid>/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 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…o rebased/firmware-install

The installer reads the robot's state from the last-known snapshot store.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With [ota] enable_install = true (or ROBOROCK_SERVER_OTA_ENABLE_INSTALL=true), the
Update button's POST /ota/device/<duid>/upgrade downloads the package the cloud
offers, checks it against the MD5 in its address, serves it to the robot from
this server and sends the robot's own OTA command. The robot has to be docked,
idle and at 80% battery or more. While it runs, the app's status polls are
answered from the robot's real state, since the cloud would answer them with an
error that the app reads as a failed update.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The cloud only learns a robot's version from the robot's own connection to it, so
after a local update it keeps offering the update and showing the old version.
The robot reports its version (protocol 203) each time it connects; the server now
keeps it and uses it for the update check and for the device list.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@virtitnerd

Copy link
Copy Markdown
Contributor Author

Good question, so I tested it. The robot does accept an older firmware as long as it is a real signed Roborock package.

On a Qrevo Curv 2 Flow (a245) I installed 02.33.48 over 02.35.52 through the server. The cloud still hands out the package for an older release if you ask for that exact version (user/devices/<duid>/fw?version=02.33.48 returns its URL; a version that was never released returns null). The robot downloaded it from the server, installed it, rebooted and came back on 02.33.48 in about 4 minutes. Maps, rooms and settings were all unchanged, and the official app now shows 02.33.48 with the update offered again.

The catch is that there is no cloud route that lists old versions, so you have to already know the version number. I'm adding to this PR a record the server keeps of every firmware it sees per model (version, package URL and md5, never pruned), so a user can pick an earlier version to reinstall later. Downgrading will be opt-in and off by default.

So far this was tested on one robot model only.

virtitnerd and others added 3 commits November 15, 2026 16:41
The cloud's currentVersion is stale after any local install (it still said
02.33.48 while the robot ran 02.35.52), so the package gate and the Update
button now use the robot's own P203 report and fall back to the cloud only
when the robot has not reported. Adds the [ota] allow_downgrade and
keep_previous_package keys, both off, used by the next commits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The cloud has no route that lists versions, only fw?version=<v> for a version
asked for by name, so the server keeps its own catalog in
runtime/firmware_catalog.json, keyed by model and never pruned. Entries come
from the version a robot reports before an install, the package installed,
and the versions the cloud offers in the update checks the server already
answers. Each records the package URL, its md5, size when known, first-seen
time and where it was learned. The robot's version before its last install
is kept per robot. GET /admin/api/firmware/catalog lists it, and
[ota] keep_previous_package keeps the package files around an install.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
OtaInstaller.start_version installs any catalog version of the robot's model
other than the one it reports, by default the one it ran before its last
install, through the same path as the Update button: same docked, idle,
error-free and 80% battery checks and the same live status for the app. It
uses the remembered package address and md5, and when that address has gone
stale it takes a fresh one only if the checksum matches. It needs
[ota] enable_install and the new [ota] allow_downgrade, both off by default.

LocalRock calls POST /ota/device/<duid>/upgrade/version?version=<v>, and the
path-style update check now adds downgradeAllowed, availableVersions and
previousVersion. The admin gets GET /admin/api/firmware/<duid>/versions and
POST /admin/api/firmware/<duid>/install-version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

blocked Waiting on an explicit dependency or maintainer hold; record the blocker. feature PR adding capability; under this two-type scheme also covers additive documentation.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants