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.
Grab the automated bash script from GitHub to follow along with the video.
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/iot/zigbee2mqtt/zigbee2mqtt-ubuntu.sh
chmod +x zigbee2mqtt-ubuntu.sh
sudo bash zigbee2mqtt-ubuntu.shBefore 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/ttyUSB0Open 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>:8080In 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.
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: password| Port | Purpose |
|---|---|
| 8080 | Zigbee2MQTT Web UI |
| /dev/ttyUSB0 | Zigbee USB coordinator (device passthrough) |
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.