1. Project Overview & Quickstart (Koenkk/zigbee2mqtt) Copy Chapter

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](https://www.zigbee2mqtt.io/guide/getting-started) Copy Chapter

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](https://www.zigbee2mqtt.io/guide/usage/integrations.html) Copy Chapter

Zigbee2MQTT integrates well with (almost) every home automation solution because it uses MQTT. However the following integrations are worth mentioning:

[Home Assistant](https://www.home-assistant.io/) Copy Section

Home Assistant OS using the official addon (other installations)

[Homey](https://homey.app/) Copy Section

Integration implemented in the Homey App (documentation & support)

[Domoticz](https://www.domoticz.com/) Copy Section

Integration implemented in Domoticz (documentation).

[Gladys Assistant](https://gladysassistant.com/) Copy Section

Integration implemented natively in Gladys Assistant (documentation).

[ioBroker](https://www.iobroker.net/) Copy Section

Integration implemented in ioBroker (documentation).

Architecture Copy Chapter

Internal Architecture Copy Section

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 Copy Section

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 Copy Chapter

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 Copy Chapter

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.

2. Official Technical Reference & Guides (Koenkk/zigbee2mqtt-docs) Copy Chapter

File: README.md Copy Chapter

Zigbee2MQTT.io

This repository contains the Zigbee2MQTT documentation.

It is based on VuePress v2.

Architecture Copy Chapter

Directory-Structure:

• docgen: Some scripts to test and generate the Device-Pages.
• docs: The current documentation.
• docs/.vuepress: Some VuePress enhancements like Stylesheets.
• public: Static assets.
• supported-devices-component: Vue.js component rendering the devices-overview page.
• navbar.ts: Configuration for the top navigation.
• sidebar.ts: Configuration for the sidebars by individual sections (like Guide).
• vuepress.config.ts: The VuePress config file.

Docgen Copy Chapter

The docgen-scripts helps to generate and update the individual device-pages (/docs/devices/*.md).
zigbee-herdsman-converters exposes a list with supported devices which is used for generation. It also updates the Devices-List used by the Supported-Devices overview page.

The ## Notes section of each page is written by hand and does not come from zigbee-herdsman-converters. This section gets preserved and can be edited.

Docgen is written in Typescript, so you need a recent version of Node.js and NPM.

# One-time initialize package-lock.json otherwise 'pnpm i' may fail due tu dependencies
pnpm install

# Install dependencies
pnpm i --frozen-lockfile

# Run docgen
pnpm run docgen

Docgen Tests Copy Section

Docgen includes some scripts to help testing the page.

• check-device-images: Checks for missing device images
• check-links: Checks for broken internal links

Attention: check-links iterates over the generated VuePress files, so you have to build the page first!

VuePress Copy Chapter

Use Node.js 20 for building VuePress (other versions are not officially supported).

# Switch to node 20 (for nvm or nvm-compatible tool users)
nvm use

# Install dependencies
pnpm i --frozen-lockfile

Building Copy Section

# Run vuepress build
pnpm run build

The build-artifact gets written to dist directory.

Development Copy Section

# Run vuepress in dev mode with hot-reloading
pnpm run dev

The dev-Mode excludes the huge amount device-pages which slows down the build process drastically.
If you are interested in the device-pages you could include them by using the pnpm run dev:devices npm-run script.

Include specific device

When running in dev-Mode, you can also specify a device (but this device only) which you would like to include in the build process.
Useful when working on improving notes of just one device.
INCLUDE_DEVICE variable should be supplied with device's filename (see /docs/devices folder), without the .md. extension.

# Run vuepress in dev mode with specific device included
npx cross-env INCLUDE_DEVICE=<DEVICE_FILE_NAME> pnpm run dev

# Example for TS011F_plug_1
npx cross-env INCLUDE_DEVICE=TS011F_plug_1 pnpm run dev

Change development port

You can change development server port when the default one (8080) is taken on your system.

# Run vuepress in dev mode on specified port
npx cross-env DEV_PORT= pnpm run dev

# Example for port no 15080
npx cross-env DEV_PORT=15080 pnpm run dev

Docker Copy Chapter

You can also just use a docker-image include Node.js.

$ docker run --rm -v $PWD:/app -u $UID -ti node:18-slim bash
node@87e1438ef553:/$ cd /app
node@87e1438ef553:/app$ pnpm i --frozen-lockfile
node@87e1438ef553:/app$ pnpm run dev

File: docs/README.md Copy Chapter

home: true
title: Home
heroImage: /logo.png
actions:
- text: Get Started
link: /guide/getting-started/
type: primary
- text: Supported Devices
link: /supported-devices/
type: primary
features:
- title: Compatible
details: Zigbee2MQTT supports various Zigbee adapters and a big bunch of devices.
- title: Integrations
details: Zigbee2MQTT integrates well with most home automation solutions because it uses MQTT.
- title: Open Source
details: Zigbee2MQTT is licenced under the free GNU General Public License 3.

footer: zigbee2mqtt.io is maintained by @Koenkk. Copy Chapter

Welcome to the Zigbee2MQTT documentation! Besides the documentation, you can also get support and ask questions on the Forum and Discord channel. In case you want to donate click the 'Sponsor' button here.