How to use the Sonoff Zigbee Bridge with Home Assistant

UPDATE: If you saw the guide before 2020/07/27, the Zigbee chipset ota file is now handled by Tasmota instead of using ExtraPutty.  This simplifies the process tremendously!

I reviewed the Sonoff Zigbee Bridge a few months ago in a video and was excited to see it had an ESP82xx chipset onboard.  This meant there was a glimmer of hope it could be flashed with open source local control firmware such as Tasmota!  That time has come!  The genius developers with Tasmota have done their magic again.  An inexpensive device you can add to Home Assistant as a Zigbee controller.  No YAML, no custom plugins, no MQTT.  One of the major advantages is being able to place it closer to your Zigbee devices which is especially helpful if you have your Home Assistant box in the basement or buried back in some closet.  Behold the ZHA Integration below.

Purchase Sonoff Zigbee Bridge from Banggood or iTead

So how do we flash this?  First and foremost, there's NO soldering; don't close the window just yet!  It's relatively easy to do.  This is a full step by step walk through, some of the Tasmota veterans can skip many of the steps such as adding Tasmota to your WiFi network. 

During this process we will need a few pieces of software and files to flash things.  We are using Windows 10 during this process, feel free to grab the alternative versions if you are using Linux, Mac, etc.  

Tasmotizer - Downloads the firmware and flashes the Bridge.  Some users have reported Tasmotizer does not work on their setup, as an alternative you can use NodeMCU Py-Flasher and manually download the tasmota-zbbridge.bin, please make sure you use the DOUT flashing method with this app. 

ncp-uart-sw_6.5.5_115200.ota Use the "Download" button on GitHub.  Do not right click and save as! This could will result in a HTML file being downloaded instead of the actual file.

Flip the Zigbee Bridge over and open it, there are four small Phillips screws on the bottom under the feet pads.  There are no wires or anything, just a simple PCB in a case.  Turn over the board and you'll notice they labeled all the via holes for us.  

For ease of flashing I use typical breadboard jumpers inserted into female to female dupont jumpers attached to the USB TTL adapter.  Please remember to set your USB TTL adapter to 3v3 and NOT 5v.   

Attach your jumpers from the Zigbee bridge to the USB TTL as follows;

ETX to RX   (Note the RX to TX and TX to RX)
3V3 to 3V3
IO0(GPIO Zero) to GND

Example USB TTL

Plug in the USB TTL to your computer and open Tasmotizer.  In the odd case of your antivirus notifying you, it's a false positive.  Choose your com port for the USB TTL flasher.  Select the Release radio button and choose tasmota-zbbridge.bin as shown below.

Press Tasmotize! and it should start the flashing process.  If not check your connections and COM port and try again.  

Once the flashing is complete, unplug the USB TTL flasher, remove the wires from the Zigbee bridge, and power it back up via the normal USB power connector.  You can also put it back in the case if needed. 

Using your phone or computer, scan for available access points and look for a Tasmota-xxxx WiFi access point.

Connect to the AP and browse to 

Click "Scan for wifi networks".  Select your network, enter the AP1 Password, select the check box next to it to verify you typed it correctly, then hit Save.  The bridge will reboot and attach to your WiFi network.  You will need to consult your router/dhcp server to determine the IP address of the new device.  Browse to this new IP address.

Click Console and paste in the following command on one line and hit enter:

Backlog Weblog 3; so65 1; Module 75

Tasmota will restart after a few seconds, once the reboot is complete, click Main Menu.

To verify the process flashes, it is recommended to open a second window with the Tasmota Console on it and use another window to flash the Zigbee chipset firmware. Click Firmware Upgrade, in the "Upgrade by file upload" box use the browse button and select the ncp-uart-sw_6.5.5_115200.ota file downloaded previously. 

Press Start upgrade.  This will instruct Tasmota to flash the Zigbee chipset on the bridge that is necessary to integrate with the Zigbee Home Assistant integration.

The file will be flashing in the background.  Do not restart or power cycle the device!  You can click Main Menu, then click Console to see the process. Note the XMD: commands, as Tasmota is pushing the OTA file via Xmodem to the Zigbee chipset automatically for you.  If you do not see this XMD: Successful message do not continue on past this point as the ZHA process will not work.  Try pushing the OTA file upload through the above process again.

Once the process is complete Tasmota will reboot and attempt to start Tasmota Zigbee.  You will see the error message below.  This is not an issue, it is a good thing to see!

Issue the following command on the console to map the Zigbee chip to TCP Server Port 8888:

backlog rule1 on system#boot do TCPStart 8888 endon ; rule1 1 ; template {"NAME":"Sonoff ZHABridge","GPIO":[56,208,0,209,59,58,0,0,0,0,0,0,17],"FLAG":0,"BASE":18} ; module 0

Once the console reboots you should see the server has started on Port 8888:

17:35:58 TCP: Starting TCP server on port 8888
17:35:58 RSL: stat/tasmota_7FC5B0/RESULT = {"TCPStart":"Done"}

We are done with Tasmota!  Let's jump into Home Assistant.  

Go to Configuration, Integrations, hit the Plus to add a new integration.  Select Zigbee Home Automation.

Choose "Enter Manually" and hit Submit.

Radio Type is EZSP

Enter socket://<your bridge IP>:8888 and use 115200 for the port speed.  Hit submit.

Give it a few seconds to query the device and you should see the following screen.

Congratulations!  You did it!  Hit Finish.  You should now have a Zigbee integration in Home Assistant.  Click Configure.

Hit the Plus and start pairing your various Zigbee devices.  

You are all done! Add all your various Zigbee device types and enjoy! We will continue to update this guide as things get shorter with the process to flash the device.  Be sure to stop in, read the process of the reverse engineering this device and thank the developers of Tasmota.  

Be sure to check us out on YouTube and Discord if you have any questions.  

Sonoff Zigbee Products

Links to products provided by the ShareASale and Amazon Affiliate program.


  1. Very nice.
    After the flashing can this bridge be used with any Zigbee devices?

    I'm using Zigbee2MQTT with a CC2531 and wondering if it's worth it to change.

    1. I don't have a massive amount of devices but I had no issues pairing various brands from Gledopto LED strips, Sengled bulbs, Tuya Zigbee sensors, Sonoff Zigbee devices. Seems to act like my normal USB Zigbee stick I used.

  2. Hello,

    I guess this is coordinator firmware and not router firmware, so this means you can have only one in the zigbee network?


  3. Great news .... thanks. I have a unit on order now and will get back to you as soon as I've got it and flashed it.

  4. Thanks a lot. Works great. Just a few clicks and I am up and running. Still keeping both the CC2531 via zigbee2mqtt and now this Sonoff ZigBee Bridge - will see which one works better. But so far I'm loving it :)
    Any idea how to show the ZigBee network map? Something similar to the Zigbee2MqttAssistant?
    Many thanks one more time.

  5. Is it possible to replace the CC2531 with this bridge, but keep on using zigbee2mqtt?

    1. Don't think so, unless you can flash this bridge with the zigbee2mqtt firmware which I don't think you can at the moment.
      You can check here the supported adapters

  6. I had error when I setting serial device path "Unable to connect to ZHA device."

    1. The bridge needs to be running and have a network path from your HA install to the Bridge on port 8888.

    2. Mark, I have the same problem despite all steps in the set-up working perfectly and the bridge being on the network. I'm guessing that the issue might be that my HA is on a VM, but I'll have to do some more digging.

    3. You might be the one that I helped on Discord?

    4. I'm having the same issue - using HA in Proxmox. ZHA can not connect. Is there a solution?

    5. The previous issue I saw with someone was the OTA firmware had to be redone. Otherwise it works great with any system as you don't have USB ports and serial ports to pass into containers and VMs. Can you ping it from proxmox?

    6. Yes, I can ping the Bridge from the Proxmox OS. I have factory reset the device and followed the process 3 times now, same result.

    7. I can also ping it from the HA VM.

    8. Can you attach to via putty and send data to port 8888 and see it on the Tasmota console? It might be easier to jump into discord to go through a few steps to see where it is blocked or not working.

  7. Hi!
    I'm having issues with this:
    I'm getting this error after the "Backlog Weblog 3; so65 1; Module 75" and after the firmware upgrade:
    01:50:16 ZIG: Resetting EZSP device
    01:50:21 ZIG: timeout, goto label 99
    And then ofc doesn't connect to HA
    Any help maybe?

    1. If you are getting an error that early. I would definitely make sure you have the zbbridge.bin file flashed.

    2. Yeah, the Sonoff ZbBridge Module bin file is installed.
      How can I test the EZSP?

    3. I think the zigbee died...
      Anything I can try?

    4. Did you flash the .ota file? Did it show XMD: Successful on the console? Discord might be easier to help troubleshoot the issue.

    5. Yes, I posted under issues.
      No, it doesn't flash the ota.
      We'll continue in discord.

    6. If you aren't seeing the XMD: Successful when sending over the OTA file I'd start back from the beginning of the console stuff in Tasmota and push the OTA file over again then. See you in discord.

  8. You can chat with sonoff and find out the status of the devices via the socket via PHP or python, right?

    1. This replaces any messy cloud usage.

    2. I need my raspberry pi to talk to the sonoff zigbee bridge, is that possible?
      I don't have a Home Assistant.

    3. Yes. Flash the other ota file and use the Zigbee Tasmota setup and it is standalone and use MQTT back and forth.


Post a Comment

Popular posts from this blog

Tuya Convert 2.3 Update | Flash Tuya Smartlife Devices | No Soldering! | Remove the cloud | Custom Firmware

Tuya Convert 2 - Flash Tuya Smartlife Devices - No Soldering - Remove the cloud with Tasmota ESPHome