Integration of the robot vacuum cleaner Xiaomi in Home Assistant: from token to automation

The Xiaomi and Roborock robot vacuum cleaners have long been an integral part of the smart home ecosystem, but their true potential is only revealed when integrated with Home Assistant. Unlike the standard Mi Home app, where functionality is limited to basic commands, connecting to the home is a must-have. HA allows you to create complex automation: cleaning according to a schedule taking into account motion sensors, zoning the rooms by time of day or even synchronization with other devices (for example, starting a vacuum cleaner after closing windows).

However, the integration process often raises questions: where to get a token for authorization, how to set up a map display in real time, or why the vacuum cleaner does not respond to commands through a computer. HA? This article covers all the steps from device preparation to fine-tuning, including solving typical problems.We will look at both the official methods through Xiaomi Miio, and alternative ways for older models where standard integration does not work.

1.Preparation: compatibility check and requirements

Before you start setting up, make sure your vacuum cleaner model is supported by Home Assistant. Xiaomi/Roborock release 2018 Compatible years, but there are exceptions:

• ✅ Supported by: Roborock S5/S6/S7/S8, Xiaomi Mi Robot Vacuum 1S/2/Pro, Dreame D9/F9 newer.
• ⚠️ Limited support: Xiaomi Mi Robot Vacuum 1 (first generation) – requires manual token acquisition.
• ❌ Not supported: some OEM-models for the Chinese market (for example, Viomi without global firmware).

Also check the version of the vacuum cleaner firmware: for correct operation with the HA It is recommended to update it to the latest through the official Mi Home or Roborock app. S5) may not support API-team.

Requirements for Home Assistant:

• ⚡ Version. HA 2023.12 or later (for full Miio Protocol support) v2).
• 🌐 Stable connection of vacuum cleaner and server HA to one network (Wi-Fi 2.4 GHz).
• 🔑 Xiaomi account with tied vacuum cleaner (to automatically receive token).

⚠️ Note: If the vacuum cleaner is connected to the network via 5 GHz, transfer it to 2.4 GHz – many models do not support dual-band Wi-Fi when integrating with the network. HA.

2. Obtaining an authorization token

The token is a unique key that allows Home Assistant to send commands to the vacuum cleaner, and there are two ways to get it:

Method 1: Automatically Received via Mi Home (recommended)

If your model supports automatic integration (see table above), follow the following steps:

1. Install the official Mi Home app (or Roborock for the respective models).
2. Log in to the account to which the vacuum cleaner is attached.
3. In Home Assistant, go to Settings → Devices and services → Add integration → Xiaomi Miio.
4. Select the server region (China, Europe or Russia – depending on the version of the application).
5. Enter the username and password from the Xiaomi account — HA automatically receive the token.

Advantage: it does not require manual manipulation of configuration files, disadvantage: if you change the password in the Xiaomi account, the token will reset, and the integration will have to be configured again.

Method 2: Manual token extraction (for older models)

If the automatic method does not work (for example, for Mi Robot Vacuum 1), use this method:

Install the Packet Capture (Android) app or HTTP Toolkit (PC)

Connect your phone/PC to the same network as the vacuum cleaner

Log in to Mi Home and start capturing traffic

Find a request to api.io.mi.com with the token option

-->

Detailed instructions:

1. Download MiHome Token Extractor (for Android) or use it Fiddler/Wireshark PC-only.
2. Start capturing traffic and open the Mi Home app.
3. Find in the logs a request to the domain api.io.mi.com with the method POST and the "token" parameter": "...".
4. Copy the value of the token (32 characters) – this is your key.

⚠️ Warning: Don't share the token with third parties! it gives full access to vacuum control. If the token has fallen into the wrong hands, dump it through the Mi Home app (lodge and log in again).

Automatically through HA

Manually by Capturing Traffic

I haven't tried it yet.

Another option-->

3. Set up integration in Home Assistant

After receiving the token, add the vacuum cleaner to HA:

1. Open configuration.yaml (via File Editor or en route) /config/configuration.yaml).
2. Add the following block (replace). IP_ADRES and YOUR TOKEN for real values: vacuum: - platform: xiaomi_miio host: IP_Address token: Your Token Name: "Robot vacuum cleaner Xiaomi"
3. Save the file and reboot the Home Assistant.

If you use YAML-Mod, after restarting, the vacuum cleaner will appear in the Devices section. UI-Mod (without editing configuration.yaml):

1. Go to Settings → Devices and Services → Add Integration.
2. Choose Xiaomi Miio.
3. Enter. IP-vacuum cleaner address and token, then click Send.

Connection Check: After adding, open the Developers tab → Conditions and find the essence vacuum.xiaomi_vacuum. If it displays status (idle, cleaning, etc.), the integration has been successful.

💡

If the vacuum cleaner doesn't respond to commands, check if your router blocks local traffic between devices. IP-vacuum address except for firewall.

4. Advanced settings: maps, zones and automation

Basic integration allows you to send commands (start, pause, return_to_base). To unlock your full potential, set up:

Displaying the map in real time

For models with mapping support (Roborock) S6/S7, Dreame D10 etc.):

1. Install the Xiaomi Miio Map expansion through HACS (Home Assistant Community Store).
2. Add to configuration.yaml: xiaomi_miio_map: vacuums: - host: IP_ADRES TOKEN: Your Token name: "xiaomi_vacuum" draw: ['all'] attributes: - calibration_points
3. Reboot. HA and add a map to the dashboard via the Picture Entity widget, specifying the essence camera.xiaomi_vacuum_map.

Maps are updated with a delay 2-5 If the card is not displayed, check if the option "Save card" is enabled in the vacuum cleaner settings (via the official app).

Set-up of cleaning areas

To start cleaning in specific areas (e.g., only in the kitchen):

1. In the official Mi Home or Roborock app, create virtual walls and zones.
2. Export zone coordinates through Developer Tools → Services in HA, call-up xiaomi_miio.vacuum_clean_zone.
3. Save the coordinates to script or automation. Example of a zone cleaning command: service: xiaomi_miio.vacuum_clean_zone data: entity_id: vacuum.xiaomi_vacuum zone: [[25000, 25000, 30000, 30000]] # Coordinators: [x1, y1, x2, y2] repeats: 2

Examples of automation

• 🕒 Scheduled cleaning: Start vacuum cleaner at 10:00 if no one is home (presence sensor).
• 🚪 Synchronization with windows: when closing the last window (sensor) binary_sensor.window) clean-up.
• 🐕 Pets mode: if the motion sensor in the corridor works more often 5 times per hour, the vacuum cleaner removes only the area near the bowl.

5. Solving typical problems

Even with the right setup, you can get errors, and here are the most common ways to fix them:

If the vacuum cleaner is disconnected from Wi-Fi:

• Check the strength of the router signal at the docking station location (should be ≥ -60 dBm).
• Set up static. IP for the router vacuum cleaner (by MAC-address).
• Turn off the energy-saving Wi-Fi mode on the vacuum cleaner (some firmware has it).

⚠️ Note: If after updating the vacuum cleaner firmware, it stopped responding to commands through HA, Reset the token and reset the integration. The manufacturer sometimes changes the authorization protocol.

6. Alternative methods of integration

If the Xiaomi Miio standard integration doesn’t work, consider alternatives:

1.Valetudo firmware

Valetudo is an open alternative to standard firmware that provides full local control over the vacuum cleaner without the Xiaomi cloud.

Advantages:

• 🔒 No dependence on Xiaomi servers (works even when the Internet is disconnected).
• 🗺️ Support for extended maps and zones.
• 🛠️ Possibility of installing custom scripts.

Disadvantages: requires manual stitching (risk of losing warranty), not all models are supported.

Installation instructions:

1. Download Valetudo from the official website.
2. Connect to the vacuum cleaner SSH (The instructions for each model are different).
3. Download the firmware via scp or web interface.
4. Set up integration with HA through REST API or MQTT.

2. Integration through MQTT

If your vacuum cleaner supports MQTT (For example, through Valetudo or custom firmware, set up messaging:

1. Install. MQTT-broker (e.g. Mosquitto) in HA.
2. In the vacuum cleaner configuration, specify the broker’s address and topics for teams (vacuum/command) and (vacuum/state).
3. Create automation in HA, posting.

Example of a team to start cleaning through MQTT:

topic: vacuum/command


payload: '{"command": "start"}'

3. Cloud Bridge (for remote access)

If you need to control the vacuum cleaner from the outside of the home network:

• Configure Nabu Casa Cloud or DuckDNS for remote access HA.
• Use a Telegram bot or Google Assistant to send commands.

💡

Alternative methods are suitable for power users. If you're a beginner, start with the standard Xiaomi Miio integration.

7. Optimization and Operational Tips

To make the vacuum cleaner work more efficiently:

• 📡 Docking station: install it in the center of the apartment, at least 0.5 m from the walls and furniture. Avoid places with direct sunlight (the sensor may overheat).
• 🔋 Battery care: If the vacuum cleaner is not used for more than a week, remove the battery or store it with a charge 40-60%.
• 🧹 Clean sensors: wipe optical sensors every month (especially on models with a high-performance sensor). LDS-lidar) cotton swab soaked in alcohol.
• 📱 Updates HA: After updating Home Assistant, check the compatibility of Xiaomi Miio integration in the official repository.

Automation tip: To reduce vacuum cleaner wear, set up the condition to start cleaning only at the battery level > 50 percent, an example of an automation condition:

condition:


- condition: numeric_state




entity_id: sensor.xiaomi_vacuum_battery




above: 50

For models with support for wet cleaning (Roborock) S7, Dreame W10):

• Use distilled water to extend the life of the pump.
• After each cleaning, wash the water tank and wipe the fabric nozzle.
• In automation, add delay: "00:02:00" between dry and wet cleaning - this will reduce the load on the engine.

FAQ: Frequent questions