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

Posted on by

To control your SmartHome with the help of cigbee2mqtt 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 (eg 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 (ie 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. 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.

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

Required tool:

NumberLink
1xscrewdriver set  Buy at Amazon
1xSD card reader  Buy at Amazon

Required material:

NumberLink
1xSONOFF Zigbee 3.0 USB Dongle Plus  Buy at Amazon
1xUSB extension cable  Buy at Amazon
1x Raspberry Pi  Buy at Amazon
1x Raspberry Pi power supply  Buy at Amazon
1x Raspberry Pi housing  Buy at Amazon
1x MicroSD card 64GB  Buy at Amazon

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

"FLASH PROGRAMMER 2".

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 a 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 boot loader 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 uartLog.py 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.

python uartLog.py

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 rear. 🙂 )

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

Silicon Labs CP210x USB to UART Bridge
i.e. 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

CC2652P

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 ammarked 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

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

Buy Me a Coffee at ko-fi.com   

35 comments

  1. Hi!
    First of all thank you for this article! I also wanted to switch my Sonoff Stick to Zigbee2MQTT today and was a little overwhelmed with the firmware upgrade. Thanks to your instructions, everything was super easy! However, I would add that it may be necessary to install the drivers for the stick before the Python script recognizes it as a serial device. I downloaded the drivers from here: https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers

    Reply

      1. Good morning,
        the driver must already be there when activating the bootloader. Otherwise Windows will not recognize the entire device as a COM port.

        greeting

        Reply

  2. Hi Fabian,
    thanks for the really good and detailed instructions.
    Helped me a lot to flash my two Sonoffs.
    Stupidly, I thought of permanently deactivating the bootloader on the second stick with the option "Disable Bootloader" in the Flash Programmer.
    Unfortunately with the result that I can't flash anything anymore. 🙁
    Do you perhaps have an idea how I can still flash ne firmware there?
    Thank you
    greeting
    Andre

    Reply

    1. Hi Andre,
      oh that hasn't happened to me yet, so I can't give you a (100%igen) tip.
      However, I would try the following.
      If you remove the case from the USB stick, a button could be installed on the circuit board. If you keep this pressed while you plug the USB stick into the USB port and release it about a second after plugging it in, the boot loader should also be activated.
      That should actually work. But like I said, I've never tried it. :/
      Best regards
      Fabian

      Reply

  3. Hi Christopher,
    thank you very much for the instructions! Almost everything went perfectly.
    Only the ieee I get to the Verr.. not flashed. I follow your pictures exactly. As ieee I would like to have my old stick. So I enter the Mac Address as in the picture and then flash the current firmware. It's also perfectly flashed, just not the ieee.
    Can it be that can not be flashed via bootloader? Or do you have any other idea what could be?

    greeting
    pure

    Reply

    1. Hi Reiner,
      oh i just see i made a stupid mistake here.
      Please enter your IEEE in the field for "Secondary Address" -> "IEEE 802.15.4 MAC address". Then it should work.
      Will try to correct that in the article. Sorry for the circumstances!
      Best regards
      Fabian

      Reply

  4. Hi. I got the following 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 https://www.zigbee2mqtt.io/guide/installation/20_zigbee2mqtt-fails-to-start.html 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?

    Reply

  6. Unfortunately, the Python script didn't work for me (although it had the same output as we described here). The flasher software could not detect the device.

    Unscrew the housing and hold down the boot button when plugging in the stick, but it finally worked!

    Reply

  7. Hello, thank you for your informative description.
    I have a problem, command shows me "no modul name gevent "
    what should i do here
    Thanks

    Reply

    1. Hi Jamal,
      then a library is missing. Try installing them with the command "pip install gevent". Then run the script again. 🙂
      Best regards
      Fabian

      Reply

  9. Hi,
    I get the error message when running python uartLog.py:
    File "uartLog.py", line 8

    ^
    Syntax error: invalid syntax

    What is causing the error message?

    Greetings
    Sebi

    Reply

    1. Hi Sebi,
      I just tried it again and the script works fine.

      The problem is probably caused by downloading the "non-RAW" content of the Python file. You most likely downloaded it by right-clicking and "save target as". In this case, the Python file is not downloaded, but the HTML page that is used to view the Python file.
      If you want to download the file correctly, it is best to download the full repository or download the file via RAW view here: https://raw.githubusercontent.com/Nerdiyde/Sonoff_zigbee_3.0_USB_dongle_plus_bootloader_script/main/uartLog.py

      Additional information on how to download the complete repository can also be found here: https://nerdiy.de/github-wie-kopieren-ich-dateien-aus-einem-github-auf-meinen-computer/

      Best regards
      Fab

      Reply

  10. Find out the IEEE address of the old Zigbee Coordinator (USB dongle)... This is tailored for Zigbee2MQTT. Is there a way to do this with ioBroker?

    Reply

    1. Hi Christof,
      Yes, that's right. Actually, you should also be able to read the address with the "Smart RF Flash Programmer 2" (which is also used in the article). Have you tried that?
      Best regards
      Fabian

      Reply

  11. Hey, I have to say, now that I've watched a few videos on flashing the "P" stick and none of them worked, I stumbled across your site after a bit of searching. Your instructions didn't work either.
    However, your pictures, explicitly the picture with the point where you have to specify the PORT (here 14 ), helped me further, because the following text of the command prompt was different for you than for me.

    I just lost the command prompt text returned from starting the bootloader, but there was a crucial point that doesn't appear in your message.

    Everything is up with you:
    xxxxxxx >>> processing
    xxxxxxx >>> processing
    END

    For me it looked like this:
    xxxxxxx >>> processing
    xxxxxxx >>> processing
    xxxxxxx >>> 0x(15)
    END

    I found out that there is a "hardware" switch installed here that supplies the bootloader with power.
    I had to unscrew the stick, then when the USB port is on the right side, there are 2 small dots (buttons) on the left, the right is the bootloader, the left is the reset button and to the left of the reset button is a lever that you can use with a Finger can move to a different position. Only after I flipped this lever, i.e. to the edge of the board, was the bootloader supplied with power.

    hp I flipped the lever first and then plugged it into the USB port.

    In case you don't know which buttons and levers I mean:
    There is a nice video on Youtube here.

    After that I was able to run your script to start the bootloader without any problems and the messages returned matched exactly those of your screenshot.

    Maybe this helps someone who also tries in vain to flash the stick again.

    Reply

    1. hey vio,
      Thanks for the hint. Is it okay if I mention or point this out in the article? 🙂
      Thank you and best regards
      Fabian

      Reply

  12. Hello!
    Is it really necessary to flash the stick again? According to various reviews on amazon, the ootb stick should work with zigbee2mqtt

    Reply

    1. Hi Christopher,
      are you sure it works with zigbee2mqtt? I had only seen hints that it worked directly with ZHA from HomeAssistant.
      If in doubt, I would follow the recommendations in the zigbee2mqtt documentation. If I saw it correctly, they still recommend flashing the appropriate firmware. 🙂
      Best regards
      Fabian

      Reply

  13. Hello
    Thanks for the great instructions. But do I understand that correctly: it is not intended for the Sonoff Zigbee 3.0 USB Dongle Plus V2 model ZBDongle-E (EFR32MG21), is it? Do you happen to have a "modification" of this guide?
    Thanks and greetings from CH
    Andre

    Reply

  14. This guide saved my life!! Was looking for instructions to cleanly flash the firmware on the stick because I had migrated my HA from a PI to a NUC and the stick then got stuck in a status that I could not fix other than flashing the firmware! Top work! Thanks very much!!

    Reply

  15. Hey, I'm going to be able to flash the USB dongle so it won't work. As the first heb ik de vraag of jullie dit doen with Windows? Flash programmer draait onder Windows maar hebben jullie also Python on de Windows machine draaien?
    I have not used the script until the boot button is printed on the dongle. Exactly what the film shows here. Real ik krijg de the following fout melding:
    >ACK/NAK not received. Expected 0x00 0xCC or 0x00 0x33, received 0x78 0x00.
    >ACK/NAK not received. Expected 0x00 0xCC or 0x00 0x33, received 0x80 0x78.
    >No response from device. Device may not be in bootloader mode. Reset device and try again. If problem persists, check connection and baud rate.
    >Connecting over serial bootloader failed: No response from device. Device may not be in bootloader mode. Reset device and try again. If problem persists, check connection and baud rate.
    >Initiate access to target: COM6 using 2-pin cJTAG.
    >Failed to create device object.
    Does anyone have any suggestions as to what else I can do about it?

    Reply

  16. I am trying to provide firmware to a USB dongle for zigbee2mqtt in various ways. For this, I am using Flash Programmer 2 from TI.
    If I do this with the boot button on the dongle, I get various error messages that there is no communication with the dongle. This is seen by the PC.
    If I use the method of opening the port with the Python script described here https://nerdiy.de/en/howto-zigbee-prepa … gbee2mqtt/, I get a log that the port is open and then the dongle is in boot mode, but then Flash Programmer 2 crashes immediately.
    What else can I try?

    Reply

    1. Hi Hans,
      I have no guaranteed solution here since this never happened during my flashing.
      But two things that might help:
      – Try starting the Flash Programmer 2 with admin rights. Sometimes there are difficulties in accessing the hardware.
      – Make sure that you have the correct zigbee dongle. If I remember right Sonoff is meanwhile also selling a newer version which might be not compatible. :/
      If you like let me know who tis came out. 🙂
      Best regards
      Fabian

      Reply

Kommentar hinterlassen

Your email address will not be published. Erforderliche Felder sind mit * markiert