Xiaomi Multimode Gateway Local Control in Home Assistant
If you’ve spent any time on the Home Assistant forums trying to get the Xiaomi Multimode Gateway (小米多模网关) working locally, you’ve probably hit the same wall: a 19-page community thread, a GitHub README that assumes a lot, and no single guide that tells you clearly what to do or why. This is that guide.
The gateway itself is capable hardware. One device covers Zigbee, BLE sensors, and Bluetooth Mesh — three separate radio protocols, all handled locally once it’s configured correctly. The confusion comes from two sources: a naming situation that makes SERP results inconsistent, and Xiaomi’s own official Home Assistant integration, which looks like the right answer but isn’t, for most people outside China.
Let me clear both of those up before getting into the setup.
What the Xiaomi Multimode Gateway actually is
The device goes by several names depending on where you bought it. The China model is the ZNDMWG03LM (sold as the 小米多模网关 or Xiaomi Multimode Gateway 1), the European variant is the ZNDMWG02LM or YTC4044GL. There’s also the ZNDMWG04LM (China) and BHR6765GL (EU), which is the Multimode Gateway 2. Despite the different model numbers and regional branding, all of them share the same internal identifier: lumi.gateway.mgl03. The XiaomiGateway3 custom component treats all of them the same way.
The hardware has three radios. The Zigbee radio uses a Silicon Labs EFR32 chip (the same family used in other popular Zigbee coordinators). There’s a BLE radio for standard Bluetooth sensors. And there’s Bluetooth Mesh (蓝牙Mesh) support for the growing range of Xiaomi Mesh devices. On a price-per-protocol basis, this is good value — a single cheap gateway gives you coverage that would otherwise require multiple separate USB sticks or bridges.
The Aqara Hub E1 (ZHWG16LM) is also supported by the same XiaomiGateway3 component if you’re coming from that direction — our Aqara Hub E1 local integration guide covers that device in full.
The official ha_xiaomi_home integration — and why it’s not fully local outside China
When Xiaomi released the official ha_xiaomi_home integration in late 2024, Chinese communities lit up with comparisons. The integration is well-maintained and covers a broad device list. But there’s a detail buried in the README that matters a lot if you’re not in mainland China.
The ha_xiaomi_home integration offers genuine local control only when a Xiaomi Central Hub Gateway (小米中枢网关, roughly CNY349) is present on the network. That device — the 中枢网关 — enables local automation execution and LAN-mode device communication. It’s only sold in mainland China. Outside China, ha_xiaomi_home routes Zigbee and BLE Mesh device commands through Xiaomi’s cloud. LAN mode in the official integration applies only to Wi-Fi-connected IP devices: smart plugs, some cameras. Your Zigbee sensors and BLE Mesh lights are going through the cloud.
This is a predictable design: Xiaomi built local control around their own newer hub hardware, not around older gateway firmware. If you have a Multimode Gateway and you’re in Singapore, Australia, the UK, or anywhere outside mainland China, ha_xiaomi_home is not a local control path for your Zigbee and Mesh devices.
Chinese communities on Zhihu (知乎) reached this same conclusion when reviewing the integration release. The consensus for international users: the Multimode Gateway running XiaomiGateway3 remains the better approach. The Central Hub Gateway’s local mode advantage evaporates once you’re outside China. We cover this trade-off in more depth in our explainer on what local control actually gets you with Xiaomi in Home Assistant.
XiaomiGateway3: the local-first alternative
AlexxIT’s XiaomiGateway3 custom component takes a different approach. It connects to the Multimode Gateway directly over your local network, using the gateway’s existing firmware. No flashing. No replacement of the gateway’s operating system. The gateway stays on its original Xiaomi firmware, and the component talks to it over the LAN.
What this gets you: Zigbee devices work without internet connectivity. BLE sensors work locally. Bluetooth Mesh devices work locally. Adding new Zigbee devices to the gateway still requires a temporary internet connection (the pairing flow uses Xiaomi’s cloud), but once paired, normal operation is fully local.
The integration reads the Mi Home token from your Xiaomi account during setup — you enter your Mi Home login credentials once, and the component fetches the token automatically. No manual token extraction tools required.
Installing XiaomiGateway3 via HACS
The component isn’t in the official HA integration list, so you install it through HACS (Home Assistant Community Store).
Prerequisites:
– HACS installed in your Home Assistant instance
– Your Multimode Gateway on the same LAN subnet as Home Assistant
– Mi Home account credentials
– Gateway firmware within the supported range (more on this below)
Installation steps:
- Open HACS in Home Assistant, go to Integrations, and search for
XiaomiGateway3. - Install the component and restart Home Assistant.
- Go to Settings > Devices & Services > Add Integration, search for
Xiaomi Gateway 3. - Enter your Mi Home account credentials. The component fetches the gateway list and token.
- Select your gateway from the list.
- Configure the options (see the Firmware Lock step below — do this before anything else).
Verify the firmware version first. Before running the integration, check the firmware version shown in the Mi Home app for your gateway, then cross-check it against the component’s own supported-firmwares list (the XiaomiGateway3 README maintains a current “Supported firmwares” section). The supported range for the Multimode Gateway 1 (ZNDMWG03LM) shifts over time as the component is updated, so the README is the authoritative source rather than any fixed version number — older firmware in the 1.4.x line may still work but is flagged unsupported, and the newest factory firmware can run ahead of what the component handles. The point is to confirm a match before you proceed, not to chase a specific build.
The firmware lock — the step most people miss
This is the part that trips up a disproportionate share of users, and Chinese communities specifically call it out as the most common failure mode.
After setting up the integration, enable the Gateway Firmware Lock option in the component settings. This tells Mi Home not to auto-update the gateway’s firmware. Without it, the next time you open the Mi Home app or the app updates in the background, it may silently push a firmware update that moves your gateway past the supported firmware range. Your HA integration stops working. You don’t get an obvious error — things just stop updating.
Several Hassbian BBS (综合讨论区) threads exist specifically for recovering from this situation. The fix is to downgrade the firmware back to a supported version, which requires some effort. Enabling firmware lock takes two seconds. Do it during initial setup, not after you’ve already hit the problem.
The option is in the integration’s configuration under the gateway entry in Devices & Services. Look for “Firmware update disable” or “Gateway Firmware Lock” depending on the component version.
Choosing a Zigbee mode: Mi Home, ZHA, or Zigbee2MQTT
Once XiaomiGateway3 is running, you have three options for how the gateway handles its Zigbee radio.
| Mode | What it does | Trade-offs |
|---|---|---|
| Mi Home mode (default) | Zigbee devices stay in Mi Home ecosystem; HA sees them via XiaomiGateway3 | Keeps Mi Home app working for Zigbee devices; most familiar if you’re migrating gradually |
| ZHA mode | Zigbee devices join HA’s native ZHA; Mi Home loses access to these devices and they must be re-paired | Full HA-native control; devices must be re-paired from scratch; Mi Home Zigbee functionality broken for those devices |
| Zigbee2MQTT mode | Uses the EFR32 EZSP chip with Z2M addon | Experimental; EFR32 EZSP over Wi-Fi is marked unstable by the official Z2M project; Chinese users report more disconnects than ZHA |
The ZHA path is the most tested option if you’re moving away from Mi Home entirely. The official Zigbee2MQTT project considers EFR32 EZSP over Wi-Fi unstable, and Chinese community reports back this up — ZHA holds up better on this specific chip in day-to-day operation.
If you’re mid-migration and still using Mi Home for some devices, stay in Mi Home mode initially and switch to ZHA when you’re ready to re-pair everything.
What happens to your BLE and Bluetooth Mesh devices
This surprises people who assume activating ZHA mode breaks everything. It doesn’t.
BLE sensors and Bluetooth Mesh (蓝牙Mesh) devices run on separate radios. They are not affected by the Zigbee mode you choose. Switching to ZHA mode takes your Zigbee devices out of Mi Home — but your BLE temperature sensors, your Mesh lights, all of that continues working in both Mi Home and Home Assistant simultaneously. The XiaomiGateway3 component handles BLE and Mesh device reporting independently.
This means a partial migration is viable: move Zigbee devices to ZHA for full local control, while keeping BLE and Mesh devices running through the gateway in parallel.
Network requirements and known failure modes
A few configuration details that cause silent failures.
Same subnet, no VLAN isolation. Home Assistant and the gateway must be on the same LAN subnet. If you’ve got Home Assistant on a trusted VLAN and IoT devices on a segmented network, the component won’t be able to communicate with the gateway directly. You’ll need either both on the same segment, or firewall rules permitting traffic between the Home Assistant host and the gateway in both directions. The component relies on the gateway being reachable on the LAN and on multicast discovery working between the two, neither of which survives a strict VLAN boundary by default — so if you must segment, allow the full bidirectional flow between those two hosts rather than trying to open a minimal port list.
Wi-Fi channel width and WPA3. 40 MHz channel width and WPA3 security are both known to cause connectivity instability with the gateway. If you’re seeing intermittent drops after setup, try switching the access point to 20 MHz channel width and WPA2 for the gateway’s connection. This isn’t a XiaomiGateway3 limitation specifically — it affects the gateway’s general stability on the network.
Re-pair after mode switch. If you switch from Mi Home mode to ZHA mode, your Zigbee devices do not automatically appear in ZHA. They need to be removed from Mi Home and re-paired from HA’s Zigbee interface. Plan for this if you have a large number of Zigbee devices.
Keeping it running: staying ahead of Mi Home updates
The firmware lock handles the most obvious failure vector, but there are a couple of other maintenance habits worth having.
Don’t leave Mi Home with auto-update permission on the gateway if you’ve disabled firmware lock for any reason. Check the component’s supported firmware list when you update the XiaomiGateway3 component itself — new component versions sometimes expand the supported firmware range, but occasionally drop support for older firmware. Verify your gateway is still in the supported range after each component update.
If you migrate to a new Home Assistant instance, the token will need to be re-fetched. The setup process is the same, but make sure your Mi Home account credentials are accessible.
Who should use this gateway vs a standalone Zigbee stick
If you already own a Multimode Gateway and want local HA control: use XiaomiGateway3. The no-flashing requirement and the multi-protocol coverage make it a reasonable bridge device, especially during a Mi Home to HA migration.
If you’re starting from scratch and you only need Zigbee: a dedicated USB Zigbee coordinator (Sonoff Zigbee 3.0 USB Dongle, HUSBZB-1, or similar) is more straightforward and not tied to Xiaomi firmware compatibility. The Multimode Gateway’s value is the BLE and Mesh coverage alongside Zigbee — if you don’t need those, a standalone coordinator is a cleaner path. Our guide on running Aqara and Xiaomi Zigbee devices in Home Assistant without a hub walks through the coordinator-only route.
For the Central Hub Gateway specifically: outside China, it loses the local-first advantage entirely. For international users, the Multimode Gateway plus XiaomiGateway3 is better value and better privacy posture.
The firmware lock step is the thing that makes this work long-term. The rest of the setup follows a predictable path. Get the firmware version right, lock it before Mi Home gets another update opportunity, and then choose your Zigbee mode based on how much of Mi Home you’re keeping. BLE and Mesh work regardless.