If you’re running an Aqara hub locally through HomeKit Controller, you’ve probably already hit its ceiling. Our M2 setup guide covers that path, and it’s a solid baseline. But HomeKit Controller only exposes what HomeKit itself understands, and the hub’s IR blaster isn’t part of that. It has no Home Assistant representation through HomeKit or Matter at all. Button-press events also arrive more sluggishly than they should.
That gap is what AqaraGateway (niceboygithub/AqaraGateway), a community HACS integration, is built to close. It reaches the hub over a local API on your own network, a telnet session to the hub itself, rather than going through HomeKit Controller or Aqara’s cloud. The problem is that telnet on Aqara hubs was never an official feature. It’s a developer-mode door Lumi has been gradually closing, and how hard it is to open depends on which hub you own and, it turns out, on when yours was built.
This is not a step-by-step guide to enabling telnet or flashing anything. That procedural depth already lives in the project’s own repositories, and duplicating it here would mean restating instructions I haven’t run myself. What follows is the decision framework instead: what you gain, what it costs by hub model, and what’s still genuinely uncertain.
This article is sourced from the AqaraGateway project’s README, its companion firmware repositories, and its GitHub issue tracker, not from hands-on testing on our bench. Where a claim comes from a single user report rather than the project’s own documentation, it’s flagged as such.
What AqaraGateway actually adds over HomeKit Controller
Per the project’s own README, AqaraGateway handles the same Zigbee child-device control HomeKit Controller already gives you, plus entity types HomeKit doesn’t carry.
- The hub’s IR blaster, so AC units and other IR remotes can be driven from Home Assistant. HomeKit and Matter expose no IR path at all, which is why our M2 HomeKit Controller guide tells readers to budget for a separate IR bridge.
- Button-press events handled more reliably, without the delay and occasional missed presses users report through the HomeKit path.
- Richer telemetry from the FP1 presence sensor, including directional movement states HomeKit Controller doesn’t surface.
One thing frequently listed as an AqaraGateway exclusive is not one: the hub’s alarm panel. Paired through HomeKit Controller, an Aqara hub already appears in Home Assistant as an alarm_control_panel entity. Our M2 HomeKit Controller guide documents it, including the quirk that you disarm it by switching between armed modes rather than setting it to off. If the alarm panel is the only reason you’re weighing telnet access, you already have what you’re after.
None of the rest is exotic. It’s the stuff people notice is missing after they’ve already set up the hub and started building automations around it. If your setup doesn’t touch IR devices or FP1 presence zones, there’s genuinely nothing here for you, and HomeKit Controller remains the simpler, fully-supported path.
One scope check before going further. The README’s supported-hardware list is specific: it names the M1S, the P3 air-conditioning controller, the E1 and the M1S 2022 in their CN forms, with the M2 and H1 supported by flashing modified firmware. If your hub shipped on global firmware, confirm your exact model appears on that list before planning around any of this. Our Hub E1 guide covers how the CN and global firmware variants diverge and which integration path suits each.
The catch: telnet access isn’t official, and Aqara keeps closing it off
Getting AqaraGateway working requires telnet on the hub itself. The README is blunt about why that keeps getting harder: Lumi has been disabling the post_init script the project depends on, and the project’s guidance is not to update your gateway’s firmware if you want the integration to keep working.
Per the AqaraGateway README, updating hub firmware after telnet access is enabled can break that access, with no guarantee a workaround follows for your specific hardware. Going this route opts that hub out of Aqara’s normal update cycle for as long as you want AqaraGateway to keep working.
That lock is about the hub’s own firmware. Updating the firmware on your Zigbee end devices is an entirely separate mechanism, covered here, and it has nothing to do with hub telnet access — the two get conflated often enough to be worth separating.
How much risk depends on which hub you own
“Enable telnet” sounds like one task. The actual method, and the risk that comes with it, varies sharply by model and by how recently the unit was manufactured.
| Hub model | Method | Risk tier |
|---|---|---|
| G3, G2H Pro | Downgrade to pre-patch firmware 3.3.4 by booting a prepared SD card | Moderate — software-only, but locks the hub to 3.3.4, and some G2H Pro owners report telnet still refused afterwards |
| M3 built before 2024.1 | Flash modified firmware from a FAT32 USB stick using the front button | Moderate — software-only, nothing gets opened |
| M3 built after 2024.1 | Firmware route closed by Lumi; UART only | High — hardware modification |
| M2, H1 | Open the case, wire out the UART pins, flash modified firmware over xmodem | High — hardware modification with real bricking risk |
The G3 and G2H Pro path is a firmware downgrade rather than a teardown, and so is the M3 route for units built before 2024.1: the maintainer’s M3 telnet notes describe copying two firmware files to a FAT32 USB stick and holding the front button through boot. The M2 and H1 are a different commitment. The project’s flashing tool moves firmware over xmodem, which means wiring the hub’s UART pins out to a USB-TTL adapter, which means opening the case.
The M2 and H1 method requires opening the hub’s case and wiring directly to its UART pins to flash modified firmware over a serial link. This is board-level work, not a software toggle, and carries genuine bricking risk. If you aren’t comfortable with a USB-TTL adapter and a soldering iron, this isn’t your entry point.
The M3 deserves its own note, because the usual community answer to “can you still telnet into it” is that nobody knows. That isn’t quite right. The maintainer’s M3 notes document the USB-stick method and then say plainly that Lumi fixed the underlying vulnerability, so units manufactured after January 2024 can’t use it and are left with the UART route. A GitHub issue asking the same question, open since September 2024 with no recorded answer, is probably why “unconfirmed” became the standing verdict. Confirmed-but-expired is the more accurate description: the easy route exists, and a hub bought new today is almost certainly past it.
If you’re choosing an M3 specifically to run AqaraGateway, assume you’ll receive a post-2024 unit and therefore the UART route, not the USB one. Manufacturing date isn’t something you can pick off a retail listing. Our M2 versus M3 comparison covers what each hub does through the supported integrations, which is a safer basis for a purchase decision.
That M2 versus M3 breakdown is here, and it’s the more conservative read on both hubs.
Even doing everything by the book doesn’t guarantee a working result. One user who successfully flashed custom firmware on an M1S still hit an authentication timeout trying to connect the integration afterwards, and the thread was closed without a documented fix. Getting the firmware step right is necessary, but it isn’t sufficient.
Is it worth it? A decision framework, not a recommendation
I think the risk asymmetry is the actual story here, more than the feature list. Two people can end up running the identical integration having taken completely different risks: one booted a USB stick, the other opened a case and soldered onto a serial header. The feature list doesn’t distinguish between them at all, and the feature list is what every write-up leads with.
Here’s a rough way to think about it, broken down by hub.
- If you want the IR blaster or richer FP1 data, own a G3, G2H Pro, or a pre-2024 M3, and are fine locking that hub out of future firmware updates, the case for trying this is reasonable.
- If you want those entities but own an M2 or H1, weigh them against board-level hardware work with bricking risk, on a device that’s otherwise working fine.
- If you’re buying an M3 now, plan for the UART route or don’t plan on AqaraGateway at all.
- If IR control is the entire motivation, a separate IR bridge is the lower-risk answer. It costs money instead of risk, and it’s what our M2 HomeKit Controller guide already recommends for exactly this gap.
- If you mainly want more reliable button events, check whether recent HomeKit Controller or Home Assistant releases have narrowed that gap before taking on telnet access at all.
FAQ
What is AqaraGateway and how is it different from the official Aqara/HomeKit Controller integration?
AqaraGateway is a community-maintained HACS integration that reaches an Aqara hub over telnet on your local network. HomeKit Controller, by contrast, uses Apple’s HomeKit protocol and only exposes what HomeKit itself models. The practical differences are the hub’s IR blaster and richer FP1 telemetry, which HomeKit doesn’t carry at all. The alarm panel is not one of them. HomeKit Controller exposes that already.
Do I need to root or modify firmware on my Aqara hub to use AqaraGateway?
It depends on the model, and for the M3 on the build date. G3 and G2H Pro hubs need a firmware downgrade booted from an SD card. An M3 built before January 2024 can be flashed from a USB stick. M2 and H1 hubs need the case opened and modified firmware flashed over UART, which is a hardware modification rather than a software step.
Can I still get telnet access on a new Aqara M3 hub?
Only on older units. The maintainer’s M3 notes document a USB-stick firmware flash and state that Lumi fixed the vulnerability, so units produced after January 2024 can’t use that route and are left with UART. The open GitHub issue asking this question still carries no answer, so check the project’s current tracker before assuming anything about a specific unit.
Will updating my Aqara hub’s firmware break AqaraGateway once it’s working?
Per the project’s own README, yes, potentially, and without a guaranteed fix — Lumi has been progressively disabling the script the integration depends on. The project’s explicit guidance is not to update hub firmware once telnet access is enabled.
Is HomeKit Controller or AqaraGateway the better starting point for local control?
HomeKit Controller, covered in our M2 guide, is the lower-risk starting point for most readers, and it already includes the alarm panel. AqaraGateway is worth considering specifically for the IR blaster, richer FP1 telemetry, or more reliable button events, and only after you’ve priced the firmware lock or the hardware modification for your particular hub.
What this research verified, and what still depends on the project
This piece draws on the AqaraGateway README, the maintainer’s companion firmware repositories, and the two GitHub issues linked above, not on hands-on testing on our bench. The entity list and the per-model setup methods come from that documentation. The M1S authentication-timeout report and the unanswered M3 issue are individual threads, real and sourced, but not confirmed as general patterns. One claim I checked against our own published coverage rather than the project’s is the alarm panel: HomeKit Controller exposes it, so it doesn’t belong on the AqaraGateway side of the ledger no matter how often the summaries put it there.
Both HomeKit Controller and AqaraGateway keep hub communication on your own network, without routing through Aqara’s cloud, so that part stays local either way. What doesn’t change is that AqaraGateway is a community project maintained outside Aqara, its continued functioning depends on Lumi not closing the telnet path entirely, and firmware updates are the thing most likely to break it. If you’re considering this, read the current state of the project’s wiki and its issue tracker yourself before opening a case or downgrading anything. Both move faster than any single article can track.