diff --git a/README.md b/README.md index 3733d0a..da8d156 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,42 @@ # Roborock Local Server - [![GHCR][badge-ghcr]][link-ghcr] -The best way to support this project is the next time you are buying a Roborock device come back here and use one of my affiliate links where I will receive a commission. - -[![Amazon Affiliate][badge-amazon]][link-amazon] -[![Roborock Affiliate][badge-roborock-affiliate]][link-roborock-affiliate] - -You can also support via BMAC or paypal: - -[![Buy Me a Coffee][badge-bmac]][link-bmac] -[![PayPal][badge-paypal]][link-paypal] +## Introduction -Roborock Local Server is a private Roborock HTTPS and MQTT stack you run on your own system. +**Roborock Local Server** is a private, self-hosted alternative to Roborock's cloud infrastructure. This project enables you to run a complete HTTPS and MQTT stack on your own network, giving you full control over your Roborock vacuum's communication and operations without relying on external cloud services. While the vacuum can still connect to some Roborock's owned services, this stack provides all necessary functionality for your vacuum to work with almost no compromise. -This service is meant to stay private. Point your own DNS at your server's LAN IP. If you want this to work away from your home network, the server does handle auth and lets you disable new devices from connecting. BUT there is ALWAYS a risk when you make a self-hosted service publicly accessible, so please only do it if you know what you are doing. If your workflow is fine with local-only access, that will always be better. If you find any vulnerabilities, please let me know. +After installation, you can block internet access entirely and the vacuum will continue to function on your local network. The stack is also fully compatible with Home Assistant and the Roborock app, so you can seamlessly repoint them to your local server for integrated control. -## Container Image +## Support +If you appreciate this project, the best way to support it is by using my affiliate links when purchasing a Roborock device. It helps support development at no cost to you. -Published image: +[![Amazon Affiliate][badge-amazon]][link-amazon] [![Roborock Affiliate][badge-roborock-affiliate]][link-roborock-affiliate] -```sh -docker pull ghcr.io/python-roborock/local_roborock_server:latest -``` +Alternatively, you can also donate directly to support the project: -## Contributing +[![Buy Me a Coffee][badge-bmac]][link-bmac] [![PayPal][badge-paypal]][link-paypal] -If you would like to contribute there are a few ways that would be great! -1. Code is always welcome that you have fully tested. -2. Video walkthroughs of how to actually set this up would be great. -3. Documentation. I hate documentation and it's something I find myself often pushing off to AI so that I can focus more on the harder problems. But I find that human written documentation always 'feels' better. +For those who want to contribute in other ways, here are things that would be helpful: -## Requirements - -- a domain you control -- a place to run the stack on your LAN -- either Docker Compose or a Home Assistant installation that supports add-ons -- a second machine for onboarding later -- a Cloudflare API token with DNS edit access for the zone if you want automatic certificate renewal +- Tested code contributions are always welcome. +- Video walkthroughs showing how to set this up would be greatly appreciated. +- Documentation is also helpful. I often put it off to AI so I can focus on the harder problems, but human-written documentation always feels better. +- Lastly, if you have a vacuum that is not yet tested with this stack, testing it and reporting your results would be very helpful to the community. See [Tested Vacuums](tested_vacuums.md) for more information. ## Getting Started -Start here if this is your first time setting up the stack: - -1. [Installation](docs/installation.md) for the shared requirements, network setup, and Docker Compose install path. -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. - -Additional docs: +For the installation process, go to [installation.md](installation.md). That guide walks through the initial setup, required components, and the order in which to configure each part of the stack so you can get up and running with minimal friction. -- [Docs index](docs/index.md) -- [Known limitations](docs/known_limitations.md) -- [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) +## Additional docs +- [Tested vacuums](docs/tested_vacuums.md) - List of vacuums that have been tested with this stack +- [Known limitations](docs/known_limitations.md) - Information about known issues with specific vacuum models +- [Home Assistant](docs/home_assistant.md) - for the add-on install path and Home Assistant integration rewiring +- [Repointing the Roborock App](docs/roborock_app.md) - How to repoint the Roborock app to your local server +- [Updating](docs/updating.md) - Procedures for updating an existing installation +- [Custom MQTT](docs/custom_mqtt.md) - Instructions for using a custom MQTT broker +- [Custom certificate management](docs/custom_cert_management.md) - Guidance for using your own certificate files ## Acknowledgements diff --git a/docs/docker_compose.md b/docs/docker_compose.md new file mode 100644 index 0000000..23c70de --- /dev/null +++ b/docs/docker_compose.md @@ -0,0 +1,91 @@ +# Docker Compose installation + +This page only covers the Docker Compose-specific parts. It is assumed you have already completed the shared setup steps in [installation.md](installation.md) and have a working hostname and DNS. + +> Advanced users can use the container image directly from: +`ghcr.io/python-roborock/local_roborock_server` + + ### Additional Requirements +- Docker with `docker compose` +- Python +- [uv](https://docs.astral.sh/uv/getting-started/installation/) + +### Steps +1. Clone this repository: + + ```bash + git clone https://github.com/Python-roborock/local_roborock_server + cd local_roborock_server + ``` + +2. Install the project dependencies: + + ```bash + uv sync + ``` + +3. Run the setup wizard: + + ```bash + uv run roborock-local-server configure + ``` + + * The wizard asks for your: + - `stack_fqdn` which you have set up in [Shared Setup](installation.md#network-setup) + - HTTPS and MQTT TLS ports (it is recommended to keep the defaults unless you have a specific reason to change them) + - Whether to use the embedded MQTT broker or your own (see [Custom MQTT](custom_mqtt.md)) + - Whether to use Cloudflare DNS-01 auto-renew + If yes, the setup ask for: + - The `ACME domain` (domain for the certificate to be issued) and `account email` (any email you want to use for ACME account registration) + - Whether to use ZeroSSL or Actalis. + - If you chose Actalis, the setup asks for your Actalis `EAB KID` and `EAB HMAC key`. + - Your `Cloudflare API token` you created earlier. + - An admin password you will use to log in to the admin dashboard + - A Home Assistant/app login email and 6-digit PIN which can be used to repoint Home Assistant or the Roborock app to your local server. + + The wizard then creates `config.toml`, generates `admin.password_hash` and `admin.session_secret`. Depending whether or not you chose Cloudflare it writes `secrets/cloudflare_token` and if you set your `acme_server = actalis`, it also writes `secrets/acme_eab_kid` and `secrets/acme_eab_hmac_key`. + +> If you chose external MQTT, fill in `broker.host` in `config.toml` before starting the stack. + +> If you skipped Cloudflare, put your certificate files in `data/certs/fullchain.pem` and `data/certs/privkey.pem`. This is the path to use when your vacuum works better with a certificate chain you manage yourself. See [Custom certificate management](custom_cert_management.md). + +4. Starting the container: + If you set your custom ports during the setup, set matching Docker Compose variables before you start the stack so the published ports stay aligned. For example: + + ```bash + ROBOROCK_SERVER_HTTPS_PORT=8443 + ROBOROCK_SERVER_MQTT_TLS_PORT=9443 + ``` + + In PowerShell: + + ```powershell + $env:ROBOROCK_SERVER_HTTPS_PORT = "8443" + $env:ROBOROCK_SERVER_MQTT_TLS_PORT = "9443" + ``` + + > In custom setups where decided to run a reverse proxy, keep `network.https_port` and `network.mqtt_tls_port` set to the backend listener ports and use `network.advertised_https_port` / `network.advertised_mqtt_tls_port` for the public ports. + +After all is done, you can start the stack with: + ```bash + docker compose up -d --build + ``` + +## Test your installation +To test your installation, open a browser and go to `https://api-roborock.example.com:555/admin` (or your custom HTTPS port). You should see the admin dashboard login page. + +If you chose Cloudflare DNS-01 auto-renew, it may take a few minutes for the certificate to be issued. If the page does not load after a few minutes, check that the DNS resolves correctly and the stack is running: + +```bash +docker compose ps #check if the stack is running +docker compose logs -f roborock-local-server #check the logs for errors +``` + +## Next Steps +- [Installation - After the Stack Starts](installation.md#after-the-stack-starts) for post-start steps. + +## Related Guides +- [Updating](updating.md) for upgrading an existing instal +- [Home Assistant](home_assistant.md#repoint-the-home-assistant-roborock-integration) if you want to repoint the Home Assistant Roborock integration to your local stack +- [Onboarding](onboarding.md) for pairing a new vacuum +- [Repointing the Roborock App](roborock_app.md) if you want to point the official app at your local stack diff --git a/docs/home_assistant.md b/docs/home_assistant.md index aaa5d0f..b668a52 100644 --- a/docs/home_assistant.md +++ b/docs/home_assistant.md @@ -1,129 +1,99 @@ # Home Assistant -This page covers two separate Home Assistant tasks: +This page only covers the Home Assistant-specific parts. It is assumed you have already completed the shared setup steps in [Installation](installation.md). -- installing the local stack as a Home Assistant add-on +This page covers two separate Home Assistant tasks: +- installing the local stack as a Home Assistant application (app or formerly known as add-on) - repointing Home Assistant's Roborock integration to a local stack that is already running -## Install As A Home Assistant Add-on - -This is an installation method, not a post-install integration step. The add-on uses the same container image as the Docker deployment: - -- `ghcr.io/python-roborock/local_roborock_server` +## Install As A Home Assistant App -Before configuring the add-on, check [Tested Vacuums](tested_vacuums.md). +This is an installation method, not a post-install integration step. The app uses the same container image as the Docker deployment. -Different vacuums do not all trust the same certificate chains. Use that page to decide whether this install should use: - -- `tls_mode = cloudflare_acme` with `acme_server = zerossl` -- `tls_mode = cloudflare_acme` with `acme_server = actalis` -- `tls_mode = provided` with your own `cert_file` and `key_file` - -For most users, prefer `acme_server = zerossl`. Use `actalis` mainly for older vacuums or when the tested-vacuum guidance for your model specifically points to it. +### Technical Details About The App +- Installing the app does **not** automatically rewrite Home Assistant's Roborock integration entry. +- Installing the app is not required to repoint Roborock integration to your local server +- The app always runs the embedded MQTT broker and keeps the topic bridge enabled. +- The app terminates TLS itself and publishes two ports: HTTPS on `https_port` and MQTT/TLS on `mqtt_tls_port`. +- If you already manage certificates in another Home Assistant app such as Nginx Proxy Manager, you can point `cert_file` and `key_file` at those PEM files through `/all_addon_configs/...`. Nginx Proxy Manager is mainly useful here as a certificate source or admin/API HTTPS convenience; it does not remove the need for a reachable MQTT/TLS port. See [Reverse Proxy](reverse_proxy.md) for more information about this setup. ### Install Steps - -1. Open the Home Assistant Add-on Store. -2. Add this repository under **Repositories**: - +1. Open the Home Assistant setting, go to Apps section, click on `Install App`, then 3 dots in the top right corner, then `Repositories`. +2. Click `Add` and enter this repository: - `https://github.com/Python-roborock/local_roborock_server` - -3. Install **Roborock Local Server**. -4. Fill the add-on options: - - - `stack_fqdn` - - `https_port` - - `mqtt_tls_port` - - `region` - - `admin_password` - - `protocol_login_email` - - `protocol_login_pin` +3. Go back to the app Store and search for **Roborock Local Server**. Install it, then click **Configuration**. +4. Fill the app options: + - `stack_fqdn` - Domain you have set up in [Shared Setup](installation.md#network-setup) + - `https_port` - Keep the default unless you have a specific reason to change it + - `mqtt_tls_port` - Keep the default unless you have a specific reason to change it + - `region` - Region to which your account is on linked (likely where you registered the Roborock app) + - `admin_password` - Password you will later use to log in to the dashboard + - `protocol_login_email` - Email you later use to link your Roborock device to Home Assistant + - `protocol_login_pin` - PIN you later use to link your Roborock device to Home Assistant + - TLS settings: - - `tls_mode = provided` with explicit `cert_file` and `key_file` - - or `tls_mode = cloudflare_acme` with `tls_base_domain`, `tls_email`, and `cloudflare_token` - - optional ACME CA selection with `acme_server` (`zerossl` is the preferred default for most users) - - if `acme_server = actalis`, also set `acme_eab_kid` and `acme_eab_hmac_key`. - -5. Start the add-on. - -Then open the admin dashboard at your configured stack hostname, for example: - -- `https://api-roborock.example.com:555/admin` - -Do not use the Home Assistant UI hostname unless it is the same hostname covered by the TLS certificate you configured for `stack_fqdn`. + - if you set `cloudflare_acme` you have to fill in: + - `tls_base_domain`- Base domain for the certificate to be issued (the same domain you used for `stack_fqdn`) + - `tls_email` - Any email you want to use for your ACME account registration + - `cloudflare_token` - Cloudflare API token you created earlier + - if you set `provided` you have to fill in your own `cert_file` and `key_file` -After the dashboard opens, complete the same post-start steps as the Docker install: -1. Use the admin dashboard cloud import to fetch your Roborock account data. -2. Confirm the expected vacuum appears in the inventory. -3. Run [Onboarding](onboarding.md) from a second machine to pair the vacuum to the local stack. + - ACME settings: + - If you set ZeroSSL, you do not need to fill in any additional fields. + - If you set Acatalis, you have to fill in: + - `acme_eab_kid` - Your Actalis EAB KID + - `acme_eab_hmac_key` - Your Actalis EAB HMAC key -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. +5. Go back to the **Info** tab and start the app. -### Add-on Behavior +If set up correctly, your local stack should be running shortly as a Home Assistant app! +It is recomended to enable the app's **Start on boot** option so the server starts automatically after Home Assistant boots. -- The add-on always runs the embedded MQTT broker and keeps the topic bridge enabled. -- The add-on terminates TLS itself and publishes two ports: HTTPS on `https_port` and MQTT/TLS on `mqtt_tls_port`. -- If you already manage certificates in another Home Assistant add-on such as Nginx Proxy Manager, you can point `cert_file` and `key_file` at those PEM files through `/all_addon_configs/...`. Nginx Proxy Manager is mainly useful here as a certificate source or admin/API HTTPS convenience; it does not remove the need for a reachable MQTT/TLS port. See [Reverse Proxy](reverse_proxy.md). -- Installing the add-on does **not** automatically rewrite Home Assistant's Roborock integration entry. +## Next Installation Steps +- [Installation - After the Stack Starts](installation.md#after-the-stack-starts) for post-start steps. -## Repoint The Home Assistant Roborock Integration +## Pointing The Home Assistant Roborock Integration +This applies whether your local stack is running via Docker Compose or via the Home Assistant app. -This applies whether your local stack is running via Docker Compose or via the Home Assistant add-on. - -### Existing Roborock Integration - -Use this flow when the Roborock integration already exists in Home Assistant. +> To repoint the Roborock integration you must first link your vacuum to Home Assistant using the official Roborock login flow, without going through the local server. 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` - - `"a"` -> `https://api-roborock.example.com:555` - - `"l"` -> `https://api-roborock.example.com:555` - - `"m"` -> `ssl://api-roborock.example.com:8881` +2. Stop the Roborock integration in Home Assistant. + > **Optional troubleshooting:** To confirm the local protocol login works, run this 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. + > On many Home Assistant systems this file is at `/config/.storage/core.config_entries`. The file is rewritten while Home Assistant integration is running, so make the edit while the Roborock integration is stopped. + +3. Find the Roborock entry and replace the endpoint values with your local stack URLs: + + - `username` - the email configured as `protocol_login_email` + - `base_url` - `https://api-roborock.example.com:555` + - `"a"` - `https://api-roborock.example.com:555` + - `"l"` - `https://api-roborock.example.com:555` + - `"m"` - `ssl://api-roborock.example.com:8881` 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. -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). + > If you changed `https_port` or `mqtt_tls_port`, use those values instead. -8. Enable the Roborock integration. +4. Start the Roborock integration. -9. Reconfigure the Roborock integration and complete the code login: +5. 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 +> **Reconfigure** action should apear in the integrations section, but 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. -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. +### Troubleshooting 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: @@ -131,15 +101,14 @@ Home Assistant derives the MQTT username and password from `rriot.u`, `rriot.s`, rejected MQTT CONNECT reason=invalid_mqtt_credentials ``` -If you see that message after reauth, check that: - -- the local server has a cloud import snapshot from the same Roborock account as the Home Assistant entry +If you see that message after reauth, try these steps: +- Check if the local server has a cloud import snapshot from the same Roborock account as the Home Assistant entry - `base_url`, `rriot.r.a`, `rriot.r.l`, and `rriot.r.m` all point at the local stack -- Home Assistant was fully restarted after editing `.storage/core.config_entries` - Reconfigure completed with `protocol_login_email` and `protocol_login_pin` +- Lastly, try restarting Home Assistant editing `.storage/core.config_entries` + ## Related Docs -- [Installation](installation.md) - [Onboarding](onboarding.md) -- [Using the Roborock App](roborock_app.md) +- [Using the Roborock App](roborock_app.md) \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 78325c3..0422e60 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,9 +4,9 @@ Use this page as the main docs hub for setup, onboarding, and follow-up guides. ## Start Here -1. Read [Installation](installation.md) for the shared requirements and network setup. +1. Read [Shared Setup](installation.md) for the prerequisites, shared terms, certificate choice, and network setup. 2. Choose an install method: - - finish the Docker Compose steps in [Installation](installation.md) + - finish the Docker Compose steps in [Docker Compose](docker_compose.md) - 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. diff --git a/docs/installation.md b/docs/installation.md index 707ecea..6c2d474 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,167 +1,103 @@ -# Installation +# Shared Setup -Start here for a first-time setup. The project supports two installation methods: +Use this page first for the setup details that apply to both installation paths. -- Docker Compose on your own Linux host or VM -- the Home Assistant add-on from this repository +Before getting started, check [Tested Vacuums](tested_vacuums.md) and [Known Limitations](known_limitations.md) to see if your vacuum model has been tested and that you understand the current limitations of the stack. -After the stack is running, continue with [Onboarding](onboarding.md) to pair a vacuum. - -## Shared Requirements +## Prerequisites - A domain name that you own -- A place to run the stack on your LAN -- A second machine for onboarding later. It needs Python 3.11+ and `uv` if you run the onboarding scripts there. +- A computer with Wi-Fi capabilities +- A local machine to run the stack on your LAN - A network that can host the stack's HTTPS and MQTT TLS ports internally. The defaults are `555` and `8881`. -- A Cloudflare API token with DNS edit access for the zone if you want Cloudflare DNS-01 auto-renew. See [Cloudflare setup](cloudflare_setup.md). - -## Credential Names +- If you want to use Cloudflare DNS-01 auto-renew (recommended), you will need a Cloudflare API token with DNS edit access for the zone. See [Cloudflare setup](cloudflare_setup.md). -The setup uses three different credentials: +## Common Terms -- The **admin password** signs in to the local server dashboard at `/admin`. +- The **stack FQDN** is the hostname you choose for this application. It must be a subdomain of a domain you own and it must start with `api-`. +- The **admin password** is used later for signing in to your local server dashboard. - The **protocol login email and PIN** are the local login that Home Assistant or the Roborock app use after you repoint them to this server. - Your **Roborock cloud email and verification code** are used only by the admin dashboard's cloud import flow so the local server can fetch your current homes, rooms, routines, and known vacuums. -## Choose Your Certificate Path First - -Before you run the setup wizard, check [Tested Vacuums](tested_vacuums.md). - -Different vacuums trust different certificate chains. That determines whether you should: - -- use `zerossl` with Cloudflare DNS-01 automation -- switch Cloudflare DNS-01 automation to `actalis` -- skip Cloudflare ACME and bring your own certificate files instead - -For most users, prefer `zerossl`. Use `actalis` mainly for older vacuums or for models that already have tested-vacuum notes showing better compatibility with that chain. - -If your model already has certificate notes on the tested-vacuums page, follow that guidance first. It is easier to choose the right certificate path up front than to reissue certs after onboarding starts. - ## Network Setup -1. Pick a hostname for this application. It must be a subdomain of a domain you own, and it **must** start with `api-`. - - For example, if you own `example.com`, use `api-roborock.example.com`. Throughout the docs this is the **stack FQDN**. +1. For the setup you need to own your own domain. If you do not have one, you can register a domain with any domain registrar of your liking. - Onboarding also has a hard 32-character limit for the final `host[:port]/` value sent to the vacuum after the `api-` prefix is stripped. Short names are safer: + > If you wish to use Cloudflare DNS-01 auto-renew, you will need to set Cloudflares nameservers for your domain. + +2. Your network **must** handle its own DNS for the network the vacuum connects to. If the vacuum, phone, or onboarding machine uses an external DNS server this will not work. - - `api-rr.example.com` with the default port becomes `rr.example.com:555/` and fits. - - `api-roborock-local-server.example.com` with the default port becomes `roborock-local-server.example.com:555/` and is too long. + > Local DNS can sometimes be handled by your router, if you don't have a router that supports local DNS, you can use a local DNS server like [Pi-hole](https://pi-hole.net/) or [AdGuard Home](https://adguard.com/en/adguard-home/overview.html) or any other of your choice. + + > Cloudflare DNS-01 certificate issuance will not require public inbound access, public port forwarding, or Cloudflare proxying. So there is no need to expose the stack to the internet. -2. Your network **must** handle its own DNS for the network the vacuum connects to. If the vacuum, phone, or onboarding machine uses an external DNS server like `8.8.8.8`, this will not work. + > Some users may want to expose the stack publicly. For this cases the server does support authentication, and can disable new device pairing. Make sure you understand the security implications before doing so. -3. Create a local DNS record pointing your stack FQDN to the LAN IP of the machine running the stack. +3. In your local DNS, create a subdomain entry starting with `api-` for the `stack FQDN` and point it to the LAN IP of the machine you are planning to run the stack on. + > Onboarding has a hard 32-character limit for the final `host[:port]/` value sent to the vacuum after the `api-` prefix is stripped. Use a short subdomain to avoid hitting that limit. For example: + > + > - `api-rr.example.com` with the default port becomes `rr.example.com:555/` and fits. + > - `api-roborock-local-server.example.com` with the default port becomes `roborock-local-server.example.com:555/` and is too long. - This should be split-horizon or local DNS through your router, Pi-hole, AdGuard Home, Unbound, or similar. Cloudflare DNS-01 certificate issuance does not require public inbound access, public port forwarding, or Cloudflare proxying. - - If you want the stack to work away from your home network, the server does handle auth and lets you disable new devices from connecting. That still makes this a publicly accessible self-hosted service, so only do it if you know what you are doing. Local-only access is always the better option when it fits your workflow. - -4. From a client on the same network the vacuum will use, verify the name resolves to the server's LAN IP: +4. From an another client on the same network open a terminal and verify the name resolves to the server's IP address: ```bash nslookup api-roborock.example.com ``` - For the first setup and onboarding flow, your home network clients should resolve this name to the server's LAN IP. If they resolve to a public IP, make sure your router and firewall setup intentionally support that path before continuing. - - With the current server behavior, the same hostname is advertised for both HTTPS and MQTT/TLS, so you do not need a separate `mqtt-...` hostname unless you have built your own custom client routing around one. - - If a reverse proxy maps public ports to different backend listener ports, see [Reverse Proxy](reverse_proxy.md) before starting the stack. - -## Method 1: Docker Compose - -### Additional Requirements + For the first setup and onboarding flow, your home network clients should resolve this name to the server's LAN IP. + > With the default server behavior, the same hostname is advertised for both HTTPS and MQTT/TLS, so you do not need a separate `mqtt-...` hostname unless you have built your own custom client routing around one. -- Docker with `docker compose` -- Python -- [uv](https://docs.astral.sh/uv/getting-started/installation/) - -### Steps - -1. Clone this repository: - - ```bash - git clone https://github.com/Python-roborock/local_roborock_server - cd local_roborock_server - ``` + > If a reverse proxy maps public ports to different backend listener ports, see [Reverse Proxy](reverse_proxy.md) before starting the stack. -2. Install the project dependencies: - - ```bash - uv sync - ``` - -3. Run the setup wizard: - - ```bash - uv run roborock-local-server configure - ``` +## Installation +### Choose Your Certificate Path First +Different vacuums trust different certificate chains. That determines whether you should: - The wizard asks for: +- use `zerossl` with Cloudflare DNS-01 automation, +- use `actalis` with Cloudflare DNS-01 automation, or +- skip Cloudflare ACME and [bring your own certificate files instead](custom_cert_management.md) - - `stack_fqdn` (must start with `api-`) - - HTTPS and MQTT TLS ports if you do not want the defaults `555` and `8881` - - embedded MQTT or your own broker - - whether to use Cloudflare DNS-01 auto-renew - - if you chose Cloudflare, the ACME account email and whether to use ZeroSSL or Actalis. In most cases, choose ZeroSSL unless you are targeting an older vacuum. - - if you chose Actalis, the Actalis EAB KID and EAB HMAC key - - your admin password - - your Home Assistant/app login email and 6-digit PIN +You can check [Tested Vacuums](tested_vacuums.md) to see of anyone has already tested your vacuum model with a specific certificate chain. For most users, prefer `zerossl` authority. The `actalis` is mainly used by older vacuums or for models that already have been tested showing better compatibility with that chain. - It then writes `config.toml`, generates `admin.password_hash` and `admin.session_secret`, and if you chose Cloudflare it also writes `secrets/cloudflare_token`. If you also chose `acme_server = actalis`, it writes `secrets/acme_eab_kid` and `secrets/acme_eab_hmac_key`. +If your model already has certificate notes on the tested-vacuums page, follow that guidance first. It is easier to choose the right certificate path up front than to reissue certs after onboarding starts. -4. If you chose external MQTT, fill in `broker.host` in `config.toml` before starting the stack. See [Custom MQTT](custom_mqtt.md). +Now you are ready to install the stack. There are two installation paths. Pick one and follow the steps for that path: -5. If you skipped Cloudflare, put your certificate files in `data/certs/fullchain.pem` and `data/certs/privkey.pem`. This is the path to use when your vacuum works better with a certificate chain you manage yourself. See [Custom certificate management](custom_cert_management.md). +### Installation Paths +* [Docker Compose](docker_compose.md) for a standalone Docker deployment +* [Home Assistant](home_assistant.md) for installing as Home Assistant app (add-on). -6. Start the container: - ```bash - docker compose up -d --build - ``` - If you changed `network.https_port` or `network.mqtt_tls_port` in `config.toml`, set matching Docker Compose variables before you start the stack so the published ports stay aligned. For example: +If you chose Cloudflare DNS-01 auto-renew, it may take a few minutes for the certificate to be issued. If the page does not load after a few minutes, check that the DNS resolves correctly and the stack is running: - ```bash - ROBOROCK_SERVER_HTTPS_PORT=8443 - ROBOROCK_SERVER_MQTT_TLS_PORT=9443 - docker compose up -d --build - ``` - - In PowerShell: - - ```powershell - $env:ROBOROCK_SERVER_HTTPS_PORT = "8443" - $env:ROBOROCK_SERVER_MQTT_TLS_PORT = "9443" - docker compose up -d --build - ``` +## After The Stack Starts - For reverse proxy setups, keep `network.https_port` and `network.mqtt_tls_port` set to the backend listener ports and use `network.advertised_https_port` / `network.advertised_mqtt_tls_port` for the public ports. +### Test your installation +To test your installation, open a browser and go to your admin dashboard at `https://api-roborock.example.com:555/admin`. You should see the admin dashboard login page. -## Method 2: Home Assistant Add-on +If the page does not load, check if the DNS resolves correctly and the stack is running: + * For Docker Compose, check with: + ```bash + docker compose ps #check if the stack is running + docker compose logs -f roborock-local-server #check the logs for errors + ``` + * For the Home Assistant app, check if the server has status `running` in the Apps section and then check the **logs** tab. -Use [Home Assistant](home_assistant.md) as the installation guide if you want to run the stack as a Home Assistant add-on instead of Docker Compose. +> If you chose Cloudflare DNS-01 auto-renew, it may take a few minutes for the certificate to be issued and the stack to start. -## After The Stack Starts -1. Open the admin dashboard at `https://api-roborock.example.com:555/admin` by default, or `https://api-roborock.example.com:YOUR_HTTPS_PORT/admin` if you chose a custom HTTPS port. +### Sync your Roborock cloud data with the local stack -2. If the page does not load, check the container and DNS before onboarding: +After either Docker or Home Assistant stack is running, you can log in to the admin dashboard and import your Roborock cloud data. - ```bash - docker compose ps - docker compose logs -f roborock-local-server - nslookup api-roborock.example.com - ``` +1. Open your admin dashboard at `https://api-roborock.example.com:555/admin`. -3. Import your data from the cloud so things like routines and rooms will work. Enter your Roborock cloud email under cloud import, select **Send code**, then enter the returned code and select **Fetch data**. +2. Log in to the interface with admin password you have configured. Under cloud import, enter your Roborock cloud email, select **Send code**, then enter the code sent to your email and select **Fetch data**. -4. For any routines that use zones, re-save them so the server stores the zone data correctly. In the Roborock app, open each routine that has zones, open the zone, tap **Edit**, open any **Zone Cleaning** entry, then tap **Save**. Repeat for each zone in the routine. +3. For any routines that use zones, re-save them so the server stores the zone data correctly. In the Roborock app, open each routine that has zones, open the zone, tap **Edit**, open any **Zone Cleaning** entry, then tap **Save**. Repeat for each zone in the routine. -## Next Steps -- [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 +## Pair a vacuum to the local stack +After everything is set up, continue with [Onboarding](onboarding.md) to pair a vacuum. \ No newline at end of file diff --git a/docs/tested_vacuums.md b/docs/tested_vacuums.md index d12137f..64f90cc 100644 --- a/docs/tested_vacuums.md +++ b/docs/tested_vacuums.md @@ -29,7 +29,6 @@ These are (maybe) using the same firmware as the two above. Any vacuum released - Roborock Qrevo Edge 2 - Roborock Qrevo S Pro - Qrevo Curv 2 Flow -- Qrevo CurvX - Saros Z70 ## Supported Vacuums @@ -42,20 +41,24 @@ Legend: - Cross: reported not working - Question mark: not reported yet -| Vacuum | Firmware | ZeroSSL / Cloudflare | Actalis | Let's Encrypt | SSL.com | +| Vacuum | Reported Firmware(s) | ZeroSSL / Cloudflare | Actalis | Let's Encrypt | SSL.com | |---|---:|---:|---:|---:|---:| +| Roborock G30U | `02.52.32` | ✅ | ❓ | ❓ | ❓ | +| Roborock Q5 PRO | `2.04.06` | ❓ | ❓ | ✅ | ❓ | +| Roborock Qrevo Curv | `02.28.60` | ❓ | ❓ | ✅ | ❓ | +| Roborock Qrevo CurvX | `02.35.88` | ✅ | ❓ | ❓ | ❓ | +| Roborock Qrevo Edge 2 | `02.11.66` | ❓ | ❓ | ❓ | ❌ | +| Roborock Qrevo Master | `02.28.26` | ❓ | ❓ | ❓ | ✅ | +| Roborock Qrevo MaxV | Not reported | ✅ | ❓ | ✅ | ❓ | +| Roborock Qrevo Plus | Not reported | ✅ | ❓ | ❓ | ❓ | +| Roborock Qrevo S5V (170) | `02.16.64` | ❓ | ❓ | ✅ | ❓ | | Roborock S5 Max | Not reported | ❌ | ✅ | ❌ | ❓ | | Roborock S7 | Not reported | ❓ | ✅ | ❌ | ✅ | -| Roborock S7 MaxV | Not reported | ✅ | ❓ | ✅ | ❓ | -| Roborock S8 | Not reported | ❓ | ❓ | ❓ | ❓ | -| Roborock S8 MaxV Ultra | Not reported | ✅ | ❓ | ❓ | ❓ | +| Roborock S7 MaxV | `2.59.36` | ✅ | ❓ | ✅ | ❓ | +| Roborock S8 | Not reported | ❓ | ❓ | ✅ | ❓ | +| Roborock S8 MaxV Ultra | `02.37.38` | ✅ | ❓ | ❓ | ❓ | | Roborock S8 Pro Ultra (a70) | Not reported | ❓ | ❓ | ❓ | ❓ | -| Roborock Saros 10R | `02.52.32` | ✅ | ❓ | ✅ | ❓ | -| Roborock G30U | `02.52.32` | ✅ | ❓ | ❓ | ❓ | -| Roborock Qrevo S5V | Not reported | ❓ | ❓ | ❓ | ❓ | -| QRevo MaxV | Not reported | ✅ | ❓ | ✅ | ❓ | -| QRevo Master | Not reported | ❓ | ❓ | ❓ | ❓ | -| QRevo Plus | Not reported | ✅ | ❓ | ❓ | ❓ | +| Roborock Saros 10R | `02.52.32`,`02.52.86` | ✅ | ❓ | ✅ | ❓ | ## Unlisted Vacuums