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

Your robot vacuum cleans your floors, but by default it also reports home — to servers you don’t control, in a jurisdiction you may not be comfortable with. Xiaomi and Roborock vacuums running stock firmware maintain persistent cloud connections. Map data, room layouts, cleaning schedules, usage telemetry, and even audio commands pass through cloud infrastructure before any of it reaches your phone. If the cloud goes down, the app stops working. If Xiaomi changes its terms, you update or lose functionality.

Valetudo changes the equation. It’s an open-source firmware replacement that runs entirely on the vacuum itself — no cloud, no account, no external dependency. You get a local web UI, MQTT integration, and full Home Assistant control including live map rendering. The trade-off is a one-way flash: once you’re on Valetudo, Xiaomi’s OTA updater is disabled. You can’t accidentally push stock firmware back via the Mi Home app. The upside is the same: the vacuum stops calling home permanently.

This guide covers the full setup flow: choosing a compatible model, generating firmware with Dustbuilder, flashing it with the XVacuum app, configuring MQTT, setting up Home Assistant autodiscovery, and rendering the live map in Lovelace — without contacting Xiaomi’s servers once.

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

What the Stock Firmware Actually Sends

Before swapping firmware, here’s what you’re removing access to.

Xiaomi vacuum stock firmware communicates with cloud endpoints on startup, after each cleaning session, and intermittently during operation. Cleaning maps (including your floor plan) are uploaded to Xiaomi’s servers, where room segmentation is computed server-side before results are returned to the Mi Home app. Usage telemetry includes session timestamps, cleaned area, error codes, and firmware version. The Mi Home app routes commands through the cloud even on a local network — if Xiaomi’s servers are unreachable, you lose remote and often local control.

This isn’t unique to Xiaomi. Most mainstream robot vacuums work this way. The concern isn’t necessarily malicious intent — it’s data custody, dependency risk, and the fact that a company in another regulatory environment holds a floor plan of your home.

Valetudo eliminates all of that. It serves everything from the device itself: map generation, room segmentation, controls, schedules. No traffic leaves your network unless you explicitly configure it to (for example, MQTT to a broker on your local server).

Compatible Models in 2025

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.

Here’s a representative compatibility snapshot for software-rootable models as of mid-2025:

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.

One important note: Valetudo does not support all firmware versions of a given model. The Dustbuilder tool (covered next) handles version management, but confirm your vacuum’s current firmware version before generating an image. If the vacuum ran a recent OTA update, it may have patched the root vector.

Generating Your Firmware with Dustbuilder

Dustbuilder is the web tool that packages Valetudo into a flashable firmware image for your specific model. It’s hosted at dustbuilder.dontvacuum.me and was actively maintained with new model support through at least early 2025.

The process is straightforward:

• Navigate to the Dustbuilder site.
• Select your vacuum model from the dropdown. If your model isn’t listed, it isn’t currently supported — stop here.
• Select the Valetudo version. Unless you have a reason to pin an older release, use the latest stable.
• Enable the SSH option. This is critical. SSH gives you a recovery path if something goes wrong post-flash. Skipping it means you have no fallback short of hardware disassembly if Valetudo misbehaves.
• Review the options — most defaults are fine for a first install.
• Click Generate. Dustbuilder queues a build job; this typically takes a few minutes.
• Download the resulting .pkg file when the build completes.

Keep the .pkg file. You’ll need it in the next step, and it’s your recovery artifact if you ever need to re-flash.

Flashing with the XVacuum App

XVacuum is the app used to push the custom firmware to your vacuum over its local Wi-Fi access point. It supports Android (4.4+) and iOS (9.0+), though the Android version is more widely used and documented for this workflow.

Prerequisites:

• Your vacuum at factory state or a known-compatible firmware version
• The .pkg generated by Dustbuilder
• An Android or iOS device able to connect to the vacuum’s AP
• The vacuum’s device token — a 32-character hex string you’ll retrieve from the vacuum’s AP

Steps:

• Put the vacuum into pairing/AP mode. On most models, hold the home button for several seconds until the indicator light signals AP mode. The vacuum broadcasts an SSID in the format rockrobo-XXXX or similar.
• Connect your device to the vacuum’s AP. Do not connect to your home network yet.
• Open XVacuum. It should detect the vacuum on the local AP.
• Retrieve the device token via XVacuum’s built-in token reader. Save this token — it’s required for the flash and for initial Valetudo configuration.
• Select “Flash firmware” and point it at the .pkg file you downloaded from Dustbuilder.
• Initiate the flash. The process typically takes 5–10 minutes. Do not interrupt power to the vacuum during this process. A power interruption mid-flash can render the device unbootable without hardware recovery.
• The vacuum will reboot when flashing completes. A successful flash ends with the vacuum broadcasting its AP again, now running Valetudo.

If the app cannot detect the vacuum or the flash fails immediately, confirm you’re connected to the vacuum’s AP, not your home router. This is the most common mistake.

First Boot: Valetudo Web UI

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

Open a browser and navigate to 192.168.8.1 — the default Valetudo web UI address across supported models.

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

• Go to Connectivity → Wi-Fi and configure your home network credentials. The vacuum will connect to your LAN and drop the AP.
• 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).
• Set a friendly name under Settings → Robot. This name propagates into Home Assistant entity labels via MQTT autodiscovery.
• 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.

At this point, Valetudo is running locally on your vacuum. Nothing has contacted Xiaomi. You can control the vacuum, view the map, and set schedules entirely from the Valetudo UI. The MQTT and Home Assistant steps are additive.

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.

If you’re using Home Assistant OS or Supervised: The Mosquitto broker add-on is the simplest path. Install it from the Add-on Store (Settings → Add-ons → Mosquitto broker), configure a username and password, and start it. It listens on port 1883 by default.

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. — the main vacuum entity with start, stop, pause, return-to-dock controls
• sensor._status — cleaning status (idle, cleaning, returning, docked, error)
• sensor._battery_level — battery percentage
• sensor._map_segments — JSON attribute listing segment (room) IDs and names
• Various sensor entities for consumable life (brush, filter, mop)

The vacuum. entity works with HA’s built-in vacuum card and services. Basic controls work immediately:

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

service: vacuum.return_to_base
target:
  entity_id: vacuum.kitchen_vacuum

The map segment data lives as an attribute on sensor._map_segments and is what you’ll need for room-by-room cleaning.

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:

In the Valetudo web UI, go to the Map view. Named rooms appear with their labels. The segment IDs are the numeric identifiers Valetudo assigned internally — visible in the map management screen, or by checking the map_segments attribute in HA Developer Tools under your vacuum’s sensor entity.

Example HA script for cleaning specific rooms:

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

Replace with the identifier string you set in Valetudo’s MQTT config. Replace 16 and 18 with your actual segment IDs.

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

This approach gives you proper room-level automations — trigger a kitchen clean after cooking, schedule the bedroom only on weekday mornings — without any cloud dependency.

Displaying the Live Map: Lovelace Valetudo Map Card

The built-in HA vacuum card doesn’t render Valetudo’s live map. For that, you need the Valetudo Map Card (also called lovelace-valetudo-map-card), a community card available through HACS. As of 2025, it has not been merged into HA core and remains a HACS-only install.

Installing via HACS:

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

Basic card configuration:

type: custom:valetudo-map-card
vacuum: vacuum.kitchen_vacuum
rotate: 0
crop:
  top: 0
  bottom: 0
  left: 0
  right: 0
show_virtual_restrictions: true
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 card shows but the map is blank or outdated, confirm that Valetudo is publishing map data via MQTT. In Valetudo’s MQTT settings, ensure “Map” is included in the published data sets.

Keeping It Local: Network Isolation

Valetudo eliminates the cloud dependency at the firmware level — the vacuum no longer has code that initiates cloud connections. But for users who want belt-and-suspenders assurance, adding network-level blocks removes any residual concern.

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

Block all other outbound traffic from the vacuum’s IP. If you’ve already flashed Valetudo, nothing breaks. Valetudo doesn’t attempt to contact external servers. Your HA integration, room cleaning, map rendering, and schedules all continue to work.

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

After this setup: the vacuum operates entirely from your local network, controlled by Home Assistant, with no Xiaomi account required. The floor plan of your home stays on your server.