Zigbee2MQTT — Bridge Zigbee Devices to MQTT Without Vendor Lock-In

Introduction

Zigbee2MQTT bridges Zigbee devices to MQTT, letting you control smart home hardware without proprietary gateways. It supports over 4000 devices from hundreds of vendors and integrates with Home Assistant, Node-RED, and any MQTT-based system.

What Zigbee2MQTT Does

• Translates Zigbee protocol messages into standard MQTT topics and payloads
• Supports over 4000 devices from brands like IKEA, Philips Hue, Aqara, and Sonoff
• Provides a built-in web dashboard for device management and pairing
• Enables OTA firmware updates for supported Zigbee devices
• Exposes device state, configuration, and commands via structured JSON over MQTT

Architecture Overview

Zigbee2MQTT runs as a Node.js process that communicates with a Zigbee USB coordinator via serial. It uses the zigbee-herdsman library to manage the Zigbee network and translates device events into MQTT messages published to a broker like Mosquitto. The frontend is a single-page app served by the same process.

Self-Hosting & Configuration

• Requires a compatible Zigbee coordinator (CC2652, EFR32, or similar USB dongle)
• Configure via data/configuration.yaml with MQTT broker address and serial port
• Set permit_join to true temporarily when pairing new devices
• Enable frontend by setting frontend.port in configuration
• Run as a Docker container or install directly on Linux, including Raspberry Pi

Key Features

• Vendor-agnostic support for 4000+ devices across 400+ brands
• Local-only operation with no cloud dependency or internet requirement
• Device groups, scenes, and bind functionality at the Zigbee level
• Touchlink commissioning for factory-reset pairing of some devices
• Extensible via custom converters for unsupported devices

Comparison with Similar Tools

• deCONZ / Phoscon — GUI-focused Zigbee gateway; Zigbee2MQTT is more configurable and supports more devices
• ZHA (Zigbee Home Automation) — Home Assistant built-in integration; Zigbee2MQTT runs independently and works with any MQTT consumer
• Hubitat — Commercial hub with local processing; Zigbee2MQTT is free and open source
• SmartThings — Samsung cloud-dependent hub; Zigbee2MQTT is fully local and privacy-first
• Thread/Matter — Newer IoT standard; Zigbee2MQTT bridges the vast existing Zigbee ecosystem

FAQ

Q: Which Zigbee coordinator should I buy? A: The SONOFF Zigbee 3.0 USB Dongle Plus (CC2652P) is widely recommended for its range, stability, and price.

Q: How many devices can Zigbee2MQTT handle? A: The Zigbee network supports up to 200+ direct devices, with router devices extending capacity. Many users run 100+ devices reliably.

Q: Does Zigbee2MQTT require Home Assistant? A: No. It publishes to any MQTT broker and can be consumed by Node-RED, custom scripts, or any MQTT client.

Q: Can I migrate from a Philips Hue bridge? A: Yes, but devices must be factory-reset and re-paired. Zigbee2MQTT supports Hue bulbs, motion sensors, and switches.

Sources

• https://github.com/Koenkk/zigbee2mqtt
• https://www.zigbee2mqtt.io/