How To Pass Through USB Zigbee Devices To Home Assistant Running In Docker

If you are running Home Assistant (which you should be!) and you want to add Zigbee devices without using proprietary hubs (which you should want to!) then you may want to add a USB ZigBee device to your Home Assistant Installation.

I run Home Assistant in Docker on UNRAID with a CC2531 USB stick connected to my UNRAID server. Whilst the process is actually very simple, I spent a few hours trying to work out how to get this to work, so to to make the process simpler for anyone else in the future, I have fully documented the process below for how to pass through USB Zigbee devices to Home Assistant!

This post includes affiliate links, as an Amazon Associate I earn from qualifying purchases.

What You Need

Let’s assume you have installed Home Assistant in a docker container (my example is using UNRAIDs built in docker management, but it should be fairly similar no matter how you are managing Docker).

• The only other thing you’ll need is some form of USB Zigbee stick

These are really popular;

But I had a (cheaper) CC2531 device I had previously bought on eBay for around £10

How To Set It Up

Again, these instructions relate specifically to Docker, but they should be transferable to other systems.

Install the USB stick

Insert the USB stick into your server

Find the Path details for the USB ZigBee stick

Within UNRAID open the terminal

And run this command

ls -l /dev/serial/by-id

Which should return something like this

The only bit you need to take note of is the bit at the end;

ttyACM0

I found a really useful guide on a website called unraid-guide which detailed a process on How to install Zigbee2MQTT on Unraid, this really helped me with this part of the process!

Always quote your sources!

Edit The Home Assistant Docker

1. Go to your Unraid web interface and navigate to the “Docker” tab.
2. Find the Home Assistant container in the list of Docker containers, and click on the container’s name.
3. In the container settings page, click on “Add another Path, Port, Variable, Label or Device” add the bottom of the page to modify the container settings.
4. In the box that appears, change the “Config Type” to “Device” using the dropdown menu.
5. In the “Name” field, you can enter a descriptive name like “CC2531 USB Zigbee Device”.
6. In the “Value” field, enter the path to the USB device using the name you got from the command earlier

It should look like this;

/dev/ttyACM0

Complete

That is all you need to do in order to pass the USB device to Home Assistant.

Read on to learn how to then present that device to Zigbee Home Automation (ZHA) and start adding Zigbee Devices.

How To Setup ZHA In Home Assistant on UNRAID

So lets look at setting up ZHA in Home Assistant and why you might want to use it.

What Is ZHA?

ZHA stands for Zigbee Home Automation, and it’s a super handy integration within Home Assistant that lets you take control of various Zigbee devices in your smart home setup.

ZHA integration in Home Assistant makes it a breeze to manage your Zigbee devices without needing to use 3rd party hubs, or apps (keeping your information private). Plus, since it’s a local solution, there’s no need to worry about cloud-based services going down or internet outages breaking your smart home.

You can easily add, configure, and control (most) Zigbee devices from a single place, making your smart home automation setup much easier to manage.

Setup ZHA in Home Assistant

1. Access your Home Assistant web interface.
2. Click on “Settings”
3. Click on “Devices & Services”
4. Click “Add Integration”
5. Search for ZHA

From here, providing you followed the steps earlier to correctly pass through your USB devices, the process should be fairly simple.

The installer should automatically find the correct USB device;

Click proceed;

Providing you did everything right earlier it should automatically appear here, click Submit;

I chose “Keep radio network settings”

Assign a location and click Finish

Add devices to ZHA

The final step is to start adding devices.

I had an Aqara Motion sensor to hand, they’re very good for the money and I’ve read the updated P1 version is even better;

To add a device

1. Open Home Assistant web interface.
2. Click on “Settings” in the left sidebar menu.
3. Click on “Devices & Services.”
4. Find the “ZHA” integration card and click on “Configure.”
5. Click on “ADD DEVICE” in the bottom right corner.
6. Put your Zigbee device in pairing mode (refer to the device’s manual for instructions).
7. Wait for the device to be discovered by ZHA, and the device will appear in the list.
8. Once discovered, the device is added to your ZHA network, and you can configure and control it within Home Assistant.

I tend to do this process within the mobile app, the process should look like this;

Summary

Hopefully this helped you pass through USB Zigbee devices to Home Assistant to use ZHA, you can probably also follow these steps to setup MQTT, which I may try later.

Adding a USB Zigbee device to Home Assistant is a great idea for several reasons:

1. Wide compatibility: Zigbee is a popular and widely adopted wireless protocol used in various smart home devices, including lights, sensors, plugs, and more. Integrating a USB Zigbee device enables Home Assistant to control and manage a diverse range of Zigbee-enabled devices.
2. Local control: Using a USB Zigbee device provides local control of your smart home devices, eliminating the reliance on cloud-based services. This ensures better privacy and faster response times, whilst also reducing the requirement for expensive additional hubs.
3. Mesh networking: Zigbee devices form a mesh network, allowing them to communicate with each other directly or through intermediate devices (only certain devices support this, motion sensors mentioned in this post don’t). This increases the network’s reliability, range, and resilience to connectivity issues.
4. Low power consumption: Zigbee devices are known for their low power consumption, making them an energy-efficient choice for smart home setups (although you will likely need to keep a stock of odd shaped batteries for when your devices do run out of battery).
5. Unified management: Home Assistant, when paired with a USB Zigbee device, provides a single platform for managing and automating your Zigbee devices. This makes it easier to create a seamless and integrated smart home experience without the need for a load of different applications to manage your smart home devices.

In summary, adding a USB Zigbee device to Home Assistant enables you to take advantage of the many benefits that Zigbee offers, without all the additional overhead of using multiple devices and apps.