There are mainly two mainstream approaches for adding Aqara/Lumi devices in Home Assistant (HA), depending on what kind of hardware you have.
Please choose one of the following approaches according to your situation:
Approach A: You have an official Aqara gateway
(such as M1S, M2, E1, Air Conditioning Companion P3, etc.).
- Core idea: integrate into HA in reverse through HomeKit.
Approach B: You have a generic Zigbee adapter
(such as Sonoff ZBDongle, SkyConnect and other USB sticks).
- Core idea: control devices directly through ZHA or Zigbee2MQTT (recommended, fully local, free from gateway limitations).
Approach A: use an official Aqara gateway (via HomeKit Controller)
This is the simplest approach, suitable for users who do not want to tinker with hardware and who already own an Aqara gateway. Most current Aqara gateways support HomeKit, and HA can “pretend” to be an iOS device over the local network to take over the gateway and its sub-devices.
Steps:
Set up the network in the Aqara App:
Download the “Aqara Home” App on your phone (try not to use the Mi Home App; Aqara Home has better HomeKit support).
Add the gateway and sub-devices (sensors, switches, etc.) to the Aqara Home App, and make sure the firmware is updated to the latest version.
Note:
If you use an iPhone, do not add this gateway in the iOS “Home” App. If you have already added it, delete the gateway in the iOS Home App (unbind it), because a HomeKit device can usually only be exclusively controlled by a single controller (phone or HA).
Discover the device in Home Assistant:
- Open the Home Assistant web interface.
- Go to Settings -> Devices & Services.
- HA usually automatically discovers HomeKit devices on the local network; you will see a discovery prompt under “HomeKit Device”.
- If it is not discovered automatically, click Add Integration in the bottom right corner and search for HomeKit Device (note: not HomeKit Bridge).
Pairing:
- Click Configure and the system will ask for the Pairing Code.
- The pairing code is usually printed on the bottom of the gateway or on the box (format XXX-XX-XXX).
- After entering it, wait a few seconds and the gateway plus all its sub-devices will automatically appear in HA.
Advantages: simple, and the official App can be used to upgrade the firmware.
Disadvantages: it depends on the gateway, and some special attributes (such as the refresh rate of the specific values from a light sensor) may be limited by the HomeKit protocol.
Approach B: use a Zigbee USB adapter (recommended: Zigbee2MQTT)
This is the first choice for advanced users and those who pursue stability. You need to buy a Zigbee USB Dongle (the Sonoff ZBDongle-P or -E version is recommended). This approach does not need an Aqara gateway; all devices connect directly to HA, giving the fastest response.
Here we introduce the most powerful Zigbee2MQTT (Z2M) method. Although it is slightly more complex than ZHA, it has the best support for Aqara’s proprietary protocol.
- Preparation:
Plug the Zigbee USB stick into the device running HA (Raspberry Pi/NAS/mini PC). It is best to use a USB extension cable to avoid USB 3.0 interference.
- Step 1: Install the MQTT Broker (Mosquitto)
- In HA, go to Settings -> Add-ons -> Add-on Store.
- Search for and install Mosquitto broker.
- Start it, and make sure “Start on boot” and “Watchdog” are enabled.
Go back to Settings -> Devices & Services; HA should automatically discover MQTT, so click Configure and submit.
- Step 2: Install Zigbee2MQTT
- Go to Settings -> Add-ons -> Add-on Store.
- Click the menu in the top right corner (three dots) -> Repositories, and add the Z2M repository address: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt (if you cannot find the official one, add this first).
After refreshing, install Zigbee2MQTT.
- Step 3: Configure Zigbee2MQTT
- On the Z2M add-on page, click the Configuration tab.
- MQTT settings:
- server: mqtt://core-mosquitto:1883
- user: (usually left blank, or enter your HA username)
password: (same as above)
Serial settings (critical):
You need to know the port path of the USB stick (for example /dev/ttyUSB0). You can find it under Settings -> System -> Hardware -> All Hardware.
serial:
port: /dev/ttyUSB0
# 根据实际情况修改</li></ul>Add this to the configuration:
Start the Zigbee2MQTT add-on and check the log to make sure it started successfully (no red errors).
Click “Open Web UI”.
- Step 4: Add Aqara devices
- At the top of the Zigbee2MQTT web interface, click Permit join (the countdown starts).
- Reset the Aqara device:
- For most Aqara sensors (motion, door/window, temperature and humidity): press and hold the reset button on the device for 5-10 seconds, until the blue indicator light flashes.
Release it at that point; if the device supports it, it will flash once more to indicate it is connecting.
Watch the Z2M interface: you will see the device go through the interview and be displayed with a model name starting with “Lumi”.
You can click the blue pencil icon next to the device name to change it to a friendly name (such as “Living Room Motion Sensor”) and tick “Update Home Assistant entity ID”.
- Advantages:
- Local: completely free from the cloud.
- Compatibility: it can connect not only Aqara but also Zigbee devices from other brands such as IKEA and Tuya.
Full features: many Aqara devices have hidden parameters (such as the sensitivity of a motion sensor, or the state memory after a power cut), and Z2M can modify these parameters directly, whereas gateway mode often cannot.
Approach C: use ZHA (Zigbee Home Automation) – the simplified USB stick approach
- If you find approach B too complex, you can use HA’s native ZHA integration, which also requires a USB stick.
- Plug in the USB stick.
- Go to Settings -> Devices & Services.
- HA usually automatically discovers the USB stick and asks whether to set up Zigbee Home Automation.
- Click Configure, choose the correct serial port, and create the network.
- After setup is complete, click Configure on the ZHA integration card -> Add device.
Press and hold the reset button on the Aqara device to pair it.
Note: ZHA’s support for Aqara devices is also good, but for some newer models or adjustments to special parameters it is less flexible than Zigbee2MQTT.
Summary and recommendations
Beginners / those who do not want to tinker with hardware: use
Approach A (Aqara gateway + HomeKit)
. It is the most reliable, and the App can also be used to upgrade device firmware.
Advanced users / those who pursue response speed / many devices
: use
Approach B (Zigbee2MQTT)
- . This is currently the most highly regarded method in the HA community and fully unlocks the potential of Aqara devices. Common problems Troubleshooting
- Devices keep dropping offline?
- Older Aqara Zigbee devices (non-T1 series) do not comply well with the standard Zigbee 3.0 protocol and easily drop offline.
Solution: add Zigbee router devices (that is, mains-powered devices such as the live+neutral version of Aqara wall switches and smart plugs) and do not let sensors connect directly to a USB stick that is too far away.
- Cannot pair?
- Pair as close as possible to the USB stick or gateway.
For Aqara devices, after holding the reset button until the light flashes, it is recommended to briefly press the button once every second to keep the device awake until pairing succeeds.
- How do I connect a gateway that can join the Mi Home App?
If it is an older Xiaomi multi-mode gateway, you can use the Xiaomi Gateway 3 integration (installed via HACS). But for newer devices it is recommended to go through the HomeKit channel, because the Mi Home protocol changes frequently and local interfaces are often blocked.
