Set Up Zigbee2MQTT on a Raspberry Pi (Step-by-Step with USB Dongle Plus-E)

Zigbee is one of the most powerful protocols in the smart home and IoT space, but getting started can be a pain. In this guide, we’ll walk you through setting up Zigbee2MQTT on a Raspberry Pi using the popular Zigbee 3.0 USB Dongle Plus-E from Sonoff. This tutorial is ideal for developers, hobbyists, or anyone looking to integrate Zigbee sensors without proprietary hubs.

What You'll Need

• Raspberry Pi 4 (or 3) with Raspberry Pi OS installed
• Internet access on the Pi
• Zigbee 3.0 USB Dongle Plus-E (EFR32MG21 based)
• A supported Zigbee sensor — we used the THIRDREALITY Motion Sensor (Model: 3RMS16BZ)

Step 1: Plug in the USB Dongle

Insert your Sonoff Zigbee 3.0 USB Dongle Plus-E into any USB port on the Raspberry Pi. You can verify the path using:

ls /dev/serial/by-id

You should see something like:

usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_XXXXXXXXXXXX-if00-port0

Step 2: Install Mosquitto (MQTT Broker)

FYI you will be running these commands in a terminal window.

sudo apt update
sudo apt install -y mosquitto mosquitto-clients
sudo systemctl enable mosquitto

Test with:

mosquitto_sub -t zigbee2mqtt/bridge/state -v

If nothing prints, that’s normal until Zigbee2MQTT starts publishing data.

Step 3: Clone and Install Zigbee2MQTT

sudo apt install -y git curl
sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
cd /opt/zigbee2mqtt

Install Node.js 18.x

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

Install pnpm (required for build)

sudo npm install -g pnpm

Install dependencies

sudo pnpm install

Step 4: Configure Zigbee2MQTT

Open the config file:

sudo nano /opt/zigbee2mqtt/data/configuration.yaml

Paste and edit with your dongle's serial port path:

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost:1883

serial:
  port: /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_XXXXXXXXXXXX-if00-port0
  adapter: ezsp

frontend:
  port: 8080
  host: 0.0.0.0
  enabled: true

advanced:
  log_level: info


Example of a complete configuration file:

https://github.com/shillehbean/youtube-p2/blob/main/configuration.yaml

Step 5: Start Zigbee2MQTT

cd /opt/zigbee2mqtt
sudo npm start

You should see output like:

Starting Zigbee2MQTT...
Zigbee2MQTT started!

If you see warnings about ezsp being deprecated, ignore them for now — this is normal with newer dongles.

Step 6: Access the Zigbee2MQTT UI

Open your browser and go to (visit this link on your local computer):

http://<your_pi_ip>:8080

If it loads, you're golden. You’ll see the Zigbee2MQTT dashboard. Turn on “Permit Join” at the top right to allow devices to pair.

Final Step: Pair Your Zigbee Sensor

We used the THIRDREALITY Zigbee Motion Sensor (Model: 3RMS16BZ), a battery-powered motion detector that works great out of the box with Zigbee2MQTT.

1. Click “Permit Join” in the Zigbee2MQTT UI
2. On the sensor, press and hold the pairing button for 5–10 seconds until the LED starts blinking
3. Watch your Zigbee2MQTT logs — you’ll see something like:

[info] z2m: Successfully interviewed '0xb40e060fffe0595b'
[info] z2m: Device '0xb40e060fffe0595b' is supported, identified as: Third Reality Wireless motion sensor (3RMS16BZ)

The sensor will now appear in your UI under “Devices.” Rename it to something useful like motion_office.

Conclusion

You've now got a working Zigbee2MQTT setup on a Raspberry Pi with full access to a web UI, live MQTT data, and a paired Zigbee motion sensor — all with open-source software and no vendor lock-in.

This setup is perfect for DIY smart home dashboards, Home Assistant integration, or custom MQTT automation. For more tutorials like this, including how to trigger actions from sensors or log motion events, follow us at ShillehTek on YouTube.

Need help or want a custom Raspberry Pi IoT project built? Contact us here.