ZHA vs Zigbee2MQTT for Aqara Devices: Which to Pick?

ZHA and Zigbee2MQTT both provide local control of supported Aqara Zigbee devices. ZHA is built into Home Assistant; Zigbee2MQTT runs separately and uses an MQTT broker. The useful comparison is how each handles the exact devices and settings you need.

For basic contact and temperature sensors, either can be a good fit. For a more complex device, compare its exposed settings and actions on your installed versions before choosing. Brand-wide claims about one integration having every feature are unreliable.

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

Use this as a starting point, then check support for your exact models:

Local Zigbee communication works with either integration. Our internet-outage guide explains which other parts of a setup may still rely on external services.

What ZHA Is and How It Handles Aqara Devices

Setup path

ZHA is part of Home Assistant. Connect a supported coordinator and add the integration from Settings > Devices & Services. It does not require a separate MQTT broker. Use the current ZHA documentation to check coordinator support and firmware.

Quirks — what they are and which Aqara devices need them

Some Aqara devices report manufacturer-specific attributes or actions that generic Zigbee handling does not interpret correctly. That does not mean every Aqara product has the same limitation.

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.

Many common Aqara sensors have established device handlers. Check the exact model and firmware when a feature is missing; similar product names can map to different handlers.

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

Configuration entities depend on the device handler. ZHA can expose sensitivity, intervals, and other settings when a matching quirk implements them. Compare the device page and current handler rather than assuming ZHA only provides state and battery.

What Zigbee2MQTT Is and How It Handles Aqara Devices

Setup path (MQTT broker + Z2M add-on)

Zigbee2MQTT talks to the coordinator and publishes device data to an MQTT broker. On Home Assistant OS, these can run as separate apps; other installations may use containers or separate hosts. Home Assistant’s MQTT integration consumes the data.

Running the bridge separately means a Home Assistant restart does not normally restart Zigbee2MQTT. The broker and bridge still need to remain available, and Home Assistant automations pause while Home Assistant is down.

Zigbee2MQTT has its own web frontend for device controls, exposed settings, logs, and supported OTA updates. You can manage those without opening Home Assistant’s device page.

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.

Both converter and quirk support depend on contributors with access to the hardware. Check the latest stable release and the relevant device-support issue if you are buying a newly released model. There is no dependable rule that one project always supports it first.

Checking the available settings

Zigbee2MQTT’s device pages list its exposed values, writable controls, and options. Compare those with the entities available in ZHA. For example:

• Presence sensors — check sensitivity, absence delay, and detection intervals for the exact model. Do not assume every presence sensor supports zones.
• Motion sensors — compare sensitivity and detection-interval controls where the model supports them.
• Temperature/humidity sensors — distinguish a software calibration offset from a setting written to the sensor. An offset cannot correct a poor installation location.

If an automation needs a particular writable setting, verify that it is available before migrating. Our FP300 Zigbee2MQTT guide covers that model’s setup.

Write down the exact control your automation needs. For the FP300 (PS-S04D), examples include presence-detection options, sensitivity, and the absence timer. The Cube T1 Pro needs the correct scene/action mode and gesture attributes such as side and action_angle. The DJT11LM exposes a sensitivity control and separate vibration, tilt, and drop actions. These are concrete items to compare with the entities and events offered by your installed ZHA handler.

That distinction matters in practice. A vibration entity can be enough for a simple knock alert, while detecting a drawer being tilted needs the tilt action. A Cube automation that picks a scene from the upper face needs a side report; an automation that changes brightness by rotation angle needs angle data. “Device supported” is too broad to answer either question.

Head-to-Head: Aqara Device Categories

Simple sensors — contact, temp/humidity, standard motion

Both integrations support many everyday sensors. Choose based on your exact models, preferred interface, and whether you want to maintain a separate broker and bridge.

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

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

For these devices, check individual actions and settings rather than treating the whole category as a single compatibility result.

The Cube T1 Pro has mode-dependent gestures. Zigbee2MQTT interprets them through a converter and ZHA through a matching quirk. Check that the mode and gestures you want are supported, then build the automation around the events actually produced.

The DJT11LM vibration sensor needs handling for vibration, tilt, and drop events. Verify all the events you intend to use in the selected integration; a working vibration entity does not establish complete action support.

For the FP300, compare the current converter and ZHA handler with your installed release. A support gap reported against an older version may already have been resolved. Start with the settings you need, such as sensitivity or absence delay.

Choose the integration that exposes the features required by your automations on the version you run.

Switches and buttons

For switches and buttons, check single press, double press, hold, and any multi-gang controls required by your automations. Support can vary by model and firmware in either integration.

OTA support is model-specific in both integrations. Check the supported-device page and available firmware before planning updates. Support for reading a sensor does not prove support for updating it.

For switches, compare the exact button actions, relay settings, and OTA support you need.

Migration Cost — What It Takes to Switch Later

Plan a switch between ZHA and Zigbee2MQTT as a re-pairing project. Do not assume a coordinator backup from one application can be restored into the other without a documented migration path.

Record the entity IDs and automations before moving devices. Reusing suitable entity IDs can help retain references and history, but check each entity after migration. Time needed depends on device access and pairing reliability as well as count.

1. Back up the working installation and note each device’s location, model, friendly name, and automation references.
2. Move one easily reached device first and compare its reports, controls, and actions.
3. Update that device’s automation references and test the actual result before moving the next group.
4. Leave hard-to-reach switches and large lighting groups until the new setup’s basic operation is established.

Choose around the devices you already own and those you plan to add. For a large installation, checking support now can save a disruptive migration later.

Which Should You Pick?

Consider the services you want to maintain and the controls your devices require.

Choose ZHA if you want the integration built into Home Assistant and its current handlers expose the features you need. It is a convenient starting point when you do not already use MQTT.

Choose Zigbee2MQTT if you prefer its device frontend, already use MQTT, or a current converter provides a feature your installed ZHA handler lacks. Check that benefit for the specific model before migrating.

Both can provide local Zigbee control. The choice is about supported features, interfaces, and maintenance. Internet access may still be needed to download updates, and notification delivery can use external services.

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?

Each application needs exclusive access to its coordinator. You can run both with separate coordinators and separate Zigbee networks, for example while testing a migration. A device belongs to one Zigbee network at a time.

Do I need an Aqara hub if I use Zigbee2MQTT?

No Aqara hub is needed for supported Zigbee devices paired directly to your own coordinator. See the Aqara setup without a hub for that process.

Which integration exposes more Aqara device settings?

Check the exact model. Zigbee2MQTT exposes controls defined by its converter; ZHA exposes those implemented by its handler. Neither list should be inferred from the brand alone.

How hard is it to migrate from ZHA to Zigbee2MQTT?

Allow for re-pairing and updating entity references. Save a device list, back up the old setup, and migrate a small group first so you can check automations before moving the rest.

Does ZHA work with the Aqara FP300 and FP2?

The FP300 has a Zigbee mode whose support depends on the installed handler. The FP2 uses Wi-Fi and HomeKit rather than Zigbee, so neither ZHA nor Zigbee2MQTT is its pairing route. Use Home Assistant’s HomeKit Device integration for a compatible FP2 setup.