I recently started converting parts of my SmartHome to the Zigbee standard.
In the past I still used sensors and actuators based on the simple 433Mhz radio. Unfortunately, there are fewer and fewer sensors or actuators for this "radio standard".
Last but not least, the very low 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 some other advantages of the Zigbee standard. Actuators that are permanently connected to the power grid (e.g. a Zigbee-capable socket) also automatically function as repeaters (called “routers” in Zigbee jargon). In this way, very large Zigbee networks (eg over several floors) can also be set up.
Battery-powered Zigbee devices can – thanks to the more suitable architecture – achieve very long battery life. 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?
A very cool and helpful open source project is Zigbee2MQTT.
As the name suggests, zigbee2mqtt is a kind of adapter that evaluates the data received via Zigbee and forwards it to your SmartHome via to MQTT server.
You can then react to this data – as you know it from sensors/actuators based on Tasmota other EspEasy.
In the following article I have described how to install zigbee2mqtt on your RaspberryPi.
Safety instructions
I know the following hints are always a bit annoying and seem unnecessary. But unfortunately, many people who knew it "better" from carelessness lost their eyes, fingers or other things or hurt themselves. In comparison, a loss of data is almost not worth mentioning, but even these can be really annoying. Therefore, please take five minutes to read the safety instructions. Even the coolest project is worth no injury or other annoyance. https://www.nerdiy.de/en/sicherheitshinweise/
Affiliate links / advertising links
The links to online stores listed here are so-called affiliate links. If you click on such an affiliate link and store via this link, Nerdiy.de receives a commission from the online store or provider concerned. The price doesn't change for you. If you do your purchases via these links, you will support Nerdiy.de in being able to offer further useful projects in the future. 🙂
Requirements
Helpful articles:
Before you start with this article, you should have prepared a RaspberryPi so that it can be reached via the network and controlled via SSH. In addition, zigbee2mqtt should of course already be installed.
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 via SSH on the RaspberryPi
To get started, you first need to log in to RasPi with SSH on Putty. How to do it is described in the article
Update package management
The package management in Linux is a "central point" over which various software packages can be installed. For this to work reliably, the lists and sources of package management should be updated before installing any new packages.
sudo apt-get update && sudo apt-get upgrade
Prepare 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 must first install a few required dependencies/libraries.
To do this, run the following command. This prepares 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
After that you have to install the Yarn Package Manager. To do this, run 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 now have to adapt the configuration file to your system.
So that your zigbee2mqtt adapter (coordinator) can be addressed correctly, you must specify the correct path in the configuration file.
The adapter should of course already be flashed with the zigbee2mqtt firmware and connected to the Raspberry Pi. You can find information about this in the following blog article, for example.
Once the Zigbee Coordinator is connected, you should find out the device path and save it.
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 is listed here. If there are several entries listed here, the easiest way is to first remove all other USB devices, retrieve the list again and then copy the only existing entry.
In the example shown, the device path searched for is as follows.
- usb-Silicon_Labs_CP2104_USB_to_UART_Bridge_Controller_019758DF-if00-port0
It is best to save this in a text file. You 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 must adjust the positions given 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 to your MQTT server correctly. To do this, you have to adjust the position 'mqtt://localhost' accordingly (if the mqtt server is not running on the same RaspberryPi as zigbee2mqtt).
Adjust dashboard password:
In order to protect access to the zigbee2mqtt dashboard, you should set the password to a value only known to you. Change the part auth_token: secretPassword123 accordingly.
Customize the path to your Zigbee Coordinator:
Set the device path at
- 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 then start the installation of zigbee2mqtt by using the following bash commands
cd /opt/zigbee2mqtt
npm ci
test install
If you want, you can already verify the successfull installation of zigbee2mqtt at this point.
To do this, just run the following commands.
cd /opt/zigbee2mqtt
npm start
This starts zigbee2mqtt and you can see the log output.
Zigbee2mqtt then runs as long as the console window is open and connected or you end the program flow with CTRL-C.
Configure Zigbee2mqtt as a system service
In order for zigbee2mqtt to run 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 paste the text below and save the file with the keyboard shortcuts 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
With the following command you can activate the autostart of zigbee2mqtt. This will start zigbee2mqtt automatically after starting the RaspberryPi.
Thanks to the already configured system service, you only have to run the following command to start zigbee2mqtt together with the Raspberry Pi.
sudo systemctl enable zigbee2mqtt.service
Restart Zigbee2mqtt
You can restart your zigbee2mqtt instance with the following command.
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 Zigbee2mqtt log
The following command shows the existing log file of zigbee2mqtt. This view is also updated automatically. For example, you can also monitor the start-up process and find errors or display error messages.
To do this, enter the following command.
sudo journalctl -f -u zigbee2mqtt
More articles on the topic
After you have set up zigbee2mqtt, you should of course integrate sensors and actuators into your Zigbee network.
The zigbee2mqtt dashboard can be used very well for this. In addition, the dashboard is also a very convenient way to administrate zigbee2mqtt. The article in which the dashboard is briefly presented 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 other articles on the subject of Zigbee and zigbee2mqtt in the following category.
Have fun with the project
I hope everything worked as described. If not or you have any other questions or suggestions, please let me know in the comments. Also, ideas for new projects are always welcome. 🙂
P.S. 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 appreciate that I share this information with you, I would be happy about a small donation to the coffee box. 🙂
English 
Deutsch 
Français 
Español 
Português do Brasil 
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