Home Home Automation Adding 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 in style with crypto-currency

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

ESP8266 WIFI lights under $5

Your Sonoff device can't do this!

Free wireless doorbell (Amazon Dash button hack)

The most terrifying situation I can imagine* is missing a parcel

New Amazon Dash Buttons

You can teach new buttons old tricks!

ESP8266 ceiling light – demo

Testing the ESP8266 as a WIFI light controller

Try Tasker and Raspberry Pi for your home automation needs!

Raspberry Pi can help you with your Tasker profiles

Smart Home

Testing 9 external antennas with CC2531 ZigBee coordinator

I have tested the range and the link quality of 9 external antennas with CC2531!

I have infinite buttons thanks to Aqara Opple

Gaming on Switch meets IoT - can you play games on Aqara Opple? Apparently you can! This and more uses of the connected wall switch

Smart lights won’t save you money

It's pretty clear how much power a smart light draws when turned on, but have you ever wonder how much do you pay to have it connected 24/7?

Alexa Routines: Setting volume on all Echos at once

Setting volumes on all Amazon Echo devices at once doesn't have to be a chore!

If Edison made smart lights: OEEONE ZigBee lightbulb

OEEONE ZigBee lightbulb may look vintage, but packs the latest ZigBee protocol