Zigbee2MQTT is a nodejs Gateway application that connects Zigbee networks to MQTT networks.
It is run from the command line but can also be started as a service on startup.
Because it is written in nodejs it will run on Windows and Linux (Raspberry Pi).
You will need a Zigbee dongle like the CC2531 USB sniffer.
You can purchase these very cheaply online, but you will have to flash them with the Zigbee firmware.
The process is described here.
However recently SonOff have made flashed devices available and you can buy them online.
They cost just a little more than a non flashed device and just be careful when ordering that you get the right one.
You install the software by cloning it from Github. Again the process is fully described here.
The zigbee2MQTT gateway functions as a gateway connecting a zigbee network with attached devices to an MQTT network.
The gateway functions as a coordinator on the Zigbee network, and is responsible for creating the zigbee network.
All of your zigbee devices must connect to this network to work with the gateway.
The zigbee2MQTT gateway is used in place of the device manufacturers gateway and can be used with devices from different manufacturers.
On the MQTT network it acts like an MQTT client and requires an external broker usually mosquitto.
The configuration file (configuration.yaml) is a yaml file and contained in the /opt/zigbee2mqtt/data/ folder.
You need to be careful editing these files they require the correct number of spaces and don’t use TABS. See this brief article for tips.
To start you only need to set the base topic that Zigbee2 MQTT will publish on, and the address or name of the MQTT broker. The following is taken from the online docs:
# MQTT settings mqtt: # MQTT base topic for Zigbee2MQTT MQTT messages base_topic: zigbee2mqtt # MQTT server URL server: 'mqtt://localhost' # MQTT server authentication, uncomment if required: # user: my_user # password: my_password
if you are using the default port then there is no need to add it . However if you use a different port then use this syntax.
The docs describe all of the available configuration file settings here
I would only do the minimum configuration manually as you can also do this much easier using the node-red admin flow which I recommend you download.
Initially you will do this manually by going to the /opt/zigbee2mqtt folder and typing npm start.
cd /opt/zigbee2mqtt npm start
Once started you should see a screen similar the the one below:
The gateway subscribes to the base topic using zigbee2mqtt/# ( wildards) and also starts publishing on this topic.
For some reason the console log doesn’t show the subscription but you can see this on the broker console
Both control and data messages are published using MQTT.
The topic structure used is:
base_topic/device_name for device data
base_topic/bridge/xxxx for commands.
- zigbee2mqtt/sensor1 -data for sensor 1
- zigbee2mqtt/bridge/log — log files
Messages are almost always in JSON format.
Using MQTT it is possible to get data from a device and change it’s state using the formats:
zigbee2mqtt/sensor1/set and zigbee2mqtt/sensor1/get
It is also possible to:
- Configure the gateway
- Add and remove Zigbee devices
- Configure Device Options
- Configure groups
- Bind Devices
This is done using the node-red admin flow. The complete topic structure is explained here.
Adding a Device to the Zigbee network
In order to add devices the Gateway( coordinator) must be in the permit join mode.
You then press the reset button on the device for x seconds (device dependent) and it should automatically join the network.
You can observe this on the zigbee2mqtt console.
Note: for the Z2M flow you probably need to install the list UI
In the Z2M admin panel you should see the device and you will be able to assign it a friendly name as will install with an unfriendly number.
You need to scroll down the device management column to find the rename device feature.
Unfortunately it doesn’t show the device you will need to select it from the device list and then scroll down to rename it.
This makes a change in the configuration.yaml file which you can easily verify as shown with my example below:
The gateway supports 15 devices. You can increase the number of devices on the network by adding routers.
A router supports 21 devices so with 1 gateway and 1 router you can have 35 devices
with 2 routers 55 devices
The routers will also increase your network range.
There are two groups of node-red nodes that you can install the are :
And I must admit they caused me some confusion as I thought the node-red-contrib-zigbee2mqtt was the zigbee2mqtt gateway which it is not.
You do not need to install these nodes, but they do have a use and I will cover them in a subsequent video and tutorial.
If you have installed the node-red-contrib-zigbee it has a herdsman node which is the zigbee coordinator and could interfere with the one in the zigbee2mqtt program.
Common Questions and Answers
Q- Can I use Aedes on node-red instead of Mosquitto.
A- Yes but Aedes doesn’t support persistent data which is needed if you are using homeassistant.
zigbee2mqtt gateway is a standalone nodejs application that connects a zigbee network to MQTT.
It has a zigbee coordinator which forms the zigbee network and lets you control and view zigbee devices using MQTT.
The Z2M admin flow is a node-red flow for managing the zigbee2mqtt gateway and connected devices.
No node-red nodes are required to use the zigbee2mqtt gateway.
- My Zigbee network notes
- Control Zigbee Devices Using Zigbee2MQTT with Home Assistant
- How to Install Mosquitto on The Raspberry Pi
- Smart Homes and MQTT
Just careful new users to home assistant trying to use Zigbee2MQTT….The default ZHA / zigbee broker needs to be disabled / uninstalled otherwise Zigbee2MQTT won’t start and will come up with a ‘bad gateway’ when trying to access the web.
Took quite a bit of googling and didn’t find an answer, so i figured ‘are two zigbee thingies breaking it’ – and yep, they were.
Tks for letting me know.
thanks for your tutorials – they are very helpful.
I am quite new to configuring my SmartHome on my own. I took part in a study and still have the used devices – the project has been discontinued and I now wanted to set up my SmartHome with RaspberryMatic. I have some HomeMatic devices which are working fine and some ZigBee devices, which I cannot connect till now. I tried to use Node-Red and was able to connect the CC2531. When I try to join my BitronHome 902010/25 plugs, they are recognized as unknown devices and when I try to switch them I get two messages:
– “Device with modelID ‘undefined’ is not supported.”
– “Please see: https://www.zigbee2mqtt.io/how_tos/how_to_support_new_devices.html”
That’s how I found your tutorials because I tried to use zigbee2mqtt, but I was unsuccessful and hope you maybe have some information for me with all your experience.
When I try to join the plug, I get some messages saying that “the Interview failed because can not get node descriptor (‘0x00124b00061f6763’)”
— I tried to attach the log but could not post the comment —
Is it possible that the devices are too old or patched for the special study purpose? I read that nearly all ZigBee devices could be used with the Zigbee stick?
Maybe you have some ideas how I could use these plugs, it would be a shame to dispose of them.
Best regards and thanks for your help in advance,
Sorry for the late reply but I wasn’t notified of the comment. I will check the blog settings.
It is probably because there isn’t a converter for the device. I did encounter this with a device and followed the instructions here
Let me know how you get on
Good article. Zigbee2mqtt is my daily driver for the entire home.
The only remark i have is that this Cc253* dongle results in an inferior experience. E.g. no updates from independent Device state changes, very bad range and only supporting small networks.
Better use one of the recommended devices as published on the website of zigbee2mqtt if you want to seriously work with this in a ‘production’ setting.
after install and running…. it is stuck at message “Connecting to MQTT server at mqtt://localhost”. not sure what to do next. – TechMan
Do you have an mqqt broker running on your local machine?
Thank you very mutch for this tutorial. I was very helpful for me.
I have some smart-switches. these switches work fine, when i send them
the switch-command ON/OFF via zigbee (zigbee2mqtt). But when i press and
release the physical rocker switch the light switch on an off immediatly again.
So the rocker switch only toggle the status of the smart-switch for the press-time and
send a zigbee message for ON and OFF state.
The product i have is the QS-Zigbee-S04-2C-LN. Do you have such experience with
Kind greetings, Hubert
Hi no I haven’t. Is this the switch
Hi, have you try some tests for MQTT over Zigbee?
Also, i saw your other topic (https://stevessmarthomeguide.com/zigbee-basics/), and i’d like to ask you have you try to use Zigbee with Node-red ?
No I haven’t used MQTT over zigbee.MQTT-SN should work with Zigbee but not sure if anyone has implemented it. The way to go with mqtt and zigbee is the gateway