AqaraGateway puts Aqara Zigbee hubs into Home Assistant, but only if you modify the hub first

A Home Assistant integration for Aqara hubs, built on XiaomiGateway3

AqaraGateway is a Home Assistant integration for a specific family of Aqara and Xiaomi hubs, the ones sold as Aqara Gateway and Hub models such as the G2H, M1S CN, P3 CN, M2 CN, H1 CN, E1 CN, G3 CN, G2H Pro, M2 2022, M2 old EU and Global, M1S 2022, and M3. Control is for Zigbee devices from Home Assistant, and gateway support covers Zigbee 3.

The hardware list is given as model numbers, which is the more useful form for a buyer: KTBL12LM, ZHWG15LM, ZHWG12LM, ZNSXJ12LM, ZNSXJ13LM, ZNSXJ15LM, ZHWG19LM, ZHWG20LM, and ZHWG24LM appear in the project description alongside the marketing names.

The lineage matters for understanding the design. The integration was based on the development work of AlexxIT on XiaomiGateway3, and the project credits Alex directly. That is not a courtesy line, it explains the architecture: the integration talks to the hub the way XiaomiGateway3 does, and the hard-won knowledge about those hubs, their MQTT broker, their Zigbee implementation, and their firmware quirks came from that upstream work rather than from reverse engineering done again from scratch.

So the value proposition is specific. Aqara sells cloud-connected hubs that work well inside its own app and poorly outside it. This project takes the hub you already own, or can buy cheaply as a used or regional model, and makes it a local Zigbee gateway that Home Assistant can talk to directly.

The hard requirement: modified firmware or a hub with telnet turned on

This is the constraint that decides whether the project is for you, and the project states it in bold.

The component only works on modified firmware (M2) or on a gateway which had telnet enabled. That is not a preference or a recommendation, it is the mechanism. The integration needs shell access on the hub to reach the internal MQTT broker and the Zigbee stack, and the stock firmware does not expose that.

The second warning is about time. The Lumi company, which makes Aqara, started disabling the post_init script. The instruction is blunt: if you still want to use this component, do not update to the latest firmware of the gateway or hub. If you already updated and telnet is not working, you need to switch to Mi Home mode and enable telnet by the soft_hack method, then flash modified firmware.

That is a real operational cost. The integration you install is a consumer of a firmware state, and the vendor is actively removing that state. Any upgrade you make for security will eventually break the integration, and the project asks you to accept that trade.

What you get in exchange is control that does not depend on the vendor's cloud service, with your Zigbee devices visible to Home Assistant as entities you can automate.

If you are unwilling to hold a device on old firmware permanently, this is the wrong project, and no amount of configuration will change that.

Flashing the M2 and H1 means opening the case and wiring out UART

For the M2 and the H1 Switch Hub, the route to modified firmware is physical. The project points you at AqaraGateway.exe, a Windows tool hosted in the companion firmware repository, and requires you to open the case of the gateway and wire out the UART pins. There are wiring diagrams in the repository for both the M2 and the H1.

This is not a casual operation. Opening the product voids whatever warranty it had, and soldering to UART is the step where a mistake becomes an expensive brick. The cost of entry is a soldering iron and a steady hand, and the failure mode is a hub that no longer boots.

For the M1S CN, the AirCondition P3 CN, the Hub E1 CN, and the Gateway M1S 2022 CN, there is a softer path. Switch to Mi Home mode and get the token using the xiaomi-cloud-tokens-extractor tool. That approach avoids opening the case and avoids the flashing step, because the token route only needs the Mi Home account credentials rather than physical access to the board.

So the project offers two tiers of involvement, and picking the cheaper one is sensible. If your model appears in the second group, use the token route. If it does not, and you are not prepared to solder, this integration is not going to happen for you, and the honest answer is to use a different gateway.

Enabling telnet manually, and the click sequence that starts it

Where flashing is not required, telnet can be enabled by hand. The project calls this good news and gives a specific recipe, described as a sequence of 5 clicks, pause, 2 clicks, pause, and so on, taken from an issue discussion in the XiaomiGateway3 tracker. The point of the odd sequence is that it is a hidden service gesture in the hub's own interface.

That method has a version limit too. Lumi removed the set_ip_info method in the newer M1S firmware, Mi version 4.0.3_0012 and Aqara version 3.5.2_0010.0636, and other hubs also lost it. If you already upgraded to that version, the project says the only way to enable custom firmware is AqaraGateway.exe, or gw_global_tool to clean the password and flash custom firmware.

There is also a custom open telnet command approach, using way 2 or way 3, which enables telnet in Mi Home mode and then lets you flash modified firmware to the M1S, P3, and E1 if you want to use them in Aqara Home. That route needs no case opening.

After telnet into the gateway via putty, there are two methods: flash, or do not flash. The do-not-flash methods install an MQTT broker and a startup script on the hub, which is the topic of the next section.

The no-flash method installs mosquitto and a post_init script on the hub

The no-flash route does the work over telnet by pushing two things onto the hub filesystem: a mosquitto binary, which is the MQTT broker the integration talks to, and a post_init.sh script, which is the hook that starts it at boot.

For the hubs outside the excluded group, meaning anything other than the G2H, E1 hub, G3, G2H Pro, M2 2022, and M3, the commands create the directories, download curl and mosquitto, and drop the post_init script:

mkdir /data/bin
cd /data/bin
wget -O /data/bin/curl "http://master.dl.sourceforge.net/project/mgl03/bin/curl?viasf=1"; chmod +x /data/bin/curl
/data/bin/curl -s -k -L -o /data/bin/mosquitto https://raw.githubusercontent.com/niceboygithub/AqaraM1SM2fw/main/binutils/mosquitto; chmod a+x /data/bin/mosquitto

mkdir /data/scripts
cd /data/scripts
/data/bin/curl -s -k -L -o /data/scripts/post_init.sh https://raw.githubusercontent.com/niceboygithub/AqaraM1SM2fw/main/binutils/post_init.sh
chmod +x /data/scripts/post_init.sh

You then restart the gateway with the reboot command.

The G2H variant differs only in where curl is written, to /tmp/curl, and which mosquitto build is fetched, from the aqarahub SourceForge path and the AqaraCameraHubfw repository. The G2H Pro and the E1 hub, G3, M2 2022, and M3 group go further and add a two-line startup script that calls fw_manager.sh to remove and then check the firmware, plus chattr +i to make the scripts directory and the post_init script immutable, so the vendor's own tooling cannot easily overwrite what you just installed.

That immutability bit is the clearest signal of the intent. The hub will try to repair itself, and the method is to prevent it.

HACS installation and a configuration flow that needs an IP and a token

Once the hub is prepared, installing the integration itself is ordinary Home Assistant work.

The supported route is HACS. You add a custom repository with the URL niceboygithub/AqaraGateway, set the category to Integration, and install it from the Integrations screen. The alternative is to download the project and copy the custom_components/aqara_gateway folder into the custom_components folder of your Home Assistant config directory.

Configuration is then a guided flow. In Configuration, then Integrations, then Add Integration, you search for Aqara Gateway. If the integration does not show up in the list you refresh the page, and if it is still missing you clear the browser cache. You enter the gateway IP address, and if you applied a telnet password on the gateway you enter that password, otherwise you ignore the field. If it is the first time you are adding the integration you enter the Xiaomi token of the gateway, otherwise you ignore that field too. Then you click Send and wait for the configuration to complete.

Two fields being optional and one being needed only on first add is the sort of detail that trips people up, so the flow reads a little denser than a typical Home Assistant integration.

For further detail there is a linked write-up by InsaneWookie, and the project also links a keytool-free set of useful links in its own resources.

A project with an unknown licence and a slow release cadence

Two facts about the project should shape how you adopt it.

First, the licence field shows no value, and the repository carries a hacs.json file for HACS publishing, a project description file, a system_health.png image, and the custom_components directory. An unknown licence is a genuine blocker if you intend to redistribute the code or build something on top of it, because without terms you have no permission to do either. If you only want to run it on your own hub and it stays on your own network, this matters much less, but it is still an unresolved question rather than a permissive one.

Second, the release rhythm is slow and the last release is old. The tagged versions are 0.3.3 on 2026-02-23, 0.3.2 on 2025-05-31, and 0.3.1 on 2025-05-27. The last push to the repository was on 2026-09-28, so there is recent work, but it is not being cut into releases on a schedule.

For a Home Assistant custom component, that pattern is common and often acceptable, since installation goes through HACS from a branch rather than from a release artefact, and fixes land in the repository rather than in a tagged version. But it does mean you are tracking a moving branch on hardware that you have been told not to update.

The pragmatic reading is that this is a project for people who already run custom Home Assistant components and accept that they will debug at odd hours when a hub update or a Home Assistant release changes something. For anyone who wants a supported product with a support policy, the vendor's own app is the only answer.

Editorial conclusion

AqaraGateway fits a Home Assistant user with an Aqara hub on an older firmware who wants local Zigbee control without the vendor cloud, and who is comfortable with telnet and firmware flashing. It does not fit someone on current hub firmware, since the vendor removed the post_init script and the project tells you not to update. Before installing, check your hub model against the supported list and decide whether you are prepared to run modified firmware with the vendor's updates switched off, because that is the trade the project asks you to make rather than a detail it can hide.

Frequently asked questions

Official sources

1. Issues
2. niceboygithub/AqaraGateway on GitHub
3. README
4. Releases