koenkk/zigbee2mqtt

Zigbee2MQTT is a bridge that lets people use Zigbee smart-home devices without the original vendor's hub or gateway. Zigbee is a low-power wireless protocol used by many lights, sensors, switches, and plugs from brands like Philips Hue, Ikea, Xiaomi, and OSRAM. Normally each brand expects you to use its own bridge. This project replaces those bridges with a single piece of software that talks to the devices directly and republishes everything as MQTT messages. MQTT is a lightweight messaging protocol that many home-automation systems already understand. Because Zigbee2MQTT speaks MQTT, it slots into almost any setup. The README calls out direct integrations with Home Assistant (via an official add-on for Home Assistant OS), Homey, Domoticz, Gladys Assistant, and ioBroker. For each of those, the README points to the relevant add-on or wiki page. Internally, the software is split into three modules, each in its own GitHub project. zigbee-herdsman talks to the USB radio adapter that physically receives Zigbee traffic, for example a Texas Instruments stick using the TI zStack API. zigbee-herdsman-converters maps individual device models to the Zigbee clusters they support; clusters are layers of the Zigbee protocol that define how lights, sensors, and switches talk to each other. The top-level Zigbee2MQTT module drives the lower layers and translates Zigbee messages to MQTT. Device state is kept in a text file called database.db that stores connected devices and their capabilities. Two web frontends, zigbee2mqtt-frontend and zigbee2mqtt-windfront, provide monitoring and configuration in a browser. The code is written in TypeScript. Contributors install dependencies with pnpm, then run pnpm run build, or pnpm run build:watch for live recompilation. Before submitting changes the README asks contributors to run a check command and a test-coverage command. The documentation site at zigbee2mqtt.io covers initial setup, integration guides, and a long list of supported devices, plus instructions for adding support for a new device that is not yet listed. Help is offered through GitHub issues and a Discord server linked from the badges at the top of the README.