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.

 sudonano /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:  'hkdd033456543n33' 
    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.

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.

Receive updates

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

zigbee2mqtt/sonoff1

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

Send commands

Commands can be sent to devices that support it.

zigbee2mqtt/sonoff1/set

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.

Status update

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

 zigbee2mqtt/sonoff1/get

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.

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.

Support NotEnoughTech
A lot of time and effort goes into keeping NotEnoughTech alive! If my work helped you out, consider buying me a coffee or check out exclusive rewards available to Patreon supporters.
SHARE