HomeHome AutomationAdding devices to Zigbee2MQTT - the easy way

Adding devices to Zigbee2MQTT – the easy way

How to pair Zigbee devices with cc2531 and Zigbee2MQTT

After some online feedback, I decided to write a quick guide to Zigbee devices in Zigbee2 MQTT. In this tutorial, I will show you how to add compatible devices to Zigbee2MQTT running on cc2531 Zigbee USB stick. If you paired your device, but the device isn’t listed, check out this guide how to add new devices to Zigbee2MQTT.

Pairing with Zigbee2MQTT

It’s not possible to cover every single device with a single tutorial, but if you follow these steps, you should be able to control new devices via NodeRED or Home Assistant via appropriate MQTT plugins.


Don’t add new device until you perform the factory reset. Devices linked with other systems can cause issues, and as such it’s best to reset it to factory settings and clear linked Zigbee devices.

The reset procedure will depend on the device you have. To reset IKEA buttons you have to press the “pair” button 4 times in quick succession, but IKEA bulbs have to be quickly toggled on/off 5 times. Always check the instructions to be sure you are doing it correctly.

On most devices, there should be a small LED that indicates the status of the device. Locate it and use it as feedback.


To pair a device with cc2531, first, you have to make sure that the Zigbee2MQTT is configured to accept new devices. Navigate to Zigbee folder and look for configuration.yaml file. Find permit_join and set it to true.

 sudo nano /opt/zigbee2mqtt/data/configuration.yaml 
homeassistant: false
 permit_join: true
   base_topic: zigbee2mqtt
   server: 'mqtt://xxx.xxx.xxx.xxx:1883'
   password: MQTTPASSWORD
   port: /dev/ttyACM0

While you are editing this file, you can double-check the MQTT settings. These should point to your MQTT broker (like mosquitto – sudo apt-get install mosquitto).

Save the changes and restart Zigbee2MQTT. I included the most useful commands:

 #Stopping zigbee2mqtt
 sudo systemctl stop zigbee2mqtt

 #Starting zigbee2mqtt
 sudo systemctl start zigbee2mqtt
 #View the log of zigbee2mqtt
 sudo journalctl -u zigbee2mqtt.service -f

You are now ready to pair. Move the device close to your cc2531 (about 10-20cm). In general, Zigbee devices can be separated into 2 groups.

Group 1

These are devices that come without a physical pairing button. These will accept the pairing as soon as the device had been reset. All you have to do is reset the device, power it on, then give it about 20 seconds before you check if the device is visible in the Zigbee2MQTT log.

It’s important to correctly reset these to put them into pairing mode.

Group 2

Devices with a pairing button require pairing action. Move the device close to the cc2531 and make sure there are no other devices nearby. For most cases holding the pairing button will link the device.

To make things complicated, even within the same ecosystem pairing procedures may differ. To pair IKEA dimmer I had to hold the pair button for about 5 seconds, but to do the same with IKEA dimming button the method didn’t work, and to pair it I only had to press the button once.

Upon successful pairing you will see the message in the Zigbee2MQTT log:

zigbee2mqtt:info  2019-12-15T14:11:23: Successfully interviewed 'hkdd033456543n334', device has successfully been paired
zigbee2mqtt:info  2019-12-15T14:11:23: Device ' hkdd033456543n334' is supported, identified as: IKEA TRADFRI motion sensor (E1525)

This message confirms that the device hkdd033456543n334 has been added to the list and it is supported natively. If your message says that your device is not supported – take a look at this guide to new devices in Zigbee2MQTT.


Revisit the configuration.yaml file again. At the bottom of the file, you will see a new device (sudo nano configuration.yaml):

  ' hkdd033456543n334':
    friendly_name:   hkdd033456543n334
    retain: false

Now, you can change the name of the device to something you will remember and save the file (Ctrl+X)

  ' hkdd033456543n334':
    friendly_name:  'NewZigbeeDevice' 
    retain: false

Now you will be able to refer to your device via name and the deviceID in MQTT Topic:


Congratulations – you can use your Zigbee devices with NodeRED or Home Assistant now.


From time to time things go wrong. The most common issues will always be related to user error. I would strongly recommend you to check all the steps above before you look for other solutions.

I will be adding the reader’s issues to this list and possible solutions. If you want to share one, there is a link to a Reddit thread at the end of this article.

Device status and updates

Zigbee uses MQTT protocol to communicate. The messages are JSON formatted and the formatting is pretty easy to understand. I have a tutorial that will explain JSON in detail for you.

All Zigbee devices will send updates. These will usually consist of the data, battery status, signal strength and performed action or state change. To listen to Zigbee devices simply use MQTT in node with the topic that is composed like this (default_zigbee2mqtt_topic/device_name|device_id):


This message is sent when the device changes the state or received the status update message.

Commands can be sent to devices that support it.


The actual command will depend on what you are trying to achieve. It could be a state toggle on|off, brightness 0-255 or colour value as #FFFFFF. The best advice I can give you is to look at the updates as often commands will have to have the same JSON structure.

Some Zigbee devices also support forced status update. An empty JSON message { } sent to the topic:


Will force the device to report back without making any changes. Usually, the status of the Zigbee device is sent back when the state of the device changes or a status update message issued at specific time intervals.


I hope you had no problems adding supported devices to Zigbee2MQTT. The process is straight forward and quick. If your device isn’t supported consider checking the guide for new devices. If you have any problems, let me know and I will list these in the “issues” section of this article. The best way to reach out is to leave the comment in this Reddit thread.


Nothing says "Thank you" better than keeping my coffee jar topped up!


Support me on Patreon and get an early access to tutorial files and videos.


Bitcoin (BTC)

Use this QR to keep me caffeinated with BTC: 1FwFqqh71mUTENcRe9q4s9AWFgoc8BA9ZU

Smart Ideas with

Automate your space in with these ecosystems and integrate it with other automation services


Learn NodeRED

NodeRED for beginners: 1. Why do you need a NodeRED server?

To server or not to server? That's a very silly question!

Best Automation Projects

Sonoff R3 DIY mode & why it sucks

Long awaited Sonoff R3 DIY mode is even worse than I expected.

IKEA TRADFRI Wireless dimmer in NodeRED

Thanks to NodeRED you can use IKEA TRADFRI Wireless Dimmer to interact with everything

Things they don’t tell you about IKEA Trådfri

There are things you should know about IKEA Tradfri before you make your purchase

Flashing Tasmota on Sonoff ZigBee Bridge

How to flash Tasmota on Sonoff ZigBee Bridge to enable it for NodeRED and Home Assistant

Flashing ESP with Tasmotizer is a dream come true

How to flash Tasmota on ESP devices with new Tasmotizer tool

Smart Home

No more hubs: Aqara G2H

Aqara G2H brings the power of ZigBee sensors to an IP camera.

Two cool features of Avatar Smart Bulbs

Avatar Smart Bulbs come with 2 cool features I wish more smart bulb manufacturers would include in their products.

Shelly 2.5 vs Sonoff DualR3

It's time to pitch similar devices against each other and compare their functions: Shelly 2.5 vs Sonoff DualR3

How to flash Tasmota on Sonoff DualR3

Make the device yours by flashing Tasmota on Sonoff DualR3. Now with channel control and power consumption

Shelly Duo – going beyond twice

Their #ShellyDuo is a WiFi-enabled lightbulb with colour temperature. Plus it comes with 2 features don't often offered by other smart lights.