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

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


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


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:


Device Support

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.

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.

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.

Related tutorials

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


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

  2. Hi Steve,
    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:
    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,

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

  4. after install and running…. it is stuck at message “Connecting to MQTT server at mqtt://localhost”. not sure what to do next. – TechMan

  5. Hi Steve.
    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
    such product?
    Kind greetings, Hubert

Leave a Reply

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