Koenkk /zigbee2mqtt
Zigbee 🐝 to MQTT bridge 🌉, get rid of your proprietary Zigbee bridges 🔨
★ 15,829⑂ 2,128👁 202⑃ 4,876● 21,413▤ 137
+4
Daily
15,829
stars
2,128
forks
202
watchers
4,876
prs
21,413
issues
137
releases
README
Zigbee2MQTT 🌉 🐝
Allows you to use your Zigbee devices without the vendor's bridge or gateway.
It bridges events and allows you to control your Zigbee devices via MQTT. In this way you can integrate your Zigbee devices with whatever smart home infrastructure you are using.
Getting started
The documentation provides you all the information needed to get up and running! Make sure you don't skip sections if this is your first visit, as there might be important details in there for you.
If you aren't familiar with Zigbee terminology make sure you read this to help you out.
Integrations
Zigbee2MQTT integrates well with (almost) every home automation solution because it uses MQTT. However the following integrations are worth mentioning:
Home Assistant
Home Assistant OS using the official addon (other installations)
Homey
Integration implemented in the Homey App (documentation & support)
Domoticz
Integration implemented in Domoticz (documentation).
Gladys Assistant
Integration implemented natively in Gladys Assistant (documentation).
ioBroker
Integration implemented in ioBroker (documentation).
Architecture
!Architecture
Internal Architecture
Zigbee2MQTT is made up of three modules, each developed in its own Github project. Starting from the hardware (adapter) and moving up; zigbee-herdsman connects to your adapter to handle Zigbee communication and makes an API available to the higher levels of the stack. For e.g. Texas Instruments hardware, zigbee-herdsman uses the TI zStack monitoring and test API to communicate with the adapter. The module zigbee-herdsman-converters handles the mapping from individual device models to the Zigbee clusters they support. Zigbee clusters are the layers of the Zigbee protocol on top of the base protocol that define things like how lights, sensors and switches talk to each other over the Zigbee network. Finally, the Zigbee2MQTT module drives zigbee-herdsman and maps the zigbee messages to MQTT messages. Zigbee2MQTT also keeps track of the state of the system. It uses a database.db file to store this state; a text file with a JSON database of connected devices and their capabilities. Zigbee2MQTT provides several web-based interfaces (zigbee2mqtt-frontend, zigbee2mqtt-windfront) that allows monitoring and configuration.
Developing
Zigbee2MQTT uses TypeScript. Therefore after making changes to files in the lib/ directory you need to recompile Zigbee2MQTT. This can be done by executing pnpm run build. For faster development instead of running pnpm run build you can run pnpm run build:watch in another terminal session, this will recompile as you change files.
Before running any of the commands, you'll first need to run pnpm install --include=dev.
Before submitting changes run pnpm run check:w then pnpm run test:coverage.
Supported devices
See Supported devices to check whether your device is supported. There is quite an extensTop issues
#8499🔋 (Xiaomi) Batteries values are questionable338 comments · 2021-08-24#10139Cannot OTA update Philips end-devices168 comments · 2021-12-11#22247[Feature request]: Please add RGB Effects to Aqara T1M Ceiling light (CL-L02D)134 comments · 2024-04-18#27262[New device support]: Aqara Climate Sensor W100 X0028HPT89132 comments · 2025-04-29#26230Philips Hue dimmer switch (RWL021) OTA not working132 comments · 2025-02-07#26407[New device support]: Aqara Display Switch V1 EU81 comments · 2025-02-17#24378[New device support]: Tuya BSD1767 comments · 2024-10-17#22338Nous A1Z stopped responding60 comments · 2024-04-28
Discussions
#33702New project - HackRF Zigbee sniffer0 comments · 2026-11-14#33695Innr RCL ceiling lights: coordinator → lamp works, lamp → coordinator stops for hours (Z-Stack, ~110 devices)0 comments · 2026-11-14#33693# ZY-M100-S_2 – Is OTA firmware updating possible without opening the device?0 comments · 2026-11-13#33687SONOFF MINI-ZB2GS fw 1.1.2: slower single press in detach mode — any way to disable the double-click window?0 comments · 2026-11-13#33683Help identifying EFS300 temperature functionality – ENGO EREL-16ZB0 comments · 2026-11-12#33655ZBMINIL2: Is firmware 1.0.19 or newer available for OTA update?1 comments · 2026-11-09#33653NOUS E6 (_TZE284_wtikaxzs): intermittent reporting stops, network icon shows X, but manual reports work1 comments · 2026-11-09#33643Naming things in Home Assistant0 comments · 2026-11-08
Latest release
2.14.3 2.14.3 2026-11-01Notes - Deprecation of 32-bit platforms: Running Zigbee2MQTT on 32-bit platforms is deprecated, and support ends when Node.js 22 reaches end-of-life (April 2027). At that point the minimum supported Node.js version becomes v24, and Node.js v24 no longer ships official builds for any 32-bit platform. This affects every installation method (Docker, bare-metal/Linux, etc.). For Docker the 32-bit Docker images (linux/386, linux/arm/v6 and linux/arm/v7) will not be updated anymore, and non-Docker installs on a 32-bit OS will no longer be able to run a supported Node.js version. If you run Zigbee2M