How to add Xiaomi devices to Home Assistant: 3 working ways + mistake-making

Why Xiaomi and Home Assistant are the perfect pair for a smart home

Xiaomi’s ecosystem offers some of the most affordable and functional smart home devices, from door-opening sensors to robot vacuum cleaners. But the standard Mi Home app limits automation by connecting users to the cloud and a closed ecosystem. Here comes Home Assistant, an open platform that allows all devices to be integrated into a single system with flexible scenarios, local management and protection from cloud failures.

In this article, you will learn how to integrate Xiaomi devices (including the Aqara, Mijia, Yeelight brands) into Home Assistant in three ways: through the official plugin, Mi Home Token, and the protocol. MQTT. We'll take a look at the nuances for different types of devices, the typical bugs, and we'll give you some tips on how to optimize your system. If you're just starting out with Home Assistant, don't worry, the instructions are tailored for users of all levels.

Before you start, make sure you have:

• 📱 Home Assistant installed (version 2023.12 or later) Suitable as Home Assistant OS on the Raspberry Pi and the container version on the NAS.
• 🔌 Xiaomi devices are connected to the Mi Home app and work stably.
• 🌐 Access to the local network (all devices must be on the same subnet as the Home Assistant server).

Method 1: Official integration via Mi Home (the easiest method)

The most reliable and recommended way is to use the official Xiaomi Miio integration, which supports most Xiaomi, Aqara and Mijia devices, which works through the local Miio protocol, does not require cloud servers and provides minimal latency.

To add integration:

1. Enter. IP-the address of the device (how to find it – read below) and the token (receiving the token will be discussed in the next section).

How do you know? IP-address:

• 🔍 If IP not visible, use a network scanner (e.g. Fing or Advanced) IP Scanner) and look for devices called lumi., miio. or yeelink.

Make sure the device is on and connected to Wi-Fi|Check the firmware version (some older versions are not supported)|Turn it off. VPN/Proxies on the Home Assistant server|Add the device to your favorites in Mi Home (sometimes helps with errors)

-->

Limitations of the method:

• ❌ Not all devices are officially supported (e.g. some Xiaomi cameras require separate integrations).
• ❌ Robot vacuum cleaners (such as Mi Robot Vacuum) may require additional valetudo tuning.
• ❌ If the device is used BLE (For example, Aqara sensors, you will need a Bluetooth proxy (say below).

Method 2: Getting Mi Home Token (for devices without official support)

If your device is not supported by official integration, or if you want to use it MQTT For more flexible settings, you need a Mi Home Token, a unique key that allows Home Assistant to interact directly with your device.

There are two ways to get a token:

Method 1: Using the Mi Home (Android) app

This will require:

• 📱 Android smartphone with Mi Home installed (version 6.0.100 or older).
• 💻 Computer with ADB (Android Debug Bridge).
• 🔗 Mihome-bin utility for token extraction.

Step-by-step:

1. Enable Developer Mode on Android: Go to Settings → The phone. → Build number and press 7 times.
2. Go back to Settings → System → For developers and enable USB debugging.
3. Connect your phone to your computer and execute the command: adb backup -f mihome.ab -noapk com.xiaomi.smarthome Confirm the creation of a backup copy on the phone (do not set a password!).
4. Use the mihome-bin utility to extract the token: java -jar mihome-bin.jar mihome.ab As a result, you will receive a file mihome.db with tokens of all your devices.

Method 2: Through a packet sniffer (for iOS or without) ADB)

If you have an iPhone or you can’t use it. ADB, You can intercept the token through network traffic analysis:

• 📡 Install Wireshark or Fiddler on your computer.
• 🔍 Set up a proxy on your phone (manually or through Charles Proxy).
• 📱 Open Mi Home and update device data (e.g., turn on/off the lamp).
• 🔎 In the sniffer, look for queries to the domain api.io.mi.com - the token will be in the Authorization header.

1.Reboot the Xiaomi device (remove the battery for 10 seconds for sensors).

2. Make sure that your device is linked to the same region (China/Europe/Russia) as your account.

3. Update the firmware of the device to the latest version.

-->

The token is valid until you reset the device or change the password in Mi Home. Store it in a safe place (for example, in the password manager).

Method 3: Connecting through MQTT (power-user)

Protocol MQTT It allows you to exchange data between Xiaomi and Home Assistant devices through a broker (for example, Mosquitto:

• 🔄 You want to reduce the load on Home Assistant (devices send data directly to the broker).
• 🌐 You have a distributed system with multiple servers.
• 🛠️ You need custom topics and data format.

The setup will require:

1. Install MQTT-Broker (for example, through Mosquitto add-on in Home Assistant).
2. Set up Xiaomi device to send data to MQTT (This is often done using Tasmota or ESPHome firmware for devices on the ESP8266/ESP32).
3. Add integration MQTT Home Assistant and set up subscriptions for topics.

Example configuration for the Aqara temperature sensor in configuration.yaml:

mqtt:


sensor:




- name:"Aqara Temperature"




state_topic:"home/sensor/aqara/temperature"




unit_of_measurement:"°C"




value_template:"{{ value_json.temperature }}"




- name:"Aqara Humidity"




state_topic:"home/sensor/aqara/humidity"




unit_of_measurement:"%"




value_template:"{{ value_json.humidity }}"

For devices that do not support MQTT"out of the box (e.g., Yeelight lamps), you can use a Python intermediate script with a python-miio library that will redirect data from Miio to the python-miio. MQTT.

💡

MQTT It is suitable for power users, but gives maximum flexibility. For most tasks, official integration of Xiaomi Miio is enough.

Connection BLE-Devices (Aqara, Mi Band, etc.)

Many Xiaomi and Aqara devices (e.g. door opening sensors, thermometers, Mi Band bracelets) use Bluetooth Low Energy protocol (BLE). To integrate them into Home Assistant, you will need a Bluetooth proxy – a device that will scan the airwaves and transmit data to the server.

Implementation options:

To set up ESP32 ESPHome:

1. Install ESPHome addon in Home Assistant.
2. Create a new configuration for ESP32 component esp32_ble_tracker.
3. Add devices to the scan list: esp32_ble_tracker: scan_parameters: interval: 300ms window: 30ms active: true sensor: - platform: xiaomi_lywsd03mmc mac_address:"XX:XX:XX:XX:XX:XX" temperature: name:"Temperature" humidity: name:"Humidity" battery_level: name:"Battery"
4. Download the firmware to ESP32 And place it next to the sensors.

💡

To increase the range of action BLE Use an external antenna (for example, ESP32 moduled ESP-WROOM-32 antennae IPEX).

Solving Common Mistakes When Connecting Xiaomi to Home Assistant

Even if you follow the instructions accurately, you can get errors, and let's look at the most common ones and how to fix them.

Error: "Cannot connect to device"

Causes and solutions:

• 🔌 Device offline: Check that the device is on and connected to the same Wi-Fi as the Home Assistant server.For battery-powered sensors, make sure the charge is not discharged.
• 🔒 Wrong token: Make sure the token is copied in full (no spaces.
• 🌍 Regional restrictions: Some devices (like Aqara) require tethering to servers in China.In Mi Home, change region to Mainland China (but note that this can reset all devices!).
• 🔄 Outdated firmware: Update the device's firmware through Mi Home.Outd-of-the-box vacuum cleaners may need to manually upgrade through Mi Home Token.

Error: "Unsupported device"

If the device is not supported by official integration:

• 🔍 Check the list of supported devices in the documentation.
• 🛠️ Use it. MQTT or custom components (e.g, xiaomi_ble for BLE-device).
• 📦 For robot vacuum cleaners, install Valetudo (alternative open-source firmware) API).

Error: "Timeout while connecting"

It's caused by slow response.

• ⚡ Check the quality of Wi-Fi (Xiaomi devices do not work well at 5 GHz – use 2.4 GHz).
• 📡 Reduce the distance between the device and the router.
• ⏳ Increase timeout in the Home Assistant configuration: xiaomi_miio: devices: 192.168.1.100: token: YOUR_TOKEN timeout: 15

Optimizing the work of Xiaomi devices in Home Assistant

Once the devices are successfully connected, you should configure them for maximum efficiency. Here are some recommendations:

1. Set up a device survey

By default, Home Assistant polls devices every 30 seconds, which can put a strain on the network.

• 🌡️ Temperature/humidity sensors: it is enough to interrogate once in a while 5-10 minute.
• 💡 Lamps and sockets: 30 seconds left (for quick response).
• 🚪 Opening Sensors: Use binary_sensor with event trigger (does not require a constant survey).

Example of configuration in configuration.yaml:

xiaomi_miio:


devices:




192.168.1.100:




token: YOUR_TOKEN




scan_interval: 300 # 5 minutes

2.Local management vs. cloud

Use local management (via Miio or if possible) BLE), where:

• ⚡ Reduce delays (commands are executed instantly).
• 🔒 Eliminate dependence on Xiaomi servers (relevant in case of problems with the Internet).
• 🛡️ Increase privacy (data does not go to the cloud).

Exception: Xiaomi cameras (such as Mi Home Security Camera) often require cloud connectivity through Xiaomi Camera or FFmpeg integration.

3. Automation with Xiaomi devices

Examples of useful automation:

• 🌅 Smart lighting: Turn on Yeelight lamps at sunset (use sun.sun trigger).
• 🚪 Security: Notification in Telegram when the door opening sensor is triggered.
• 🌡️ Climate control: Mi Air Conditioning at temperatures above 25°C.
• 🤖 Cleaning on schedule: launch of the robot vacuum cleaner Mi Robot Vacuum on weekdays at 10:00.

Example of automation for a motion sensor:

automation:


- alias: "Switch on the lights while driving"




trigger:




platform: state




entity_id: binary_sensor.motion_sensor_158d000xxxxxx




to:"on"




condition:




- condition: sun




after: sunset




before: sunrise




action:




service: light.turn_on




target:




entity_id: light.yeelight_color1




data:




brightness: 255




color_temp: 400

FAQ: Frequent questions about Xiaomi and Home Assistant integration