Multimode Gateway 2 is supported and Xiaomi Gateway 2 is not, and only Token firmwares write a key to disk

Multimode Gateway 2 works and Xiaomi Gateway 2 does not

The support table is the first thing to read, because two of the names differ by one word and sit on opposite sides of it.

Supported: Xiaomi Multimode Gateway, known as Gateway 3, in the CN version ZNDMWG03LM and the EU versions ZNDMWG02LM and YTC4044GL. Also Xiaomi Multimode Gateway 2, in the CN version DMWG03LM and the EU versions ZNDMWG04LM and BHR6765GL. Also Aqara Hub E1 in the CN version ZHWG16LM.

Not supported: Xiaomi Gateway 2 in the CN version DGNWG02LM, which is pointed at the official xiaomi_aqara integration instead, and Xiaomi Gateway in the EU version DGNWG05LM, which is pointed at openlumi. A further row collects Aqara Hub E1 in the EU version HE1-G01, Aqara G2H, Aqara H1, Aqara M1S, Aqara M2 and Aqara P3, all pointed at a different community project.

The Aqara line splits the same way: the CN Hub E1 is on the supported list while the EU Hub E1 is in the row of models that are not. Buying on the region alone is not enough to tell whether a hub will work.

Firmware 1.4.6 to 1.4.7 may work and issues are closed on them

The firmware table pairs each gateway with the access it needs:

* Xiaomi Multimode Gateway, CN and EU, firmwares 1.5.0 to 1.5.4 need only a token. * Xiaomi Multimode Gateway 2, CN and EU, firmwares 1.0.3 to 1.0.6 need only a token. * Aqara Hub E1, CN, firmware 4.0.1 needs only a token. * Xiaomi Multimode Gateway, CN and EU, firmwares 1.5.5 to 1.5.6 need a token and a key. * Xiaomi Multimode Gateway 2, CN and EU, firmware 1.0.7 needs a token and a key.

Below the table sits the recommendation: 1.5.4 to 1.5.6 for the first gateway, 1.0.6 to 1.0.7 for the second, and 4.0.1 for the Hub E1. So the recommended range straddles both access levels, which is the practical version of the table.

One band is explicitly excluded. Firmwares 1.4.6 to 1.4.7 for the first gateway may work but are marked unsupported, with a request not to open issues if something does not work on them. That is a deliberate support boundary rather than an oversight, and it matters for anyone whose hub shipped on those revisions and refuses to update.

Only Token firmwares get a key written to keys.json

The note under the firmware table explains what happens on the easier half of the matrix. For only Token firmwares the integration will get the key automatically, and save it to the integration settings and to a file under the Home Assistant configuration directory:

/config/.storage/xiaomi_gateway3/keys.json

The note ends with a request to save it safely somewhere else. That is the whole security surface of this component in one sentence: a long lived device key is written into the storage folder that Home Assistant keeps its own configuration in, in plain form, and the user is the backup.

That is also why the token and key split matters beyond convenience. On 1.5.4 and lower, on 1.0.6 and lower, and on Hub E1 4.0.1 and lower, the component only needs the Mi Home device token and does the rest. On the newer firmware revisions it needs both, which is a different procedure rather than a smaller one. The README has a dedicated section for obtaining the token and points at it from the firmware table.

Aqara Hub E1 past 4.0.1 has no documented solution at all

A second table answers the question the first one raises: how to get a key when the firmware wants one. Its rows are situations rather than models, and three of them point outside the repository.

For firmware 1.5.4 and lower, 1.0.6 and lower, or Hub E1 4.0.1 and lower, the answer is to set up the integration and use only the token. For a gateway on 1.5.5 or later that shipped from the factory with 1.4.6 or lower, and for a gateway that worked before the firmware was updated to the latest, the answer is a button click method documented as an issue in a different repository, AlexxIT/Blog issue 13. For a gateway on 1.5.5 or later that never worked, and for the second gateway on 1.0.7 or later that never worked, the answer is UART, documented as issues 1057 and 1166 in this repository.

The last row is the one with no answer. Aqara Hub E1 on firmware 4.0.4 and more, never having worked, is listed as no solution. Since the supported firmware table stops at 4.0.1, that model has both a ceiling and no documented way past it.

Two firmware-opening write-ups, one of them from an unnamed author

Getting Telnet open is a separate matter from the component itself, and the acknowledgements at the top of the README name two sources. One is a community post by @Serrj explaining how to enable Telnet on old firmwares. The other is a pasted page credited to an unknown researcher, explaining how to open Telnet on new firmwares.

For Xiaomi Multimode Gateway there are then two optional extras, both links into a third repository: an optional firmware update over Telnet, and an optional install of custom firmware from the same tree. The sentence that follows them asks readers not to ask why it is needed.

So the full picture for a new gateway is spread over three places: this repository for the component and its compatibility tables, an issue thread in AlexxIT/Blog for the button method, and a gist with no named author for opening Telnet on current firmware. The component itself needs none of this on the only Token firmwares, which is the version of the setup most readers will meet first.

The default Zigbee mode splits device support between Mi Home and Hass

The gateway's Zigbee chip can work in three modes, and the choice decides where a device appears.

The default is Mi Home. In that mode Xiaomi and Aqara Zigbee devices are supported at the same time in Mi Home and in Home Assistant, while some Zigbee devices from other brands are supported only in Home Assistant. That second clause is the one to plan around: a mixed-brand setup works, but a third-party device may exist only on the Home Assistant side, so moving between the two apps shows different inventories.

The second mode named is Zigbee Home Automation, and Zigbee2MQTT has its own section further down. The table of contents is twenty four entries long for a single component, covering installation, configuration, network configuration, regional restrictions, a statistics table, gateway controls, three levels of advanced config, both Zigbee modes, custom Zigbee firmware, button actions, BLE locks, obtaining the device token, running against several Home Assistant instances, disabling the buzzer, how it works, troubleshooting, debug mode and an FAQ.

A HACS manifest, a custom_components directory and print_models.py

The repository is laid out the way a Home Assistant custom component is expected to be. The README opens with a HACS badge, the Home Assistant Community Store, and the tree carries a hacs.json manifest and a custom_components directory. There is no build step to run and no package file to install.

The rest of the root is small enough to enumerate: DEVICES.md at the top level, assets/, tests/, print_models.py, LICENSE.md rather than a file named LICENSE, and .github/ for the issue and pull request templates that a project of this shape needs.

Release naming is the other convention worth noting. The three most recent tags are v4.2.4, v4.2.3 and v4.2.2, and each release title carries its own date, for example v4.2.4 - 2026-09-16. The dates run 2026-09-16, 2026-09-03 and 2026-09-01, and the default branch is master with a push on 2026-10-01, so the branch is running ahead of the last tagged build. The component is distributed under the MIT license.

Editorial conclusion

XiaomiGateway3 fits someone with one of the five supported gateway models who wants their Xiaomi and Aqara Zigbee devices inside Home Assistant without replacing the stock firmware. Four things to check before you install it. Model names are a trap, because Xiaomi Multimode Gateway 2 is supported while Xiaomi Gateway 2 is not. Firmware revisions decide how much access the component needs, since 1.5.5 and later on the first gateway and 1.0.7 on the second want a token and a key, and on the older ones the integration fetches the key itself and writes it to a file inside the Home Assistant configuration directory. Firmware 1.4.6 to 1.4.7 may work but issues are closed on them. And the procedures for the newer firmwares are not in this repository at all; they live as issue threads in another repository. Releases carry their date in the tag name, with v4.2.4 dated 2026-09-16, and the branch was pushed on 2026-10-01.

Frequently asked questions

Official sources

1. AlexxIT/XiaomiGateway3 on GitHub
2. Issues
3. License: MIT
4. README
5. Releases