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 the Aqara hub (M2 gateway).

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 Official Aqara Integration

The official Aqara integration in HA requires an Aqara M2 (or M1S Gen 2) hub on the same network. It communicates locally with the hub via the Aqara local API. This approach doesn't require a Zigbee coordinator dongle but does require buying an Aqara hub (~$35).

1. Set up your Aqara hub and pair devices in the Aqara Home app first
2. In HA: Settings → Integrations → Add → Aqara
3. Enter the hub's IP address and access token (from the Aqara app developer settings)
4. Devices appear in HA automatically

Downside: you're dependent on the Aqara hub's firmware and the Aqara app for device management. 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.