How to Add Xiaomi Gateway 3 to Home Assistant: A Complete Guide to Typical Problem Solutions

Gateway Xiaomi Gateway 3 (model) ZNDMWG03LM) It has become one of the most popular devices for building the smart home ecosystem from Xiaomi, but its integration with the Home Assistant, an open automation platform, often raises questions among users. Unlike the standard Mi Home app, where the connection takes minutes, adding a gateway to the device is a good idea. HA requires knowledge of the nuances of the Zigbee and MiOT protocols, as well as the settings of the access token.

This article does not just repeat the official documentation, but reveals hidden configuration options that avoid typical errors, from the lack of devices on the network to problems with updating the firmware. We will discuss two main methods of integration – through the official Xiaomi Miio component and the alternative. Zigbee2MQTT, — We also show you how to make the gateway work stably, even with unofficial firmware.

If you've tried Gateway 3 before and you've encountered errors like "Failed to connect" or devices that show up as unavailable, here's the solution. And for beginners, we've prepared step-by-step instructions with visual examples of configuration files.

Preparing for integration: what to know before you start

Before you start setting up, make sure your Xiaomi Gateway 3 meets the key requirements:

• 🔹 Firmware version: the gateway must work on firmware 1.5.7_0043 Older versions may not support the MiOT protocol needed to integrate with Home Assistant.
• 🌍 Device region: The gateway must be linked to China Mainland servers (even if you are in another country). API Xiaomi.
• 📡 Wi-Fi network: the device only supports 2.4 GHz networks. If your router is running in 5 GHz mode, create a separate network for smart devices.
• 🔑 Access token: you have to get it manually (this is discussed in the next section.

Also check that your Home Assistant is updated to the latest version (at least 2023.12).In older versions, the Xiaomi Miio component may not work properly. OS, Update the system via the web interface (Settings) → System system → Updates).

⚠️ Warning: If you've previously configured the gateway through the Mi Home app, reset it to factory settings. To do this, hold the button on the device body for 10 seconds until the indicator flashes yellow, which will remove all attached devices, but avoid conflicts during integration.

For convenience, prepare:

• 📱 Smartphone with Mi Home application (required to receive a token).
• 💻 Computer with access to Home Assistant configuration files (via Samba or Terminal & SSH).
• 📝 Notepad for records (token, IP-lock-house, MAC-address).

2. Obtaining access token for Xiaomi Gateway 3

A token is a unique key that allows Home Assistant to interact with Xiaomi devices over the cloud or local area network, without which integration is impossible. There are several ways to get a token, but we will look at two of the most reliable ones:

Method 1: Using the Mi Home app (for Android)

This method only works on Android devices with the Mi Home app installed version 6.0.100 or older.

1. Open Mi Home and go to your account profile.
2. Click on... (three dots) in the upper right corner and select About program.
3. Tap on the app version 5-7 Once until the message "Debugging mode is enabled" appears".
4. Go back to the main menu, find your Gateway 3 in the device list and open its settings.
5. Press on... → Device information → Get a token.

Copy the string that appears, and that's your token. It looks like a set of 32 characters (lowercase numbers and letters) and don't pass it on to third parties!

Method 2: Through Mi Home API (universalism)

If you have iOS or the previous method did not work, use the web service mihome.dev:

1. Sign in to the site through your Xiaomi account (use the same data as in the Mi Home app).
2. In the Devices section, find your Gateway 3 (the device will be marked as lumi.gateway.mgl03).
3. Copy the token from the Token column.

⚠️ Note: If the token is received through mihome.dev, it may stop working after changing the password in the Xiaomi account.

Check the token for validity with the command in Terminal (if you have access to the Home Assistant server):

curl -X POST "http://[IP_ SLAWS]/miio/info" -H "Content-Type: application/json" -d "{"id":1}"

Replace. [IP_Gateway to the real IP-If the answer contains data on the model and firmware version, the token is working.

💡

If the gateway is not responding to ping, check if the router firewall is blocking it. Add the device to exceptions or turn off protection for the time of setting up.

3.Add gateway through official Xiaomi Miio component

This is the easiest way to integrate, but it has limitations: not all devices connected to the gateway will be available in Home Assistant, for example, motion sensors can be displayed, but buttons can't. However, for basic functionality, this is enough.

Step 1: Configure the configuration file

Open the Home Assistant configuration file (configuration.yaml) and add the following block:

xiaomi_miio:


devices:




- host: [IP_ Gateway]




Token: [YOUR TOKEN]




model: lumi.gateway.mgl03

Example IP-address 192.168.1.100 and token a1b2c3d4e5f678901234567890abcdef:

xiaomi_miio:


devices:




- host: 192.168.1.100




token: a1b2c3d4e5f678901234567890abcdef




model: lumi.gateway.mgl03

Step 2: Reboot Home Assistant

Save the changes and restart the system via the web interface (Settings) → System system → Reboot) or team:

ha core restart

Step 3: Checking the connection

After restarting, open the Settings section. → Devices and services. Xiaomi Gateway 3 should appear on the list with Connected status. If the device appears as Unavailable, check it out:

• 🔌 Correctness IP-address and token.
• 🌐 Accessibility of the gateway in the local network (ping).
• 🔄 No conflicts with other integrations (e.g, Zigbee2MQTT).

If the gateway is successfully connected but not all sensors are displayed, try manually adding them via configuration.yaml:

sensor:


- platform: xiaomi_miio




host: 192.168.1.100




token: a1b2c3d4e5f678901234567890abcdef




name: "Xiaomi Gateway 3 Sensors"

The gateway is displayed in the "Devices and Services" section"|IP-lossless ping|Token verified through curl|Motion/light sensors are available in HA-->

Alternative method: Zigbee2MQTT full control

If the official integration is not satisfied with limited functionality, use the Zigbee2MQTT — This is a solution that allows you to work with Xiaomi Gateway. 3 It's a very complex Zigbee coordinater, and it's a very difficult method to set up, but it gives you access to all the devices in the ecosystem, including buttons, switches and sensors that you ignore. xiaomi_miio.

Step 1: Installation Zigbee2MQTT

If Zigbee2MQTT Not yet installed, add it through HACS (Home Assistant Community Store or manually:

1. Go to Settings. → Supplements → Additions store.
2. Find it. Zigbee2MQTT and set it up.
3. Launch the add-on and open the web interface at the address http://[IP_HA]:8080.

Step 2: Configure the configuration

Open the configuration file Zigbee2MQTT (configuration.yaml in the add-on folder) and add:

serial:


port: tcp://[IP_GLASS]:8888




advanced:




network_key: [GENERATE_NEW_KEY]

To generate new network_key use the command:

openssl rand -hex 16

Step 3: Connecting the gateway

In the web interface Zigbee2MQTT Go to the Settings section → Zigbee and:

1. Select Xiaomi Gateway 3 from the list of supported devices.
2. Indicate. IP-address and port 8888.
3. Save the settings and restart the service.

After successful connection, all devices connected to the gateway will appear in Home Assistant as separate entities (sensor, binary_sensor, switch etc.).

⚠️ Attention: when used Zigbee2MQTT disconnect integration xiaomi_miio So, two systems don't have to control the same device at the same time, so that you don't have to control the same thing.

5. Solving Typical Integration Problems

Even when you set it up correctly, users often encounter errors, and we've collected some of the most common problems and solutions.

If your problem is not described in the table, check the Home Assistant logs. → System system → Errors with 401 code are usually associated with the token, 502 with network problems, and 9999 indicates internal gateway errors (reboot required).

To diagnose network problems, use the command:

tcpdump -i eth0 host [IP_ gateway]

This will help you see if the packets are reaching the device.

💡

If the gateway is unstable, try connecting it to the router via an Ethernet cable (Gateway 3 supports wired connection).

6. Optimization of the gateway in Home Assistant

After successful integration, set up the gateway for maximum efficiency:

• 📊 Automation: create scenarios for motion sensors, buttons and lights, such as turning on the light automatically when motion is detected:

automation:


- alias: "Switch on the lights while driving"




trigger:




platform: state




entity_id: binary_sensor.motion_sensor_158d0001234567




to: "on"




action:




service: light.turn_on




target:




entity_id: light.gateway_light_7811dca12345

• 🔄 Update firmware: check the relevance of the firmware once in a while 2-3 Newer versions often fix compatibility errors with Home Assistant.
• 🛡️ Security: Disable access to the gateway from the Internet in the router settings. Use only the local area network.
• 📈 Monitoring: Add gateway sensors to Lovelace panel to track Zigbee network status:

type: entities


entities:




- entity: sensor.gateway_zigbee_network_status




- entity: sensor.gateway_wifi_strength




- entity: sensor.gateway_memory_usage

To reduce the load on the gateway, disable unnecessary entities in configuration.yaml:

xiaomi_miio:


devices:




- host: 192.168.1.100




token: a1b2c3d4e5f678901234567890abcdef




model: lumi.gateway.mgl03




sensors:




- "humidity"




- "temperature"




Disable unnecessary sensors:




- "!pressure"




- "!illuminance"

Comparison of integration methods: which to choose?

Choice between xiaomi_miio and Zigbee2MQTT depends on your tasks:

If you need simple integration for basic devices (temperature sensors, lighting), enough xiaomi_miio. For full control of the Xiaomi ecosystem (buttons, switches, custom scenarios) choose Zigbee2MQTT.

Some users combine both methods: xiaomi_miio to control the gateway LED and sound signals, and Zigbee2MQTT — But it requires careful adjustment to avoid conflict.

FAQ: Frequent questions about Xiaomi Gateway 3 Home Assistant and Home Assistant