improve docs

Lash-L · Lash-L · commit 42b48566bac6 · 2026-06-04T21:33:43.000-04:00
diff --git a/README.md b/README.md
@@ -49,6 +49,7 @@ Start here if this is your first time setting up the stack:
 2. [Home Assistant](docs/home_assistant.md) if you want to install the stack as a Home Assistant add-on instead of Docker Compose.
 3. [Cloudflare setup](docs/cloudflare_setup.md) if you want Cloudflare DNS-01 auto-renew for certificates.
 4. [Onboarding](docs/onboarding.md) to pair a vacuum from a second machine after the server is running.
+5. [Updating](docs/updating.md) if you already have an install and are moving to a newer stable release.
 
 Before choosing a certificate path, check [Tested vacuums](docs/tested_vacuums.md). Different models do not all accept the same certificate chains. For most users, start with ZeroSSL. Use Actalis mainly for older vacuums or models that are already known to trust that chain more reliably.
 
@@ -59,6 +60,7 @@ Additional docs:
 - [Tested vacuums](docs/tested_vacuums.md)
 - [Home Assistant](docs/home_assistant.md) for the add-on install path and Home Assistant integration rewiring
 - [Using the Roborock App](docs/roborock_app.md)
+- [Updating](docs/updating.md)
 - [Custom MQTT](docs/custom_mqtt.md)
 - [Custom certificate management](docs/custom_cert_management.md)
 
diff --git a/docs/home_assistant.md b/docs/home_assistant.md
@@ -71,11 +71,27 @@ If you need the MITM protocol sync secret for the Roborock app flow, sign in to
 
 This applies whether your local stack is running via Docker Compose or via the Home Assistant add-on.
 
-1. Open your Home Assistant configuration directory and locate `.storage/core.config_entries`.
+### Existing Roborock Integration
 
-   On many Home Assistant systems this file is at `/config/.storage/core.config_entries`.
+Use this flow when the Roborock integration already exists in Home Assistant.
 
-2. Find the Roborock entry and replace the endpoint values with your local stack URLs:
+1. Make sure the local stack is running and has a cloud import snapshot from the same Roborock account used by the Home Assistant integration.
+
+2. OPTIONAL but useful: confirm the local protocol login works from a shell on the Home Assistant host or another machine that can reach the stack:
+
+   ```bash
+   curl -sk -X POST "https://api-roborock.example.com:555/api/v5/auth/email/login/code" \
+     -H "Content-Type: application/json" \
+     -d '{"email":"you@example.com","code":"123456"}'
+   ```
+
+   Replace `you@example.com` with `protocol_login_email` and `123456` with `protocol_login_pin`. A successful response includes `data.rriot.r.a`, `data.rriot.r.l`, and `data.rriot.r.m` pointing at your local stack.
+
+3. Disable the Roborock integration in Home Assistant.
+
+   On many Home Assistant systems this file is at `/config/.storage/core.config_entries`. The file is rewritten while Home Assistant is running, so make the edit while the Roborock integration is stopped.
+
+5. Find the Roborock entry and replace the endpoint values with your local stack URLs:
 
    - `username` -> the email configured as `protocol_login_email` (you likely don't need to change this)
    - `base_url` -> `https://api-roborock.example.com:555`
@@ -85,22 +101,31 @@ This applies whether your local stack is running via Docker Compose or via the H
 
    The current server advertises the same hostname for HTTPS and MQTT/TLS, so `"m"` should normally use the same `stack_fqdn`, not a separate `mqtt-...` hostname.
 
-3. If you changed `https_port` or `mqtt_tls_port`, use those values instead.
+6. If you changed `https_port` or `mqtt_tls_port`, use those values instead.
+
+7. Restart Home Assistant (Or start it if you had it stopped).
 
-4. Restart Home Assistant so the integration reloads the updated endpoints.
+8. Enable the Roborock integration.
 
-5. Reconfigure the Roborock integration in Home Assistant and complete the code login:
+9. Reconfigure the Roborock integration and complete the code login:
 
    - The account email must be the value configured as `protocol_login_email`.
    - Use the 6 digit `protocol_login_pin` as the code.
 
    Reauth updates the stored Roborock `user_data`, including the MQTT credentials derived from `rriot`.
 
+The **Reconfigure** action may not appear until Home Assistant has loaded the edited local endpoint data. If you do not see it, check that the integration was stopped while editing `.storage/core.config_entries`, then restart Home Assistant and open the integration again.
+
 ### First Time Home Assistant Setup
 
-Home Assistant currently creates a Roborock config entry through the official Roborock login flow. If you have never added the Roborock integration before, create the integration once with the official Roborock API, then stop the integration and edit `.storage/core.config_entries` as described above.
+Home Assistant currently creates a Roborock config entry through the official Roborock login flow. If you have never added the Roborock integration before:
+
+1. Add the Roborock integration once with the official Roborock API.
+2. Disable the integration.
+3. Edit `.storage/core.config_entries` as described above.
+4. Start Home Assistant, enable the integration, then run **Reconfigure** and enter your local PIN.
 
-After editing the endpoints and restarting Home Assistant, run **Reconfigure** on the Roborock integration and enter your local PIN. Home Assistant derives the MQTT username and password from `rriot.u`, `rriot.s`, and `rriot.k`; stale values commonly show up in the local server logs as:
+Home Assistant derives the MQTT username and password from `rriot.u`, `rriot.s`, and `rriot.k`; stale values commonly show up in the local server logs as:
 
 ```text
 rejected MQTT CONNECT reason=invalid_mqtt_credentials
diff --git a/docs/index.md b/docs/index.md
@@ -10,6 +10,7 @@ Use this page as the main docs hub for setup, onboarding, and follow-up guides.
    - or use [Home Assistant](home_assistant.md) to install the stack as a Home Assistant add-on
 3. Use [Cloudflare setup](cloudflare_setup.md) if you want Cloudflare DNS-01 auto-renew for certificates.
 4. Run [Onboarding](onboarding.md) from a second machine after the server is running.
+5. Use [Updating](updating.md) when moving an existing install to a newer stable release.
 
 ## Support This Project
 
@@ -20,6 +21,7 @@ If you want to support this project, next time you buy a Roborock, use one of my
 - [Known limitations](known_limitations.md)
 - [Home Assistant](home_assistant.md)
 - [Using the Roborock App](roborock_app.md)
+- [Updating](updating.md)
 - [Tested vacuums](tested_vacuums.md)
 - [Custom MQTT](custom_mqtt.md)
 - [Custom certificate management](custom_cert_management.md)
diff --git a/docs/installation.md b/docs/installation.md
@@ -159,4 +159,5 @@ Use [Home Assistant](home_assistant.md) as the installation guide if you want to
 - [Onboarding](onboarding.md) for pairing a new vacuum
 - [Home Assistant](home_assistant.md) if you want to repoint Home Assistant's Roborock integration to your local stack
 - [Using the Roborock App](roborock_app.md) if you want to point the official app at your local stack
+- [Updating](updating.md) for upgrading an existing install
 - [Docs index](index.md) for the rest of the guides
diff --git a/docs/updating.md b/docs/updating.md
@@ -0,0 +1,81 @@
+# Updating
+
+Use this page when moving an existing install to a newer stable release.
+
+## Before Updating
+
+1. Back up your config and data directory.
+
+   For Docker Compose installs, this usually means `config.toml`, `secrets/`, and `data/`.
+
+   For the Home Assistant add-on, take a Home Assistant backup or copy the add-on config and any certificate files you mounted through `/all_addon_configs/...`.
+
+2. Check the release notes or changelog for the version you are installing.
+
+3. Keep your current `stack_fqdn`, HTTPS port, MQTT/TLS port, certificate mode, and `protocol_login_email` stable unless you intentionally want to repoint clients again.
+
+## Updating From A Stable Or RC Release
+
+If you were already on a stable release such as `0.0.5`, `0.0.6`, `1.0.0`, or a late release candidate, updating should usually not require manual migration.
+
+After updating:
+
+1. Start the stack.
+2. Open `/admin`.
+3. Confirm the expected vacuums are still listed.
+4. Confirm Home Assistant or the Roborock app can still connect.
+
+If Home Assistant reports MQTT credential failures after the update, run **Reconfigure** on the Roborock integration and enter your local `protocol_login_pin` again.
+
+## Updating From An Older Main-Branch Build
+
+If you ran an early development build from `main`, compare your config with the current `config.example.toml` in the repository root. The stable stack expects the current config shape.
+
+In particular, check that:
+
+- `network.stack_fqdn` is your `api-...` hostname.
+- `network.https_port` and `network.mqtt_tls_port` match the ports you publish.
+- `broker.mode` is either `embedded` or `external`.
+- `tls.mode` is either `cloudflare_acme` or `provided`.
+- `admin.password_hash`, `admin.session_secret`, `admin.protocol_login_email`, and `admin.protocol_login_pin_hash` are present.
+
+If your config is missing required fields, the safest path is to rerun:
+
+```bash
+uv run roborock-local-server configure
+```
+
+Then copy over only the settings you intentionally want to preserve, such as the hostname, ports, certificate mode, and data directory. But I would honestly recommend starting from scratch. (you may just want to copy over the signature samples to save yourself some time)
+
+## Docker Compose
+
+Pull the current image or rebuild from the updated checkout:
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+If you build locally instead of pulling the published image:
+
+```bash
+git pull
+docker compose up -d --build
+```
+
+## Home Assistant Add-on
+
+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).
+
+## After Updating
+
+Open the admin dashboard and check:
+
+- the server health status
+- certificate status
+- known vacuums
+- recent HTTP and MQTT activity
+
+If routines with zones stop behaving as expected, re-save those routines in the Roborock app so the server refreshes the zone data.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -53,6 +53,7 @@ nav:
     - Home Assistant: home_assistant.md
     - Cloudflare Setup: cloudflare_setup.md
     - Onboarding: onboarding.md
+    - Updating: updating.md
   - Integrations:
     - Using the Roborock App: roborock_app.md
   - Reference:
diff --git a/roborock_local_server_addon/DOCS.md b/roborock_local_server_addon/DOCS.md
@@ -30,7 +30,9 @@ After the dashboard opens:
 
 This add-on does not auto-edit Home Assistant's Roborock config entry. You still need to update `.storage/core.config_entries` so Home Assistant points at your local stack.
 
-After updating `username`, `base_url`, `rriot.r.a`, `rriot.r.l`, and `rriot.r.m`, restart Home Assistant and use **Reconfigure** on the Roborock integration. Enter `protocol_login_email` as the account and `protocol_login_pin` as the code.
+Disable the Roborock integration before editing `.storage/core.config_entries`. Update `username`, `base_url`, `rriot.r.a`, `rriot.r.l`, and `rriot.r.m`, then restart home assistant and enable the integration.
+
+Use **Reconfigure** on the Roborock integration after Home Assistant has loaded the local endpoint data. Enter `protocol_login_email` as the account and `protocol_login_pin` as the code. If **Reconfigure** is not available yet, restart Home Assistant and reopen the integration.
 
 ## Notes
 
