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!

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;

SONOFF Zigbee 3.0 USB Dongle Plus Gateway, Universal Zigbee USB Gateway with Antenna for Home Assistant, IoBroker, Wireless Zigbee 3.0 USB Adapter(1 Pack)
  • Pre-flashed with Z-Stack 3.x.0 coordinator firmware
  • Can use ZHA in Home Assistant or use Zigbee2MQTT
  • Base on TI CC2652P + CP2102N
  • +20dBm output gain
  • SMA interface external antenna,Aluminum housing effectively reduces signal interference from peripherals

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;


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;



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;

[Upgraded Version] Aqara Motion Sensor P1, Requires AQARA HUB, 5-Year Battery Life, Configurable Detection Timeout, for Alert System and Automations, Compatible with HomeKit, Alexa, IFTTT
  • ✽[NOTES] Requires an Aqara Zigbee 3.0 hub (*Not support Zigbee hubs from other brands). Requires a secured 2.4 gigahertz Wi-Fi network connection for Hub M2/ M1S/ E1/M1S Gen2 and Camera Hub G2H Pro/ G2H, and 2.4/ 5 GHz Wi-Fi for Camera Hub G3. The Motion Sensor P1 is compatible with Aqara Home, HomeKit, Alexa, IFTTT. (*Note: Does not support light sensitivity function in HomeKit and Alexa; please update the hub’s firmware version to the latest for optimal use.)
  • [5-Year Battery Life] The Motion Sensor P1 has an industry-leading five-year battery life and will have acceptable battery life even in low temperatures or lightning-fast detection timeouts. The dimension of Aqara Motion sensor P1: ‎1.46″D x 2.17″W x 2.76″H
  • [Configurable Detection Timeout] The detection timeout can be easily configured without any hardware modifications. By configuring the timeout from 1 to 200 seconds in the Aqara Home app, you can save energy or sense every movement in no time.
  • [Adjustable Viewing Angle & Detection Distance] Extra-wide field of view: 170° for up to 4 meters and 150° for up to 7 meters. With a versatile 360° stand, you can easily adjust the viewing angle, and only trigger the sensor when it’s needed. Moreover, the three sensitivity modes (high, medium, and low) are configurable, and they refer to the distance the sensor will be triggered from.
  • [Alert System and Home Automations] By setting the Aqara Home Alert System or using it in HomeKit or other supported systems, you will enjoy constant monitoring, local sound, light alarms, and cloud notifications in case motion is detected. The sensor is also a part of smart home automations: configure the IF conditions and THEN actions, and many routine tasks such as turning on the lights with the Aqara Smart Wall Switch or controlling the TV with the Aqara Smart Plug can become automated.

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;


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.

2 thoughts on “How To Pass Through USB Zigbee Devices To Home Assistant Running In Docker”

  1. Thanks for writing this up, you absolute legend. Google/Reddit provided surprisingly few answers for this, this guide is perfect. Had it the USB stick and 3 devices up and running in under 10 minutes.

    • Thanks for the kind comment!

      Really appreciate you letting us know our content was helpful for you.

      I personally spent hours messing around getting this to work when in reality it’s a 10 minute job when you get your head around the process!



Leave a Comment