Valetudo on Xiaomi Vacuum: Cloud-Free Local Control with Home Assistant

A robot vacuum’s app can depend on a vendor account and cloud connection even when the vacuum is on your home Wi-Fi. If you want its controls and map available locally, Valetudo is an option for specifically supported models.

Valetudo replaces the cloud service used by the robot; it is not a replacement firmware. It runs on a rooted robot alongside the vendor firmware and provides a local web interface and MQTT integration. Rooting and recovery procedures depend on the exact model. See the project’s newcomer guide before deciding to install it.

Start by checking compatibility and the model-specific installation instructions. Once Valetudo is running, the MQTT, HA, room-cleaning, and dashboard steps below help connect it to your local setup.

Disclosure: Some links in this article may be affiliate links. We may earn a small commission at no extra cost to you.

What changes with Valetudo

The data path depends on the robot and app. A floor plan, cleaning history, or remote command can be handled through the vendor’s service. This guide does not include a traffic audit of every Xiaomi or Roborock firmware, so it cannot establish exactly what a particular model uploads.

Valetudo provides the cloud-replacement interface on the robot. Keep its MQTT broker and HA integration local, then check the network restrictions separately if you want to prevent external connections.

Check the exact robot and rooting method

Valetudo is a community project, not a vendor product. Support depends on whether researchers have reverse-engineered the target device’s firmware and root path. Not every Xiaomi or Roborock model is supported, and newer models increasingly use encrypted bootloaders or soldered NAND that require hardware disassembly to root — beyond the scope of this guide.

Support does not imply a software-only installation. These examples illustrate why you need the exact entry in the project’s supported-robots list:

How to identify your model: Check the sticker on the underside of the vacuum. The model number format is typically SDJQR02RR, STY-02, or similar. Cross-reference with the Valetudo supported devices list before proceeding.

If your model requires hardware rooting — opening the chassis, connecting to UART, or replacing NAND chips — this guide isn’t the right starting point. The Valetudo documentation covers hardware root paths for supported models separately.

Confirm the robot’s label, production revision, and installed firmware against its supported entry. A similar product name or a package appearing in a build tool does not establish compatibility.

Generating Your Firmware with Dustbuilder

Some supported installation routes use Dustbuilder to create a model-specific rooted package. Use it only as directed by your robot’s installation guide; it is not a universal installer for every Valetudo-supported vacuum.

1. Open your robot’s entry in the supported-robots list.
2. Read the linked rooting guide, including prerequisites and recovery requirements.
3. If it calls for Dustbuilder, select the exact model and package type specified there.
4. Keep the resulting files and the configuration needed for recovery.

Keep the files required by that method. A local OTA package and an image for hardware rooting are different artifacts.

Install using the model-specific rooting guide

Do not use one XVacuum workflow for every Xiaomi or Roborock. The current Roborock installation documentation includes different OTA and hardware methods, and documents valetudo-helper-miioota for its supported local OTA route.

Before starting, confirm the required firmware, package type, power state, tools, and recovery procedure. If the guide requires disassembly, assess that work before downloading or flashing anything.

Follow the project’s complete instructions for your model. Do not interrupt power during a flash, and do not substitute a package built for a similarly named robot. Stop if the reported model, firmware, or required access differs from the guide.

For a Roborock that the guide explicitly marks as eligible for local OTA: the documented workflow is concrete. It is not the method for an S6/S7 requiring hardware access.

1. If previously used with the vendor app, perform the factory reset required by the project. Confirm firmware eligibility; the guide identifies newer miio firmware and some later recovery images as blockers.
2. In Dustbuilder, choose the exact model and Build update package (for installation via local OTA). Keep the downloaded package and recovery information.
3. Download the appropriate valetudo-helper-miioota release for your computer. Connect that computer to the robot’s access point and run the guide’s install-firmware command with your package filename.
4. Keep power stable and wait for the completion announcement. Do not interrupt the robot or assume a quiet minute means flashing has failed.

Follow the complete Roborock installation guide for eligibility and recovery. For a failed connection, check battery charge, VPN/firewall interference, and the network interface before retrying. Future updates use the rooted robot’s documented update route rather than blindly repeating this initial installation.

First Boot: Valetudo Web UI

After flashing, the vacuum runs Valetudo and broadcasts its access point. Connect your device to that AP again.

Use the access-point address documented for your robot. Common addresses differ by model; 192.168.8.1 is not universal.

You should see the Valetudo web interface — a clean, local-only dashboard. From here:

1. Go to Connectivity → Wi-Fi and configure your home network credentials. The vacuum will connect to your LAN and drop the AP.
2. Once it joins your LAN, find its assigned IP via your router’s DHCP lease table, or set a static reservation by MAC address (recommended — the MQTT config and HA integration both reference this IP).
3. Set a friendly name under Settings → Robot. This name propagates into Home Assistant entity labels via MQTT autodiscovery.
4. Confirm the map is rendering under the Map tab. If the map is empty, do a short manual cleaning run to let Valetudo build the initial floor map.

Check that manual controls, docking, and the map work in the local interface before adding HA. A successful local setup does not prove that the robot never contacted a server before installation.

Setting Up MQTT

Valetudo publishes its state — map data, entity states, cleaning status — over MQTT. To integrate with Home Assistant, you need an MQTT broker the vacuum can reach.

With Home Assistant OS: install and configure the Mosquitto broker app (called an add-on in older releases). Use a dedicated MQTT account.

If you’re running Home Assistant Container or Core: Run Mosquitto as a Docker container or system service. The configuration is the same; just ensure the broker is reachable from the vacuum’s IP on port 1883.

Configuring Valetudo MQTT:

In the Valetudo web UI, go to Connectivity → MQTT Connectivity:

• Broker hostname: IP address of your MQTT broker (your HA host, typically)
• Port: 1883 (or 8883 for TLS — configure certificates separately)
• Username / Password: match what you set in Mosquitto
• Identifier: a short, unique string — this becomes the MQTT topic prefix (e.g., kitchen_vacuum)
• Enable Home Assistant Autodiscovery: toggle this on

Save and apply. Valetudo connects to the broker and begins publishing. If autodiscovery is enabled, it publishes discovery payloads to homeassistant/... topics, which HA picks up automatically.

Test the connection from Valetudo’s UI — it should show “Connected” under the MQTT status. If it shows an error, verify the broker IP, credentials, and that port 1883 isn’t firewalled between the vacuum’s VLAN and your HA host.

Home Assistant Integration

With MQTT autodiscovery enabled in Valetudo, Home Assistant creates entities automatically — no YAML configuration required. Within a minute of the vacuum connecting to MQTT, you should see a new device in HA under Settings → Devices & Services → MQTT.

Typical entities that appear:

• vacuum.<name> — the main vacuum entity with start, stop, pause, return-to-dock controls
• sensor.<name>_status — cleaning status (idle, cleaning, returning, docked, error)
• sensor.<name>_battery_level — battery percentage
• Map and segment-related entities depend on the capabilities exposed by your robot and Valetudo version
• Various sensor entities for consumable life (brush, filter, mop)

Use the discovered vacuum entity for basic controls. This example starts cleaning; call vacuum.return_to_base separately when you want it to dock. Replace the entity ID with yours.

service: vacuum.start
target:
  entity_id: vacuum.kitchen_vacuum

Use the Valetudo interface to select rooms and obtain the correct payload for a room-cleaning command. Do not assume a map_segments sensor exists on every setup.

Advanced: Room-by-Room Cleaning via MQTT

Room-specific cleaning uses Valetudo’s segment cleaning capability. Each room Valetudo has identified gets a numeric segment ID. You pass those IDs via MQTT publish to tell the vacuum which rooms to clean.

Finding your segment IDs:

Select the intended rooms in Valetudo, then long-press the button that starts the action to obtain its MQTT payload. Check the base topic in MQTT Connectivity and the capability topic in the HA integration guide.

Example HA script for cleaning specific rooms:

alias: "Vacuum: Clean Kitchen and Living Room"
sequence:
  - service: mqtt.publish
    data:
      topic: "valetudo/YOUR_IDENTIFIER/MapSegmentationCapability/clean/set"
      payload: >
        {
          "action": "start_segment_action",
          "segment_ids": ["16", "18"],
          "iterations": 1,
          "customOrder": false
        }

Replace YOUR_IDENTIFIER, the base topic if changed, and the example room IDs with the values generated by your robot. Test the command for one room first.

The iterations key sets how many cleaning passes per room. customOrder: true cleans in the order listed; false lets Valetudo optimize the path.

You can then use that command in a schedule or another HA routine. Check that the selected rooms are still correct after changing the map.

Displaying the Live Map: Lovelace Valetudo Map Card

The Valetudo Map Card renders the map in a HA dashboard. Follow its current installation instructions; it is a custom card rather than part of HA’s basic vacuum controls.

Installing via HACS:

1. In HA, go to HACS → Frontend.
2. Search for “Valetudo Map Card”.
3. Install and reload the browser.

Card configuration: the card’s vacuum field uses its MQTT/system identifier, not vacuum.kitchen_vacuum. The project’s map walkthrough shows where to find it. Prefer the card editor if unsure.

type: custom:valetudo-map-card
vacuum: valetudo_YOUR_SYSTEM_ID
show_segments: true

The card renders the live map as the vacuum cleans — you see it move in real time, with room labels overlaid. Virtual restrictions (no-go zones and virtual walls) you configure in Valetudo’s web UI appear here too.

If the map is blank, check the card identifier, MQTT connection, and discovered map camera. Compare with the map in Valetudo before changing the dashboard configuration.

Keeping It Local: Network Isolation

Use a per-device WAN block if you want to enforce local networking. Valetudo’s cloud-replacement role is separate from verifying every connection on your own installation.

Practical approach:

Put the vacuum on a dedicated IoT VLAN or Wi-Fi SSID that has no outbound internet access. Configure your firewall to allow:

• Inbound from HA host to vacuum IP on port 80 (Valetudo web UI, optional once setup is complete)
• Inbound/outbound between vacuum and MQTT broker on port 1883

Keep the local web and MQTT connections available, plus any required local network services. Test cleaning, docking, room commands, and map updates with WAN access denied, including after a restart.

If you have other Xiaomi devices on your network — Zigbee sensors, switches, or cameras — see our guide on integrating Xiaomi Zigbee devices into Home Assistant via Zigbee2MQTT for the same local-first approach applied to the rest of your Xiaomi stack.

The Result

With the supported installation and local MQTT connection working, HA can control the vacuum without the vendor app. Keep recovery files, check maps and room IDs after updates, and repeat the offline test after network changes.