Adding devices to Zigbee2MQTT – the easy way

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.

Reset

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.

Pair

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
 mqtt:
   base_topic: zigbee2mqtt
   server: 'mqtt://xxx.xxx.xxx.xxx:1883'
   user: MQTTUSERNAME
   password: MQTTPASSWORD
 serial:
   port: /dev/ttyACM0
 devices:

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.

Rename

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

devices:
  ' 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)

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

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

zigbee1mqtt/hkdd033456543n334 
or
zigbee1mqtt/NewZigbeeDevice

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

Issues

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.

zigbee2mqtt/sonoff1

zigbee2mqtt/sonoff1/set

 zigbee2mqtt/sonoff1/get

Conclusion

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.