Aqara Devices Integration for Home Assistant

Aqara Devices (G3, G2H Pro, G410, G4, M3, M100, M200, FP2, FP300, A100, A100 Pro, Xingyao/ACN002 locks, and U200) connects supported Aqara cameras, doorbells, hubs, presence sensors, and locks to Home Assistant with Aqara Open API v3 and aqara-rocketmq-bridge.

Instead of relying only on periodic polling, the integration now uses Aqara Message Push -> RocketMQ -> bridge -> Server-Sent Events (SSE) so Home Assistant receives live updates while the integration keeps Aqara authentication, token refresh, and resource subscriptions in sync.

Documentation

• Setup guide
• Architecture notes
• Bridge repository
• Integration repository

What You Need Before Starting

Before adding the integration, prepare:

• an Aqara developer account and project;
• APP_ID, KEY_ID, and APP_KEY from the Aqara developer console;
• MQ_NAMESRV_ADDR from Aqara Message push;
• a strong BRIDGE_TOKEN;
• a reachable bridge URL for Home Assistant;
• Home Assistant with this integration installed.

For the complete step-by-step setup, follow the published guide linked above.

Installation

HACS

1. Click the button above, or add https://github.com/Darkdragon14/ha-aqara-devices manually as a custom repository in HACS with category Integration.
2. Search for Aqara Devices and install it.
3. Restart Home Assistant.
4. Go to Settings -> Devices & Services -> Add Integration.
5. Search for Aqara Devices.

Manual installation

1. Copy custom_components/ha_aqara_devices into your Home Assistant custom_components directory.
2. Restart Home Assistant.
3. Add the Aqara Devices integration from Settings -> Devices & Services.

Quick Start

1. Configure Aqara Message Push

In the Aqara developer console:

1. Create or open your Aqara project.
2. Copy APP_ID, KEY_ID, and APP_KEY.
3. Open Message push.
4. Select Get messages based on message queue.
5. Enable push and keep User-defined subscription mode.
6. Copy the MQ message subscription address as MQ_NAMESRV_ADDR.

2. Run the bridge

Use one of these supported paths:

Home Assistant installation	Bridge deployment	Typical Bridge URL
Home Assistant Container	Docker or Compose	http://aqara-rocketmq-bridge:8080
Home Assistant OS	Aqara RocketMQ Bridge add-on	http://HOME_ASSISTANT_IP:8080 or your reverse-proxy URL

For Home Assistant OS, add the bridge add-on repository automatically:

Bridge setup details, add-on instructions, and Compose examples are in the published guide:

• Aqara RocketMQ Bridge setup guide

3. Add the integration in Home Assistant

The config flow asks for:

Field	Value
Aqara account (email or phone)	Your Aqara login identifier
Region	EU, US, CN, RU, KR, SG, or OTHER
Bridge URL	The URL Home Assistant can use to reach the bridge
Bridge token	The same token as BRIDGE_TOKEN
App ID	Your Aqara APP_ID
App key	Your Aqara APP_KEY
Key ID	Your Aqara KEY_ID

After the first step, Aqara sends a verification code to your email address or phone number. Enter that authorization code to finish setup.

Optional camera live streams with go2rtc

G3, G2H Pro, G410, and G4 devices can expose a Home Assistant camera entity through a separate go2rtc instance. Video support is optional; all other Aqara entities continue to work when go2rtc is not installed.

Important

Camera configurations created with the prerelease tag v1.4.0-beta-camera-rtsp-streams are not migrated. Direct RTSP settings cannot be converted into a HomeKit pairing and are ignored by this version. Reconfigure each camera through go2rtc; the old rtsp_cameras options are left untouched so downgrading does not destroy them.

For Home Assistant OS or Supervised, install the go2rtc add-on from https://github.com/AlexxIT/hassio-addons. Home Assistant Container users can run the official alexxit/go2rtc container instead. Keep the go2rtc API and media ports on localhost or a trusted private network.

Open the integration options and use:

Menu	Purpose
Account and bridge	Update Aqara Open API account details, developer keys, or bridge connection settings
go2rtc	Configure and validate the go2rtc API and RTSP output URLs
Camera streams	Pair a discovered camera or associate an existing go2rtc stream

When pairing a camera, select the Aqara device, select the local HomeKit camera discovered by go2rtc, and enter its HomeKit pairing code. The code is sent directly to go2rtc and is not stored by this integration. go2rtc performs the local HomeKit pairing, stores its pairing keys, and provides the stream consumed by Home Assistant. The HomeKit Device integration is not required.

The automatically paired stream currently exposes video only. HomeKit uses AAC-ELD audio, which requires an additional FFmpeg transcoding source; advanced users can configure that in go2rtc and associate the resulting existing stream.

HomeKit cameras generally pair with one controller at a time. If discovery or pairing fails, remove any existing Apple Home, HomeKit Device, or other go2rtc pairing first. This does not remove the camera from the Aqara app or affect its Aqara Open API entities.

Advanced users can associate an existing go2rtc stream instead of pairing through the integration. Streams created outside this integration are never deleted or unpaired automatically.

Hub child devices

The integration discovers child devices connected to supported G3, G2H Pro, M3, M100, and M200 hubs and registers each child under its parent hub in Home Assistant. Readable Aqara resources are exposed as generic read-only sensor or binary_sensor entities.

Only resources considered safe and useful are enabled automatically, including reportable binary states and common measurements with units. Writable, unknown, or less useful resources are disabled by default. To use one of these entities, open the child device in Home Assistant, select its disabled entities, and enable the ones you need. Enabling or disabling a child entity reloads the integration so polling and Aqara subscriptions stay aligned with the active entities.

The ha_aqara_devices.open_pairing_mode and ha_aqara_devices.close_pairing_mode services can start or stop child-device pairing on a supported hub. Both services require the parent hub's Aqara DID.

How It Works

Aqara RocketMQ -> aqara-rocketmq-bridge -> SSE -> ha_aqara_devices -> Home Assistant

• aqara-rocketmq-bridge consumes Aqara Message Push events and exposes GET /health and GET /events;
• ha_aqara_devices validates the bridge, connects to the SSE stream with Authorization: Bearer <bridge token>, and manages Aqara Open API authentication;
• the integration subscribes only to the Aqara resources it needs and creates entities for supported devices.

Supported Devices

Device	Models
Hub G3	lumi.camera.gwpgl1, lumi.camera.gwpagl01
Camera Hub G2H Pro	lumi.camera.agl001, lumi.camera.acn003
Doorbell G410	lumi.camera.acn017, lumi.camera.agl006
Doorbell G4	lumi.camera.agl002, lumi.camera.acn005
Hub M3	lumi.gateway.acn012, lumi.gateway.agl004
Hub M100	lumi.gateway.agl008, lumi.gateway.agl010
Presence Sensor FP2	lumi.motion.agl001
Presence Multi-Sensor FP300	lumi.sensor_occupy.agl8
Door Lock A100	aqara.lock.agl002
Door Lock A100 Pro	aqara.lock.acn001
Smart Lock U200	aqara.matter.4447_10242
Smart Video Door Lock Xingyao (全自动智能猫眼门锁 星耀)	aqara.lock.acn002

Each discovered supported device in your Aqara account gets its own entities and device metadata inside Home Assistant.

For the full per-device entity details, see the published bridge documentation:

• Supported devices reference

The U200 is exposed by Aqara as Matter model aqara.matter.4447_10242, so this integration reads it through the Aqara trait API instead of the older resource API.

Need Help?

• Full setup and troubleshooting guide
• Issues and feature requests

Credits / Acknowledgements

Camera streaming is powered by AlexxIT/go2rtc, distributed separately under the MIT license. Thanks also to Aqara support for their help and information; this project is community-maintained and is not officially affiliated with or endorsed by Aqara.

Missing translation

Want to see your language? Open an issue or submit a PR with new entries under custom_components/ha_aqara_devices/translations/.