Set up Zigbee with Home Assistant - ZHA integration guide

In this guide, I will show you how to set up Zigbee with Home Assistant, So we can connect most Zigbee devices and control them locally directly from Home Assistant.

So, what is Zigbee?

Zigbee is a technology used for short-range communication, similar to WiFi and Bluetooth. It’s based on the IEEE 802.15.4 standard. It uses a small amount of power and low data rate, making it ideal for home automation using light bulbs, plugs, sensors, and other devices. Because Zigbee devices require low power, devices using this technology usually are smaller and last for a year on a coin size battery. Zigbee is also built as a mesh network. So devices can transmit data over a longer distance by passing data through devices in the mesh network.

What devices can we use?

There are a large number of devices available that use Zigbee. I’m personally using some Aqara plugs, switches, door sensors, and also some Phillips Hue lights. To configure these Zigbee devices, it would require a hub which in most cases, is sold separately by the same manufacture. That hub would then connect to the home WiFi, and you would use an application to configure and control those devices. Also, in most cases, those devices would connect to the cloud.

With Home Assistant, you can purchase 1 USB gateway that you can use to link Zigbee devices and control them locally directly from Home Assistant. There are a few gateways or modules available that you can use. The one I’ve been using for a while now and recommend is the Conbee II from Dresden Elektronik. They also have a module called RaspBee II that you can connect inside of a Raspberry Pi. That one I haven’t use. However, it could be handy if you have Home Assistant installed on a Raspberry Pi, and you don’t want to have a USB adapter sticking out on the outside.

How to set it up with Home Assistant

There are 2 ways that you can configure the gateway with Home Assistant. You can use the deCONZ add-on or the Zigbee Home Automation (ZHA) integration. I’ve been using the ZHA integration for a while now, and I think that is the best choice. It’s very simple to configure and also easy to add new Zigbee devices. For this tutorial, I’ll show you how to set up the ZHA integration instead of the deCONZ add-on.

Zigbee gateway setup

Connect the Zigbee gateway to the machine running Home Assistant. If you have Home Assistant running in a virtual machine using, for example, Proxmox. You want to assign the Zigbee gateway to the Home Assistant VM. To do that, go to the Proxmox web interface, select the Home Assistant VM, click on Hardware, then Add and select USB Device. On the pop-up window, select Use USB Vendor/Device ID, and from the drop-down, select the Zigbee gateway. Click OK and restart the Home Assistant virtual machine.

After that, check that Home Assistant can see the Zigbee gateway connected. So, open the Home Assistant user interface and go to Supervisor and then, System. Under Host System, click on the More Options menu and select Hardware. For the Conbee II, you would see the device listed as follow: /dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_....

Next, set up the Zigbee integration, so go to Configuration, Integrations, and click on the “+” plus icon. Search for ZHA, select it, and on the pop-up that comes up, click on the drop-down. The Zigbee gateway should come up as an available option to select. If it doesn’t get automatically discovered, you can manually enter the path seen under Hardware.

Click on Submit, and the integration should identify the type of radio the gateway is using. If it’s not detected, a pop-up will come up for you to select the radio type. For the Conbee II, you would choose deconz. However, if you are installing another brand of Zigbee gateway, you would need to select the specific radio for that device.

When the Zigbee gateway is successfully added, you can assign it to a specific area in your home and then click on Finish.

Add devices to gateway

To add a new Zigbee device, you first need to put it into pairing mode. For example, the Aqara devices have a button that you can press and hold for a few seconds, and an LED start blinks when the device is ready to pair.

Once you have your device in pairing mode, click Configure under the ZHA integration. Then click on the “+” plus icon, and the integration starts searching for new devices. When a device is discovered, it’s also paired and automatically added to Home Assistant. You can then change the device name and set up the device location in your home. Once you are done pairing your devices, you can click on the back arrow on the top left to get out of the searching mode.

Under the Zigbee Network, you can check the devices that you have paired or see all the entities available from all devices.

How to link and control several devices at the same time

If you have a few devices that you want to link together and then have one device, control all other devices simultaneously. For example, a switch that would control lights or plugs at the same time. Well, in the ZHA Integration, you could set up clusters which would link devices together. However, when I tried to set up clusters with my Aqara devices, it didn’t really work for me. And for what I found out, that feature does play well with some Zigbee devices. So, what I end up doing was setting automations that would toggle the lights and plugs on and off when pressing the button on a switch.

Let’s set up an automation as an example to toggle a plug on and off from a switch.

Set up Automations with Zigbee devices

In Home Assistant, go into Configuration and then, Automations. Click on the “+” plus icon to add a new automation, and on the pop up that comes up, click on Skip.

In the Automation Editor, set up a name for the automation and also a description if you want to. The Mode, leave it as Single which is the default.

Set the Trigger type to Device and for Device, select the Zigbee switch. Now for the Trigger, there are several options available for the Aqara switch. To toggle the plug on and off, select button pressed.

Under actions, set the Action type to Device, and for the Device, select the Zigbee plug. Now, for the Action, it is the same thing as the Trigger above. There are several options available for the Aqara plug. Select the Toggle option, so the plug can turn on and off when the switch button is pressed. Click on the Save icon, and you can now test the automation and see if everything is working.

There are so may different automations that you can set up with Zigbee devices. For example, with window and door sensors, you could set up an automation that would notify you when you’re not home, that the door or window was opened. If you have cameras, you could add to that automation to send you an image to know who or what triggered the sensor.

Conclusion

Anyway, I hope this guide helps you get started with Zigbee and the Home Assistant ZHA integration.

If you have any questions or suggestions, you can always reach out to me via the Home Assistant community forum or also via Twitter.