All good things come to end.

As my network grew larger, I experienced significant stability issues with Zigbee2mqtt and switched to a deCONZ / Conbee II setup with much better results. More about that here…

I’m way overdue for another smart home post. I’ve made many improvements over the past six months and am very pleased with my production setup which involves an Intel NUC running Ubuntu 18.04 with all services (e.g., MQTT, Home Assistant, Plex, etc.) containerized using Docker.

I recently went through the process of flashing a few CC2531 dongles to replace two Xioami hubs. Xioami makes excellent, inexpensive sensors that are perfect for apartments but use a unique Zigbee library making them notoriously difficult to work with other hub solutions. Using the CC2531 with Zigbee2mqtt bridge software, you can eliminate the Xioami hub (and other popular hubs) with the CC25351 dongle.

Why Zigbee2mqtt?

Key benefits include:

  • Xioami hubs regularly phone home to China. If you’re focused on a secure, private smart home system, this is not ideal. I’d previously blocked the Xioami gateway from connecting to the internet (local control is enabled), but it continually flashes whenever it tries to connect to the internet.
  • The CC2531/Zigbee2mqtt solution eliminates the need to have multiple Zigbee hubs. You can take Hues, Ikea’s Trade, Xiaomi, and others and replace them with a single solution.
  • Building on the consolidation theme, you don’t need multiple apps on your phone. Just use Home Assistant to control all the devices. MQTT does a great job as messaging protocol used to communicate between the Zigbee coordinate, any routers in the mesh, and the end devices.


The overall process is pretty straightforward:

  1. Flash the coordinator with Zigbee2mqtt firmware
  2. Install Zigbee2mqtt (I used the Docker setup outlined here)
  3. Pair your devices

You should already have an MQTT broker established at this point. In my case, I’m running Mosquitto in a Docker Container and already integrated with Home Assistant before establishing Zigbee2mqtt.

CC2531 + EquipmentTo get started, you’ll need:

  • At least x1 CC2531. All Zigbee mesh networks consist of 1 (and only 1) coordinator, option routers (as many as you need), and at least one device.
  • CC debugger + downloader cable
  • A Zigbee device for testing. In my case, I’m using an out of the box Xioami motion sensor.

Head on over to the immensely useful and well documented Zigbee2mqtt site. Carefully follow the Getting Started instructions step by step. The overall process is easy and should take less than 1 hour IF you follow the instructions.

I flashed the router on my Intel NUC running Ubuntu 18.04. The only issue I had was related to the usblib-1.0 dependency.  I kept getting a “Dependency not met” error when trying to run the cc-tool configure script. I solved it by installing the usblibdev package. After that, the remaining configuration worked as outlined in the instructions.

Next, I set up the Zigbee2mqtt Docker container and configured the docker-compose to integrate with the rest of my services stack. For me it looks like this:

Copy to Clipboard

One other thing I found confusing was to ensure you install/update the correct nodejs and npm outlined on the main installation page here. I had incorrectly assumed these dependencies would be handled in the Docker container, but apparently not.

With Zigbee2mqtt running, it’s time to configure it before pairing any devices (general instructions here).

For my initial test, I used a Xioami MiJia human body movement sensor (occupancy). I have around ~50 Xioami devices total in my setup and like their robust design and low cost. After resetting the device. Pro tip: a SIM card tool works great to reset most Xioami devices that don’t have physical buttons. After performing a reset, you can confirm the connection in the Zigbee2mqtt Docker container and by checking the Zigbee2mqtt config file which will also reflect the new device if all goes well.

Cool. Thirty minutes in and everything’s working flawlessly. Exciting stuff and I was amazed at how easy everything works. Going into the project, I anticipated the usual headaches of baby-stepping through errors, especially with the hardware involved.

3D Printed CasesThe next step is to flash the router firmware to a few more USB dongles. This is crucial if you’re using battery powered Zigbee devices (e.g., Xioami) because these devices generally don’t act as repeaters; they will not strengthen the Zigbee mesh. The CC2531 has a relatively small range (~30 ft). The coordinator also has a 15 device limit which can be worked around by just adding routers. Each new router supports 20 direct child devices.

Routers aren’t necessary if you’re using other Zigbee devices that function as repeaters. In my case, I’m only using Xioami sensors which are battery powered and don’t act as repeaters. Eventually, I’ll swap out all my Wi-Fi bulbs in favor of Hue. Hue bulbs use the ZigBee standard and each bulb act as a repeater to the network. Once this happens, the routers won’t be necessary.  Each router can be plugged into a low powered wall mounted USB adapter. If you go this route, it’s a good idea to get a vertical adapter (like this) or use a right angle adapter (like this) to keep things flush. This is especially important if you have small children or clumsy pets.  

Finally, I wasn’t thrilled with having a bunch of exposed dongles all over the place. You can order 3D printed cases (or print your own if you have a printer) using this .STL file found on Thingiverse.  


  • Replace vendor specific Zigbee hubs with Zigbee2mqtt.
  • Follow the instructions outlined on the Zigbee2mqtt site to set up using the configuration and devices of your choice.
  • Add routers to extend the range of your Zigbee mesh.
  • Don’t forget to harden your Zigbee network. Consider taking a good look at your Home Assistant and MQTT broker attack surfaces.
  • BONUS: 3D print cases to enhance the aesthetics of your setup. Don’t make the same mistake I did and order all the same color cases (assuming you use multiple routers). I have six routers + the coordinator, and all have identical white cases…