Using Zigbee2MQTT- A Beginners Guide

zigbee2mqtt-iconZigbee2MQTT 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 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.

Zigbee2MQTT Function

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 you zigbee devices must connect to this network to work with the gateway.

On the MQTT network it acts like an MQTT client and requires an external broker.

Mosquitto is a common choice but you can also use Aedes on node-red.

Configuring

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.

  server: 'mqtt://localhost:1884'

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.

Starting Zigbee2MQTT

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:

zigbee-mqtt-start

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
and
base_topic/bridge/xxxx for commands.

Examples

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

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.

Z2M-admin

You need to scroll down the device management column to find the rename device feature.

rename-deviceUnfortunately it doesn’t show the device you will need to select it from the device list and then scroll down to rename it.

Node-Red Nodes

There are two groups of node-red nodes that you can install the are :

  • node-red-contrib-zigbee
  • node-red-contrib-zigbee2mqtt

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.

Summary

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.

Related tutorials

Please Let me Know if you found it Useful
[Total: 0 Average: 0]

Leave a Reply

Your email address will not be published. Required fields are marked *