HowTo: Zigbee – Installing zigbee2mqtt on the Raspberry Pi

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 (e.g. 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 an MQTT server.

You can then react to this data – as you know it from sensors/actuators based on Tasmota and 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.

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 shop via this link, receives a commission from the online shop or provider concerned. The price doesn't change for you. If you do your purchases via these links, you will support in being able to offer further useful projects in the future. 🙂


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.

In the following lists you will find all the parts you need to implement this article.

Required tool:

1xScrewdriver set  Bei Amazon kaufen
1xSD card reader  Bei Amazon kaufen

Required material:

1xSONOFF Zigbee 3.0 USB Dongle Plus  Bei Amazon kaufen
1xUSB extension cable  Bei Amazon kaufen
1x Raspberry Pi  Bei Amazon kaufen
1x Raspberry Pi power supply  Bei Amazon kaufen
1x Raspberry Pi housing  Bei Amazon kaufen
1x Micro SD Card 64GB  Bei Amazon kaufen

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

After entering your username and password you can start to enter the first commands.

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.

To start the package management update you have to enter the following command.
sudo apt-get update && sudo apt-get upgrade
Depending on how long your last update of the package management is, this process can take some time. First, the lists are updated in which the individual repositories are referenced.
Then the packages themselves are updated. As this additional memory is occupied, you will again asked for your consent. You have to confirm this with a "J"(in German) or a "Y" and "Enter".
When the update is complete, you will see a small summary of the duration and scope of the update.

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 | 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 | gpg --dearmor | sudo tee /usr/share/keyrings/yarnkey.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] 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 /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 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
  # Location of the adapter (see first step of this guide)
  port: /dev/ttyACM0

  network_key: GENERATE
  ikea_ota_use_test_url: true
  legacy_api: false
  log_level: debug

  port: 8038
  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 installation

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.


ExecStart=/usr/bin/npm start
# Or use StandardOutput=null if you don't want Zigbee2MQTT messages filling syslog, for more options see systemd.exec(5)


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 it that I share these information with you, I would be happy about a small donation to the coffee box. 🙂

Buy Me a Coffee at   


  1. Danke für die tolle Anleitung! Leider kann ich keine Ikea Lampen koppeln, Touchlink erkennt die Lampen zwar, kann sie auch Resetten aber danach erscheint die Lampe nicht unter den Geräten. Auch im Log scheint nichts von einer Bindung auf. Ich habe 2 verschiedene Taster (E2001/E2002 und E1743) erfolgreich eingebunden, aber mit zwei verschiedenen Lampen (LED1836G9 und LED2003G10) will es nicht klappen…

    1. HI Mario,
      hast du schon versucht die Lampen “konventionell” also ohne Touchlink zu koppeln?
      Ich arbeite gerade an den Anleitungen für die LED Lampen von Ikea, werde die vermutlich auch bald online stellen.
      Ich habe die Lampen so verbunden, dass ich erst den Zugang zu meinem Zigbee Netzwerk freigeschaltet habe (über das zigbee2mqtt Dashboard) und dann die Lampen (durch mehrmaliges ein und ausschalten) resettet habe.
      Das hat bisher bei allen Lampen gut geklappt. Vllt. kannst du das mal ausprobieren? 🙂
      Beste Grüße

      1. Hallo Fabian,
        direktes koppeln zwischen Lampen und Schaltern funktioniert, auch mehrere (beide) Lampen an einem Schalter. Dabei fiel mir aber auf dass ich fürs direkte koppeln die Kopplungstaste ca.10 sek halten muss. Um einen Schalter mit z2m zu koppeln muss ich die Kopplungstaste 4 mal schnell hintereinander drücken. Das entspräche eigentlich einem Reset. Dh ich kann einem Taster nicht zu z2m und gleichzeitig einer oder mehreren Lampen (direkt) zuweisen? Wenn ein Taster erst mal mit z2m gekoppelt ist beginnt nicht mal die rote LED beim Kopplungsversuch mit anderen Geräten zu leuchten. Erst nach einem Reset (4 mal drücken) ist der Taster wieder “frei”. Kann es sein das mein z2m in einem “Nicht Ikea Modus” läuft der nur die Taster kann und keine Lampen?
        Beim verbinden der Lampen mit z2m habe ich 2 Abläufe probiert:
        * Zuerst Anlernen aktiviert (zählt dann von 255 sek runter) und dann im Touchlink Tab die erkannte Lampe resettet. Im Logs Tab sehe ich dass der Reset erfolgreich war aber keine einzige Meldung dass es danach einen Kopplungsversuch gegeben hätte. Lampe danach einmal aus- und wieder einschalten habe ich auch schon versucht.
        * Beim 2ten Ablauf habe ich ebenfalls zuerst dass anlernen aktiviert und dann durch 6 maliges aus- und wieder einschalten einen Reset der Lampe durchgeführt. (Etwas frickelig aber man sieht den Erfolg wenn die Lampe ab und aufdimmt) Auch hier kommt nichts im Log und keine Kopplung.
        Den einzigen Unterschied zu deinem Setup den ich noch nicht erwähnt habe ist dass mein z2m + Mosquitto + NodeRED (für später) nicht auf einem RPi läuft sondern auf einem frisch installierten Debian 11 in einer virtuellen KVM Maschine. Kann es sein dass der im Vergleich zum Pi zu schnell reagiert und irgendwo ein Laufzeitproblem hat?

      2. Hallo nochmal,
        gleich nach meinem vorigen Posting hab ich mich durch dummes rumprobieren aus dem Frontend ausgesperrt. Deshalb habe ich die configuration.yaml mehrfach editiert um wieder Zugang zu bekommen. Dann hab ich noch einmal eine Kopplung versucht und jetzt hats geklappt! – mit beiden Lampen. Leider ist mir noch unklar was ich geändert habe…
        Lediglich mit dem Reset im touchlink funktioniert das Koppeln trotzdem nicht.
        Auf jeden Fall Danke für deine Bemühungen

  2. Vielen Dank für dieses Tutorial.

    zigbee2mqtt benötigt einen mqtt Server. Bei mir war keiner vorinstalliert (Raspberry PI OS 64 bit lite). Der wohl einfachste Weg wäre:

    sudo apt install -y mosquitto mosquitto-clients
    sudo systemctl enable mosquitto.service

    Und 2 Schritte hier könnten noch ein bisschen korrigiert werden:
    – Bei diesem Schritt kann das “” entfernt werden:
    echo “deb [signed-by=/usr/share/keyrings/yarnkey.gpg] stable main” | sudo tee /etc/apt/sources.list.d/yarn.list
    – Bei diesem Schritt kann das “sudo apt-get update ” entfernt werden oder sollte mit einem lionebreak oder “und” verbunden werden:
    sudo apt-get update sudo apt-get install yarn -y

    1. Scheint da wurde was aus meinem Kommentar gefiltert… zwischen den Anführungsstrichen stand das line break tag.

  3. Hallo Fabian,
    Dietmar noch mal hier.
    ich habe immer noch das Problem, dass ich nicht auf das Dashboard zugreifen kann. habe jetzt noch mal das Journal durchlaufen lassen. Dabei bringt es mir den Fehler : “zigbee2mqtt.service: Failed with result ‘exit-code’.”. Was soll ich damit anfangen?
    Außerdem, was gebe ich den in Zigbee2mqtt “configuration.yaml” unter Url: ein? Bleibt da der localhost?
    In Deiner Anleitung ist das ausgegraut.
    Viele Grüße

    1. Hi Dietmar,
      genau, die Einstellung bei URL bleibt bei “localhost”.
      Kannst du mal die komplette Ausgabe vom Journal hier rein kopieren? Dann kann ich mal gucken ob mir da etwas auffällt. 🙂
      Beste Grüße

  4. Guten Morgen Fabian,
    ich hatte ja über das verlängerte Wochenende Zeit, mich nochmal eingehend auf Fehlersuche zu begeben. 😉
    Heureka! Bei der Konfiguration ist ein PUNKT reingeraten! Jetzt läuft das Ding. Ich kann auf das Frontend zugreifen.
    Aber nun taucht das nächste problem auf, wir haben uns für den Start unseres Smarthomes ein Thermostat von MOES “BHT-002” besorgt. (Stichpunkt Energieeinsparung ) Das Ding bekomme ich aber nicht gepairt. Liegt ganz offenbar an dem Teil. Die Beschreibung (Manuell) ist sehr einfach gehalten und Recherchen im Netz haben auch nicht viel gebracht. DasProblem ist, dass die Raumtemperatur um 1,5 Grad zu hoch erfasst wird. Das war der Auslöser für das Zigbee Projekt.
    So ist das ist manchmal, ein Sache löst eine Kette von Ereignissen aus.
    Aber vielen Dank für Deine Bemühungen.
    Viele Grüße

    1. Hi Dietmar,
      das klingt doch schonmal gut. 🙂
      Wie bist du beim anlernen des BHT-002 denn vorgegangen?
      Hattest du die Pairing Hinweise hier gesehen: Speziell “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.”
      Und hattest du Zigbee2mqtt vorher in den pairing modus geschaltet? 🙂
      Wie man dabei vorgehen kann habe ich auch hier beschrieben:
      Beste Grüße

Leave a Reply

Your email address will not be published. Required fields are marked *