Xiaomi Aqara devices is an extremely cheap and versatile series of smart home devices.
Whilst cheap, they still perform very well and are easy to integrate in Home Assistant.

In contrast to the devices by Shelly, they communicate over Zigbee instead of WiFi. Because of this, the devices require a Zigbee hub that acts as an intermediary between the devices and your smartphone, home automation system, etc.

That’s where the deCONZ Zigbee gateway comes in.
To let the deCONZ software communicate over Zigbee, you’ll need a ConBee II (a USB stick) or a RaspBee Shield for the Raspberry Pi, both by Dresden Elektronik.
Since I’m running Home Assistant on a server rather than on an RPi, I bought the ConBee II.

Home Assistant also provides a deCONZ integration, allowing for a very smooth integration of Zigbee devices in HA.

In this tutorial, I’ll explain how to install an Aqara Door and Window Sensor(NA). This method works for other Aqara Zigbee devices, like the Aqara Motion Sensor(NA) or Aqara Vibration Sensor(NA) , as well.
In fact, this tutorial will work for just about any sensor/switch/… that works over Zigbee.

The Aqara Door and Window Sensor is a tiny battery-power door/window sensor. It also has a temperature sensor inside of it.

Aqara Door and Window Sensor
Aqara Door and Window Sensor

Yes, it’s tiny!

Installing the ConBee II gateway

Get a Dresden Elektronik ConBee II USB gateway

First of all, you’ll need to get a Dresden Elektronik ConBee II USB gateway.
You can buy this at Amazon [COM][DE]. Make sure you use smile.amazon.{com,de} to donate to charity.

ConBee II USB stick
ConBee II USB stick

Add ConBee II to your system

Once you got the USB-stick, plug it in your system.

Note: It appears that the WiFi chip on the Raspberry Pi (probably due to its proximity) may interfere with the signal of the Zigbee stick (since both run on 2.4GHz). You may want to create some distance between the two by connecting to ConBee II to a USB extension cord(NA).

If you’re – like me – running Home Assistant in a Virtual Machine (VM), you’ll need to assign the device to your VM.
In Proxmox, you can do this by opening the Hardware tab of your VM and adding a new USB Device.
I’m pretty sure you’ll want to uncheck USB3 here.

Use USB Vendor/Device ID so that you can plug the USB stick in any USB port on your system without needing to reconfigure your VM.
You only need to bind to a USB Port if you’re for some reason plugging in two ConBee II’s.

Adding ConBee II to Proxmox VM
Adding ConBee II to Proxmox VM

Next, reboot your Home Assistant VM and verify it can reach the ConBee II.
Open the Supervisor menu, go to the system tab, press the three dots under Host System and open the Hardware list.

Home Assistant - Open hardware menu
Home Assistant - Open hardware menu
Home Assistant - Open hardware list
Home Assistant - Open hardware list

If you cannot find the ConBee II in this list, you may need to remove and plug the USB stick back in, check your assignment in Proxmox and fully reboot HA (not just reload).

Copy the hardware address (e.g., /dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_xxx).

Install deCONZ add-on

  1. Open the Supervisor menu and go to the Add-on Store tab
  2. Install the deCONZ add-on
  3. Open the deCONZ add-on menu and go to the Configuration tab
    Paste the hardware address under the device-key
    device: >-
  /dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_xxx
  4. Under the info tab, check “Watchdog” and “Auto update”, if you want
  5. Start the add-on and check the logs for errors
Install deCONZ add-on
Install deCONZ add-on

Adding the Aqara Door and Window Sensor

Launch deCONZ / Phoscon

Either check the “Show in sidebar” and open the deCONZ app from there, or click “Open web UI” in the deCONZ add-on menu.

I chose to work with the Phoscon app.

deCONZ app selection
deCONZ app selection

On first launch, you’ll need to create an account. Be sure to remember these credentials (add them to your password vault) as you’ll need this each time you open the app.
You’ll most likely also need to do an initial configuration of your ConBee II gateway and update it’s firmware.

Proceed without lights.
Skip the creation of groups.

Add the sensor

Make sure you already unboxed the sensor by now.

  1. Open the sidebar menu and click on Sensors under the Devices section.
  2. Click “Add new sensor”
  3. Pick “Other” as Vendor
  4. The search for new sensors is now active for 3 minutes
  5. Pick up your Aqara Door and Window Sensor and shortly press the small button on the sensor
  6. The sensor should be picked up in about 10 seconds. If not, move closer to the ConBee II and press the button again
  7. Give the sensor a name (e.g. DW Front Door)

Rename in Home Assistant

The Aqara sensor is now added to Home Assistant.
The device will also have 2 related entities: 1 binary sensor for the door/window state (on = open, off = closed) and a sensor for the battery percentage.

This step is optional, but I prefer to rename the device so that the entity_id’s are a bit more sensible.

  1. Go to the Devices list under the Configuration menu
  2. Search for deCONZ
  3. Aside from the Phoscon-GW, the daylight sensor (built-in in Phoscon) and (in my case) an unnamed device, you should also find your Door and Window Sensor
    In my case, it’s identified as a lumi.sensor_magnet.aq2 by LUMI
  4. Open the device menu
  5. Click the cogwheel at the top right of your window
  6. Give the device a new name and set the location
  7. Say Yes when Home Assistant asks you if you want to also rename the entities
    If this fails, you can manually rename the entities from the device menu as well.
Device menu - Aqara sensor
Device menu - Aqara sensor

Create automations

Now you can create automations based on the state of the sensor.
Want to turn on the hallway lighs when the door opens? No problem!
Want an alert on your phone when the door opens while nobody’s home? No problem! Want to … ? No problem!

Since I’m using Node-RED for all my automations, I opened the Node-RED application and set up my automation.

This automation triggers when the state of the door sensor changes.
If it opened, the light turns on. If nobody is home, an alert is sent to my phone with a picture from the front door camera and a link to the security tab of my Lovelace interface.
If it’s closed, the light turns off after 2 minutes. You’ll perhaps want to have an override here for when the hallway light switch is on.

You can automate your lights using e.g. a Shelly. This device can be added to Home Assistant using the new Shelly integration, via ShellyForHass or via MQTT.

Node-RED example flow for front door sensor and hallway lights
Node-RED example flow for front door sensor and hallway lights

The code for this flow can be found below:

[{"id":"9ec7d5da.d232f8","type":"tab","label":"Example flow sequr.be","disabled":false,"info":""},{"id":"b440de1.8abb82","type":"comment","z":"9ec7d5da.d232f8","name":"DW sensor front door","info":"","x":140,"y":60,"wires":[]},{"id":"5c6334e3.285aec","type":"server-state-changed","z":"9ec7d5da.d232f8","name":"Door open?","server":"2ce15169.23b9de","version":1,"exposeToHomeAssistant":false,"haConfig":[{"property":"name","value":""},{"property":"icon","value":""}],"entityidfilter":"binary_sensor.dw_frontdoor","entityidfiltertype":"exact","outputinitially":false,"state_type":"habool","haltifstate":"true","halt_if_type":"bool","halt_if_compare":"is","outputs":2,"output_only_on_state_change":true,"x":110,"y":180,"wires":[["e7dcb7d6.bde698","a07a0cb.75cad7"],["b4b17f00.c9b63"]]},{"id":"e7dcb7d6.bde698","type":"api-call-service","z":"9ec7d5da.d232f8","name":"Hallway lights on","server":"2ce15169.23b9de","version":1,"debugenabled":false,"service_domain":"light","service":"turn_on","entityId":"light.hallway_lights","data":"","dataType":"json","mergecontext":"","output_location":"","output_location_type":"none","mustacheAltTags":false,"x":310,"y":160,"wires":[[]]},{"id":"b4b17f00.c9b63","type":"delay","z":"9ec7d5da.d232f8","name":"","pauseType":"delay","timeout":"2","timeoutUnits":"minutes","rate":"1","nbRateUnits":"1","rateUnits":"second","randomFirst":"1","randomLast":"5","randomUnits":"seconds","drop":false,"x":280,"y":220,"wires":[["ae62427e.0af6b8"]]},{"id":"ae62427e.0af6b8","type":"api-call-service","z":"9ec7d5da.d232f8","name":"Hallway lights off","server":"2ce15169.23b9de","version":1,"debugenabled":false,"service_domain":"light","service":"turn_off","entityId":"light.hallway_lights","data":"","dataType":"json","mergecontext":"","output_location":"","output_location_type":"none","mustacheAltTags":false,"x":470,"y":220,"wires":[[]]},{"id":"a07a0cb.75cad7","type":"ha-get-entities","z":"9ec7d5da.d232f8","server":"2ce15169.23b9de","name":"Anyone home?","rules":[{"property":"state","logic":"is","value":"home","valueType":"str"},{"property":"entity_id","logic":"starts_with","value":"person.","valueType":"str"}],"output_type":"count","output_empty_results":true,"output_location_type":"msg","output_location":"payload","output_results_count":1,"x":300,"y":120,"wires":[["d9c12867.acebe8"]]},{"id":"d9c12867.acebe8","type":"switch","z":"9ec7d5da.d232f8","name":"0 ppl home","property":"payload","propertyType":"msg","rules":[{"t":"eq","v":"0","vt":"num"}],"checkall":"true","repair":false,"outputs":1,"x":490,"y":120,"wires":[["98d5bdb7.611b2"]]},{"id":"b20702ac.a4503","type":"api-call-service","z":"9ec7d5da.d232f8","name":"Send notification","server":"2ce15169.23b9de","version":1,"debugenabled":false,"service_domain":"notify","service":"mobile_app_me","entityId":"","data":"","dataType":"json","mergecontext":"","output_location":"","output_location_type":"none","mustacheAltTags":false,"x":1000,"y":120,"wires":[[]]},{"id":"98d5bdb7.611b2","type":"function","z":"9ec7d5da.d232f8","name":"Notification data with camera image","func":"msg.payload =\n{\n    \"data\": {\n        \"title\": \"Someone opened front door\",\n        \"message\": \"Somone opened front door, but nobody is home\",\n        \"data\": {\n            \"image\": \"https://example.org/api/camera_proxy/camera.frontdoor?token=verylongstring\",\n            \"clickAction\": \"/lovelace/security\"\n        }\n    }\n}\nreturn msg;\n","outputs":1,"noerr":0,"initialize":"","finalize":"","x":740,"y":120,"wires":[["b20702ac.a4503"]]},{"id":"2ce15169.23b9de","type":"server","name":"Home Assistant","legacy":false,"addon":true,"rejectUnauthorizedCerts":true,"ha_boolean":"y|yes|true|on|home|open","connectionDelay":true,"cacheJson":true}]

Did you find this how-to useful and/or did you make a crazy automation based on this tutorial? Hit me up on Twitter and let me know!