ZHA vs Zigbee2MQTT for Aqara Devices: Which to Pick?

If you’re setting up Aqara Zigbee devices in Home Assistant without a hub, you’ll hit this fork in the road pretty quickly: ZHA or Zigbee2MQTT? Both are fully local, both are well-maintained, and both work with the same USB coordinators. The generic comparison articles don’t help much here because they treat Aqara as just another brand. The reality is that Aqara devices have some specific quirks, attribute gaps, and community support patterns that make the choice non-trivial for certain device categories.

I’ve spent time with both stacks across a range of Aqara hardware and the short version is: for most people with common sensors, ZHA is fine. If you’re running anything more complex — presence sensors, the Cube T1 Pro, vibration sensors — Zigbee2MQTT gives you meaningfully more control. The long version is below.

If you haven’t picked a coordinator yet, start with our guide to running Aqara Zigbee devices in Home Assistant without the Aqara hub, then come back here to choose the integration layer.

The Quick Answer

Before getting into the detail, here’s a decision table. If you recognize yourself in one of these profiles, you can stop reading here.

Neither choice locks you into cloud. Both integrations are entirely local once you’re up and running, the same way the Aqara hardware itself keeps working without internet.

What ZHA Is and How It Handles Aqara Devices

Setup path

ZHA is part of Home Assistant core. No extra add-ons, no broker. You plug in a compatible coordinator — a Home Assistant SkyConnect, a Sonoff Zigbee 3.0 USB Dongle Plus, a HUSBZB-1 — and configure ZHA directly from the HA integrations UI. Pairing a new device is a matter of putting it in pairing mode and watching HA pick it up. That’s genuinely the whole thing.

For anyone who wants Zigbee in HA with minimum configuration overhead, ZHA’s setup path is hard to beat.

Quirks — what they are and which Aqara devices need them

Aqara Zigbee devices frequently deviate from ZCL (Zigbee Cluster Library) standards. This is a recurring pattern with budget and mid-range Zigbee hardware: vendors implement proprietary attribute reporting, non-standard cluster usage, or custom scene-cluster events to get features out without full spec compliance.

ZHA handles this through a “quirks” system — device-specific override code packaged into the ZHA integration (the quirks originate in the zha-device-handlers project and ship as the zha-quirks library). A quirk teaches ZHA how to interpret a particular device’s non-standard behavior and surface the right entities. Without a matching quirk, you might get a device that pairs successfully but only exposes a handful of generic Zigbee attributes rather than all its sensors and controls.

The coverage is solid for Aqara’s mainstream lineup. Contact sensors, basic motion sensors (MS-S02, MS-S01), and temperature/humidity sensors (WSDCGQ11LM and similar) have well-established quirks and pair cleanly. Where ZHA starts to show gaps is on newer or more complex devices — more on that below.

What ZHA exposes for common Aqara sensors

For the core sensor categories, ZHA delivers what you’d expect:

• Contact sensors — open/closed state, battery level, tamper in some models
• Temperature/humidity — temperature, humidity, pressure where supported
• Standard PIR motion — motion state, battery
• Buttons and remotes — action events, battery

What you typically don’t get through ZHA on more capable Aqara devices is the deeper configuration layer: sensitivity adjustments, detection interval settings, absence delays. Those parameters exist in the device firmware and are exposed over Zigbee — but accessing them requires either a matching quirk that exposes the config cluster, or a stack that reads them natively. ZHA does neither for most Aqara devices.

What Zigbee2MQTT Is and How It Handles Aqara Devices

Setup path (MQTT broker + Z2M add-on)

Zigbee2MQTT runs as a standalone bridge. It talks to your Zigbee coordinator on one side, and to Home Assistant via MQTT on the other. In practice, this means two add-ons: Mosquitto MQTT broker and Zigbee2MQTT itself. Both need to be running for Zigbee to work.

That’s more moving parts. An HA restart doesn’t interrupt the Z2M bridge process — it keeps running — so your Zigbee network stays stable even while HA reloads. But there are more logs to check, more configuration files to understand, and more potential failure points when something goes wrong.

The Z2M add-on includes its own web frontend, which is where a lot of the value lives. You can inspect every paired device, read and write configuration attributes, trigger OTA updates, and watch raw MQTT traffic — all without touching HA’s UI.

Converters — how they differ from quirks

Z2M’s equivalent of ZHA’s quirks is its converter system. Each supported device gets a converter file that maps its specific Zigbee attributes and clusters to the entities Z2M exposes via MQTT. The converter also defines which configuration parameters are writable from the frontend or via MQTT commands.

The community around Z2M’s converter library is active and fast-moving. When a new Aqara device ships, a converter typically appears within days to a few weeks, driven by community contributors who have the hardware. ZHA quirks for the same device can lag by weeks to months, depending on whether someone with the hardware submits a pull request. For recently released Aqara devices, this gap is often the deciding factor.

What Z2M exposes that ZHA does not

This is the meaningful difference for Aqara users. Where Z2M has a mature converter, the configuration depth is significantly greater than what ZHA exposes for the same device. Examples from the Z2M device library:

• Presence sensors (FP300) — motion sensitivity, absence delay, detection zone configuration, PIR detection interval. None of these are accessible via ZHA without custom quirk development.
• Motion sensors — some models expose LED scheduling, sensitivity levels, and detection interval through Z2M’s frontend. ZHA surfaces state and battery only.
• Temperature/humidity sensors — some models allow calibration offsets (e.g. +0.5°C to compensate for sensor placement near heat sources). Z2M exposes these. ZHA typically does not.

If you’re building automations that depend on tuning device behavior rather than just reading state, that configuration access is the actual reason to choose Z2M. Our FP300 Zigbee2MQTT setup walkthrough shows what that configuration depth looks like in practice.

Head-to-Head: Aqara Device Categories

Simple sensors — contact, temp/humidity, standard motion

For this category, both stacks reach functional parity for day-to-day use. You get all the state entities you need. ZHA’s setup is faster. Z2M gives you the calibration offsets and a few extra configuration fields, but if you’re not chasing those, they don’t matter.

Verdict: ZHA is fine. Z2M is also fine. Pick on setup preference.

Complex sensors — FP300, Cube T1 Pro, vibration (DJT11LM)

This is where the stacks diverge.

The Cube T1 Pro uses a proprietary action encoding for its rotation, flip, and tap events. Z2M’s converter decodes these into clean action entities — rotate_left, flip_to_side, shake, and so on. ZHA requires a matching quirk to decode the same events; without it, you get generic ZCL attribute reports that don’t map to the cube’s gesture set.

The vibration sensor DJT11LM sends scene-cluster events rather than standard ZCL vibration attributes. Z2M handles this correctly, exposing vibration, tilt, and drop actions. Under ZHA, a missing or incomplete quirk means you may get the vibration entity but miss the tilt and drop events.

The FP300 presence sensor is the clearest example of Z2M’s advantage. The detection zone configuration, sensitivity adjustment, and PIR interval that make the FP300 genuinely useful are all accessible through Z2M. Under ZHA, you can get presence detection, but the tuning layer that lets you adapt it to your specific room is not available.

Verdict: Z2M wins clearly for this device category.

Switches and buttons

Aqara wall switches and wireless mini-switches are generally well-covered by both stacks. Single and double-press events, hold events, and multi-gang state reporting work in both. The edge cases tend to be around newer firmware versions or newer switch variants where Z2M’s converter library picks up support before a ZHA quirk is available.

OTA firmware updates are supported by both integrations for many Aqara switches, though Z2M’s OTA coverage is broader. There are exceptions worth knowing about: the FP300, for example, still has no OTA support in Z2M as of 2026, so its firmware has to be updated through the Aqara app and then re-paired to Z2M. Gaps like this usually close eventually, but not always quickly — check the device’s Z2M page before assuming OTA is covered.

Verdict: Mostly parity. Z2M has an edge on newer device support and OTA breadth.

Migration Cost — What It Takes to Switch Later

If you start with ZHA and later decide you want Z2M (or vice versa), the switching cost is real: you have to re-pair every device. Zigbee network state is not portable between the two stacks. There is no migration tool that moves paired devices from a ZHA network to a Z2M network.

For a small setup — ten to fifteen devices — re-pairing is annoying but manageable in an afternoon. For a setup with forty or sixty sensors spread across multiple rooms, it’s a meaningful project. You’ll also lose any device-specific entity history tied to the old integration’s entity IDs.

This means it’s worth getting the decision right upfront rather than treating it as easy to reverse later. If you have any advanced Aqara devices in your plans, starting with Z2M from the beginning avoids a re-pairing project later.

Which Should You Pick?

The framing I find useful is complexity tolerance versus configuration need.

Choose ZHA if:
– You’re running fewer than ~30 devices
– Your Aqara hardware is mostly contact, motion, and climate sensors
– You want the fastest possible path to a working integration
– You’re new to Home Assistant and want to limit variables
– You don’t already have Mosquitto MQTT running for other purposes

Choose Zigbee2MQTT if:
– You’re running or planning to run presence sensors (FP300, FP2), the Cube T1 Pro, or vibration sensors
– You want device-level configuration access — sensitivity, intervals, calibration offsets
– You’re building a larger mesh and want Z2M’s network visualization and diagnostics
– You want faster support for newly released Aqara devices
– You’re already running MQTT in your stack

One thing worth being clear about: neither integration is more “local” than the other. Both run entirely on your own hardware with no cloud dependency, which is the same reason Aqara devices keep working without internet regardless of how you integrate them. If local control is your primary concern, that concern is satisfied by either choice. The decision is about feature depth and operational complexity, not about privacy posture.

If you’d rather keep an Aqara hub in the mix instead of a USB coordinator, see our guides to the Aqara Hub M3 as a Matter bridge and the Aqara Hub E1 local integration — those take a different path to the same local-control goal.

Frequently Asked Questions

Can I run ZHA and Zigbee2MQTT at the same time?

Not on the same coordinator. Each stack needs exclusive access to the coordinator’s serial port. You can run them on separate coordinators (one USB dongle each), but that means two separate Zigbee networks and no device portability between them. In practice, almost nobody does this — pick one and run all your devices through it.

Do I need an Aqara hub if I use Zigbee2MQTT?

No. Z2M (and ZHA) replace the Aqara hub entirely. You pair your Aqara Zigbee devices directly to your USB coordinator. The Aqara hub, M2 or M3, is a Zigbee coordinator in its own right — when you use Z2M or ZHA with a USB dongle, the Aqara hub is not in the picture at all. For the full no-hub setup, see our Aqara without the hub guide.

Which integration exposes more Aqara device settings?

Zigbee2MQTT, in most cases. For devices where a mature Z2M converter exists, you get writable configuration attributes — sensitivity, intervals, calibration offsets — through Z2M’s frontend or via MQTT commands. ZHA exposes these only when a matching quirk implements the configuration cluster, which is less common for Aqara’s more complex devices.

How hard is it to migrate from ZHA to Zigbee2MQTT?

It requires re-pairing all your devices. There is no migration path that preserves your existing Zigbee network state. Plan for the re-pairing effort based on device count — small setups can manage it in a few hours, larger ones will take longer and risk losing entity history in HA. Start with the right stack to avoid it.

Does ZHA work with the Aqara FP300 and FP2?

Both devices pair under ZHA and report presence state. What ZHA does not give you is the configuration layer — the sensitivity adjustment and detection interval settings that let you tune the sensors to your room. If you’re happy with default settings and just want a presence/absence entity, ZHA works. If you want the full configuration, Z2M is the better fit for these sensors.