zigbee2mqtt README

The project's README from github.com/Koenkk/zigbee2mqtt. As one markdown file: README.md.



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


Home Assistant OS using the official addon (other installations)


Homey

Homey


Integration implemented in the Homey App (documentation & support)


Domoticz

Domoticz


Integration implemented in Domoticz (documentation).


Gladys Assistant

Gladys Assistant


Integration implemented natively in Gladys Assistant (documentation).


ioBroker

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 extensive list, including devices from vendors like Xiaomi, Ikea, Philips, OSRAM and more.

If it's not listed in Supported devices, support can be added (fairly) easily, see How to support new devices.

Support & help

If you need assistance you can check opened issues. Feel free to help with Pull Requests when you were able to fix things or add new devices or just share the love on social media.

zigbee2mqtt (Koenkk/zigbee2mqtt)

Searching Database…

15.7K ·GitHub
Zigbee2mqtt
这是什么？Zigbee2MQTT 让你通过 MQTT 控制 Zigbee 设备，而不必使用厂商自有的专用网桥或网关，因此你可以把这些设备接入任何你喜欢的智能家居系统。
这是我要安装的应用，还是需要自己运行的服务？它是一个自托管的 Node.js/TypeScript 服务，需要在连接了 Zigbee 适配器的机器上持续运行，并附带一个网页前端（zigbee2mqtt-frontend 或 zigbee2mqtt-windfront），用于监控和配置。
我该如何让它运行起来？请按照官方文档操作，文档会讲解安装和首次运行的配置步骤；如果你对 Zigbee 还不熟悉，文档里也解释了相关术语。
我需要 Zigbee USB 适配器和 MQTT 消息代理吗？需要。zigbee-herdsman 需要 Zigbee 协调器适配器（例如德州仪器的硬件）才能与你的设备通信；而且由于 Zigbee2MQTT 会把所有数据桥接到 MQTT，因此你还需要运行一个 MQTT 消息代理。
它支持市面上所有的 Zigbee 设备吗？小米、宜家、飞利浦和 OSRAM 等主流品牌基本都支持，但你应先查看“支持的设备”列表；列表中没有的设备，通常只需按照设备支持指南操作，就能比较容易地添加。
它能接入哪些智能家居平台？由于它使用 MQTT 通信，几乎可以与任何家庭自动化系统配合使用，并且针对 Home Assistant、Homey、Domoticz、Gladys Assistant 和 ioBroker 提供了有文档说明的专门集成。
Zigbee2MQTT 如何记录我的设备？它把已连接的设备及其功能保存在 database.db 文件中，这是一个纯文本的 JSON 数据库，由 Zigbee2MQTT 模块在内部维护。
这个项目背后的三个内部模块是什么？zigbee-herdsman 负责与硬件适配器通信，zigbee-herdsman-converters 把设备型号映射到 Zigbee 簇（cluster），Zigbee2MQTT 模块则将它们串联起来，并把消息转发到 MQTT。
What are similar projects?glasshouse, esphome, WLED, ha_xiaomi_home, EchoMuse, Tasmota, core, local_roborock_server
Which topics is it in?smart-home, mqtt, home-assistant, home-automation, iot, hardware, json, dashboard, monitoring, hacktoberfest, gplv3, automation
Creator
Koenkk
Size
112.9 MB
Stars
15.7K
Updated
CommitOct 02Release2.14.2Oct 01
Age
8y
Commits · 90 Days