Hack Sonoff Zbbridge-pro and Esphome

Nico Writing by Nico
  6 min of reading

This page has been visited ... times

Hack Sonoff Zbbridge-pro and Esphome

It no longer needs to be presented, already two years since the Sonoff ZBbridge-pro was released, it is an all-in-one control gateway (zigbee-wifi-bluetooth), exclusively dedicated to products from the Sonoff brand. But thanks to this tutorial you will be able to use it with ZHA or Zigbee2mqtt. You will find several discussions on the internet that will allow you to make ZBbridge-pro work in Home Assistant, but by installing Tasmota firmware. After some research I was able to hack the ZBbridge-pro directly with Esphome Firmware and thus make the Zigbee cc2652 key work with ZHA or Zigbee2mqtt all very easily.

Zigbee 3.0 cc2652p remote gateway, wifi and bluetooth

ZBBridge Pro

By Sonoff

Zigbee 3.0 cc2652p remote gateway, wifi and bluetooth


Presentation of ZBbridge-pro

Thanks to Itead for providing me with this module, you will see that the ZBbridge-pro has completely ordinary packaging in the emblematic colors of the Sonoff brand. No frills, instructions, a USB cable and a micro-module ZBbridge-pro.

presentation of the Sonoff ZBbridge-pro and presentation of the printed circuit

This Sonoff gateway ZBbridge-pro costs between 20 and 30 euros, *it has the advantage of being able to use wifi, bluetooth and Zigbee 3.0, which makes it an all-in-one mini gateway *.

Let’s not waste time and move on to the Hack.

Esphome code injection

As written above, this tutorial allows you to achieve perfect integration into Home-Assistant thanks to the esphome module.

Start by connecting the ZBbridge-pro via USB using a Uart/ftdi module. To access the printed circuit and in order to connect the Ftdi you will need to remove the 4 mini-pads which hide the screws. Then nothing could be simpler, connect the ftdi according to the table below:

ftdi connection on Sonoff ZBbridge-pro for esphome
Sonoff ZB Bridge PROFTDI programmer
GPIO00GND (on power on)

Then create a new device in the esphome tab (note the name of the module $devicename must be attached without a hyphen) and paste the code below by adapting the passwords.

  devicename: zbbridge
  friendly_name: zb-bridge-pro

  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
    ssid: ${devicename}_ap
    password: !secret zbbridge_ap_password


  password: !secret zbbridge_ota_password
    url: https://github.com/haade-administrator/zbbridge-pro.git
    ref: main
    refresh: 0s
    files: [

  - source: github://oxan/esphome-stream-server

The Github repository did not happen on its own, I was strongly inspired by the source Github repository: Zbbridge-pro Giancky79 integration

All you have to do is validate the code and push everything onto the Sonoff ZBbridge-pro.

Once uploaded the last step of Esphome integration, go to the applications and configure your esphome device, click on the link below.

Homeassistant Intégration

Module rendering in esphome:

At the time I write this post you will have access to all the necessary information, if you do not want to use the bluetooth tracker which is activated by default copy these lines of code into the esphome modules

    active: false
rendering of Sonoff gateway ZBbridge-pro in esphome

What information is reported in esphome:

  • zb_bridge_pro_fw_update (switch reset and firmware upload)
  • zb_bridge_pro_uptime_readable (reading time)
  • internal temperature
  • IP adress
  • mac address
  • the voltage of the internal battery

and many more…

ZHA configuration

If you want to use the zigbee key in zha, you still have to configure the key as in the screenshots below, click on the link below to go directly to the key config:

Homeassistant add Intégration

Then open a second page and go to the esphome integration by clicking on the link below:

Homeassistant configure integration

click on the button at the very top zbbridge firmware update and when the LED turns green confirms the integration of the key in ZHA, if you encounter a problem click again on the firmware update of esphome (the manipulation of the toggle firmware update is the same to update the firmware of the zigbee key). I hope this information is clear enough to you, otherwise contact me.

socket://[your_address_ip]:6638 // for me
baudrate: 115200
target: sofware


socket://[devicename.local]:6638 // replace the device name with the alternate name in my case **zbbridge**
baudrate: 115200
target: software

I made a video integrating the zigbee key into zha with an integration fault. To do this, prepare the address of the key, then activate the fx switch in esphome and configure the key quickly, otherwise restart the operation and that will do it.

If you upgrade with the latest firmware discovery in ZHA will be done without needing to click on the fw switch.

Connection and operation method of zbbridge-pro cc2652 zigbee key in ZHA

Below is the light operation after activating the switch. The green light lets you know when to integrate or update the firmware:

How the zigbee firmware switch works in esphome

zigbee2mqtt configuration

The configuration in Z2M is slightly different because you will make a call by TCP and not by socket

Go to the configuration.yaml file in the zigbee2mqtt folder and modify the following lines:

Ps: if you don’t know how to modify files in HA, install the File Editor module by clicking on the link below:

Homeassistant supervisor addons ingress
  port: tcp://[your_address_ip]:6638
  adapter: auto

Zigbee 3.0 firmware upgrade

By default the firmware dates from September 2022. You will find the firmware on the github Zigbee2mqtt takes the launchpad version

Z-stack zigbee2mqtt firmware launchpad cc2652p

To update the firmware of the zigbee cc2652p key follow the readme from the Haade repository dedicated to this tutorial installing latest Zigbee firmware

If you can’t do it, don’t hesitate to write to me

Sonoff documents ZBbridge-pro

Zigbee 3.0 cc2652p remote gateway, wifi and bluetooth

ZBBridge Pro

By Sonoff

Zigbee 3.0 cc2652p remote gateway, wifi and bluetooth

specification of Sonoff ZBbridge-pro


This is a simple way to integrate a ZBbridge-pro key into home-assistant with Esphome firmware. The advantage of this zigbee key is that it is easily portable because it is linked via wifi, you can use the BLE sniffer (bluetooth 4.2) and the famous cc2652 zigbee 3.0 key, all in one.



Founding member of the Haade site, a home automation enthusiast with all the tricks that go well.