How to Connect Xiaomi Gateway 3 (Mijia Hub) to Home Assistant: A Complete Guide to Error Solutions

Xiaomi Gateway 3 (also known as Mijia Hub) ZNDMWG03LM) — It is the central device of the Mi Home ecosystem that allows you to control sensors, lamps and other Xiaomi gadgets through a single interface, but many users have difficulty integrating it with Home Assistant, an open platform for smart homes. Unlike previous versions of gateways (e.g. Gateway 2), the third model requires a special approach due to changes in the communication protocol and security policy of Xiaomi.

In this article, you will find the latest 2026 instructions, taking into account the latest Home Assistant updates (version 2026.6).+) We will discuss two main ways of connecting: through formal integration (with restrictions) and through the custom component of Xiaomi Miio with manual receipt of the token. You will also learn how to avoid common bugs, such as Unable to connect to the device or Invalid token, and what to do if the gateway is not detected on the network.

Before you start, make sure you have:

• 📱 Gateway Xiaomi Gateway 3 (model) ZNDMWG03LM) last-fixed.
• 🖥️ Installed Home Assistant (version 2023.12 or later).
• 📲 Mi Home app (version for your region: China, Europe or Russia).
• 🌐 Stable Internet connection (gateway requires cloud authorization).

1.Preparation of the Xiaomi Gateway 3 gateway for integration

Before connecting to Home Assistant, the Xiaomi Gateway 3 gateway must be configured correctly in the Mi Home application. This step is critical, since the ability to obtain access tokens and the stability of further work depend on it.

First, link the gateway to a Xiaomi account in the region corresponding to your firmware. For example, if you bought a device in China, use a Chinese server (Mainland China). For European models, choose Europe or Russia. Changing the region after the gateway is tied can lead to loss of control of the device!

• 🔧 Open the Mi Home app and go to Profile → Settings → Region.
• 🌍 Select the right region (for example, Russia for Russian firmware).
• 🔄 If the gateway is already linked to another region, delete it from your account and add it again.

Next, update the lock firmware to the latest version.

1. Go to the gateway settings in Mi Home (click on the device) → ⚙️ Settings → Firmware update).
2. If the update is not available, check your internet connection or change region to Mainland China (there are updates earlier).

⚠️ Attention: Gateway Gateway 3 Does not support local management without the cloud if its firmware is newer 1.5.6_0039. Working with Home Assistant in offline mode may require a firmware rollback (risky!) or the use of alternative protocols, such as, Zigbee2MQTT.

Make sure the gateway is tied to the right region in Mi Home|

Update the firmware to the latest version|

Write it down. MAC-Gateway address (located on the sticker or in the Mi Home settings)|

Shut down. VPN/Proxy on the phone during setting up|

Check that the gateway and Home Assistant are on the same network-->

2. Obtaining access token for Xiaomi Gateway 3

The Mi Home Token is a unique key that allows Home Assistant to interact with Xiaomi devices. Unlike older gateway models, Gateway 3 requires a token even for local management. There are several ways to obtain it, but we will look at two of the most reliable ones: through the Mi Home app (for Android) and through a web service.

Method 1: Receiving a token through an Android application (recommended)

This method only works on Android devices with Mi Home installed and requires the use of a third-party Packet Capture tool or a new version of the device. HTTP Toolkit for intercepting traffic.

1. Install the Packet Capture app from Google Play.
2. Start capturing traffic and log in to Mi Home.
3. Open the Gateway 3 gateway settings and wait until the logs contain a request to the api.io.mi.com server.
4. Find the line “token” in the server response: “your token” (usually in the JSON-format).

Method 2: Use of Web Services (alternative)

If you have an iPhone or can't intercept traffic, you can use online services like miot-spec.org.

1. Sign in to the site through your Xiaomi account.
2. Select the Gateway 3 device (lumi.gateway.mgl03) list.
3. Copy the generated token.

⚠️ Note: Some web services may request access to your Xiaomi account.Use only verified resources (e.g. miot-spec.org) and change your password after receiving the token if you have any doubts about security.

An example of a correct token for Gateway 3:

5f4dcc3b5aa765d61d8327deb882cf99

3. Set up Home Assistant to work with Xiaomi Gateway 3

Once you get the token, you can start integrating the gateway into Home Assistant, and there are two main approaches: through official Xiaomi Miio integration (easier but with limitations) and through the custom component (more features, but more difficult to set up), we will discuss both options.

Method 1: Official integration of Xiaomi Miio

This method is suitable for most users and does not require editing configuration files.

1. Open the Home Assistant web interface and go to Settings → Devices & Services → Add Integration.
2. Type in Xiaomi Miio and select integration.
3. Indicate. IP-Gateway address (can be found on the router or in Mi Home) and previously received token.
4. Press Submit and wait for the connection.

If the integration is successful, the Xiaomi Gateway 3 will be included in the list of devices with light, temperature and humidity sensors, but controlling Zigbee devices (such as motion sensors or buttons) through this integration may not work, and they will require additional adjustment.

Method 2: Manual addition via configuration.yaml

To fully control the gateway, a custom component is recommended, which allows you to manage Zigbee devices connected to the gateway, but requires editing the configuration.yaml file.

Add the following code to the file (located in the Home Assistant configuration folder):

xiaomi_miio:


devices:




- host: 192.168.1.100 # Replace your gateway with IP




token: "yash token" # Token from the previous step




model: lumi.gateway.mgl03 #Gateway 3 model

Once you save the file, restart Home Assistant. If everything is set up correctly, the interface will show:

• 🌡️ Temperature, humidity and illumination sensors.
• 🔔 Status of Zigbee connected devices (if supported).
• 🎵 Control of the built-in speaker of the gateway (sounds, melodies).

⚠️ Warning: If Home Assistant doesn’t see the gateway after rebooting, check: Correctness IP-Addresses (it can change when you reboot the router), no lock from the firewall or antivirus. Relevance of the token (it can be reset when you change region in Mi Home).

💡

If the gateway is not connected, try temporarily disabling encryption in the Miio settings. To do this, add a line to configuration.yaml. force_polling: True under the parameters of the device.

4. Manage Zigbee Devices through Gateway 3

One of the key features of Xiaomi Gateway 3 is support for the Zigbee 3.0 protocol, which allows you to connect sensors, switches and other gadgets without having to buy a separate hub. However, in Home Assistant, these devices may not display correctly or at all.

Problem: Zigbee devices are not displayed in Home Assistant

This is most often due to the fact that the official Xiaomi Miio integration does not support Zigbee devices.

1. Use the component Zigbee2MQTT. This will require a separate Zigbee adapter (e.g., a Zigbee adapter, CC2531 or ConBee II), Gateway 3 is not a coordinator for the Zigbee2MQTT.
2. Set up the custom component of Xiaomi Gateway 3. This method is more complicated, but allows you to control Zigbee devices through the Xiaomi gateway.

Solution: Castom component for Zigbee devices

To activate support for Zigbee devices:

1. Install. HACS (Home Assistant Community Store in your system.
2. Through HACS Find and install the Xiaomi Gateway 3 repository (author: AlexxIT).
3. Add to configuration.yaml:

xiaomi_gateway3:


devices:




192.168.1.100: # IP gateway




token: "your-token"




key: "your key" # encryption key (optional)

After the reboot, the interface will appear:

• 🚪 Opening sensors for doors/windows (Xiaomi) Door/Window Sensor).
• 👤 Motion Sensors (Xiaomi Motion Sensor).
• 🔘 The buttons and switches (Xiaomi Wireless Switch).

💡

The Xiaomi Gateway 3 customy component from AlexxIT is the only way to control Zigbee devices through the gateway without an additional hub, but it requires regular updates due to changes in the Xiaomi protocol.

5. Solving common connection errors

Even with the correct following of the instructions, users often encounter errors, and let's look at the most common problems and ways to fix them.

Error 1: "Unable to connect to the device"

This error occurs if the Home Assistant cannot establish a connection to the gateway.

• 🔌 Gateway not online: Check that the device is powered and the blue indicator is on.Reset the gateway (hold the reset button for 5 seconds).
• 🌐 Wrong. IP: Make sure that IP-The gateway address has not changed (configure static). IP router).
• 🔒 Firewall Lock: Turn off firewalls on routers or operating systems where Home Assistant works.
• 🔄 Outdated firmware: Update the gateway via Mi Home.

Mistake 2: "Invalid token"

A token may become invalid for several reasons:

• 🔑 Change of region to Mi Home: When you change region (for example, from China to Europe), the token is reset.
• 🔄 Mi Home Update: After an app update, re-authorization is sometimes required.
• ⏳ Expire: Xiaomi tokens could expire in 6-12 months.Update token.

Mistake 3: Zigbee devices are not working

If the sensors or buttons are not displayed:

• 🔄 Reconnect devices: In Mi Home, remove and re-add problem sensors.
• 📡 Interference in Zigbee network: Make sure there are no sources of interference nearby (2.4GHz Wi-Fi routers, microwaves).
• 🛠️ Use Custom Component: As described in Section 4, official integration does not support Zigbee.

6. Optimize the Xiaomi Gateway 3 in Home Assistant

Once the gateway is successfully connected, you can improve the way it works in Home Assistant with automation, scripts, and additional integrations. Let's look at some useful settings.

Automation with gateway sensors

Gateway 3 has built-in temperature, humidity and light sensors that can be used to create automatics.

• 🌞 Lighting control: Turn on lamps in low light conditions (e.g, sensor.gateway_3_illuminance < 50).
• 🌡️ Climate Control: Send notification if temperatures exceed 30°C.
• 🚪 Safety: Turn on the lock siren when the motion sensor is triggered.

Example of automation for high temperature notification:

alias: "Overheating warning"


trigger:




- platform: numeric_state




entity_id: sensor.gateway_3_temperature




above: 30




action:




- service: notify.notify




data:




Message: "The temperature in the room is over 30°C!"

Integration with voice assistants

To manage the gateway through Alice, Google Assistant, or Amazon Alexa, set up the appropriate integrations in Home Assistant:

1. For Alice: Use the Yandex Smart Home component.
2. For Google Assistant: activate Google Assistant SDK customized.
3. For Alexa: Set up the Home Assistant Cloud skill.

After setting up, you will be able to voice:

• 🔦 Switch on/off the lock lighting (light.gateway_3_led).
• 🔔 Reproducing sounds through the speaker (media_player.gateway_3).
• 📊 Request sensor readings (e.g., "What temperature is in the room?").

Backup of configuration

To avoid losing settings when updating Home Assistant or crashing:

1. Create a backup of the config folder (where configuration.yaml is stored).
2. Export a list of devices and automations through Settings → Backup copies.
3. Keep the gateway token in a secure location (such as a password manager).

💡

For stable operation of the Gateway 3 gateway in Home Assistant, it is recommended to disable automatic firmware updates in Mi Home. New versions of firmware can break compatibility with custom components.

7. Alternative ways of connecting (if nothing works)

If none of the methods described worked, consider alternative options for integrating Xiaomi Gateway 3 with Home Assistant.

Method 1: Use of the Zigbee2MQTT externally adaptable

If you want full compatibility with Zigbee devices, you can drop the Xiaomi gateway as coordinator and use:

• 📡 adapter CC2531 (~500–1000 ₽) + Z-Stack firmware.
• 🖥️ ConBee II Sonoff ZBDongle-E (more reliable options).

Advantages:

• ✅ Full compatibility with all Zigbee devices (not just Xiaomi).
• ✅ Local management without depending on the cloud Xiaomi.
• ✅ Regular firmware updates from the community.

Method 2: Cloud Integration with Home Assistant Cloud

If local connectivity is not possible (for example, due to a provider’s blocking), you can use a cloud bridge:

1. Activate Home Assistant Cloud in your settings.
2. Connect to Xiaomi account through Xiaomi Mi Cloud integration.
3. Set up the synchronization of the devices.

Disadvantages:

• ❌ Xiaomi Cloud Dependence (Delays Up to 5 Seconds).
• ❌ Limited functionality (e.g. no control of Zigbee devices).

Method 3: Firmware alternative software (for advanced)

Gateway 3 allows you to replace the stock firmware with an alternative, such as OpenMQTTGateway or Tasmota, which will allow you to use the gateway as a universal Zigbee coordinator without being tied to Xiaomi.

• 🔧 Requires soldering and the use of a programmer (the risk of "bricking" the device).
• 🚫 Deprives Xiaomi of warranty and support.
• 🔄 May require manual recovery after updates.

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