HowTo: Zigbee – Prepare a Sonoff zigbee 3.0 USB Dongle Plus for zigbee2mqtt

To control your SmartHome with the help of zigbee2mqtt you need a Zigbee adapter so that you can also connect Zigbee sensors or actuators.

This is the interface between the Zigbee device and the SmartHome system (e.g. NodeRed) and is often available in the form of a simple USB stick including an antenna.

One of these Zigbee-enabled USB sticks is the “Sonoff zigbee 3.0 USB Dongle Plus”.

This is equipped with the very powerful CC2652P IC and thus supports the Zigbee 3.0 standard and up to 50 directly connected sensors or actuators (i.e. without going through another router).

In order for this Zigbee USB stick to be able to communicate with zigbee2mqtt, it must first be equipped with the appropriate firmware.

I have described how this works in the following article

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

Download flashing software

So that you can flash the Zigbee USB stick with the appropriate firmware, you must first download the appropriate software. This later helps to copy the actual firmware to the USB stick.

To do this, open the Texas Instruments website (this is the manufacturer of the IC used and the associated flash software) under the following link.

Then click on the download button…

…and on the following page to the

“Download options”-Button

in section


In the window that opens you should then select the option

“Windows Installer for SmartRF Flash Programmer”

At this point you have to verify yourself with an TI account.

This account can be created for free. Simply follow the link below

“Register now”.

After that you should be redirected to the shown view. Here you can click on the download button shown …

… and start downloading the software.

You now have to install the downloaded software.

In the following article I have described how to proceed with the installation of a program under Windows.

During the installation it may happen that the window shown is displayed. This is only an indication that additional drivers will be installed and can be confirmed by clicking on “Install”.

After the installation process is complete, you can start the software directly.

Download correct firmware

But before you can start the flashing process, you must first download the correct firmware version. This depends on the chip used and the desired configuration. In most cases, however, you can use the firmware linked below.

Under the following link you will find an overview of the available firmware versions and the associated hardware.

The current firmware version is also linked here.

Alternatively, the current firmware version is linked under the following link.

Activate the bootloader of the USB stick

Now only one last step is necessary to prepare the USB stick for the flash process. So that this can be equipped with the new firmware, you have to activate the bootloader. This is a small program component of the firmware currently installed on the USB stick, which helps to transfer the new firmware to the USB stick.

To activate the bootloader, the manufacturer of the USB stick provided a python script, which I uploaded (slightly modified) to the following GIT repository. I only translated the Chinese debug messages into English. The handling should therefore be a little easier than seen on the screenshots.

You should now connect the Zigbee USB stick to your computer.

So navigate to the GIT repository linked above and copy the python script to your computer.

I have described how you can download files from a GIT repository using an example in the following article.

After you have downloaded the script you can start it. To do this, open a command prompt, navigate to the location of the script and run the following command.


You may have to install the pySerial and/or gevent library for a successful start. To do this, you need to run the following commands.

pip install pyserial

pip install gevent

The script will now perform a few simple steps and then list all the connected COM ports. Here it can happen that more than one COM port is found. In this case you have to specify the COM port that belongs to your Zigbee USB stick.

If your USB stick is not recognized there, you may first have to install the appropriate driver. You can find the driver under the following link. (Thanks to Christopher for the hint. 🙂 )

In this example you can recognize the correct COM port by the line with the entry

“Silicon Labs CP210x USB to UART Bridge”
also COM14

If you have several devices with this entry, it is easiest if you first disconnect all other devices from the computer, restart the script and then continue.

In any case, you must enter the number of the associated COM port and confirm with Enter.

In the example shown here, “14” for COM14.

The script then carries out all the necessary steps to activate the bootloader on your USB stick.

Important: From now on you may no longer disconnect the USB stick from your computer. If so, you have to run the script again to reactivate the bootloader.

Start flash process

Now you can (finally) start the flashing process. To do this, start the previously installed software – if you haven’t already done so

  • SmartRF Flash Programmer 2

In the view shown, you should select your Zigbee USB stick again in the upper left corner. You can recognize this by the entry

“Silicon Labs CP210x USB to UART Bridge”

Then select the entry “Unknown” below.

After that you should select the IC used on the Zigbee USB stick. In this case, that’s the one


Select the relevant entry in the list below on the left.

This step is optional:

If you migrate from another Zigbee stick and want to transfer a known MAC address directly to the USB stick, you have to go to the tab

MAC Address

This step is optional:

Then enter the desired MAC address in the text field for “Secondary Address”. Attention: In the picture the wrong text field is marked! The correct text field is the one with the label “Secondary Address”.

You can find more information about this in the article

You can then select the firmware to be flashed by clicking on the button

  • Browse

You downloaded the firmware in one of the previous steps.

The path to the selected firmware is then displayed in the marked text field.

Now you can start the flash process.

To do this, tick the boxes as shown and click on the marked arrow button.

The flashing process will now start and its progress will be displayed in the lower area.

As soon as this has been successfully completed, the following message will appear in the read amrked area

  • Success!

Update zigbee2mqtt configuration file

So that zigbee2mqtt knows at which address it can address the new Zigbee USB stick, you now have to configure the configuration file of zigbee2mqtt correctly.

In order for this to work, you should now connect your Zigbee USB stick to the Raspberry Pi on which zigbee2mqtt is installed.

With the following command you can now list the connected Zigbee USB sticks.

ls /dev/serial/by-id/

In the example shown, only one USB stick is connected, which is why only one entry is displayed here.

If there are several entries there, you should select the entry with the identification string for the “Sonoff Zigbee 3.0 USB Dongle Plus”.

Copy the complete line here:

  • /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_aa2513a6c419ec11abc477e5f01c6278-if00-port0

and save them in a text file, for example, so that you can later insert them into the configuration file.

Now open the configuration file of zigbee2mqtt by entering the following command.

sudo nano /opt/zigbee2mqtt/data/configuration.yaml

If necessary, delete an existing entry at the marked position in the “port:” section.

You must now paste the previously copied address for your Zigbee USB stick into the configuration file as shown in the example.

Make sure that the indentation is correct and that there is only one entry under the “port:” category.

Now save the changes in the configuration file

  • STRG-X, Y and Enter

Restart zigbee2mqtt to apply the changes

In order to apply the changes to the configuration file, you should now restart your zigbee2mqtt installation.

All you have to do is run the following command.

sudo systemctl restart zigbee2mqtt

Zigbee2mqtt should now restart and the configured Zigbee USB stick should be available. In the following articles I have described how you can add Zigbee sensors or actuators and administrate zigbee2mqtt via a simple dashboard.

In the following category I have also listed other 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. There you will also find articles on various Zigbee devices and how they can be controlled from NodeRed.

External links:

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. Hi!
    Ersteinmal vielen Dank für diesen Artikel! Ich wollte heute auch meinen Sonoff Stick auf Zigbee2MQTT umstellen und war mit dem Firmware-Upgrade ein wenig überfordert. Dank deiner Anleitung ging alles super einfach! Ich würde allerdings noch hinzufügen, dass es u.U. nötig sein kann die Treiber für den Stick zu installieren bevor dieser vom Python-Skript als serielles Gerät erkannt wird. Die Treiber hab ich hier heruntergeladen:

      1. Moin,
        der Driver muss aber schon beim Aktivieren ds Bootloaders da sein. Windows erkennt sonst das ganze Gerät nicht als COM-Port.


  2. Hi Fabian,
    danke für die richtig gute und ausführliche Anleitung.
    Hat mir sehr geholfen meine beiden Sonoffs zu flashen.
    Blöderweise dachte ich mir direkt beim zweiten Stick mit der Option “Disable Bootloader” im Flash Programmer den Bootloader dauerhaft zu deaktivieren.
    Leider mit dem Ergebnis daß ich jetzt gar nichts mehr draufflashen kann. 🙁
    Hast Du vielleicht eine Idee wie ich da trotzdem noch ne Firmware flashen kann?
    Danke Dir

    1. Hi Andre,
      oh das ist mir bisher noch nicht passiert, deswegen kann ich dir keinen (100%igen) tipp geben.
      Ich würde allerdings mal folgendes ausprobieren.
      Wenn du das Gehäuse von dem USB Stick entfernst könnte auf der Platine ein Taster verbaut sein. Wenn du diesen gedrückt hälst während du den USB Stick in den USB-Anschluss steckst und ca. eine Sekunde nach dem Einstecken losläasst, sollte der Bootlader auch aktiviert werden.
      Das sollte so eigentlich klappen. Habe es aber wie gesagt noch nie ausprobiert. :/
      Beste Grüße

  3. Hi Christopher,
    herzlichen Dank für die Anleitung! Hat fast alles perfekt geklappt.
    Nur die ieee bekomme ich ums Verr.. nicht geflasht. Ich gehe exakt nach deinen Bildern vor. Als ieee hätte ich gern die meines alten Sticks. Also trage ich die bei Mac Address wie im Bild ein und flashe dann die aktuelle Firmware. Die ist auch perfekt geflasht nur eben die ieee nicht.
    Kann es sein, dass sich die nicht per Bootloader flashen läßt? Oder hast du sonst eine Idee, was sein könnte?


    1. Hi Reiner,
      oh ich sehe gerade, dass ich hier einen blöden Fehler gemacht habe.
      Trag deine IEEE bitte mal in das Feld bei “Secondary Address” -> “IEEE 802.15.4 MAC address” ein. Dann müsste es klappen.
      Werde versuchen das im Artikel zu korrigieren. Sorry für die Umstände!
      Beste Grüße

  4. Hi. I got the follwing feedback

    Zigbee2MQTT:info 2022-02-04 12:48:28: Logging to console and directory: ‘C:\zigbee2mqtt\data\log\2022-02-04.12-48-26’ filename: log.txt
    Zigbee2MQTT:info 2022-02-04 12:48:29: Starting Zigbee2MQTT version 1.23.0 (commit #unknown)
    Zigbee2MQTT:info 2022-02-04 12:48:29: Starting zigbee-herdsman (0.14.10)
    Zigbee2MQTT:error 2022-02-04 12:48:59: Error while starting zigbee-herdsman
    Zigbee2MQTT:error 2022-02-04 12:48:59: Failed to start zigbee
    Zigbee2MQTT:error 2022-02-04 12:48:59: Check for possible solutions
    Zigbee2MQTT:error 2022-02-04 12:48:59: Exiting…
    Zigbee2MQTT:error 2022-02-04 12:48:59: Error: AREQ – SYS – resetInd after 30000ms
    at Timeout._onTimeout (C:\zigbee2mqtt\node_modules\zigbee-herdsman\src\utils\waitress.ts:64:35)
    at listOnTimeout (node:internal/timers:557:17)
    at processTimers (node:internal/timers:500:7)

    Do you have any idea for this problem?

  5. Das Python-Script hat leider nicht funktioniert bei mir (auch wenn es die gleiche Ausgabe hatte wir hier beschrieben). Die Flasher-Software konnte das Gerät nicht erkennen.

    Das Gehäuse aufschrauben und dem Boot-Button beim Einstöpseln des Sticks gedrückt halten hat jedoch schließlich geklappt!

  6. Hallo, vielen Dank für deine informative Beschreibung.
    Ich habe ein Problem und zwar command zeigt mir “no modul name gevent ”
    was soll ich hier machen

    1. Hi Jamal,
      dann fehlt noch eine Bibliothek. Versuch mal sie zu installieren mit dem Befehl “pip install gevent”. Danach dann das Skript nochmal ausführen. 🙂
      Beste Grüße

  7. Hi,
    bei mir kommt beim Ausführen von python die Fehlermeldung:
    File “”, line 8

    SyntaxError: invalid syntax

    Was verursacht die Fehlermeldung?


    1. Hi Sebi,
      habe es gerade nochmal probiert und das Skript funktioniert einwandfrei.

      Das Problem wird wahrscheinlich durch das Herunterladen des „nicht RAW“-Inhalts der Python-Datei verursacht. Höchstwahrscheinlich hast du es per Rechtsklick und “Ziel speichern unter” heruntergeladen. In diesem Fall wird nicht die Python-Datei heruntergeladen, sondern die HTML-Seite, die der Ansicht auf die Python-Datei dient.
      Wenn du die Datei korrekt herunterladen möchtest, lade am besten das vollständige Repository herunter oder oder lade die Datei über die RAW-Ansicht hier herunter:

      Zusätzliche Infos, wie du das komplette Repository herunterladen kannst, findest du auch hier:

      Beste Grüße

  8. IEEE Adresse des alten Zigbee-Coordinater (USB-Dongle) herausfinden… Das ist auf Zigbee2MQTT zugeschnitten. Gibt es eine Möglichkeit das mit der ioBroker zu machen?

    1. Hi Christof,
      Ja das stimmt. Eigentlich müsstest du die Adresse auch mit dem “Smart RF Flash Programmer 2” (der auch in dem Artikel genutzt wird) auslesen können. Hattest du das mal versucht?
      Beste Grüße

  9. Hey, ich muss sagen, nachdem ich jetzt einige Videos zum Thema Flashen des „P“ sticks durch habe und keines funktioniert hat, bin ich nach eiterer Suche auf deine Seite gestoßen. Auch deine Anleitung hat nicht funktioniert.
    Allerdings haben mir deine Bilder, explizit das Bild mit dem Punkt, wo man den PORT angeben muss (hier 14 ) weiter geholfen, denn der nachfolgende Text der Eingabeaufforderung lautete bei dir anders als bei mir.

    Ich habe den Eingabeaufforderungstext der vom starten des Bootloaders zurück gegeben wpurde gerade nicht mehr verfügbar aber es war ein entscheidener Punkt vorhanden, der in deiner Meldung nicht auftaucht.

    Bei Dir steht alles auf:
    xxxxxxx >>> processing
    xxxxxxx >>> processing

    Bei mir sah es wie folgt aus:
    xxxxxxx >>> processing
    xxxxxxx >>> processing
    xxxxxxx >>> 0x(15)

    Ich habe rausgefunden, das hier ein „hardware“ Schalter verbaut ist, der den Bootloader mit Strom versorgt.
    Ich musste den Stick aufschrauben, dann sind, wenn der USB Port auf der rechten seite sitzt, links danneben 2 kleine Punkte ( Buttons) der Rechts ist der Bootloader, der Linke der Resetknopf und links vom Reset knopf ist ein Hebel, den man mit einem Finger auf eine andere Position setzen kann. Erst nachdem ich diesen Hebel umgelegt habe, also an den Rand der Platine, wurde der Bootloader mit Strom versorgt.

    PS. Ich hab den Hebel erst umgelegt und dann in den USB port gesteckt.

    Falls man noch nicht weiß welche Knöpfe und Hebel ich meine:
    Hier gibt es ein schönes Video auf Youtube.

    dannach konnte ich dein Script zum starten des Bootloaders ohne Probleme durchführen und die zurückgegebenen Meldungen entsprachen genau die deines Screenshots.

    Evtl hilft das hier ja jemandem der ebenfalls vergeblich versucht den Stick neu zu Flashen.

    1. Hey Vio,
      vielen Dank für den Hinweis. Ist es in Ordnung, wenn ich das im Artikel erwähne bzw. darauf hinweise? 🙂
      Danke und beste Grüße

  10. Hallo!
    Ist es tatsächlich notwendig den Stick neu zu flashen? Laut diversen reviews auf amazon sollte der Stick ootb mit zigbee2mqtt funktionieren

    1. Hi Christoph,
      bist du sicher, dass er mit zigbee2mqtt funktioniert? Ich hatte nur Hinweise gesehen, dass er direkt mit ZHA aus HomeAssistant funktioniert.
      Im Zweifelsfall würde ich den Empfehlungen in der zigbee2mqtt Dokumentation folgen. Wenn ich es richtig gesehen habe empfehlen die immer noch das flashen der entsprechenden firmware. 🙂
      Beste Grüße

  11. Hallo
    Danke für die tolle Anleitung. Aber verstehe ich das richtig: es ist nicht für den Sonoff Zigbee 3.0 USB Dongle Plus V2 model ZBDongle-E (EFR32MG21) gedacht, oder? Habt ihr da zufällig eine “Abwandlung” dieser Anleitung?
    Danke und Grüsse aus CH

  12. Diese Anleitung hat mir mein Leben gerettet!! Hatte nach einer Anleitung gesucht sauber die Firmware neu auf den Stick zu flashen da ich mein HA von einem PI auf einen NUC migriert hatte und der Stick dann in einem Status hängen geblieben ist den ich nicht anders als mit einen Flash der Firmware beheben konnte! Top Arbeit! Vielen Dank!!

Leave a Reply

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