# Getting started
In order to use Zigbee2MQTT we need the following hardware:
A Zigbee Adapter which is the interface between the Computer (or Server) where you run Zigbee2MQTT and the Zigbee radio communication. Zigbee2MQTT supports a variety of adapters with different kind of connections like USB, GPIO or remote via WIFI or Ethernet. Recommended adapters have a chip starting with CC2652 or CC1352. See supported Adapters. It’s recommended to check out your adapter’s recommendation details before the installation process, to find out whether it needs any additional configuration parameters.
A Server where you would run Zigbee2MQTT. Most Raspberry-Pi models are known to work but you can run it on many computers and platforms including Linux, Windows and MacOS. It should have an MQTT broker installed. Mosquitto
open in new window ) is the recommended MQTT broker but others
One or more Zigbee Devices which will be paired with Zigbee2MQTT.
To improve network range and stability use a USB extension cable. If you experience ANY trouble with device (timeouts, not pairing, devices unreachable, devices dropping from the network, etc.) this is the first thing to do to avoid interference. See Improve network range and stability.
You can run Zigbee2MQTT in different ways, see Installation. In this example Docker
open in new window is used to set up and run Zigbee2MQTT.
# 1.) Find the Zigbee-Adapter
After you plug the adapter in see the dmesg output to find the device location:
As we can see the adapter was identified and mounted on ttyUSB0 .
Here we can see that the adapter is owned by root and accessible from all users in the dialout group.
# 2.) Setup and start Zigbee2MQTT
It’s assumed, that you’ve a recent version of Docker and Docker-Compose is installed.
First, we create a folder where we want the project to reside mkdir folder-name . In the folder, we create we save the docker-compose.yml file which defines how Docker would run our containers. The following file consists of two services, one for the MQTT-Server and one for Zigbee2MQTT itself. Be sure to adjust the file to your needs and match the devices-mount in the case your adapter was not mounted on /dev/ttyUSB0 .
In the next step we’ll create a simple Zigbee2MQTT config file in zigbee2mqtt-data/configuration.yaml .
We should now have two files in our directory and can start the stack:
After some short time you should see some log messages that Mosquitto and Zigbee2MQTT is running now. You can open the frontend using http://localhost:8080
open in new window (or the hostname of your remote server).
We can now go on and pair our first device.
# Connect a device
Search the supported devices for your device and follow the instructions how to pair.
If no instructions are available, the device can probably be paired by factory resetting it.
Once you see something similar to below in the log your device is paired and you can start controlling it using the frontend and MQTT messages.
Install from the command line:
Recent tagged image versions
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.
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.
Zigbee2MQTT integrates well with (almost) every home automation solution because it uses MQTT. However the following integrations are worth mentioning:
- Home Assistant: Using the official addon
- Generic install or Hassbian: Using instructions here
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 Zigbee adapter 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. Zigbee-herdsman handles the core Zigbee communication. 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 a web-based interface that allows monitoring and configuration.
Zigbee2MQTT uses TypeScript (partially for now). Therefore after making changes to files in the lib/ directory you need to recompile Zigbee2MQTT. This can be done by executing npm run build . For faster development instead of running npm run build you can run npm run build-watch in another terminal session, this will recompile as you change files.
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.
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.
GNU General Public License v3.0
It is possible to run Zigbee2MQTT in a Docker container using the official Zigbee2MQTT Docker image
This image support the following architectures: 386 , amd64 , arm/v6 , arm/v7 , arm64 . Since Zigbee2MQTT images are manifest listed, Docker will auto-detect the architecture and pull the right image.
Start by figuring out the location of your adapter as explained here.
IMPORTANT: Using a Raspberry Pi? Make sure to check Notes for Raspberry Pi users.
# Creating the initial configuration
Navigate to the directory where you whish to store the Zigbee2MQTT data and execute:
Now configure the MQTT server, adapter location, network key and frontend as explained here.
# Running the container
Execute the following command, update the —device parameter to match the location of your adapter.
- —name zigbee2mqtt : Name of container
- —restart=unless-stopped : Automatically start on boot and restart after a crash
- —device=/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00:/dev/ttyACM0 : Location of adapter (e.g. CC2531). The path before the : is the path on the host, the path after it is the path that is mapped to inside the container. You should always use the /dev/serial/by-id/ path on the host.
- -v $(pwd)/data:/app/data : Directory where Zigbee2MQTT stores it configuration (pwd maps to the current working directory)
- -v /run/udev:/run/udev:ro : only required for auto-detecting the port and some adapters like ConBee
- -e TZ=Europe/Amsterdam : Configure the timezone
- -p 8080:8080 : port forwarding from inside Docker container to host (for the frontend)
If you run the MQTT-Server on the same host (localhost) you could use the IP of the docker0 bridge to establish the connection: server: mqtt://172.17.0.1 .
# Rootless container
To improve the security of the deployment you may want to run Zigbee2MQTT as a non-root user.
- Identify the group that has access to the adapter (in Ubuntu, e.g. it might be assigned to dialout ). Update ttyACM0 to match your adapter location.
- If you want to run Zigbee2MQTT using your current user find the uid (UserID) and gid (GroupID):
- Start the docker container after updating device , user (uid:gid) and group-add :
- —user 1001:1001 : Run the Zigbee2MQTT process within the container using the provided UserID and GroupID
- —group-add dialout : Assign the dialout group to the user to be able to access the device
To update to the latest Docker image:
The following tags are available:
- Latest release version: latest
- Latest dev version (based on dev
open in new window branch): latest-dev
# Docker Compose
Example of a Docker Compose file:
You can also run a rootless container with docker-compose by adding the required attributes to the zigbee2mqtt service block in your docker-compose.yml :
# Starting the container
To start the Docker container:
You can optionally skip zigbee2mqtt and it will start all containers listed in the compose file.
To update to the latest Docker image:
You can optionally skip zigbee2mqtt and it will pull any new images for all containers in the compose file, and then restart those that were updated.
# Notes for Raspberry Pi users
- If you are running Raspbian Buster (not Bullseye!) (find out by executing grep «PRETTY_NAME» /etc/os-release ) you need to install libseccomp2 , this can be done by executing the following commands:
If you do not do this you will get the following error when starting the Zigbee2MQTT container:
- For Raspberry Pi 1 and zero users: there is a bug in Docker which selects the wrong image architecture. Before executing docker run pull the correct image with docker pull koenkk/zigbee2mqtt —platform linux/arm/v6 .
# Docker Stack device mapping
This is only relevant when using Docker Stack
Docker stack doesn’t support device mappings with option —devices when deploying a stack in Swam mode. A workaround is to bind the device as volume binding and set the right permissions.
The workaround is based on the solution found at Add support for devices with «service create»
open in new window , all credits goes this him.
Identify serial adapter Identify the serial adapter using the following command:
Create a new udev rule for serial adpater, idVendor and idProduct must be equal to values from lsusb command. The rule below creates device /dev/zigbee-serial :
Reload newly created rule using the following command:
Connecting Zigbee device to Raspberry Pi using zigbee2mqtt and Node-red.
Connecting Zigbee compatible devices to private home automation server running on Raspberry Pi.
Setting up the zigbee coordinator
CC2531 would need a CC debugger and downloader cable. Complete instructions here. Note that there are different adapters that can be used as zigbee coordinator, follow the correct flashing guide with the one you have. Plug-in the zigbee coordinator to RPi after flashing.
Install zigbee2mqtt from IOTStack
Update docker-compose.yml file zigbee2mqtt/devices /dev/ttyACM0:/dev/ttyACM0
Check if zigbee2mqtt recognizes the zigbee coordinator by checking the logs
Pair zigbee enabled device
Bring the zigbee device close to the zigbee coordinator and press the pairing button on the zigbee device.
Add zigbee2mqtt nodes to Node-Red
Open Manage Palette in Node-Red, search and install zigbee2mqtt
Next, search for zigbee2mqtt at search nodes
Drag and drop bridge node to the flow
Double click on the bridge node and add new zigbee2mqtt server. Deploy to Node-Red after this so it could collect devices information from the zigbee coordinator.
Update your device’s Friendly name. Click on Set button after changing friendly name for each device. Deploy Node-red after this.
Drag zigbee2mqtt in node and a debug node, connect them together
Update zigbee2mqtt in node and select server and the device. Deploy to Node-Red.
Use Git or checkout with SVN using the web URL.
Work fast with our official CLI. Learn more.
Launching GitHub Desktop
If nothing happens, download GitHub Desktop and try again.
Launching GitHub Desktop
If nothing happens, download GitHub Desktop and try again.
If nothing happens, download Xcode and try again.
Launching Visual Studio Code
Your codespace will open once ready.
There was a problem preparing your codespace, please try again.
Failed to load latest commit information.
This project is a Web GUI for the very good Zigbee2Mqtt software (github sources).
- If you’re using zigbee2mqtt for your devices, it’s a must.
- Display zigbee devices and the status of each of them.
- Display an interactive map of the network
- Touchlink support
- Automatically turn off allow join of Zigbee network — no matter how you turned it on (don’t need to be turned on from Z2MA). Default is 20 minutes.
- Flexible installation:
- Available as a HASS.IO add-on (integration into Home Assistant). Ingress is supported too. note: can be used without Home Assistant.
- Published as a docker images for following architectures
- Linux AMD64 (alpine): linux-x64
- Linux ARM32 (buster-slim): linux-arm32 ( armv7 + processor required — Won’t work on Raspberry Pi Zero or Zero-W!)
- Linux ARM64 (apline): linux-arm64 ( armv8 + processor required)
- Windows 64 bits (v10.0.17763+): win-64
- Windows ARM32 (v10.0.17763+): win-arm32
- Also published as a multi-arch manifest: latest (or dev for development version)
- Operations on devices:
- Allow network join — no more need to setup virtual switches in HA just for that.
- Rename devices
- Remove devices from network (+ forced remove)
- Configure device (force reconfiguration of device’s reportings)
- Bind device to another one (mostly used for Ikea TRÅDFRI devices — documentation here)
- Visualize device health
- OTA Upgrades
- Based on ASP.NET Core 3.1 LTS.
OPTION 1 — Installing as HASS.IO Add-on
- Add the following repository url in HASS.IO:
OPTION 2 — Installing from docker
Run the following command by replacing , , with your correct values.
Draft note: Environment variables are currently the easiest way to set those settings. Open an issue if you need it to be in a configuration file/folder.
Docker Compose example
If you’re using Docker Compose, fell free to use this. 8880 is the port where the service will be available, from the outside of the container itself.
Accepted for Docker-compose Manifest v.3
OPTION 3 — Installing from sources & compiling using Visual Studio
- Compile the solution file
- Adjust settings in appsettings.json for your MQTT connection
Note: it won’t compile using the dotnet core build yet. For now, MSBuild is required to build it.
This method is not recommended because any change to dependencies will require you to update your development/deployment environment.
There is 2 channels for Zigbee2MqttAssistant: dev and stable . When a build version is considered stable enough, it will be pushed from dev to stable (there’s no git branch dedicated to the stable version).
If you want to try newest features, you can get the dev branch in the following way:
- On HASS.IO, pick zigbee2mqttassistant-dev package
- On Docker, pick the following package/tag: carldebilly/zigbee2mqttassistant:dev
You can refer to Settings.cs file for more information on allowed settings. Here’s the important settings:
|BaseTopic||«zigbee2mqtt»||Base MQTT topic when Zigbee2Mqtt is publishing its data|
|HomeAssistantDiscoveryBaseTopic||«homeassistant»||Base MQTT topic for HASS Discovery|
|MqttServer||«mqtt»||Name or IP address of the MQTT server. Put only the name or the address of the server here. DON’T USE THE mqtt:// ADDRESS FORMAT.|
|MqttSecure||false||If should use TLS to connect to MQTT server. Valid options are true , false or «insecure» . Insecure means it’s using TLS, but without any server certificate check.|
|MqttPort||1883 (normal) or 8883 (secured)||Port for MQTT server|
|MqttUsername||«»||Username for MQTT server|
|MqttPassword||«»||Password for MQTT server|
|LowBatteryThreshold||30||Threshold for triggering low-battery warning (%)|
|AllowJoinTimeout||20||Timeout for turning off allow join of Zigbee network. Set 0 to disable this feature|
|AutosetLastSeen||false||Will turn on last_Seen on Zigbee2Mqtt automatically when detected as off.|
|DevicesPollingSchedule||*/12 * * * *||Schedule (cron expression) for device list refresh. Default value: every 12 minutes.|
|NetworkScanSchedule||0 */3 * * *||Schedule (cron expression) for device list refresh. Default value: every 3 hours. This network scan can have high cost on your network: details here.|
For environment variables, you can use any of the previous fields, prefixed with Z2MA_SETTINGS__ . By example, you can specify the MqttPort with an environment variable in the following way:
Note: Uppercase is used here as a convention. It’s actually case insensitive.
If you need to change cron expression for other values, you should use a site like https://crontab.guru/ to validate them. Attention: if you specify specific hours, take care of the time offset (timezone) inside the container!
Listening to Alternate Port / Linux Security
When running this container on Linux, it’s a best practice to run containers with a non-root account. To achieve that with Zigbee2MqttAssistant, it’s required to change the listening port to something else than 80 , because ports number under 1024 are restricted to priviledged users.
Since it’s using ASPNET Core, it’s possible to change the listening port in the container to something else by using one of the following method:
Set the —urls parameter on the command line:
Use the ASPNETCORE_URLS environment variable:
This method can also be used to set another scheme ( https:// ), a specific ip address or many ports at the same time. Microsoft ASPNET Core documentation.
- Build a CI + publish to docker hub
- Shorter environment variables + config file (for docker image)
- Create a HASS.IO add-on
- Support for HASS.IO Ingress
- Automatic update of repo on new version
- Support Zigbee Bindings
- Support Docker Manifest (support for ARM + Windows)
- Support mapping of network
- Allow-join auto-off
- Support Zigbee groups
- Support for device images
You need a running installation of Zigbee2Mqtt v1.5.0+
- Also tested on v1.6.0, v1.7.0, v1.7.1 and v1.8.0, v1.11 (needed for firmware update feature)
Simple MQTT connection with username/password (TLS supported)
- Client certificates not supported yet — open an issue if your need it.
Zigbee2Mqtt required settings:
Home Assistant Discovery should be activated for a better experience (to see components)
AN ACTUAL INSTALLATION OF HOME ASSISTANT IS NOT REQUIRED
To activate: homeassistant: true in Zigbee2Mqtt configuration
last_seen should be activated on Zigbee2Mqtt (any format supported). There’s an option ( AutosetLastSeen ) to activate it automatically through MQTT.
- If you have suggestions or find bugs, don’t hesitate to open and issue here, on Github.
- PULL REQUESTS are welcome! Please open an issue first and link it to your PR. If you’re unsure about how to implement a feature, we should discuss it in the issue first.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!