Home automation has come a long way, with many devices now supporting wireless protocols like Zigbee for easy integration. However, one challenge has been the walled gardens created by different vendors - with proprietary bridges, hubs, and ecosystems locking you in.
This is where Zigbee2mqtt comes in - an open-source software project that bridges Zigbee devices directly to MQTT. It eliminates vendor lock-in allowing you to easily control, automate, and integrate your Zigbee devices over MQTT.
In this guide, I will dive into what exactly Zigbee2mqtt is, how it works, why it's useful, and how to get set up with it.
What is Zigbee2MQTT?
Zigbee2mqtt is an open-source software project that allows you to use inexpensive Zigbee devices with any home automation system without the vendor's bridge or gateway. It bridges events and allows you to control your Zigbee devices via MQTT.
In simple words, it acts as a translator between Zigbee devices and a MQTT broker. It supports all major brands using the Zigbee protocol, including Philips Hue, IKEA TRADFRI, Xiaomi Aqara, and many more.
How Zigbee2MQTT Works
Zigbee2mqtt requires a Zigbee gateway like CC2652 to be plugged into your system. This gateway connects to your Zigbee mesh network wirelessly. The Zigbee2mqtt software runs locally and connects to the CC2652 stick using serial over USB.
It translates Zigbee messages received from the mesh network into MQTT messages. These MQTT messages are then published to an MQTT broker like Mosquitto which can be accessed by other home automation platforms. Commands can be sent to Zigbee devices by publishing MQTT messages to control topics.
This allows your Zigbee devices to integrate with any software that supports MQTT like Home Assistant without the need for proprietary hubs or bridges.
Advantages of using Zigbee2MQTT
Here are some of the key advantages of using Zigbee2MQTT:
Works with a wide range of inexpensive Zigbee devices from different manufacturers. You don't need to stick with a single brand's ecosystem.
Provides local control of devices without relying on vendor's cloud services. Your device data stays private.
Allows integrating Zigbee devices directly with home automation platforms like Home Assistant using MQTT. Removes dependency on proprietary bridges/hubs.
More reliable Zigbee network handling compared to bridges provided by vendors. Automatically manages network health and repairs.
Allows advanced features like binding devices directly, building scenes, and automations across vendors.
Active open-source community provides quick support, bug fixes, and new feature additions.
Easy to get started using the friendly UI, ample documentation, and active community forums.
Highly customizable to suit your specific needs - encryption, advanced Zigbee config, custom MQTT topics, etc.
Regular updates and maintenance ensure support for new devices and standards.
So in summary, Zigbee2MQTT provides flexibility, reliability, privacy, and interoperability compared to locked-down single-vendor bridges. The open-source nature ensures transparency and continuous improvements as well.
Difference between Zigbee and MQTT
Zigbee and MQTT are two different technologies that serve different purposes:
Zigbee is a protocol for low-power local mesh networks typically used for IoT and smart home devices like lights, sensors, etc. It defines how Zigbee-compatible devices communicate with each other directly over a wireless mesh network.
MQTT is a publish-subscribe-based messaging protocol commonly used in IoT and M2M communication. It allows remote devices to publish data to topics that can be subscribed to by other clients.
The key differences are:
Zigbee operates on a local mesh network, while MQTT uses TCP/IP and can work over WANs like the internet.
Zigbee deals with low-level device-to-device communication, and MQTT focuses on data transmission between remote clients and brokers.
Zigbee has security and networking specifications included, and MQTT relies on underlying network security like TLS.
MQTT uses a topic/subscription model allowing 1 to many propagation of data. Zigbee has no inherent publish-subscribe model.
Zigbee handles local device networking while MQTT enables remote client communication. Zigbee2MQTT bridges these two technologies allowing Zigbee devices to transmit data to remote systems over MQTT.
Setting up Zigbee2MQTT
Hardware requirements
To use Zigbee2mqtt, you will need:
A Zigbee USB coordinator dongle with the CC2652 chip
A computer or Raspberry Pi to run the Zigbee2mqtt software
Zigbee-compatible devices like smart bulbs, sensors, switches, etc.
Best Zigbee2MQTT Coordinators
Zigbee2MQTT supports any coordinator that is based on the Texas Instruments CC2652/CC1352 chip.
The CC2652 is the most popular and affordable Zigbee stick for this project. It provides a good range and supports all the necessary features.
In my personal experience, the Conbee II has performed the best for me in Zigbee2MQTT but I would also highly recommend the SONOFF Zigbee 3.0 USB Dongle Plus ZBDongle-P as it can easily be flashed to support Thread and run custom firmware to turn it into a Zigbee router to extend your network.
| ConBee II | SONOFF Zigbee 3.0 USB Dongle Plus ZBDongle-P |
 |  |
| $34.55 | $31.99 |
Tip
Looking for a Zigbee coordinator that is compatible with Home Assistant? Check out my detailed article here.
Software requirements
A machine running Linux, Windows or MacOS
Docker or Node.js installed to run Zigbee2mqtt
MQTT broker (e.g. Mosquitto) for integration
Docker provides the simplest setup, while Node.js allows more customization if needed. The MQTT broker is required for publishing data to other platforms.
If you use Home Assistant then using the Zigbee2MQTT and MQTT broker addons will be the easiest way to get started.
Installation steps
Get a CC2652 USB stick. Flash it with custom firmware for Zigbee2mqtt compatibility.
Install Docker and Docker Compose on your machine.
Create a docker-compose.yml file for Zigbee2mqtt and MQTT broker.
Connect CC2652 stick and start containers using docker-compose up.
Accept zigbee2mqtt pairing requests on your devices.
(Optional) Integrate MQTT data with Home Assistant or other platforms.
Tip
Follow my Zigbee2MQTT guide for Home Assistant for detailed instructions on how to install and configure Zigbee2MQTT.
Configuring Zigbee2MQTT
Integrations
Out of the box, Zigbee2mqtt publishes data to MQTT in a Home Assistant friendly format. This allows easy integration with Home Assistant for automations and control.
Other common integrations include:
Node-RED: For visual programming and automation flows.
Grafana: Build custom dashboards and graphs.
InfluxDB: Time series database for sensor data.
Advanced configuration
The docker-compose file provides a basic setup. But Zigbee2mqtt has tons of options for advanced users:
Network encryption keys for security
Device-specific options and overrides
Advanced Zigbee options for experimenters
Publishing MQTT data to custom topics
Integrated Home Assistant discovery
Check the documentation for details on all the available options.
Using Zigbee2MQTT
Paired devices
Once running, Zigbee2mqtt will automatically discover and connect with nearby supported Zigbee devices. You can view and control the paired devices from the Zigbee2mqtt frontend.
Clicking on a device allows changing settings like friendly names, icons, etc. You can also find useful info like the model, Zigbee endpoints, etc.
Publishing data
Zigbee2mqtt publishes data from all paired devices to MQTT topics. For example, motion sensor events, temperature readings, button clicks, etc.
This data can be used for automation and visualization. You can watch the MQTT traffic directly using a tool like MQTT Explorer.
Device groups
You can configure Zigbee2mqtt to add devices into custom groups. For example, to group all motion sensors or lights on a particular floor.
Groups allow controlling multiple devices together, e.g. turning off all lights on the top floor. This is more convenient than managing each device individually.
Zigbee2MQTT Port
The default port used by Zigbee2MQTT is 8080. This allows accessing the frontend web UI by going to http://[ip]:8080 in your browser.
Some key points about the Zigbee2MQTT port:
The port can be changed by setting the PORT environment variable in the docker run command or docker-compose file. For example:
environment:
- PORT=8085If you change the port, make sure to update any integrations or links using the old port.
Port 8080 is common for home automation services as it is an alternative HTTP port that is normally not used by other applications.
The port only allows accessing the frontend/UI. The underlying MQTT broker runs on the default port 1883 and is accessed internally by Zigbee2MQTT.
You may need to open or forward the chosen port on your router for external access if required.
If running on a service like Zigbee2MQTT Hass.io add-on, the port will be managed by the addon configuration.
So in summary, 8080 is the standard port but can be customized if needed. Just make sure to update integrations, port forwarding, etc. to match any changes. The MQTT broker itself always runs on the fixed port 1883.
Zigbee2MQTT Frontend
Adding frontend: true to your configuration.yaml file will enable the Zigbee2MQTT frontend from where you can see the attached devices.
Additional options and settings include:
Create and manage device groups
View your Zigbee network map
Manage OTA firmware updates
View detail logs
Zigbee2MQTT web interfaceZigbee2MQTT Automations
A key benefit of Zigbee2mqtt is enabling automation across different vendors and devices. There are two main approaches:
Use Home Assistant automations by integrating Zigbee2mqtt as MQTT. React to MQTT messages from sensors.
Create rules directly in Zigbee2mqtt using plugins like Node-RED. This allows automation without Home Assistant.
Automations can be designed to suit your specific needs. Some examples include:
Turn on hall lights at sunset
Flash front porch lights when a door opens
Notify on smoke alarm activation
Tips for troubleshooting Zigbee2MQTT
Here are some tips if you are running into issues with your Zigbee2mqtt setup:
Check logs from the Zigbee2mqtt frontend or using
docker logs. Look for warnings or errors.Try resetting the network cache if devices are not pairing using the reset button the CC2652.
Ensure the CC2652 stick is fully compatible and flashed with the latest firmware.
Delete old Zigbee2mqtt data and do a clean re-pairing of all devices.
Post questions on the Zigbee2mqtt forum or GitHub discussions for help.
As a last resort, backup your configuration and do a fresh re-install of Zigbee2mqtt.
Conclusion
Zigbee2mqtt provides a locally controlled Zigbee to MQTT bridge for smart home automation. It simplifies integrating a wide range of Zigbee devices across different vendors with systems like Home Assistant. With cheap CC2652 hardware, easy setup via Docker, and tons of customizations, it's a great way to build your smart home automation system.
