Smart home is not just a collection of disparate gadgets, but a single ecosystem where devices communicate with each other without delay and binding to cloud servers. Integrating Xiaomi gateway into the Home Assistant platform gives users access to local management, complex automation and complete control over data, which is impossible with the standard Mi Home application. Many device owners face difficulties in initial configuration, as the process requires understanding of network protocols and features of the Zigbee network.
In this article, we’ll look at all the available connectivity methods, from using third-party integrations to working directly with the Zigbee protocol. Local control allows your scripts to run instantly even when the Internet is off, which is critical for security and climate control. We’ll look at the nuances of how different gateway models work, as not all of them support the same connectivity methods.
Before you start, make sure your Home Assistant server is already installed and has stable access to the LAN. It is important to understand that adding a gateway is only the first step, followed by setting up individual sensors and actuators. The right network architecture is the key to keeping the entire smart home system running for years to come.
Selecting the right gateway model for integration
Not all Xiaomi gateways are equally friendly to third-party software. The most popular and recommended model for many years remains Xiaomi Gateway 3 (ZNDMWG03LM) with a Realtek chip. It has an open telnet port and supports custom firmware installation that turns the device into a powerful bridge for Zigbee2MQTT or Xiaomi Gateway 3 (Official) integration. If you are only planning to buy equipment, focus on this model first.
Older versions such as Xiaomi Gateway 2, They also support connectivity, but their functionality can be limited, and the process of hacking (getting a token) is more complex. 2023-2026 years, often have enhanced protection and may not support third-party installation without complex soldering or use UART-Always check the specifications of a specific audit before buying.
⚠️ WARNING: When buying a Chinese fork gateway, make sure it supports the region you want in the Mi Home app, as some versions are available. CN You can be blocked from working with European accounts without crutches.
For advanced users who want complete independence, there are universal Zigbee coordinators based on CC2652 or ConBee that completely replace the Xiaomi gateway. However, if you already have devices tied to the Xiaomi gateway and you do not want to re-tether them, using a native gateway in bridge mode will be the best solution. Compatibility is a key factor in building hybrid systems.
Home Assistant Preparation and Dependency Setup
The standard Home Assistant OS installation requires the use of HACS (Home Assistant Community Store) to install most custom integrations. If you don't already have HACS installed, that's the first thing you need to do through the terminal or add a repository manually.
To work with Xiaomi gateways, the most common requirement is the presence of MQTT-It's a lightweight service that provides messaging between a gateway and a smart home server. MQTT Many advanced features will be unavailable, and devices will remain invisible to the system.
☑️ Environment preparation
Make sure your server is static. IP-address in the local network. Dynamic change of address IP This will cause the gateway to break, and all devices will no longer respond. Reserve the address in the router settings or write it statically in the Home Assistant network configuration.
Method 1: Integration with Xiaomi Gateway 3 (Official)
The official integration developed by the community (often known as Xiaomi Gateway 3 by AlexxIT) is the most stable way for owners of the third version of the gateway.It does not require flashing the device and runs on top of standard software, using vulnerabilities or open ports to retrieve data, which allows you to save work with the Mi Home application in parallel.
To get started, you need to get your device token, which is a unique security key that you can't manage locally without, and you can extract it through tools like miio (Python library) or using scripts available in the integration repository if you have a Xiaomi account with a tied device.
pip install python-miio
miio cloud --username your email --password your password --country deAfter receiving the token, add integration through HACS, Find the repository Xiaomi Gateway 3. In the settings, specify IP-The gateway address and the token that you get will automatically detect the connected devices and start synchronizing them, and device attributes, such as signal level or firmware version, will be made available to create state sensors.
💡
Use the "Firmware Hack" mode in integration settings if the standard connection method is unstable, this will add telnet access and expand the functionality of the gateway.
Method 2: Use Zigbee2MQTT to control the entire system
For those who want maximum independence, the ideal option is to reflash the gateway Xiaomi Gateway 3 under control. Zigbee2MQTT. This method turns the gateway into a full-fledged Zigbee network coordinator, completely removing dependence on Xiaomi servers and cloud services. MQTT-pole-topics.
The firmware process requires connecting to the gateway over telnet (port 23) and executing a command to install alternative firmware. This action can void the warranty, but gives you incredible flexibility. You can connect devices from any manufacturer (Aqara, IKEA, Tuya) that Zigbee2MQTT supports, ignoring the limitations of the Xiaomi ecosystem.
| Parameter | Standard lock. | Zigbee2MQTT | HomeKit (through the gateway) |
|---|---|---|---|
| Dependence on the cloud | Tall. | No. | No (locally) |
| Support for devices | Only Xiaomi/Aqara | Any Zigbee. | Only compatible with HK |
| Response speed | Medium | Instant. | Tall. |
| Difficulty setting up | Low. | Tall. | Medium |
After successful firmware, the Home Assistant adds Zigbee2MQTT integration, which automatically creates all devices and their entities. MQTT topes allow you to transmit not only state (on/off), but also detailed telemetry, communication quality and battery parameters. This is the best choice for enthusiasts.
⚠️ Note: When the lock is under the lock Zigbee2MQTTSome devices can uncouple, they will need to be re-coupled in the search mode for new devices.
Setup of automations and scenarios
Once you've successfully added the gateway and the devices, the magic begins. In Home Assistant, you can create complex chains of reactions that are not available in the Mi Home app. For example, when you activate the Aqara motion sensor, you can not just turn on the lights, but check the light level, the time of day and the presence of people in the room through the camera.
Use an automation editor or YAML-Triggers can be anything from the time of sunrise to a 0.5 degree temperature change. Actions can include sending notifications to Telegram, changing the volume of the media player or launching a robot vacuum cleaner.
Example of complex automation of YAML
Don't forget about Debouncing for door opening sensors, so that one opening doesn't generate a dozen notifications. At Home Assistant, this is solved by adding a waiting condition or using special filter integrations. Competent logic setup will save you from false positives.
Problem Solving and Diagnostics
A common problem is that devices become "Unavailable" and this may be because the gateway has lost communication with a particular sensor due to a weak signal or battery discharge. Home Assistant (Configuration -> Logs) logs can see messages about loss of packets or Zigbee timeouts.
If the gateway stops responding fully, check if it has changed. IP-Address or block the brandy ports (typically 1990, 1991, 23) and may also be a problem with Wi-Fi network congestion if the gateway is wirelessly connected, although Ethernet models are preferable for stability.
⚠️ Warning: Frequent gateway reboots can lead to device flash memory degradation, so avoid scripts that record logs to the gateway itself.
For diagnostics, use Zigbee tools such as a network map (available in Zigbee2MQTT) that will show the quality of communication (LQI) between devices. If communication is poor, consider installing repeaters (continuously powered devices, such as smart sockets) that will amplify the Mesh signal.
💡
The stability of the Zigbee network depends on the number of constant-powered devices that work as signal repeaters.