Fix Xiaomi & Home Assistant Integration Issues (Guide)

Integrating Xiaomi Devices with Home Assistant: A Troubleshooting Guide

Xiaomi offers a vast range of affordable and popular smart home devices, from sensors and lights to vacuum cleaners and air purifiers. Integrating them into a powerful, local control system like Home Assistant can unlock their full potential. However, the process is not always straightforward and can present several challenges, especially for beginners.

This guide is designed to help you troubleshoot the most common problems encountered when connecting Xiaomi devices to Home Assistant (HA).

Common Xiaomi Integration Problems

If you are facing one of the following issues, you are in the right place:

• Device Discovery Fails: Home Assistant does not automatically find your Xiaomi device.
• 'Unavailable' or 'Unresponsive' Entities: The device is added to HA, but its sensors or controls are greyed out and marked as 'unavailable'.
• Authentication or Token Errors: You receive errors in your Home Assistant logs related to an invalid key or token.
• Difficulty Extracting the Token: You are struggling to find the 32-character security token required for the integration.
• Intermittent Connectivity: The device works for a while but then becomes unavailable, only to reconnect later.

Key Solutions for a Stable Integration

Let's work through the most critical steps for a successful and reliable connection.

1. The Challenge: Obtaining the Device Token

This is the biggest hurdle for most users. For security reasons, Xiaomi does not make the device's local API key (the 'token') easily accessible. This token is essential for Home Assistant to communicate directly with the device.

• The Problem: The official Mi Home app encrypts and hides this token.
• The Solutions:
  1. Modified Mi Home App (Android): One of the most reliable methods involves uninstalling your current Mi Home app and installing an older, modified version (e.g., v5.0.19). When you log into this version, it stores the device tokens in a plain text file on your phone's storage, which you can then access.
  2. Cloud Token Extraction Tools: There are scripts and tools available (often as custom HA integrations via HACS) that can log into your Xiaomi Cloud account and retrieve the tokens for you. This is often easier than the modified app method. A popular choice is the Xiaomi Cloud Tokens Extractor.
  3. Xiaomi Gateway 3 Integration: If you have a Xiaomi/Aqara Gateway (hub), the custom Xiaomi Gateway 3 integration (available via HACS) is excellent. It can often discover and add child devices connected to the gateway without you needing to manually find tokens for each one.

2. The Unstable Connection: Static IP Addresses

This is the second most common cause of problems. By default, your router assigns IP addresses to devices dynamically (using DHCP). This means your Xiaomi device's IP address can change when it reconnects or your router reboots. When this happens, Home Assistant loses the connection because it is still trying to talk to the old IP address.

• The Solution: DHCP Reservation / Static IP
  • Log in to your router's administration page.
  • Find the 'DHCP Settings' or 'Connected Devices' list.
  • Locate your Xiaomi device in the list (you can identify it by its MAC address, which is often printed on the device or found in the Mi Home app).
  • Use the 'DHCP Reservation' or 'Assign Static IP' feature to lock the current IP address to that device's MAC address.
  • This ensures that even after a reboot, the device will always have the same IP address, and Home Assistant will never lose track of it.

3. The 'Unavailable' Entity: Network and Firewall Issues

If the device has the correct token and a static IP but is still unavailable, the problem may be on the network level.

• Network Segmentation: If you have a complex network with multiple VLANs or subnets (e.g., a separate 'IoT' network), you must ensure that your Home Assistant server can communicate with the IoT network. This often requires setting up specific firewall rules to allow traffic between the two.
• Router Firewall: Some routers have security settings that can block local device-to-device communication. Check your router's firewall or 'AP Isolation' settings to ensure they are not preventing Home Assistant from reaching your Xiaomi device.

4. Choosing the Right Integration

Home Assistant has several ways to integrate Xiaomi devices.

• Xiaomi Miio: This is the official, core integration. It is reliable for many devices like vacuums, fans, and lights, but requires you to manually enter the IP address and token in your configuration.yaml file or through the UI.
• Xiaomi Gateway 3 (via HACS): As mentioned, this is a powerful custom integration for users with a Xiaomi Gateway. It offers better device support and easier setup for devices connected to the hub.
• Specific Device Integrations (via HACS): For some devices, like the Mi Flora plant sensor, there are dedicated custom integrations that offer more features than the official ones.

By systematically addressing the token, assigning a static IP, and checking your network, you can build a rock-solid integration between your Xiaomi smart devices and Home Assistant.