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