Recently, I have started to use parts of my SmartHome to the Zigbee standard.
In the past, I still used sensors and actuators based on the simple 433Mhz radio. Unfortunately, however, there are fewer and fewer sensors and actuators for this "radio standard".
Last but not least, the very reasonable prices for Zigbee accessories at Ikea were the decisive argument for me to switch to this standard.
In addition to these advantages, there are of course other benefits of the Zigbee standard. For example, actuators that are permanently connected to the power grid (e.g. a Zigbee-capable socket) automatically act as repeaters (called "routers" in Zigbee jargon). This means that even very large Zigbee networks (e.g. over several floors) can be set up.
Battery-powered Zigbee devices can achieve very long battery life thanks to the more suitable architecture. A window or door sensor, for example, can be operated for several years with a single CR2032 button cell.
All right, but how can you integrate Zigbee sensors and actuators into your own SmartHome integrate?
A very cool and helpful open source project for this is Zigbee2MQTT.
As the name suggests, zigbee2mqtt is a type of adapter that evaluates the data received via Zigbee and transmits it to your SmartHome forwarded.
You can then access this data - as you can from on Tasmota and EspEasy based sensors/actuators.
How to install zigbee2mqtt on your RaspberryPi I have described in the following article.
Safety instructions
I know the following notes are always kind of annoying and seem unnecessary. Unfortunately, many people who knew "better" have lost eyes, fingers or other things due to carelessness or injured themselves. Data loss is almost negligible in comparison, but even these can be really annoying. Therefore, please take five minutes to read the safety instructions. Because even the coolest project is not worth injury or other trouble.
https://www.nerdiy.de/sicherheitshinweise/
Affiliate links/advertising links
The links to online shops listed here are so-called affiliate links. If you click on such an affiliate link and make a purchase via this link, Nerdiy.de will receive a commission from the relevant online shop or provider. The price does not change for you. If you make your purchases via these links, you support Nerdiy.de in being able to offer other useful projects in the future. 🙂
Requirements
Helpful articles:
Before you start with this article, you should have prepared a RaspberryPi so that it is accessible via the network and controllable via SSH. You should also have a MQTT server already installed be.
The following articles describe what needs to be done to prepare the RaspberryPi.
- RaspberryPi – setup for nerdiys!
- RaspberryPi – The first configuration!
- RaspberryPi – Control the RaspberryPi via SSH
In the following lists you will find all the parts you need to implement this article.
Required tool:
| Number | Link |
|---|---|
| 1x | Screwdriver set Buy at Amazon |
| 1x | SD card reader Buy at Amazon |
Required material:
Log in to the RaspberryPi via SSH
To start, you must first log in to the Rasp Pi with Putty via SSH. How to do this is in the article RaspberryPi - Control the RaspberryPi via SSH described.
Update package management
The package management in Linux is a "central place" through which various software packages can be installed. In order for this to work reliably, the lists and sources of the package management should be updated before each installation of new packages.
sudo apt-get update && sudo apt-get upgrade
Preparing the installation on the Raspberry Pi
The installation of zigbee2mqtt can be started with a few simple bash commands.
But before you can start with the actual installation of zigbee2mqtt you have to install a few required dependencies/libraries.
To do this, execute the following command. This will prepare the installation of NodeJs.
sudo curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
The following command then installs NodeJs including various compilers.
sudo apt-get install -y nodejs git make g++ gcc
Then you need to install the Yarn Package Manager. To do this, execute the following commands on your Raspberry Pi.
curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/yarnkey.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | sudo tee /etc/apt/sources.list.d/yarn.list<br>
sudo apt-get update sudo apt-get install yarn -y
You can then use the following commands to download the zigbee2mqtt repository and set the required directory rights.
sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
sudo chown -R pi:pi /opt/zigbee2mqtt
Set Zigbee2mqtt configuration
After downloading the zigbee2mqtt files, you must now adapt the configuration file to your system.
To ensure that your zigbee2mqtt adapter (coordinator) can be addressed correctly, you must enter the correct path in the configuration file.
Of course, the adapter should already be flashed with the zigbee2mqtt firmware and connected to the Raspberry Pi. You can find information on this in the following blog article, for example.
As soon as the Zigbee Coordinator is connected, you should find out the device path and save it temporarily.
You can display the device path of the connected adapters with the following command.
ls /dev/serial/by-id/
If you only have one adapter connected, only the device path to your Zigbee adapter will be listed here. If several entries are listed here, it is easiest to first remove all other USB devices, call up the list again and then copy the only existing entry.
In the example shown, the device path you are looking for is the following.
- usb-Silicon_Labs_CP2104_USB_to_UART_Bridge_Controller_019758DF-if00-port0
It is now best to save this in a text file. You will need the device path to enter it later in the configuration file.
Now create or open the configuration file of zigbee2mqtt by entering the following command.
nano /opt/zigbee2mqtt/data/configuration.yaml
The content of the file should look like this. However, you will need to adapt the positions below accordingly.
# MQTT settings mqtt: # MQTT base topic for Zigbee2MQTT MQTT messages base_topic: zigbee2mqtt # MQTT server URL server: 'mqtt://localhost' # MQTT server authentication, uncomment if required: # user: my_user # password: my_password # Serial settings serial : # Location of the adapter (see first step of this guide) port: /dev/ttyACM0 advanced: network_key: GENERATE ikea_ota_use_test_url: true legacy_api: false log_level: debug frontend: port: 8038 host: 0.0.0.0 auth_token: secretPassword123 url: http ://localhost
It is important that you adapt a few settings in the configuration file to your situation.
Customize Mqtt server:
Set the domain name for your MQTT server correctly. To do this, you must change the 'mqtt://localhost' accordingly (if the mqtt server is not running on the same RaspberryPi as zigbee2mqtt).
Customize password to the dashboard:
To protect access to the zigbee2mqtt dashboard, you should set the password to a value known only to you. To do this, change the part auth_token: secretPassword123 accordingly.
Adjust the path to your Zigbee Coordinator:
Sets the device path for the entry
- port: /dev/ttyACM0
to the correct value. You should have copied the appropriate device path in the previous step.
Start installation
After you have completed all configurations, you can now start the installation of zigbee2mqtt.
You can then start the installation of zigbee2mqtt by entering the bash command
cd /opt/zigbee2mqtt
changes to the directory and starts the installation with
npm ci
starts.
Test installation
If you want you can test the installation of zigbee2mqtt at this point.
To do this, simply execute the following commands.
cd /opt/zigbee2mqtt
npm start
This will start zigbee2mqtt and you can view the log output.
Zigbee2mqtt then runs as long as the console window is open and connected or you end the program run with CTRL-C.
Configure Zigbee2mqtt as a system service
To ensure that zigbee2mqtt runs without an open console window, you should install a system service.
To do this, create a new configuration file for the system service by entering the following command.
sudo nano /etc/systemd/system/zigbee2mqtt.service
Then insert the text below and save the file using the shortcut keys CTRL-X, Y and Enter.
[Unit] Description=zigbee2mqtt After=network.target [Service] ExecStart=/usr/bin/npm start WorkingDirectory=/opt/zigbee2mqtt StandardOutput=inherit # Or use StandardOutput=null if you don't want Zigbee2MQTT messages filling syslog, for more options see systemd.exec(5) StandardError=inherit Restart=always User=pi [Install] WantedBy=multi-user.target
Set up autostart of Zigbee2mqtt
You can use the following command to activate the autostart of zigbee2mqtt. This will start zigbee2mqtt automatically after starting the RaspberryPi.
Thanks to the already configured system service, you only need to execute the following command to start zigbee2mqtt together with the Raspberry Pi.
sudo systemctl enable zigbee2mqtt.service
Restart Zigbee2mqtt
You can use the following command to restart your zigbee2mqtt instance.
Enter the following command to restart zigbee2mqtt.
sudo systemctl restart zigbee2mqtt
Stop Zigbee2mqtt
You can use the following command to stop your zigbee2mqtt instance.
Enter the following command to stop zigbee2mqtt.
sudo systemctl stop zigbee2mqtt
Show log from Zigbee2mqtt
The following command displays the existing log file of zigbee2mqtt. This view is also updated automatically. For example, you can monitor the start process and find errors or display error messages.
Enter the following command.
sudo journalctl -f -u zigbee2mqtt
More articles on the topic
Once you have set up zigbee2mqtt, you should of course now integrate sensors and actuators into your Zigbee network.
The zigbee2mqtt dashboard can be used very well for this purpose. The dashboard is also a very convenient way to administer zigbee2mqtt. The article in which the dashboard is briefly introduced can be found here.
In the following category I have listed some Zigbee devices which can be controlled or read out with the NodeRed code offered there.
I have summarized further articles on the subject of Zigbee or zigbee2mqtt in the following category.
Have fun with the project
I hope everything worked as described for you. If not or you have questions or suggestions please let me know in the comments. I will then add this to the article if necessary.
Ideas for new projects are always welcome. 🙂
PS Many of these projects - especially the hardware projects - cost a lot of time and money. Of course I do this because I enjoy it, but if you think it's cool that I share the information with you, I would be happy about a small donation to the coffee fund. 🙂
English 
Deutsch 
Français 
Español 
Nederlands
Thanks for the great instructions! Unfortunately I can't connect any Ikea lamps, Touchlink recognizes the lamps and can also reset them, but the lamp does not appear under the devices afterwards. Nothing about a binding appears in the log either. I have successfully integrated 2 different buttons (E2001/E2002 and E1743), but it doesn't want to work with two different lamps (LED1836G9 and LED2003G10)...
Hi Mario,
have you already tried to couple the lamps "conventionally" without touch link?
I'm currently working on the instructions for the LED lamps from Ikea, and I'll probably put them online soon.
I connected the lamps in such a way that I first enabled access to my Zigbee network (via the zigbee2mqtt dashboard) and then reset the lamps (by switching them on and off several times).
This has worked well for all lamps so far. maybe can you try it? 🙂
Best regards
Fabian
Hello Fabian,
direct coupling between lamps and switches works, even several (both) lamps on one switch. But I noticed that I had to hold the pairing button for about 10 seconds for direct pairing. To pair a switch with z2m I have to press the pairing button 4 times in quick succession. That would actually correspond to a reset. Ie I can't assign a button to z2m and at the same time one or more lamps (directly)? Once a button is paired with the z2m, not even the red LED will light up when attempting to pair with other devices. Only after a reset (press 4 times) is the button "free" again. Can it be that my z2m is running in a "not Ikea mode" that can only use the buttons and no lamps?
When connecting the lamps with z2m I tried 2 processes:
* First activate the teach-in (then counts down from 255 seconds) and then reset the recognized lamp in the Touchlink tab. In the logs tab I see that the reset was successful but not a single message that there was a pairing attempt afterwards. I've also tried turning the lamp off and back on again.
* With the 2nd process, I also first activated the teach-in and then reset the lamp by switching it off and on again 6 times. (A bit fiddly, but you can see the success when the lamp dims up and down) Here, too, there is nothing in the log and no coupling.
The only difference to your setup that I haven't mentioned yet is that my z2m + Mosquitto + NodeRED (for later) is not running on an RPi but on a freshly installed Debian 11 in a virtual KVM machine. Can it be that it reacts too quickly compared to the Pi and has a runtime problem somewhere?
Hello again,
Right after my previous posting, I locked myself out of the frontend by trying and trying stupid things. That's why I edited the configuration.yaml several times to get access again. Then I tried a pairing again and now it worked! – with both lamps. Unfortunately, I'm still not sure what I changed...
Only with the reset in the touchlink does the coupling still not work.
In any case, thanks for your efforts
Greetings
Mario
Hi Mario,
very good. Oh, the main thing is that it works. 🙂
Thanks for the info.
Best regards
Fabian
Thank you for this tutorial.
zigbee2mqtt requires an mqtt server. I didn't have any pre-installed (Raspberry PI OS 64 bit lite). Probably the easiest way would be:
sudo apt install -y mosquitto mosquitto-clients
sudo systemctl enable mosquitto.service
And 2 steps here could still be corrected a bit:
– In this step, the "" can be removed:
echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
– At this step the “sudo apt-get update ” can be removed or should be connected with a lionebreak or “and”:
sudo apt-get update sudo apt-get install yarn -y
Seems something was filtered out of my comment... between the quotation marks was the line break tag.
Hello Fabian,
Dietmar here again.
I still have the problem of not being able to access the dashboard. I ran the journal again. It gives me the error: "zigbee2mqtt.service: Failed with result 'exit-code'.". What should I do with that?
Also, what do I enter in Zigbee2mqtt "configuration.yaml" under Url:? Is there the localhost?
It's greyed out in your instructions.
Best regards
Dietmar
Hi Dietmar,
Exactly, the setting for URL remains at "localhost".
Can you copy the entire issue of the journal in here? Then I can see if I notice anything. 🙂
Best regards
Fabian
Good morning Fabian,
I had time over the long weekend to do some troubleshooting again. 😉
Eureka! A POINT got in during the configuration! Now the thing works. I can access the frontend.
But now the next problem appears, we got a thermostat from MOES "BHT-002" for the start of our smart home. (Key point: energy saving) But I can't get the thing paired. It's obviously the part. The description (manual) is kept very simple and research on the net didn't bring much either. The problem is that the room temperature is recorded 1.5 degrees too high. That was the trigger for the Zigbee project.
It's like that sometimes, one thing sets off a chain of events.
But thank you for your efforts.
Best regards
Dietmar
Hi Dietmar,
that sounds good. 🙂
How did you go about teaching the BHT-002?
Did you see the pairing instructions here: https://www.zigbee2mqtt.io/devices/BHT-002-GCLZB.html Specifically, "Switch the thermostat off. Press and hold the temperature down button for +- 8 seconds to enable the pairing mode (display lights up and a WiFi-like icon is blinking). After successful interview turn the thermostat on again.”
And did you switch Zigbee2mqtt to pairing mode beforehand? 🙂
I have also described how to do this here: https://nerdiy.de/howto-zigbee-geraete-bzw-sensoren-und-aktoren-an-zigbee2mqtt-anmelden/
Best regards
Fabian
Hi folks,
I am failing to test the installation. A SONOFF Zigbee 3.0 USB dongle is connected to the Raspberry and I followed the instructions step by step. Nevertheless, Zigbee2MQTT cannot connect:
Does anyone here have any tips?
Thanks in advance
> zigbee2mqtt@1.33.2 start
> node index.js
Zigbee2MQTT:debug 2023-11-28 21:14:00: Loaded state from file /opt/zigbee2mqtt/data/state.json
Zigbee2MQTT:info 2023-11-28 21:14:00: Logging to console and directory: '/opt/zigbee2mqtt/data/log/2023-11-28.21-13-59' filename: log.txt
Zigbee2MQTT:info 2023-11-28 21:14:00: Starting Zigbee2MQTT version 1.33.2 (commit #311ea070)
Zigbee2MQTT:info 2023-11-28 21:14:00: Starting zigbee-herdsman (0.21.0)
Zigbee2MQTT:debug 2023-11-28 21:14:00: Using zigbee-herdsman with settings: '{"adapter":{"concurrent":null, "delay":null, "disableLED":false}, "backupPath":"/opt/zigbee2mqtt/data/coordinator_backup.json", "databaseBackupPath":"/opt/zigbee2mqtt/data/database.db.backup", "databasePath":"/opt/zigbee2mqtt/data/database.db", "network":{"channelList":[11], "extendedPanID":[221,221,221,221,221,221,221,221], "networkKey": "HIDDEN", "panID":6754}, "serialPort":{"path":"/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_1ca5d6628045ed119031cf8f0a86e0b4-if00-port0″}}‘
Zigbee2MQTT:info 2023-11-28 21:14:02: zigbee-herdsman started (resumed)
Zigbee2MQTT:info 2023-11-28 21:14:02: Coordinator firmware version: '{"meta":{"maintrel":1, "majorrel":2, "minorrel":7, "product":1, "revision":20210708, "transportrev":2}, "type": "zStack3x0″}'
Zigbee2MQTT:debug 2023-11-28 21:14:02: Zigbee network parameters: {"channel":11, "extendedPanID": "0x00124b002a9a882a", "panID":6754}
Zigbee2MQTT:info 2023-11-28 21:14:02: Currently 0 devices are joined:
Zigbee2MQTT:warn 2023-11-28 21:14:02: `permit_join` set to `true` in configuration.yaml.
Zigbee2MQTT:warn 2023-11-28 21:14:02: Allowing new devices to join.
Zigbee2MQTT:warn 2023-11-28 21:14:02: Set `permit_join` to `false` once you joined all devices.
Zigbee2MQTT:info 2023-11-28 21:14:02: Zigbee: allowing new devices to join.
Zigbee2MQTT:info 2023-11-28 21:14:02: Connecting to MQTT server at mqtt://localhost:1883
Zigbee2MQTT:debug 2023-11-28 21:14:02: Using MQTT anonymous login
Zigbee2MQTT:error 2023-11-28 21:14:02: MQTT error: connect ECONNREFUSED ::1:1883
Zigbee2MQTT:error 2023-11-28 21:14:02: MQTT failed to connect, exiting...
Zigbee2MQTT:info 2023-11-28 21:14:02: Stopping zigbee-herdsman...
Zigbee2MQTT:error 2023-11-28 21:14:03: MQTT error: connect ECONNREFUSED ::1:1883
Zigbee2MQTT:error 2023-11-28 21:14:04: MQTT error: connect ECONNREFUSED ::1:1883
Zigbee2MQTT:error 2023-11-28 21:14:05: MQTT error: connect ECONNREFUSED ::1:1883
Zigbee2MQTT:error 2023-11-28 21:14:06: MQTT error: connect ECONNREFUSED ::1:1883
Zigbee2MQTT:error 2023-11-28 21:14:07: MQTT error: connect ECONNREFUSED ::1:1883
Zigbee2MQTT:error 2023-11-28 21:14:09: MQTT error: connect ECONNREFUSED ::1:1883
Zigbee2MQTT:error 2023-11-28 21:14:10: MQTT error: connect ECONNREFUSED ::1:1883
Zigbee2MQTT:error 2023-11-28 21:14:11: MQTT error: connect ECONNREFUSED ::1:1883
Zigbee2MQTT:error 2023-11-28 21:14:12: MQTT error: connect ECONNREFUSED ::1:1883
Zigbee2MQTT:error 2023-11-28 21:14:13: MQTT error: connect ECONNREFUSED ::1:1883
Zigbee2MQTT:info 2023-11-28 21:14:13: Stopped zigbee-herdsman
Hi Schlikkes,
The problem is probably that you have not installed an MQTT server.
I didn't mention this very clearly in the article either (and have now adjusted it a little), thank you.
You can find the article here: https://nerdiy.de/de_de/mosquitto-auf-der-himbeere-mqtt-server-auf-dem-raspberrypi-installieren/
Best regards
Fabian