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

Posted on by

So that your with the help of cigbee2mqtt also Zigbee sensors or actuators for controlling your SmartHome you need a Zigbee adapter.

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

One of these Zigbee-capable 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 sensors or actuators connected directly (i.e. without the detour via another router).

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

How this works 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 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 case  Buy at Amazon
1x Micro SD card 64GB  Buy at Amazon

Download software to flash

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

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

Then click on the download button there...

...and on the following page on the

"Download options" button

in the section

"FLASH-PROGRAMMER-2".

In the window that opens you should then select the option

"Windows Installer for SmartRF Flash Programmer"

select

At this point you will need to verify yourself with a TI account.

This account can be created for free. Just follow the link under

"Register now.

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

... start the download of the software.

Now you have to install the downloaded software.

How to install a program under Windows I have described in the following article.

During the installation, the window shown may appear. This is merely an indication that additional drivers are being 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 have to 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 can find an overview of the available firmware versions and the corresponding hardware.

The current firmware version is also linked here.

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

Activate bootloader of the USB stick

Now only one last step is necessary to prepare the USB stick for the flash process. So that it 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 has provided a python script, which I have uploaded (slightly modified) in the following GIT repository. I only translated the chinese debug messages to english. So the handling should be a bit easier than shown on the screenshots.

At the latest now you should 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.

How you can download files from a GIT repository I described with an example in the following article.

After you have downloaded the script, you can run it. Open a command prompt, navigate to the location of the script and execute the following command.

python uartLog.py

You may need to install the pySerial and/or gevent library to start successfully. To do this, you must execute the following commands.

pip install pyserial

pip install gevent

The script now performs a few simple steps and then lists all 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 have to install the appropriate driver first. 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 that starts with the entry

"Silicon Labs CP210x USB to UART Bridge"
i.e. COM14

If you have more than one device with this entry, the easiest way is to first disconnect all other devices from the computer, restart the script and then continue.

In any case you have to enter the number of the corresponding COM port and confirm with Enter.

In the example shown here, "14" stands for COM14.

The script will then perform all the necessary steps to activate the bootloader on your USB stick.

Important: From now on you must not disconnect the USB stick from your computer. If you do, you must run the script again to re-enable the bootloader.

Start flashing process

Now you can (finally) start the flash process. To do this - if not already done - start the previously installed software

  • SmartRF Flash Programmer 2

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

"Silicon Labs CP210x USB to UART Bridge"

Then select the "Unknown" entry below.

After that you should select the IC used on the Zigbee USB stick. In this case it is the

CC2652P

Selects the corresponding entry in the list at the bottom left.

This step is optional:

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

MAC Address

change

This step is optional:

Then enter the desired MAC address in the text field under "Secondary Address". Attention: In the picture the wrong text field is marked! The correct text field is the one labeled "Secondary Address".

You can also find more information in the article

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

Browse

select

You have downloaded the firmware in one of the previous steps.

The path to the selected firmware is then displayed in the highlighted text box.

Now you can start the flashing process.

To do this, set the checkmarks as shown and click on the highlighted arrow button.

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

As soon as this is successfully completed, the message

Success!

displayed.

Update configuration file of zigbee2mqtt

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

For this to work you should now connect your Zigbee USB stick to the Raspberry Pi with zigbee2mqtt 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".

Copies here the complete line thus:

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

and saves them, for example, in a text file to be able to insert them later 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.

The previously copied address to your Zigbee USB stick must now be pasted 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.

Saves the changes in the configuration file now by

  • CTRL-X, Y and Enter

restart zigbee2mqtt to apply the changes

To apply the changes to the configuration file you should restart your zigbee2mqtt installation.

All you have to do is run the following command.

sudo systemctl restart zigbee2mqtt

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

In the following category I have also listed other Zigbee devices which can be controlled or read out with the NodeRed code offered there.

More articles on the topic

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 look like NodeRed can be controlled.

External links:

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

Buy Me a Coffee at ko-fi.com       

41 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.
    Unfortunately, I thought I could permanently deactivate the bootloader on the second stick using the "Disable Bootloader" option 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 under "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 and command shows me "no modul name gevent "
    what should i do here
    Thanks

    Reply

    1. Hi Jamal,
      then a library is still missing. Try installing it 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 "not RAW" content of the Python file. Most likely you downloaded it by right-clicking and "Save target as". In this case, it is not the Python file that is 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 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 these instructions?
    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

  17. I have informed the supplier. He gave the following response:
    This newer E version of the Zigbee dongle from Sonoff is equipped with a Silabs/Silicon Labs EFR32MG21 chip and therefore uses a different firmware upgrade process and, of course, different firmware. The steps you are currently following seem to be designed for the older P version of the Zigbee dongle from Sonoff, which is equipped with a CC2652P chip from Texas Instrument (TI).

    By the way, if you are planning to use this dongle with Home Assistant, I recommend using it with the ZHA (Zigbee Home Assistant) implementation. This dongle works stably with ZHA, but is still experimentally supported within Zigbee2MQTT. In addition, Home Assistant has also released a Zigbee dongle with EFR32MG21 chip, so this Sonoff dongle is also expected to receive good support in the future.

    Because I'm working with Domoticz, I need Zigbee2MQTT. So now I will continue searching for a solution.

    Reply

  18. Class article! Thank you very much. I also just flashed a SONOFF stick. In the end, I gave up on Python scripting on Windows, screwed the thing up, and flipped the switch. Then, when connecting, held one switch to the USB port and off we went.

    Reply

  19. Thanks for the instructions, but I had a big problem with the TI flash tool. According to various forums and the developer "Koenkk", the tool has a bug and cannot flash the linked coordinator HEX file.

    Your script to activate the bootloader ran, but unfortunately did not have the desired effect.
    The boot loader is not activated.
    I unscrewed the stick and used the hardware buttons. The tip from "Vio" also helped me to operate the switch on the board.

    My approach was:
    - Unscrewing the stick
    - Slide the switch to the edge of the board
    - Hold down the bootloader button and insert the stick at the same time

    Instead of the TI tool, I used the "ZigStar Multi Tool". This allowed the HEX to be flashed immediately.
    Here is the link to the project:
    https://zig-star.com/radio-docs/zigstar-multi-tool/

    Maybe it will help someone.

    Reply

    1. Thank you! It was exactly the same for me. No matter what I tried, the TI tool only ever produced errors.

      I got it flashed just like you did:
      1) Screw on
      2) Switch to "ON" (to the edge of the circuit board)
      3) Plug in while pressing the BOOT button on the stick
      4) Flashing with ZigStar GW Multi tool v0.3.5:
      - Refresh
      - Select COM port
      - Select firmware file
      - Check Erase, Write, Verify
      - Press Start

      Reply

Kommentar hinterlassen

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.