Skip to content
Merged
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
16 changes: 5 additions & 11 deletions docs/home_assistant.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,19 +60,13 @@ After the dashboard opens, complete the same post-start steps as the Docker inst

If you need the MITM protocol sync secret for the Roborock app flow, sign in to the admin page and open **Protocol Auth**. The dashboard shows the active `admin.session_secret`, so you do not need to inspect `/data/config.toml` manually.

### Opt-in Beta testing
### Beta add-on

The repository also provides **Roborock Local Server Beta** for prerelease
testing. Install it explicitly from the add-on store after its prerelease image
has been published. Stable installations remain on their stable image version.
**Roborock Local Server Beta** is currently unused and remains on `1.1.0-rc2`.
Install **Roborock Local Server** for the stable `1.1.0` release.

Beta has a separate add-on slug and persistent data, so the first installation
requires its own configuration and cloud import. If reusing the same hostname
and ports, stop the stable add-on and disable its start-on-boot setting while
testing. Later Beta versions use the normal Home Assistant update flow.

See the [Beta setup and testing instructions](https://github.com/Python-roborock/local_roborock_server/blob/main/roborock_local_server_beta_addon/DOCS.md)
for installation, V2 checkpoints, and returning to stable.
Beta and stable keep separate data. See [switching from Beta to stable](updating.md#switching-from-beta-to-stable)
if you tested an RC using the Beta add-on.

### Add-on Behavior

Expand Down
2 changes: 1 addition & 1 deletion docs/onboarding.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ Japan (No DST): `JST-9`

- The first successful attempt usually increases the query sample count.
- If the sample count increases but the public key is still missing, run another cycle.
- Public-key recovery can take several minutes. On some newer models, the query sample count stays at zero during recovery; watch for **Public Key determined** instead.
- Once the public key is ready, the script will tell you to do one final pairing cycle so the vacuum connects fully.
- Some vacuums are slow on that final cycle and may take a few minutes before they say Wi-Fi connected or show up as connected in the server.
- Some vacuums need 2-4 cycles total.
Expand Down Expand Up @@ -144,7 +145,6 @@ Everything in "What To Expect" above still applies. Some vacuums need 2-4 cycles

## Related Docs

- [Experimental V2 public-key recovery](v2_onboarding.md)
- [Installation](installation.md)
- [Tested vacuums](tested_vacuums.md)
- [Home Assistant](home_assistant.md)
Expand Down
13 changes: 6 additions & 7 deletions docs/tested_vacuums.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,16 +17,13 @@ The following vacuums are not supported and may never be supported.
- Roborock Q7 L5
- Roborock Q10 s5/ s5+

These vacuums likely all use a newer firmware version that uses a v2 of the region endpoint. In order to support them, we need to get a firmware dump. If you would like to disassemble your vac, we can likely get this. Please reach out.
## Potentially Supported
These models have not yet been confirmed working. Version `1.1.0` adds V2
onboarding support; please report your model, firmware, and certificate chain
if you try one.

- Roborock Saros 20 Sonic
- Roborock Qrevo Curv 2 Pro
- Saros 20

## Potentially Supported
These are (maybe) using the same firmware as the two above. Any vacuum released after Sep 2025 is likely not supported in its current form. Please give it a try and let me know so I can update the docs.

- Roborock Qrevo Edge 2
- Roborock Qrevo S Pro
- Qrevo Curv 2 Flow
- Qrevo CurvX
Expand All @@ -51,6 +48,8 @@ Legend:
| Roborock S8 MaxV Ultra | Not reported | ✅ | ❓ | ❓ | ❓ |
| Roborock S8 Pro Ultra (a70) | Not reported | ❓ | ❓ | ❓ | ❓ |
| Roborock Saros 10R | `02.52.32` | ✅ | ❓ | ✅ | ❓ |
| [Roborock Saros 20 Sonic (a279)](https://github.com/Python-roborock/local_roborock_server/pull/84#issuecomment-5701936113) | `02.42.52` | ✅ | ❓ | ❓ | ❓ |
| [QRevo Edge 2 Set (a298)](https://github.com/Python-roborock/local_roborock_server/pull/84#issuecomment-5684924538) | `02.15.44` | ❓ | ❓ | ✅ | ❓ |
| Roborock G30U | `02.52.32` | ✅ | ❓ | ❓ | ❓ |
| Roborock Qrevo S5V | Not reported | ❓ | ❓ | ❓ | ❓ |
| QRevo MaxV | Not reported | ✅ | ❓ | ✅ | ❓ |
Expand Down
11 changes: 11 additions & 0 deletions docs/updating.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,17 @@ Update the add-on from the Home Assistant Add-on Store, then restart the add-on.

The add-on does not automatically rewrite Home Assistant's Roborock integration entry. If you changed the stack hostname or ports during the update, repeat the endpoint edit in [Home Assistant](home_assistant.md).

### Switching From Beta To Stable

The Beta add-on is currently unused. For `1.1.0`, use **Roborock Local Server**.
Back up Beta before switching, then stop it and disable **Start on boot** before
starting stable on the same ports.

The two add-ons have separate settings and data; installing stable does not copy
Beta's configuration, cloud import, or recovered keys. If stable was already
configured, update and start it. Otherwise, follow the [Home Assistant setup](home_assistant.md).
You may need to pair the vacuum again and reconfigure clients for stable.

## After Updating

Open the admin dashboard and check:
Expand Down
107 changes: 0 additions & 107 deletions docs/v2_onboarding.md

This file was deleted.

2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[project]
name = "roborock-local-server"
version = "1.1.0-rc2"
version = "1.1.0"
description = "private local Roborock server stack."
requires-python = ">=3.11,<3.14"
readme = "README.md"
Expand Down
8 changes: 8 additions & 0 deletions roborock_local_server_addon/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# Changelog

## 1.1.0

- Added V2 onboarding support, including automatic public-key recovery and multipart NC registration.
- Removed the obsolete V2 unsupported status from the dashboard and guided onboarding.
- Confirmed working on QRevo Edge 2 Set and Saros 20 Sonic. See the tested-vacuum list for firmware and certificate details.
- Fixed certificate renewal handling when acme.sh reports that renewal is not yet needed.
- Existing settings and recovered keys are retained when updating. The Beta add-on is currently unused; use the stable add-on for this release.

## 1.0.2

- Added external TLS support and basic reverse proxy support.
Expand Down
2 changes: 1 addition & 1 deletion roborock_local_server_addon/config.yaml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name: Roborock Local Server
version: "1.0.2"
version: "1.1.0"
slug: roborock_local_server
description: Private Roborock HTTPS and MQTT stack for Home Assistant environments.
url: "https://github.com/Python-roborock/local_roborock_server"
Expand Down
2 changes: 2 additions & 0 deletions roborock_local_server_beta_addon/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Changelog

Beta is currently unused. Use **Roborock Local Server** for the stable `1.1.0` release.

## 1.1.0-rc2

- Parse multipart NC form fields so the server can identify the vacuum, preserve its provisioning values, encrypt the reply with its recovered public key, and record the NC onboarding step.
Expand Down
76 changes: 6 additions & 70 deletions roborock_local_server_beta_addon/DOCS.md
Original file line number Diff line number Diff line change
@@ -1,73 +1,9 @@
# Roborock Local Server Beta

This is an opt-in prerelease for testing experimental changes. Version
`1.1.0-rc2` includes V2 public-key recovery and multipart NC form parsing.
The NC fix lets the server identify the vacuum and encrypt its reply when a
recovered public key is available. Complete V2 onboarding and MQTT connectivity
still need hardware tests.
**Currently unused.** Install **Roborock Local Server** for the stable `1.1.0`
release. This Beta entry remains on `1.1.0-rc2` for existing installations and
future prerelease testing.

The stable **Roborock Local Server** add-on remains on `1.0.2`. Installing or
updating that add-on does not select this prerelease. Beta is a separate add-on,
with its own settings, cloud import, keys, and persistent `/data` directory.

## First installation

1. Wait until the `v1.1.0-rc2` GitHub prerelease has published its container image.
2. Add the repository `https://github.com/Python-roborock/local_roborock_server`
in the Home Assistant add-on store if it is not already present, then refresh
the store and install **Roborock Local Server Beta**.
3. Back up the stable add-on if installed. If reusing its hostname and ports,
stop the stable add-on and turn off its **Start on boot** setting while testing.
The two add-ons use the same default ports (`555` and `8881`) and cannot run
together on those ports. Beta defaults to manual startup.
4. Enter the server hostname, ports, admin password, protocol email/PIN, and TLS
settings in Beta's configuration. Settings and private certificate files are
not automatically copied from the stable add-on; use certificate paths that
Beta can access, or configure certificate issuance for Beta.
5. Start Beta, open `https://YOUR_API_HOST:555/admin` using the configured port,
and perform cloud import so the test vacuum appears. Enable **Allow new app
logins, onboarding, and first-time vacuum connections**.
6. On a second computer with Wi-Fi, use the onboarding scripts from the
`v1.1.0-rc2` checkout and run:

```bash
uv run start_onboarding.py --server YOUR_API_HOST:555
```

Follow the model's Wi-Fi reset and hotspot prompts. The terminal tool allows
retrying while the server still marks V2 unsupported.

## What to check

When updating from rc1, keep the existing Beta data and recovered key. Update
and restart Beta, then repeat pairing. This fix does not require a state wipe or
another public-key recovery. If you inserted a key into the state file manually,
restart the server before pairing so the live encryptor loads it.

The V2 query sample counter may remain zero because V2 uses header signatures.
Wait for **Public Key determined** in the admin dashboard, then perform another
pairing cycle and check for NC registration, authenticated MQTT traffic, status
updates, and a command response. A recovered key or HTTP 200 alone does not
establish successful onboarding. The unsupported banner remains in this build.

For the NC check, look for a `POST /nc` attributed to the correct vacuum, a
string in `response_json.result` instead of a plaintext object, and an NC step
recorded for that vacuum. These show that the server handled the request;
MQTT traffic is still needed to establish that the vacuum accepted the reply.
If pairing stops at NC, retain its content type, redacted request field names,
response shape, and MQTT/TLS logs from the same time for investigation.

Keep the saved Beta data between attempts. Report the model, firmware, Beta
version, recovery state, and furthest connection stage reached. Keep original
logs locally and redact credentials before sharing excerpts.

## Later updates and returning to stable

Subsequent prereleases appear as updates to **Roborock Local Server Beta** after
the store refreshes. Update that entry normally to keep its settings and samples.

To return to stable, stop Beta and start the stable add-on. Restore its original
start-on-boot setting if desired. Stable's saved data is retained, but changes
made while testing Beta are not copied back. A vacuum paired to Beta may need
another onboarding cycle, and clients reconfigured for Beta may need to be
reconfigured for stable again.
Beta and stable have separate settings and data. Follow
[switching from Beta to stable](https://python-roborock.github.io/local_roborock_server/updating/#switching-from-beta-to-stable)
if you used Beta during RC testing.
2 changes: 1 addition & 1 deletion roborock_local_server_beta_addon/config.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name: Roborock Local Server Beta
version: "1.1.0-rc2"
slug: roborock_local_server_beta
description: Opt-in prerelease testing of the Roborock local server, including experimental V2 key recovery.
description: Currently unused. Install Roborock Local Server for the stable release.
stage: experimental
url: "https://github.com/Python-roborock/local_roborock_server"
image: "ghcr.io/python-roborock/local_roborock_server"
Expand Down
2 changes: 1 addition & 1 deletion src/roborock_local_server/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@

__all__ = ["__version__"]

__version__ = "1.1.0-rc2"
__version__ = "1.1.0"
Loading
Loading