How to Add Xiaomi Devices to Home Assistant: A Complete Guide with Examples

Integrating Xiaomi devices with the Home Assistant platform opens up new possibilities for smart home automation, but often faces technical nuances. Despite the brand’s popularity, many users are lost in configuration.yaml settings, obtaining tokens or solving connection problems. This article will help you understand all the stages from preparing a Mi Home account to fine-tuning sensors and relays in the Home Assistant interface.

Xiaomi devices (including the Aqara sub-brand) are characterized by their closed ecosystem, which requires workarounds to integrate with third-party systems. We will look at two main methods: official through Mi Home Integration (with limitations) and alternative through Mi Home Token Extractor (with full control).

1.Preparation: What to Know Before Connecting

Before you start integration, make sure your system meets the minimum requirements:

• 📱 Home Assistant version at least 2023.12 (recommended 2026.4)+ Full compatibility with Xiaomi)
• 🌐 Mi Home account with associated devices (region should coincide with the region of purchase of devices!)
• 🔧 Access to Home Assistant Configuration Files (via Samba Share, SSH or File Editor)
• 📡 Stable Internet connection (to receive tokens and initial synchronization)

Xiaomi’s regional restrictions are critical: Devices purchased in China (cn) won’t work properly with eu, ru, or us servers. If you encounter a “Device not found” error, check the region in the Mi Home app first:

⚠️ Warning: Changing your Mi Home account region after you've linked your devices will lead to decoupling! First, reconfigure the region in the app, then re-assign the devices.

For Aqara devices (such as the Aqara Hub M2 or Aqara Door Sensor), the integration process is similar, but requires a separate aqara component in configuration.yaml.

2. Method 1: Official integration via Mi Home

The simplest, but limited method is to use an embedded component. xiaomi_miio. It supports most devices, but does not provide access to advanced features (for example, setting up Zigbee network settings via Aqara Hub).

Steps for connection:

1. Open the configuration.yaml file and add:

xiaomi_miio:


username: !secret mi_home_username




password: !secret mi_home_password




discovery_retry: 5




cache_devices: true

Where!secret is a link to secrets.yaml (recommended for security) If you don't use secrets, replace it with a direct username/password from Mi Home.

Once Home Assistant is rebooted, a new integration will appear in Settings → Devices and Services, but this method has significant limitations:

💡

If the devices don’t appear after adding integration, check the account region in the Mi Home app. Sometimes switching to the China Mainland server (even for European devices) helps, and then returning to the original region.

Method 2: Connecting through a token (full control)

For devices that are not supported by official integration, or if you need advanced functionality (for example, managing a Zigbee network through Aqara Hub), you will need a device token.

• 🔑 Mi Home (Android) – requires debugging USB and special script
• 📱 Mi Home Token Extractor (the easiest method)
• 🖥️ Python-script miio-cli – for experienced users

Consider the most universal way - using the Mi Home Token Extractor (requires Android-device):

Install the Mi Home Token Extractor app on Android

Sign in to your Mi Home account via the app

Select a device from the list and copy the token

Keep the token in a safe place (it is needed for configuration.yaml)

Reboot Home Assistant after adding a token

-->

After receiving the token, add to configuration.yaml:

fan.xiaomi_miio:


- name: "Xiaomi Air Purifier 3H"




host: 192.168.1.100




token: YOUR_TOKEN_HERE




model: zhimi.airpurifier.mb4





vacuum.xiaomi_miio:




- name: "Xiaomi Robot Vacuum"




host: 192.168.1.101




token: YOUR_TOKEN_HERE




model: roborock.vacuum.s7

Where:

• host - local IP-Device address (must be static!)
• Token – the received 32-digit token
• Model - device model (the list of supported models is in the Home Assistant documentation)

⚠️ Note: Xiaomi device tokens may change after a firmware update or reset.If integration stops working, get a new token.

Integration of Zigbee devices (Aqara, MiJia)

Zigbee-based devices (such as Aqara or MiJia sensors) don’t connect directly through the device. xiaomi_miio. There are two options for them:

1. Through USB-Zigbee adapter (e.g, CC2531 or ConBee II) firmware Zigbee2MQTT

The first way is simpler: connect the Aqara Hub to the Home Assistant via a token (as in method 2), then add to configuration.yaml:

aqara:


discovery_retry: 3




gateways:




- key: YOUR_AQARA_KEY

The key can be found on the back of the hub or retrieved through the Mi Home app, and once rebooted, all sensors connected to the hub will appear automatically in the Home Assistant.

For power users, the second option offers more flexibility: you can manage the Zigbee network directly, without depending on the Xiaomi cloud, but it requires additional Zigbee2MQTT setup and manual pairing of devices.

5. Solving common mistakes

Even with the right setup, you can run into problems. Here are the most common mistakes and their solutions:

If the device is connected but the data is rarely updated, add a parameter to the configuration. scan_interval:

xiaomi_miio:


scan_interval: 60 # Survey every 60 seconds

For devices that require frequent surveying (such as motion sensors), it is possible to reduce the interval to 10 seconds, but this will increase the load on the network.

💡

If after all the manipulations, the device did not appear in the Home Assistant, check its firmware. Some models (for example, Xiaomi Gateway 3) require a downgrade firmware to work with tokens.

6. Automation and examples of use

Once Xiaomi devices are successfully connected, you can create automation, and here are some practical examples.

• 💡 Smart lighting: Turn on Yeelight when motion is detected by the Aqara sensor and turn off after 5 minutes without movement.
• 🌡️ Climate Control: Automatically turn on Xiaomi Air Purifier if the Mi Temperature & Humidity Sensor shows PM2.5 > 50.
• 🚪 Security: Send a notification to Telegram if the door opening sensor is triggered in your absence.
• 🧹 Cleaning: Run Roborock on schedule or when no one is home (according to geolocation data).

Example of automation for lighting (added in automations.yaml):

- alias: "Switch on the lights while driving"


trigger:




platform: state




entity_id: binary_sensor.motion_sensor_158d000xxxxxx




to: "on"




action:




service: light.turn_on




entity_id: light.yeelight_color1_0xxxxxxxx




condition:




condition: sun




after: sunset




before: sunrise

For Zigbee-enabled devices (such as Aqara Button), you can configure multiclicks:

- alias: "Light control from a button"


trigger:




platform: event




event_type: zha_event




event_data:




device_id: 01:23:45:67:89:ab:cd:ef




command: single




action:




service: light.toggle




entity_id: light.living_room

Don’t forget to test automation manually before saving! Use the Developer Tools → Services tool in the Home Assistant interface.

7. Optimization and safety

After setting up the integration, you should take care of security and performance:

• 🔒 Restrict access to tokens: Store them in secrets.yaml, not in the main configuration file.
• 🔄 Home Assistant Update: New versions often add support for Xiaomi devices.
• 📡 Set up a local network: Tie up IP-Device addresses in the router to avoid problems when changing DHCP.
• 📊 Monitor the load: Excessive number of device surveys can slow down the system.

For devices that support local management (e.g. Yeelight), disable cloud sync in Mi Home settings, which will reduce latency and increase reliability.

⚠️ WARNING: If you use Xiaomi Camera in Home Assistant, never expose the stream of video to the internet without protection! NGINX s SSL remotely.

💡

For battery-powered devices (opening sensors, motion sensors), increase the survey interval to 300-600 seconds to save charge. This will have a slight effect on the response of automation, but will extend the battery life by 2-3 times.

Frequently asked questions