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

Xiaomi’s 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, Home Assistant allows you to create complex automations: running a scheduled cleaning service based on your location, binding to humidity sensors, or even voice control through Alice or Google Assistant.

However, the connection process often raises questions: where to get a token, why the vacuum cleaner does not appear in the interface, how to circumvent regional restrictions Mi Home? In this guide, we’ll break down all the current integration methods (including bypassing cloud constraints through a local protocol), analyze common bugs, and show you how to make the most of your Mi Robot Vacuum, Viomi, or Dreame in the Home Assistant ecosystem. We will pay special attention to models with support LDS-Laser (e.g. Xiaomi Mi Robot Vacuum-Mop 2 Pro) where advanced zoning and mapping features are available.

1.Preparation: What will be needed for integration

Before you start setting up, make sure you have everything you need. The minimum requirements depend on the method of connection you choose (cloud or on-premises), but the basic set is the same for all options:

• 📱 Smartphone with Mi Home app installed (version no lower than 6.0.100) Important: account must be tied to the same region as the vacuum cleaner (usually Mainland China, Europe or Russia).
• 🖥️ Home Assistant Work Server (version 2023.12 or later) will suit both installation on a Raspberry Pi and container in Docker.
• 🔑 Token devices – a unique identifier for accessing API. It can be obtained in several ways (we will discuss below).
• 🌐 A stable Internet connection (for cloud method) or a local area network (for direct connection).

If you use a Xiaomi vacuum cleaner older 2019 Years (e.g. Mi Robot Vacuum) 1S), Check MiIO support in the official Home Assistant documentation. Some budget models (e.g. Viomi) V2) You may need to manually adjust. device_id.

⚠️ Note: Dreame vacuum cleaners (e.g. Dreame) D9) They use a separate DreameVacuum protocol, and they need different integration — dreame_vacuum Home Assistant.

To simplify the process, we recommend in advance:

• 🔄 Update the vacuum cleaner to the latest version through Mi Home.
• 📡 Connect the vacuum cleaner and Home Assistant server to the same local network (preferably over 5 GHz Wi-Fi for stability).
• 📝 Write it down. MAC-vacuum cleaner address (can be found in router settings or in Mi Home in Device section) → Settings → About the device).

2. Obtaining a device token: 3 working methods

Token is the key to access API There are several ways to get it, varying in complexity and reliability, and let's look at it from the simplest to the most technical.

Method 1: Through the Mi Home app (for beginners)

The easiest way, but it doesn't work for all regions, is if your account is linked to Mainland China servers:

1. Open Mi Home and go to the vacuum cleaner settings.
2. Click on three dots in the upper right corner → About the programme.
3. Tap 5-7 times on the firmware version until the Debug menu appears.
4. Select Get Token – the system will generate the token and copy it to the clipboard.

Method 2: Through Python script (universally)

If the first method didn't work, use miio-cli, which is suitable for all regions, but requires minimal command line knowledge.

pip install python-miio


miio discover --handshake 0




miio inspect --ip <IP_ vacuum cleaner> --token < your token account Mi>

Where <IP_vacuumer> — local IP-address of the device, and <Your Token Account Mi> You can get it through this repository (instruction in English).

Method 3: Through HTTP-interception (for experienced)

An alternative method is to intercept the token when logging into Mi Home via Fiddler or Charles Proxy.

⚠️ Note: Tokens obtained through Mi Home Debug can be reset after a firmware update. Use the miio-cli method for reliability.

3. Set up integration in Home Assistant

Once the token is received, we move on to adding a vacuum cleaner to Home Assistant. There are two main approaches: over a cloud bridge (easier, but depends on Xiaomi servers) and through a local connection (more reliable, but requires additional settings).

Method 1: Cloud integration (via Mi Home)

If you don’t want to mess around with the local network, use the official Xiaomi Miio integration:

1. In Home Assistant, go to Settings → Devices and Services → Add Integration.
2. Type in the Xiaomi Miio search and select it.
3. Indicate. IP-vacuum cleaner address, token and select region (e.g. cn for China).
4. Press Submit – the device will appear in the list.

Method 2: Local Connection (recommended)

For stability, it is better to use the local MiIO protocol, which will eliminate dependence on the Xiaomi cloud and speed up the response to commands.

1. Add the following code to the configuration.yaml file: vacuum: - platform: xiaomi_miio host:!secret vacuum_ip token:!secret vacuum_token name: "Xiaomi Vacuum" model: "roborock.vacuum.a10" # Please indicate your model (list below)
2. Add secrets.yaml to the file: vacuum_ip: "192.168.1.100" # Replace it with IP your vacuum cleaner vacuum_token: "your token here"
3. Reboot Home Assistant.

List of popular models for the model parameter:

• roborock.vacuum.s5 — Xiaomi Mi Robot Vacuum-Mop
• viomi.vacuum.v7 — Viomi V7
• dreame.vacuum.p2008 — Dreame D9
• rockrobo.vacuum.v1 — Mi Robot Vacuum 1S

4. Advanced settings: maps, zones and automation

Basic integration allows you to just start and stop cleaning, but the real magic starts when you plug in maps of the space and set up zonal cleaning.

Connecting cards (for models with) LDS)

Laser scanner models (Mi Robot Vacuum-Mop 2 Pro, Dreame) Z10 Pro) support map display in Home Assistant:

1. Install the Xiaomi Miio Map Extractor HACS.
2. Add to configuration.yaml: camera: - platform: xiaomi_miio_map host:!secret vacuum_ip token:!secret vacuum_token name: "Vacuum Map" draw: ["charger", "path", "robot", "zones"] attributes: - calibrated - cleaning
3. After the reboot, a map with the current location of the vacuum cleaner will appear in the Media section.

Configuring zones and virtual walls

To clean only certain rooms, use zoned cleanup. Example of a kitchen cleaning command (coordinates taken from the map):

service: vacuum.send_command


target:




entity_id: vacuum.xiaomi_vacuum




data:




command: app_zoned_clean




params: [[25000, 25000, 30000, 30000, 2]] # [x1, y1, x2, y2, repetitions]

To create virtual walls (for example, so that the vacuum cleaner does not come into the nursery), use the parameter. app_segment_clean zone-identified.

💡

If the map is not displayed, check that the vacuum cleaner is on base and not in cleaning mode. Also make sure that the Mi Home settings enable the Send Card Data setting (in some firmware it is disabled by default).

5. Typical errors and their solutions

Even if you follow the instructions accurately, you can have problems, and we'll look at some of the most common mistakes and how to fix them.

If you see a Device error not found, but IP And the token is right, try it:

• 🔄 Reboot the vacuum cleaner (hold the power button for 5 seconds).
• 📡 Reconnect it to Wi-Fi.
• 🔧 Temporarily disable the firewall on the router.

⚠️ Note: Xiaomi vacuum cleaners with firmware more recent than 2023 can block local connections if the Mi Home does not turn on developer mode. → Settings → Developer mode.

Automation: Examples of Useful Scenarios

Now that the vacuum cleaner is connected, you can create automations that will save you time. Here are some ready-made examples for automations.yaml:

Automatic cleaning on schedule

Start cleaning every day at 10:00 am if no one is home:

alias: "Schedule cleaning"


trigger:




- platform: time




at: "10:00:00"




condition:




- condition: state




entity_id: person.your_name




state: "not_home"




action:




- service: vacuum.start




target:




entity_id: vacuum.xiaomi_vacuum

Cleaning at high concentration of dust

If you have an air quality sensor (such as Xiaomi Air Purifier), you can run the vacuum cleaner when you exceed it. PM2.5:

alias: "Prevention of pollution"


trigger:




- platform: numeric_state




entity_id: sensor.air_quality_pm25




above: 50




action:




- service: vacuum.start




target:




entity_id: vacuum.xiaomi_vacuum




- delay: "00:30:00" # Cleaning 30 minutes




- service: vacuum.return_to_base




target:




entity_id: vacuum.xiaomi_vacuum

Voice control through Alice

To control the voice vacuum cleaner, integrate Home Assistant with Yandex Alice via Yandex Smart Home:

1. In configuration.yaml add: yandex_smart_home: filter: include_entities: - vacuum.xiaomi_vacuum exclude_domains: - script
2. In the Yandex app, add Home Assistant as a control device.
3. Now you can say, "Alice, turn on the vacuum cleaner" or "Alice, put the vacuum back on base."

💡

For reliable operation of automation always check the conditions, for example, do not start cleaning if the vacuum cleaner is already working or the charge level is below 20%.

7. Optimization and Operational Tips

To ensure that the vacuum cleaner works stably and lasts longer, follow these recommendations:

• 🔋 Charging: Do not keep the vacuum cleaner permanently on base. The optimal is to charge up to 80% and discharge up to 20% (this prolongs the life of the battery). In Home Assistant, you can set up automation that will turn the vacuum cleaner off the base after reaching 80%:

alias: "Charge limitation"


trigger:




- platform: numeric_state




entity_id: sensor.xiaomi_vacuum_battery




above: 80




action:




- service: vacuum.return_to_base




target:




entity_id: vacuum.xiaomi_vacuum

• 📡 Wi-Fi: Xiaomi vacuum cleaners don't work well with 5GHz networks. If you have a dual-band router, tie the vacuum cleaner to the 2.4GHz network manually.
• 🗺️ Maps: Periodically (every 1-2 months) reset the map in the vacuum cleaner settings and retrain the vacuum cleaner.
• 🛠️ Maintenance: Clean sensors and brushes at least 1 time per week. clogged sensors lead to chaotic cleaning.

Critical feature of models with laser navigator (LDS): Do not use them in direct sunlight. The laser sensor can malfunction, and the vacuum cleaner will go blind".

FAQ: Answers to Frequent Questions