Sonoff Zigbee Dongle Plus firmware update steps

The difference is one label on the enclosure: ZBDongle-P or ZBDongle-E.

They look similar. They are not similar where it matters. The ZBDongle-P runs on Texas Instruments’ CC2652P. The ZBDongle-E uses Silicon Labs’ EFR32MG21. Their firmware files, bootloaders, flashing tools, and failure modes diverge immediately. Treating them as interchangeable is not experimentation. It is negligence with a USB port.

A Sonoff Zigbee Dongle Plus firmware flash is usually performed for one of three reasons: updating coordinator firmware for Zigbee2MQTT or Home Assistant, switching the device to router mode, or moving it to an OpenThread or MultiPAN role. Each can be legitimate. Each can also break an otherwise stable mesh if the operator skips the boring parts.

Before touching the dongle, record four things:

• The exact hardware model printed on the casing: ZBDongle-P or ZBDongle-E.
• Its current role: Zigbee coordinator, Zigbee router, OpenThread RCP, or another radio function.
• The serial device path used by Home Assistant, Zigbee2MQTT, or another controller.
• A backup of the coordinator data and the smart-home application configuration, where the platform supports it.

Firmware is not the Zigbee network database. That distinction causes a regular crop of avoidable disasters. Updating the radio firmware may preserve the network. Replacing a coordinator, changing platforms, or erasing storage may not. The word “flash” has convinced too many people that all states are safely contained in one tiny USB stick. They are not.

The dangerous part is not flashing firmware. It is flashing the correct firmware into the correct radio while assuming the network state is somewhere else.

Identify the dongle before downloading anything

Sonoff sells two hardware versions under the broad “Zigbee 3.0 USB Dongle Plus” naming. That branding is convenient for retail shelves and terrible for operational clarity.

The first check is physical. Read the text on the dongle. Do not infer the model from a product listing, an old order confirmation, a blurry marketplace image, or the color of the case. Retail catalogs are full of stale photos and naming shortcuts. Hardware has no sympathy for catalog hygiene.

The second check is logical. Confirm what software currently owns the adapter. A Zigbee2MQTT installation may be configured against a stable serial path rather than a temporary device name. Home Assistant may expose the adapter through an add-on or a USB device mapping. Disconnecting the wrong serial device during maintenance is an efficient way to flash nothing while breaking the actual coordinator.

The third check is architectural. A coordinator firmware update is not an excuse to redesign the entire radio stack. If the dongle runs a working Zigbee network, keep the task narrow: update the coordinator firmware, restore service, verify devices, then move on. Combining a firmware upgrade with a migration to Thread, a different Zigbee stack, and a new Home Assistant host is how troubleshooting turns into archaeology.

Do not cross the firmware streams

The ZBDongle-P needs TI-compatible .hex firmware. The ZBDongle-E needs Silicon Labs .gbl firmware. There is no clever exception hidden behind the phrase “custom firmware.”

The P model’s CC2652P radio commonly uses Z-Stack firmware builds. The E model’s EFR32MG21 uses Silicon Labs-compatible images. The file extension is not merely a packaging preference. It reflects different platform tooling and different bootloader expectations.

A flash Zigbee coordinator firmware procedure begins with this mundane classification because the alternative is a false economy: save two minutes identifying the device, then spend hours trying to explain why a serial adapter no longer appears as one.

The official web flasher is the sensible default

For most owners, Sonoff’s browser-based Dongle Quick Flasher is the lowest-risk path. It detects the attached dongle model and can install official or custom firmware without opening the case. The advertised flashing operation takes under a minute. That claim is plausible because the payload is small. It should not be confused with a guarantee that the surrounding environment is clean.

The web flasher relies on the browser’s WebSerial API. In practice, that means Google Chrome or Microsoft Edge. A browser that cannot speak WebSerial will not suddenly become useful because the dongle is plugged in more firmly.

The procedure is simple enough to describe without turning it into a ceremonial checklist:

1. Shut down the service currently using the coordinator. Stop Zigbee2MQTT, the relevant Home Assistant integration, or any process with the serial port open. A serial port cannot be safely shared by software that believes it owns the radio and a flasher trying to reset it.

2. Plug the dongle directly into the host running the browser, preferably through a short USB extension cable if that is how it normally operates. Do not use a questionable unpowered hub for the one operation where a brief disconnect matters.

3. Open the official flasher in Chrome or Edge and select the serial device presented by the browser.

4. Let the tool identify whether it is dealing with the P or E hardware. Verify that result against the label on the enclosure. Automatic detection is useful. Blind faith in automatic detection is still blind faith.

5. Select the firmware role and image deliberately. A Zigbee coordinator image is not a Zigbee router image. An OpenThread RCP image is not a coordinator update with extra features.

6. Start the flash and do not remove the device, close the tab, sleep the host, or restart Home Assistant midway through the process. USB power management remains one of consumer computing’s quieter attack vectors against reliability.

7. When the tool reports completion, reconnect the dongle to its normal host and start the Zigbee software. Confirm that the serial adapter opens, the coordinator starts, and existing devices remain visible.

The web route avoids case disassembly and, in normal cases, avoids manually forcing bootloader mode. That is a meaningful improvement. It is not magic. A bad firmware choice remains bad after being delivered by a polished browser interface.

Coordinator, router, Thread: labels are operational decisions

The official tool can expose several firmware families, including Zigbee Coordinator, Zigbee Router, OpenThread RCP, and MultiPAN RCP. That menu can create the illusion that the dongle is a generic radio token waiting for a personality. It is closer to a role change than a cosmetic update.

A coordinator is the control point for a Zigbee network. It has a network identity, paired devices, and software that expects it to behave consistently. A router extends Zigbee coverage but does not replace a coordinator. OpenThread RCP is intended for a different protocol architecture. MultiPAN has its own stack and compatibility implications.

Installing router firmware on the only Zigbee coordinator does not improve the mesh. It removes the coordinator. The network will not admire the initiative.

Firmware selection is not a feature menu. It defines what the radio is allowed to be when it boots.

Home Assistant can flash the dongle without moving it to another machine

The Sonoff Dongle Flasher add-on for Home Assistant offers a more practical route for installations where the coordinator is physically attached to the Home Assistant host. Version 1.1.0 supports armv7, aarch64, and amd64 systems. That covers the usual mix: Raspberry Pi-class hardware, ARM mini-servers, and conventional x86 machines.

The advantage is obvious. The dongle stays connected to the machine that already knows its device mapping. There is no need to detach it, carry it to a desktop, and later wonder why the USB path changed. The less physical movement around home infrastructure, the fewer accidental variables enter the incident.

The operating logic remains the same:

• Stop the Zigbee service that currently claims the adapter.
• Open the Sonoff flasher add-on and select the detected serial device.
• Confirm the model and intended firmware role.
• Flash the image.
• Restart the service and inspect the logs before declaring victory.

The logs matter. A dashboard showing “running” is not proof that the coordinator joined the process correctly. The relevant evidence is more prosaic: the serial port opens, the adapter initializes, the PAN or network information is available, and devices begin reporting again.

If the environment runs Zigbee2MQTT, make sure its adapter configuration still matches the new firmware family and serial path. If it uses a stable /dev/serial/by-id/ style reference, preserve that reference where possible. If it was configured against a fragile /dev/ttyUSB0 name, this is an opportunity to stop outsourcing infrastructure decisions to enumeration order.

There is another trap. The Home Assistant add-on reduces physical friction; it does not eliminate version compatibility. A newly flashed coordinator can expose behavioral differences to the Zigbee stack above it. Update one layer at a time where possible. Radio firmware first. Verify. Then consider application updates. A simultaneous upgrade of Home Assistant, Zigbee2MQTT, the host operating system, and coordinator firmware does not create a “clean slate.” It creates four suspects.

Manual flashing on the ZBDongle-P: TI hardware, .hex files

Manual flashing is for cases where the web tool is unavailable, the device is attached to a system better managed from a shell, or an operator specifically needs a firmware build outside the convenient paths. It is not inherently superior. Command-line tooling merely makes every assumption visible.

For the ZBDongle-P, the relevant tool is cc2538-bsl. The CC2652P-based dongle accepts .hex images. The manual command follows this form: python3 cc2538-bsl.py -p <port> -e -v -w --bootloader-sonoff-usb <firmware.hex>.

Each part has a job:

• -p <port> selects the serial device. This must point to the actual dongle, not a Bluetooth modem, a console port, or another USB serial device with an equally unhelpful name.
• -e erases the target before writing.
• -v verifies the programmed firmware.
• -w writes the selected image.
• --bootloader-sonoff-usb attempts to place the Sonoff dongle into bootloader mode through RTS/DTR control signals.
• <firmware.hex> is the TI-compatible firmware file selected for the intended radio role.

The automatic bootloader flag is the important quality-of-life feature. It means a ZBDongle-P can normally be flashed without opening the enclosure or pressing hardware buttons. The feature was added to the cc2538-bsl project’s main branch in early 2022, and it removes one of the more tedious parts of older serial-flashing workflows.

Normally is not always. USB serial adapters, host permissions, container boundaries, and older hardware revisions all have opinions. Most of them are poorly documented. If automatic bootloader entry fails, do not respond by repeating the same command ten times and calling it persistence. Inspect the port, confirm that no service is holding it, and verify the dongle model and firmware file.

The manual route has two advantages: it exposes the exact artifact being installed, and it produces output that can be inspected. It also has a familiar downside. The operator is responsible for everything the web interface would otherwise abstract away, including selecting the correct image.

What to inspect after the write completes

A successful write operation is not the final validation. It only proves that a tool wrote bytes to a device and received an acceptable response.

After flashing the P model, the operator should confirm:

• The dongle reconnects as a serial device after being unplugged and reattached.
• The smart-home platform can open the expected port.
• The Zigbee application identifies the adapter rather than reporting timeouts or initialization failures.
• Existing devices remain associated and begin communicating after the mesh settles.
• The system logs do not show repeated coordinator resets, serial disconnects, or adapter startup loops.

A mesh can take time to resume normal reporting after a coordinator restart. That is ordinary. A permanently silent network is not. The temptation to re-pair every device immediately should be resisted until the coordinator configuration and data path have been checked. Re-pairing is often the point where a recoverable configuration error becomes a household-wide reset.

Manual flashing on the ZBDongle-E: the physical BOOT button returns

The ZBDongle-E is less forgiving of remote optimism. It uses Silicon Labs’ EFR32MG21 radio and requires .gbl firmware images. The standard manual tool is universal-silabs-flasher.

The command structure is: universal-silabs-flasher --device <port> flash --firmware <firmware.gbl> --allow-cross-flashing.

The --allow-cross-flashing option deserves attention. It is not a permission slip to install arbitrary firmware from the internet. It allows the tool to proceed across supported firmware identities within the Silicon Labs flashing context. The chipset boundary remains absolute. It does not make a TI .hex image compatible with an EFR32MG21, and it does not make an OpenThread image a safe replacement for a Zigbee coordinator.

Manual ZBDongle-E flashing requires access to the physical BOOT button. That means opening the enclosure. The sequence is mechanical:

1. Disconnect the dongle from USB power.

2. Open the casing carefully enough to avoid turning a firmware task into a hardware repair task.

3. Locate the BOOT button near the USB connector.

4. Hold the BOOT button down while reconnecting the dongle to the computer.

5. Keep holding it for approximately five seconds, then release it.

6. Run the flashing command against the correct serial device and .gbl file.

7. Reassemble the dongle only after the flash completes and the device is tested.

This is precisely why the official web flasher should be the first choice for ordinary updates. The E model’s manual path is not impossible. It is simply exposed to more failure points: casing clips, button timing, USB power, port detection, file selection, and software permissions. Consumer hardware is often designed around the assumption that nobody will need to touch it after purchase. Firmware work exposes that assumption with the usual lack of elegance.

The figure sometimes cited for ZBDongle-E NCP firmware is 115200 baud. That setting belongs to the serial communication context, not an excuse to randomly alter every baud-rate field in an existing Zigbee configuration. If the platform already has a working serial setup, document it before changing anything. Settings drift is one of the less glamorous forms of lateral movement in a home lab: a small change migrates into a larger outage because nobody remembers the original state.

The post-flash test should be dull

A safe Sonoff Zigbee 3.0 USB Dongle Plus flashing procedure ends in verification, not applause.

Bring the coordinator back online and watch its behavior for a while. Test a mains-powered router device and a battery-powered end device. Check a sensor that reports periodically and an actuator that should respond immediately. This samples different parts of the mesh without requiring a theatrical tour of every bulb in the house.

If devices do not return:

• Confirm the flashed firmware role is still Zigbee Coordinator.
• Confirm the smart-home software is targeting the correct serial device.
• Inspect application logs for adapter initialization errors.
• Verify that the coordinator database or backup was not replaced, erased, or pointed at a new empty location.
• Check that a USB extension cable or hub has not changed the physical stability of the connection.
• Avoid factory-resetting end devices until the coordinator itself is proven healthy.

For a ZBDongle-E used as a router, holding the BOOT button for around eight seconds can remove it from a Zigbee network and return it to pairing mode. That is useful for a router deployment. It is not a recovery ritual for a coordinator outage. Pressing buttons without knowing the active firmware role is how hardware support forums acquire their longest threads.

The cleanest firmware update is boring: correct model, correct file type, one controlled tool, a verified restart, and no unrelated configuration changes. Sonoff’s newer browser and Home Assistant flashing routes make that boring path accessible. Good. The industry has spent years making radio maintenance needlessly ceremonial.

But the dongle still contains two different chip families under one product name. That remains the critical fact. Identify the silicon first. Everything else follows from it.