📶 Setup Zigbee2MQTT — Bridge Zigbee Devices to MQTT
Deploy Zigbee2MQTT to convert Zigbee device signals into MQTT messages, enabling hundreds of Zigbee sensors and smart devices to work with any home automation system.
📦 Resources & Setup Scripts
Grab the automated bash script from GitHub to follow along with the video.
Quick Install:
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/iot/zigbee2mqtt/zigbee2mqtt-ubuntu.sh
chmod +x zigbee2mqtt-ubuntu.sh
sudo bash zigbee2mqtt-ubuntu.shTutorial Steps
1 Download & Run the Installer
Before running the script, plug in your Zigbee USB coordinator dongle (e.g. SONOFF Zigbee 3.0 USB Dongle Plus). The script detects the device path, installs Docker, configures Zigbee2MQTT with your coordinator, and starts the container. The coordinator is passed into Docker using the device flag.
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/iot/zigbee2mqtt/zigbee2mqtt-ubuntu.sh
chmod +x zigbee2mqtt-ubuntu.sh
sudo bash zigbee2mqtt-ubuntu.sh
# The container is started with device passthrough:
# --device=/dev/ttyUSB0:/dev/ttyUSB02 Access the Web UI
Open your browser and navigate to the Zigbee2MQTT frontend. The dashboard shows connected devices, their status, network map, and real-time logs. You can manage all settings from the web interface without editing configuration files.
http://<your-server-ip>:80803 Pair Zigbee Devices
In the web UI, click "Permit join (All)" to enable pairing mode for 3 minutes. Press the pairing button on your Zigbee device (each device has a specific pairing sequence — consult the device manual). The device will appear in the dashboard with its name and model. Zigbee2MQTT supports 3000+ devices from brands like IKEA, Philips Hue, Aqara, and Tuya.
4 Connect to Home Assistant
Zigbee2MQTT automatically publishes device data to your MQTT broker using the homeassistant/ discovery prefix. In Home Assistant, add the MQTT integration (Settings → Devices & Services → MQTT) and point it to your Mosquitto broker. All Zigbee devices will be discovered automatically as Home Assistant entities with no additional configuration needed.
# In Zigbee2MQTT configuration.yaml, ensure this is set:
homeassistant: true
mqtt:
server: mqtt://<mosquitto-ip>:1883
user: username
password: passwordPorts Used
| Port | Purpose |
|---|---|
| 8080 | Zigbee2MQTT Web UI |
| /dev/ttyUSB0 | Zigbee USB coordinator (device passthrough) |
Overview
Zigbee2MQTT bridges Zigbee protocol devices (smart bulbs, sensors, switches) to an MQTT broker, making them controllable by Home Assistant and other automation platforms — entirely without manufacturer clouds or apps. It supports over 3,000 Zigbee devices from hundreds of manufacturers.
Why Use It
Zigbee devices from brands like Ikea, Philips Hue, Sonoff, and Tuya normally require their respective cloud apps. Zigbee2MQTT replaces all those apps with one local bridge, eliminating internet dependency, preventing data collection, and enabling unified control from Home Assistant or any MQTT client.
When You Need It
Who Should Use It
Real Use Cases
Main Features
How to Use After Installation
Security Best Practices
Ports and Firewall Notes
Zigbee2MQTT's web dashboard runs on port 8080. This is an internal tool — keep it accessible only from your local network. The service communicates with Mosquitto over port 1883 internally. No public internet access is required or recommended.
Backup and Maintenance
Common Mistakes
Troubleshooting
Alternatives
Alternatives include the brand-specific apps (Ikea Home Smart, Hue app), Home Assistant's built-in Zigbee Home Automation (ZHA), Deconz with Phoscon, and Z-Wave JS for Z-Wave devices. Choose Zigbee2MQTT for the widest device support and most active community.
When Not to Use It
Avoid Zigbee2MQTT if you only have Philips Hue devices and already own a Hue Bridge — the native integration works well. Also avoid if you are not comfortable with YAML configuration files and Linux serial device management.
PrismaTechWork Professional Help
PrismaTechWork provides end-to-end infrastructure services — from initial deployment and security hardening to ongoing monitoring, automated backups, and dedicated support. Whether you need a single-server setup or a multi-site network, our team ensures your infrastructure is built right, secured properly, and maintained reliably.
Frequently Asked Questions
What Zigbee coordinator hardware do I need?
You need a supported Zigbee coordinator USB dongle. The most popular and recommended options are the SONOFF Zigbee 3.0 USB Dongle Plus (CC2652P chip), the SMLIGHT SLZB-06 (network coordinator, no USB needed), and the Electrolama zig-a-zig-ah (zzh). Avoid older CC2531 sticks — they have limited range and are outdated.
How many Zigbee devices can I connect?
A single Zigbee coordinator supports up to around 50 direct connections. The Zigbee mesh extends range significantly — mains-powered devices (bulbs, plugs) act as routers and relay signals from battery-powered end devices (sensors, remotes). A well-structured mesh can support hundreds of devices.
Does Zigbee2MQTT work without internet?
Yes — once set up, Zigbee2MQTT runs completely offline. It communicates locally between the Zigbee coordinator USB dongle, the Mosquitto MQTT broker, and Home Assistant entirely on your local network. Internet is only needed for initial setup, updates, and checking the supported devices list.
How do I pair a new Zigbee device?
Enable pairing mode in the Zigbee2MQTT dashboard or set permit_join: true in configuration.yaml temporarily. Then put your device into pairing mode (usually by pressing the reset button or power-cycling it a specific number of times — check the device manual). The device appears in the dashboard when paired successfully.
Can I control Zigbee devices without Home Assistant?
Yes. Zigbee2MQTT publishes device states and accepts commands via MQTT topics. You can control devices using any MQTT client, Node-RED, ioBroker, openHAB, or any automation system that speaks MQTT. Home Assistant is popular but not required.
How do I update Zigbee device firmware?
For supported devices, Zigbee2MQTT can perform OTA (over-the-air) firmware updates directly. Go to the device page in the Zigbee2MQTT dashboard and click Check for update. If an update is available, click Update. The device downloads and applies the firmware update wirelessly.