ZigBee Installation and Practical Example

ZigBee Basics and Overview

• Required Hardware
  • Raspberry Pi (I am currently using Raspberry OS Buster, but the following documentation may also work for other versions)
  • SONOFF Zigbee 3.0 USB Dongle Plus ZBDongle-P (zigbee2mqtt also supports a range of other ZigBee coordinators)
• Used Software
  • zigbee2mqtt
    • The software is open source and supports an immense variety of ZigBee devices. The interface is very user-friendly.
    • Most importantly, no external cloud service from another company is required to operate your own devices.
  • mosquitto
    • The setup and usage of MQTT with mosquitto is documented in a separate post. An MQTT server is required.
  • Raspberry OS (Buster)

What is ZigBee and why do you need it?

ZigBee is a specification for wireless networks with low data rates and low power consumption. Many ZigBee devices act as relay stations for each other – automatically and without additional configuration. This allows you to network your home with ZigBee without having to buy additional repeaters.

With ZigBee2MQTT, the signals can be converted into MQTT topics, which can then be processed further with a smart home hub.

Installation on Raspberry Pi OS Buster (and other Debian-based systems)

Connect to your Raspberry Pi via SSH using the default user “pi”.

# Update apt sources and install required dependencies
sudo apt update && sudo apt -yf upgrade
sudo apt -yf install nodejs git make g++ gcc

# Set up Node.js + required dependencies
sudo curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -

# Prepare and install zigbee2mqtt
sudo mkdir /opt/zigbee2mqtt
sudo chown -R ${USER}: /opt/zigbee2mqtt
git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
npm ci --prefix /opt/zigbee2mqtt

First, update the sources under Raspberry OS, bring the system up to date, and install the required packages.

Currently, no official package exists in the Raspberry OS repositories. However, there are many other installation alternatives, such as Docker or add-ons in smart home hubs.

ls -l /dev/serial/by-id/

Next, you need to find your ZigBee coordinator – the USB stick that will control the ZigBee network. Mine came pre-flashed, so simply plugging it in was enough. I found it under /dev/serial/by-id/. To avoid conflicts, it should be identified by zigbee2mqtt using its ID. Enter the full device path you find with the above command into /opt/zigbee2mqtt/data/configuration.yaml.

# MQTT settings
mqtt:
  base_topic: zigbee2mqtt
  server: 'mqtt://localhost'
  user:******* # Enter your configured MQTT credentials here
  password: ******* # Enter your configured MQTT credentials here
  client_id: Zigbee

# Serial settings
serial:
  # Location of the adapter (see first step of this guide)
  port: >-
    /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_**********-if00-port0
advanced:
    network_key: GENERATE
frontend:
  port: 8081 # Default is 8080, but it was already in use on my system

This is an example of my configuration.yaml at software initialization. During operation, zigbee2mqtt will add further entries that you can configure via the interface.

npm start --prefix /opt/zigbee2mqtt

Start zigbee2mqtt and check if it works. The last step is enabling autostart.

[Unit]
Description=zigbee2mqtt
After=network.target

[Service]
ExecStart=/usr/bin/npm start
WorkingDirectory=/opt/zigbee2mqtt
StandardOutput=inherit
# Or use StandardOutput=null if you don't want Zigbee2MQTT messages filling syslog, for more options see systemd.exec(5)
StandardError=inherit
Restart=always
RestartSec=10s
User=pi

[Install]
WantedBy=multi-user.target

Create the above file under /etc/systemd/system/zigbee2mqtt.service.

sudo systemctl enable zigbee2mqtt.service
sudo systemctl start zigbee2mqtt

This makes the new service known to the system and starts it if needed.

First Steps

Enter the address of your Raspberry Pi in your browser and add the configured port “:8081”.

Enable pairing mode by clicking on “Permit join (All)” and power on an unpaired ZigBee device. It should appear right away.

The device name also defines its ZigBee path. You can use “/” to create structures. For Hue lamps, I use something like “ug/officeAlex/undef/lightBulb/Hue/WhiteAndColor/E27/[network address]” in line with MQTT best practices.

Under “Logs” you can see directly what is happening.

In fact, I was able to completely replace the original Hue Bridge. zigbee2mqtt supports all the functions I use, as well as OTA updates for the lamps. I am still working on dynamic scenes and music responsiveness.

With “Groups” you can control multiple devices at once. This replaces “Rooms” and “Zones” as they were available under the Hue Bridge.