How to connect Xiaomi gateway to Home Assistant: 3 working methods + error solving

Why to Integrate Xiaomi Gateway with Home Assistant

Xiaomi Mi Home Gateway (Aqara Gateway, Mi Gateway 3, and others) is a central element of Xiaomi’s smart home ecosystem that manages sensors, switches, and other devices using the Zigbee protocol. However, the standard Mi Home app limits functionality: no time-of-day automation, complex scenarios, or integration with other brands. Here comes Home Assistant, an open smart home platform that allows you to combine all devices into a single system.

Connecting Xiaomi’s gateway to Home Assistant offers several key benefits:

• 🔄 Local management without dependence on the Xiaomi cloud (works even when the Internet is disconnected).
• 🛠️ Advanced automation with the use of YAML-Scripts, triggers and conditions.
• 📊 Detailed analytics: event logs, energy consumption graphs, sensor response history.
• 🔌 Integration with other systems (Google Home, Alexa, Apple HomeKit via Home Assistant).

In this article, we will discuss three ways to connect: through the official Xiaomi Miio plugin, an alternative Zigbee2MQTT (for advanced users), and the Mi Home Auto cloud bridge. You will also learn how to avoid typical errors (for example, Device not found or problems with the Zigbee network) and optimize the system.

Method 1: Connect via the official Xiaomi Miio plugin

The easiest method is to use the built-in integration of Xiaomi Miio into Home Assistant, which supports most Xiaomi/Aqara gateways and allows you to control connected devices (motion sensors, temperature sensors, buttons, etc.) without additional manipulation, but this method has a limitation: you need a cloud account Mi Home and a stable Internet connection for initial authorization.

To connect:

1. Open the Home Assistant web interface and go to Settings → Devices & Services → Add Integration.
2. Enter the username and password from the Mi Home account (make sure that the account is linked to the mainland region of China - this is critical!).
3. Select the gateway from the list of detected devices. If the gateway does not appear, check that it is connected to the same Wi-Fi network as the Home Assistant server.

💡

If you have an Invalid credentials error when you log in, try changing your Mi Home password and using a new one, sometimes by logging out on all devices.

Once successfully connected, the Home Assistant will have entities to manage the gateway and its devices, such as:

• 🔊 media_player.xiaomi_gateway — lock-control.
• 🌡️ sensor.xiaomi_temperature — temperature-sensing.
• 🚪 binary_sensor.xiaomi_motion — motion-sensorship.

⚠️ Note: The official Xiaomi Miio integration does not support Zigbee devices from third parties (e.g., from Tuya or other devices). IKEA). If you want complete freedom in the selection of sensors, consider the method of using the Zigbee2MQTT.

Method 2: Connect via Zigbee2MQTT (for advanced)

If you want to completely abandon the Xiaomi cloud and manage devices locally, the best option is to use Zigbee2MQTT. This method requires more effort, but gives you complete control over the Zigbee network, support for devices from other brands and high stability.

• 🖥️ Home Assistant Server (Available on Raspberry Pi, NAS PC).
• 🔌 Zigbee adapter (recommended) CC2531, CC2652 or ConBee II).
• 📦 Installed by Mosquitto Broker (MQTT-server Zigbee2MQTT.

Adjustment steps:

1. Connect the Zigbee adapter to the server and check that it is defined by the system (the command ls /dev/tty* should show the device, for example, /dev/ttyACM0).
2. Install Zigbee2MQTT via HACS or manually (instructions on the official website).
3. Open the configuration file configuration.yaml and add:

zigbee2mqtt:


data_path: /config/zigbee2mqtt




external_converters: []




devices: devices.yaml




advanced:




network_key: GENERATE_NEW_KEY_ON_FIRST_START




mqtt:




base_topic: zigbee2mqtt




server: mqtt://localhost




serial:




port: /dev/ttyACM0 # replace with your port




adapter: zstack

Next, you need to reset the Xiaomi gateway to factory settings and connect it to Zigbee2MQTT as a new device:

Method 3: Cloud Bridge Mi Home Auto (alternative for beginners)

If the first two methods seemed complicated, you can use an intermediate solution – Mi Home Auto. This is a cloud bridge that syncs devices from Mi Home with Home Assistant without the need to configure Zigbee or MQTT.

Instructions for setting:

• 📱 Install the Mi Home Auto app on your smartphone (available for Android and iOS).
• 🔗 Log in to your Mi Home account and select a gateway to sync.
• 🖥️ In Home Assistant, add Mi Home Auto integration HACS manually.
• 🔑 Enter the access token generated in the mobile application.

Once connected, all gateway devices will appear in Home Assistant as prefixed entities. mi_home_auto. For example:

• switch.mi_home_auto_plug_158d0001234567 — plug-in.
• binary_sensor.mi_home_auto_motion_158d0001234568 — motion-sensor.

⚠️ Warning: Mi Home Auto cloud bridge does not support local scenarios. If the Internet goes down, automation will stop working. Zigbee2MQTT.

Typical errors and their solutions

When connecting Xiaomi gateway to Home Assistant, users often face the following problems:

If the devices are unstable after connecting (for example, temperature sensors are updated every 10 minutes instead of 1 minute), check the following points:

• 📶 Zigbee signal level: the gateway should be in the center of the house, not in the corner. Zigbee2MQTT signal-level (LQI).
• ⚡ Gateway power: Some models are sensitive to unstable voltage. USB-feed-in.
• 🔄 Conflicts with other Zigbee devices: If you have other hubs (like Philips Hue), they can interfere with your network.

💡

For stable operation of Zigbee-network avoid using channels 15-20 – they intersect with Wi-Fi at 2.4 GHz. Optimal channels: 11, 20, 25.

Optimizing the Gateway in Home Assistant

After a successful connection, several steps are recommended to improve performance and reliability:

1. Turn off cloud sync in the Mi Home app if you are using Zigbee2MQTT. This will reduce delays and reduce the load on the gateway.
2. Configure backup configuration Zigbee2MQTT. To do this, add to configuration.yaml:

zigbee2mqtt:


backup_path: /config/zigbee2mqtt_backups

1. Create automation for critical devices, for example, if the smoke detector is triggered, turn on the siren and send a notification to the phone:

automation:


- alias: "Fire alarm"




trigger:




platform: state




entity_id: binary_sensor.smoke_sensor




to: "on"




action:




- service: switch.turn_on




entity_id: switch.siren




- service: notify.mobile_app_iphone




data:




message: "⚠️ Smoke sensor is activated!"

So for ease of control, you can group the devices into rooms, for example, all the sensors in the bedroom can be grouped together. group.sensors_bedroom:

group:


sensors_bedroom:




name: Bedroom sensors




entities:




- binary_sensor.bedroom_motion




- sensor.bedroom_temperature




- sensor.bedroom_humidity

💡

If you have a lot of Zigbee devices, consider buying a Zigbee router (like IKEA Tradfri or Aqara Range Extender) that will increase network range and reduce the load on the gateway.

FAQ: Frequent questions about connecting Xiaomi gateway