Skip to content

Home Assistant

This page covers two separate Home Assistant tasks:

  • installing the local stack as a Home Assistant 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

Before configuring the add-on, check Tested Vacuums.

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.

Install Steps

  1. Open the Home Assistant Add-on Store.

  2. Add this repository under Repositories:

  3. https://github.com/Python-roborock/local_roborock_server

  4. Install Roborock Local Server.

  5. Fill the add-on options:

  6. stack_fqdn

  7. https_port
  8. mqtt_tls_port
  9. region
  10. admin_password
  11. protocol_login_email
  12. protocol_login_pin

  13. 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.

  14. 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.

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 from a second machine to pair the vacuum to the local stack.

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.

Add-on Behavior

  • 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/....
  • Installing the add-on does not automatically rewrite Home Assistant's Roborock integration entry.

Repoint The Home Assistant Roborock Integration

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.

On many Home Assistant systems this file is at /config/.storage/core.config_entries.

  1. Find the Roborock entry and replace the endpoint values with your local stack URLs:

  2. username -> the email configured as protocol_login_email (you likely don't need to change this)

  3. base_url -> https://api-roborock.example.com:555
  4. "a" -> https://api-roborock.example.com:555
  5. "l" -> https://api-roborock.example.com:555
  6. "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.

  1. If you changed https_port or mqtt_tls_port, use those values instead.

  2. Restart Home Assistant so the integration reloads the updated endpoints.

  3. Reconfigure the Roborock integration in Home Assistant and complete the code login:

  4. The account email must be the value configured as protocol_login_email.

  5. Use the 6 digit protocol_login_pin as the code.

Reauth updates the stored Roborock user_data, including the MQTT credentials derived from rriot.

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.

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:

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
  • 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