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.

Interference from Raspberry Pi is also a known factor. If your device is working fine in terminal but you are not able to pair new devices, try connecting the coordinator via USB extension cable and move it away from Raspberry Pi.

If you already have some devices in the network – especially end devices, you could be at the limit of the coordinator and you need a more powerful one – take a look at CC2652R from Electrolama and the flash guide to increase the count to 50 direct children and 200 devices.

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

Tuya SDK for beginners: Intro to Tuya Cloud API

Working with Tuya Cloud API. A guide to Cloud automation for beginners, get started with REST!

NEST your old thermostat under $5

Nest-ing up your older thermostat under $5

Nora – Google Assistant in NodeRED

Integrate Google Assistant with NodeRED thanks to Nora - NodeRED home automation

Sonoff Zigbee Bridge – review

Sonoff line up will soon include Sonoff Zigbee Bridge and more Zigbee sensors - here is the first look

DIY Smart Washing Machine – for about 15 bucks!

Learn how to add washing machine notifications to your Google Home on the cheap

Smart Home

SwitchBot S10: cleaning re-imagined!

SwitchBot S10 promises unattended vacuuming and mopping so you can focus on things you love and care for. Does it deliver?

Sonoff for households and gardens

ITEAD released two ZigBee devices to manage water in your household and gardens. Now you can monitor the flow and dispense water with Sonoff SWV and prevent water damage using the Sonoff Water Leak sensor with a twist.

I wish I had known about the SMLIGHT ZigBee/Thread Coordinators sooner!

SMLIGHT coordinators are the perfect choice for anyone just diving into ZigBee. SLZB-06 series is easy to use and comes with future-proofing Thread support.

Sonoff ZigBee Bridge U isn’t what you think!

I expected Sonoff ZB Bridge U to be a next gen ZigBee bridge with Matter support. Turns out, there is much more to talk about!

Aqara “Everything” M3 Hub

When I started my home automation adventure, the current problem was the number of ecosystems needed to outfit your smart home. Aqara M3 Hub has a long list of protocols to match that!