Sonoff ZBBridge to Zigbee2MQTT: Tasmota Flash Guide

The original SONOFF ZBBridge can be repurposed as a Wi-Fi-to-serial coordinator bridge for Zigbee2MQTT. It contains two separate processors: the ESP8266/ESP8285 side runs Tasmota, while the EFR32MG21 radio needs compatible Zigbee coordinator firmware. Flashing one does not update the other.

This guide is for the original board with the CoolKit SM-011 radio module. It is not a procedure for ZBBridge Pro or Ultra. It gives the UART, firmware and TCP setup steps, but no bridge was opened or flashed to test them here. The Wi-Fi serial link remains a reliability compromise compared with a suitable wired coordinator.

What the Sonoff ZBBridge actually is

The community-maintained hardware entry identifies the original ESP82xx/SM-011 EFR32MG21 combination. The Tasmota device-configuration entry provides its labelled UART connections and templates. Confirm the product and PCB/module markings against that entry before using these instructions.

ZBBridge Ultra is another distinct product, not a third revision covered by these pin assignments. A shared family name does not establish that an ESP image or NCP file belongs on it. Normal use powers the original bridge from its USB input at 5V; serial flashing below uses the board’s 3.3V rail and 3.3V logic.

Why repurpose it instead of buying a dedicated coordinator

This can be useful if you already own the original bridge and accept the wiring and recovery work. A suitable USB coordinator or Ethernet-connected coordinator avoids this particular Wi-Fi serial compromise. The choice depends on what you have and how much reliability the installation needs.

Tasmota replaces the stock ESP-side service, and Zigbee2MQTT can control the radio through a local TCP tunnel. That is separate from SONOFF DIY Mode, an interface for specific Wi-Fi products. It is not a universal conversion of every SONOFF gateway.

What you’ll need

• The confirmed original ZBBridge, with access to its labelled PCB pads.
• A USB-to-UART adapter using 3.3V logic, suitable wiring and a stable 3.3V supply for programming. Small pads may require soldering.
• A screwdriver, the correct ESP binary and a compatible signed SM-011 coordinator image.
• A computer with Espressif’s esptool, access to Tasmota’s web interface, and a recovery folder for firmware, settings and backups.

Stop any ZHA or Zigbee2MQTT process using the bridge. Record the board, current firmware and network configuration before changing it. If it already runs Tasmota, export its configuration from the web UI and record templates/rules. If it already hosts a working Zigbee2MQTT network, stop that service and copy its whole data directory and supported coordinator backup separately.

Flashing Tasmota onto the ESP8266 side

Remove the rubber feet and case screws, then identify the labelled pads on the original PCB. The reset button is not a substitute for identifying IO0. The device entry’s mapping is:

With power disconnected, connect the UART and ground IO0. Apply programming power so the ESP enters its ROM download mode. Keep the wiring stable; remove the IO0-to-ground connection for normal boot after programming. Tasmota’s serial-start guide explains this boot sequence and crossed TX/RX connection.

Download the ESP8266 tasmota-zbbridge.bin release asset, rather than a generic ESP32 or Pro binary. Version 15.6.0 was the released build checked here. Keep its file and published checksum. The following commands use current esptool’s hyphenated names and a Windows example port; replace COM5 with the actual port:

python -m esptool --chip esp8266 --port COM5 flash-id
python -m esptool --chip esp8266 --port COM5 read-flash 0 ALL zbbridge-esp-original.bin

Espressif documents ALL as flash-size autodetection. Confirm the detected chip/size and that the backup file has the expected size. Keep a separate copy; a second read with a matching file hash is a useful check before erasing. This backs up the ESP flash, not the EFR32 radio, its network state or every item required to recover stock eWeLink operation.

Once the backup and correct image are secured, erase the ESP flash and write the uncompressed binary at address zero:

python -m esptool --chip esp8266 --port COM5 erase-flash
python -m esptool --chip esp8266 --port COM5 write-flash --flash-mode dout 0x0 tasmota-zbbridge.bin

Wait for write verification. Disconnect programming power and wires, remove the IO0 ground, then use the normal USB supply. Join the Tasmota access point, configure Wi-Fi and reopen its web UI at the assigned address. The ZBBridge build uses this Wi-Fi setup rather than serial Wi-Fi provisioning. Confirm the build/model before proceeding.

Flashing the Zigbee radio’s coordinator firmware

The original radio’s bootloader normally requires a signed/encrypted SM-011 image. An unsigned dongle image, router image or Pro CC2652 file is not interchangeable. The firmware maintainer’s SM-011 repository documents signed versus unsigned bootloader variants and identifies the original bridge among the signed targets. Match the actual module/bootloader; stop if it differs.

For the current Ember route, that repository contains ncp-uart-sw-7.4.5.0_115200.ota, a specific signed SM-011 NCP UART image. It is community firmware, not a vendor-guaranteed upgrade. Obtain the actual binary through the repository’s raw/download control. The older 6.7.x image in the legacy instructions is not compatible with the current ember driver.

The released 15.6.0 code still has a relevant limitation: its abort stop clears the Zigbee application’s active flag, while the main loop runs the XMODEM uploader only when that flag is active. File-upload completion does not set it active again. That supports checking this specific failed starting state; it does not claim that every upload on every modern version fails.

1. With no external Zigbee client connected, select the original Sonoff ZbBridge (75) module in Tasmota and let it restart. This gives Tasmota the original radio pins for its firmware uploader.
2. Open Firmware Upgrade → Upgrade by file upload, select the matching radio .ota image and start the upload. This is the radio step, not another ESP binary write.
3. Keep power stable and wait for completion and reboot. Record the image and upgrade result. A failure needs diagnosis before changing images again.
4. Move to TCP mode below. Tasmota’s built-in Zigbee2Tasmota application has its own protocol-version limits; a newer NCP image for Ember need not produce the old guide’s successful Zigbee2Tasmota startup log. Verify the NCP version and successful initialization in Zigbee2MQTT’s Ember logs.

This firmware/control change should be planned as a new network when converting a stock eWeLink bridge. Inventory its devices and reset/re-pair them using their own instructions. Do not promise that stock account bindings, old groups or network keys migrate automatically. A previously configured independent network requires its own compatible backup/migration plan.

An original-bridge owner’s upgrade account documents moving from 6.7.9 to a signed 7.4.3 image through module 75, followed by the TCP template. It supports this general route on that person’s board/software; it does not establish every combination of a newer ESP build, bootloader and NCP as tested.

Connecting Zigbee2MQTT over the network

The legacy Zigbee2MQTT ZBBridge guide still illustrates ezsp. The current Ember guide lists supported firmware families and deprecates that old driver. The 7.4.5 NCP image above targets the supported 7.4.x family; do not infer that any newer number or multiprotocol image will work.

Apply the original-board TCP template in Tasmota’s Console, then Module 0 and wait for its restart. This published legacy-format template is converted by Tasmota when applied; its GPIO1/3 functions are TCP Tx/Rx rather than Zigbee2Tasmota’s radio application:

Template {"NAME":"ZHA ZBBridge","GPIO":[56,208,0,209,59,58,0,0,0,0,0,0,17],"FLAG":0,"BASE":18}
Module 0

The name is cosmetic; the serial tunnel can serve Zigbee2MQTT. Set its baud rate and a boot rule in Console. Replace 192.168.10.10 with the actual source IPv4 address the bridge sees from the Zigbee2MQTT host, including any container/NAT effects. Use an unused rule slot or merge into an existing rule after backing it up:

SerialLog 0
TCPBaudRate 115200
TCPConfig 8N1
Rule1 ON System#Boot DO TCPStart 8888,192.168.10.10 ENDON
Rule1 1
TCPStart 8888,192.168.10.10

Tasmota’s TCP documentation explains that the listener needs an explicit start and can restrict the connecting IPv4 address. Port 8888 belongs to the ESP-side Tasmota service; it is not a listener created by the Zigbee radio firmware. Keep it reachable only from the intended client and do not expose it to the internet.

Use the following in the actual Zigbee2MQTT configuration, substituting the bridge address and chosen port:

serial:
  port: tcp://192.168.10.42:8888
  adapter: ember
  baudrate: 115200
  rtscts: false

The physical UART rate is set on Tasmota and must match the selected NCP image. The original board does not provide a hardware RTS/CTS wiring path in this setup. Reserve stable addresses, allow the client-to-bridge TCP connection and its return traffic, then start one Zigbee client. Do not run ZHA, Zigbee2MQTT and Zigbee2Tasmota against the same radio concurrently.

Check both Tasmota’s connection log and Zigbee2MQTT’s reported NCP version/initialized coordinator. Pair one noncritical device, verify a fresh report and command, then check recovery after a planned bridge/client restart. A connected socket alone does not prove the Zigbee protocol initialized successfully.

The reliability tradeoff

The project’s remote-adapter documentation warns against Wi-Fi serial-to-IP bridges because packet loss and latency can upset the serial protocol. Its older ZBBridge example also labels its EZSP path experimental. That label should not be turned into a universal statement that every current Ember TCP implementation is experimental.

A stronger Wi-Fi signal or successful ping is not a complete serial-link test. Observe disconnections, initialization failures and missed device events over time. For a network that must recover reliably without attention, a supported USB or wired Ethernet coordinator is the more direct way to avoid this Wi-Fi transport dependency.

Common connection failures and what they usually mean

Issue #16947 is a March 2023 original-bridge report on 1.30.2 with socket-opening failures. It was closed as not planned, which is not evidence of a diagnosed Wi-Fi cause or a verified fix. Issue #28134 concerns the Pro’s Z-Stack path and a socket that opened before protocol initialization failed. Its advice is not automatically applicable to the original EFR32 board.

For ESP recovery, the same documented programming-mode wiring and esptool write-flash 0x0 zbbridge-esp-original.bin can restore a valid full backup to the same board. Confirm its chip/size and preserve it first. That does not restore an altered radio image, prove an old Zigbee network is intact or guarantee stock eWeLink recovery.

For the specific status-99 radio-upload problem, issue #23001’s January 2026 participants report that Tasmota 14.1.0 could reflash their original EFR32 bridges, while 14.2.0 failed. This is a reported older-uploader workaround, not a universal safe downgrade. If the board and symptom match, the concrete recovery sequence is:

1. Stop every Zigbee client, preserve the current ESP/settings and network backups, and obtain the exact original-board tasmota-zbbridge.bin from 14.1.0 plus the intended compatible signed radio image.
2. Use the ESP programming wiring and backup/erase/write sequence above with that older ESP binary in place of the 15.6.0 file. Reconfigure Wi-Fi locally after the erase and select module 75. The radio image is still separate.
3. Upload the matching signed NCP image through the working older web uploader and check actual completion. The reported tests include reverting to a Tasmota-supported 6.7.9 image; that is only a Zigbee2Tasmota recovery endpoint. For an intended Ember conversion, install and confirm the matching signed 7.4.5 NCP while the working uploader is still available, before switching the ESP back to the current TCP build. Do not stop at 6.7.9 and expect Ember to initialize it. This staged combination remains dependent on the exact board/bootloader and verified upload outcome.
4. For intended Ember/TCP operation, return the ESP to the current matching build through serial if necessary, without assuming OTA jumps across old versions succeed. Reapply the saved/current TCP template, baud rate and rule, then confirm the radio’s actual version and initialization before reconnecting devices.

Do not leave an old uploader deployed as an assumed fully supported modern coordinator. An August 2026 participant also reported OTA-forward failures from 9.1 and used serial flashing instead; that is another reason to retain UART access and distinguish an ESP update from a radio update. If the older uploader does not restore a working bootloader path, stop and use board-specific radio recovery tooling rather than guessed images. Neither deleting Zigbee network backups nor erasing the radio is a socket-error remedy.

FAQ

Can the original ZBBridge be a Zigbee2MQTT coordinator? Yes, with the appropriate ESP firmware, compatible coordinator NCP image and TCP setup. Its Wi-Fi transport limitations remain.

Which adapter setting should I use? Use ember with the matching supported coordinator image; this procedure identifies a signed 7.4.5 SM-011 image. An old 6.7.x NCP is not compatible with that current route. Check both the installed driver and actual radio firmware.

Does this cover Pro or Ultra? No. Confirm the exact board and follow its own supported procedure; original-board pinouts and images are not interchangeable.

Must I solder? The initial ESP flash needs reliable connections to small PCB pads. The device entry notes that ordinary Dupont connections may require soldering; it is not a plug-and-play USB data flash.

Is TCP port 8888 fixed by the radio? No. Tasmota starts the listener on the port you select, and Zigbee2MQTT must use that same port.

Does normal control need eWeLink? The local Tasmota/Ember/Zigbee2MQTT path can run without that account. Download sources, time services and other enabled Tasmota/Home Assistant features are separate network dependencies.

What this article verified, and what to check yourself

The board mapping comes from the maintained device entry; ESP/TCP commands from Tasmota and Espressif; the signed-image distinction from its firmware maintainer; and driver compatibility and Wi-Fi limits from Zigbee2MQTT. Firmware and settings instructions were reviewed against released sources, without a successful-flash claim or physical device test.

Verify your actual board, bootloader/image family, UART rate and one-client initialization before pairing a network. Keep ESP, Tasmota settings and Zigbee network backups distinct. A working local control path avoids the stock eWeLink service in that path; it does not prove every configured service sends no data outside the LAN.