How to Connect Aqara Devices to Home Assistant

Compatibility Overview

Aqara makes a wide range of Zigbee devices — motion sensors, temperature/humidity sensors, door/window sensors, cube controllers, wall switches, and more. The vast majority work with Zigbee2MQTT and ZHA without needing an Aqara hub (Hub M3, or the older M2).

Common Aqara devices confirmed working:

• RTCGQ11LM / RTCGQ01LM — Motion sensors (PIR)
• WSDCGQ11LM — Temperature, humidity, pressure sensor
• MCCGQ11LM — Door/window contact sensor
• WXKG01LM / WXKG11LM — Wireless mini switches
• QBKG03LM / QBKG04LM — Wall switches (Zigbee)
• DJT11LM — Vibration sensor

Via an Aqara Hub (Matter)

Home Assistant has no Aqara hub integration that you log into with an IP address and token. Its Aqara page covers Aqara's Matter products: Aqara is a "Works with Home Assistant" partner, and its devices are added through HA's built-in Matter integration, with local push updates. The hub HA lists is the Aqara Hub M3, the successor to the Hub M2. It adds a Matter controller and a Thread border router. Aqara also gave the older Hub M2, Hub E1 and M1S Gen 2 Matter-bridge firmware in 2023, so those can share their Zigbee devices over Matter as well.

1. Set up your Aqara hub and pair devices in the Aqara Home app first
2. In the Aqara Home app, enable Matter on the hub and copy its Matter pairing code
3. In HA: Settings → Devices & Services → Add Integration → Matter, then add the hub with that code
4. Supported Aqara child devices appear in HA as Matter entities

Two things to know. First, HA's older "Xiaomi Gateway (Aqara)" integration only covers the legacy Xiaomi Mijia gateways, not the M2 or M3. Second, community guides report that the Hub M2 can also be paired to HA with the HomeKit Device integration, which stays local. In both cases you're dependent on the Aqara hub's firmware and the Aqara app for device management, and a Matter bridge exposes fewer device attributes than a direct Zigbee connection. For a true local-first setup, Zigbee2MQTT is better.

Via Zigbee2MQTT (Recommended)

This approach bypasses the Aqara hub entirely. Your Zigbee coordinator becomes the hub.

1. Ensure Mosquitto broker and Zigbee2MQTT are installed and running in HA
2. In the Zigbee2MQTT web UI, enable Permit join
3. Put your Aqara device into pairing mode (method varies by device — usually hold the reset button until the LED flashes)
4. Watch the Zigbee2MQTT device list — your device appears within 30 seconds
5. Give it a friendly name in the Z2M UI
6. HA auto-discovers the device entities via MQTT autodiscovery

Via ZHA

1. In HA: Settings → Integrations → ZHA → Add Device
2. Put your Aqara device into pairing mode
3. ZHA discovers and adds it — entities appear automatically

ZHA supports most Aqara devices but may expose fewer attributes than Zigbee2MQTT. For example, an Aqara WSDCGQ11LM via ZHA gives you temperature and humidity; via Zigbee2MQTT it also exposes pressure, battery voltage, and link quality.

Entity Examples

After pairing an Aqara P1 motion sensor (RTCGQ13LM) via Zigbee2MQTT, you'll get these HA entities:

• binary_sensor.bedroom_motion_occupancy — motion detected (on/off)
• sensor.bedroom_motion_battery — battery percentage
• sensor.bedroom_motion_illuminance — light level in lux
• sensor.bedroom_motion_linkquality — Zigbee signal strength

Motion → Light Automation (Full YAML)

automation:
  - alias: "Hallway light on motion"
    description: "Turn on hallway light when motion detected, off after 5 minutes"
    trigger:
      - platform: state
        entity_id: binary_sensor.hallway_motion_occupancy
        to: "on"
    condition:
      - condition: time
        after: "06:00:00"
        before: "23:00:00"
    action:
      - service: light.turn_on
        target:
          entity_id: light.hallway
        data:
          brightness_pct: 80
      - wait_for_trigger:
          - platform: state
            entity_id: binary_sensor.hallway_motion_occupancy
            to: "off"
            for:
              minutes: 5
      - service: light.turn_off
        target:
          entity_id: light.hallway

Troubleshooting

• Device won't pair: Move it within 1m of the coordinator. Aqara original series devices can be finicky at distance during initial pairing.
• Device pairs but drops off: Usually a weak Zigbee mesh. Add more mains-powered Zigbee devices (plugs, switches) between the sensor and coordinator.
• Entities show "unavailable": Check Zigbee2MQTT logs for the device. Common cause: low battery or the device lost its Zigbee network association (re-pair it).
• Wall switches don't control loads locally: Aqara wall switches in "decoupled" mode send Zigbee commands instead of directly controlling the relay. Set the device mode in Zigbee2MQTT device settings.

FAQ

SmartWired uses affiliate links. If you buy through our links, we may earn a commission at no extra cost to you. See our Affiliate Disclosure.