Zigbee OTA Updates

This guide explains OTA (Over-the-air) firmware updates of Zigbee devices: either directly in the web browser with the online OTA updater (with ConBee II or ConBee III), or with the deCONZ software (with ConBee II, ConBee III or RaspBee II).

OTA update: firmware transfer to an IKEA TRADFRI light in the web OTA updater

OTA Update via Web Browser

Prerequisites

ConBee II or ConBee III
An internet connection to start the OTA Updater
Web browser Chrome, Edge, Opera, or Firefox (151 or later)

The Web Serial API protocol required for the update is supported by Chrome, Edge, Opera, and Firefox 151 or later (desktop only, not Firefox for Android). A list of supported browsers is available here: https://developer.mozilla.org

Performing the OTA Update

OTA updater after connecting: the ConBee is connected, the link indicator is green

Once the ConBee is connected, the OTA updater reports the connection through the green Link indicator. The device list remains empty at first.

Open the website https://phoscon.de/ota/.
Establish connection: Click the Connect button and connect the plugged-in ConBee II or ConBee III.
Pair a Zigbee device (only needed for new devices): click the Pair a device button to start pairing mode. Put the Zigbee device you want to update into pairing mode as well. Devices already joined to a Zigbee network appear in the list automatically once the connection has been established.
Select device: After successful pairing, the device appears in the Devices list. Click on the corresponding device to open the detailed view and update status.

Device list of the OTA updater with four devices and their firmware status

The device list shows the firmware status of every device:

Update available: a newer firmware is available for the device.
Up to date: the device already has the latest known firmware. Reflashing it is possible.
No firmware: no firmware was found for the device.

Firmware transfer in the OTA updater: progress and block grid of the running update

Perform the firmware update: start the update process with Start update. The application transfers the firmware files to the device block by block. The progress is displayed in the block grid; elapsed and remaining time are shown.

Done!

The duration depends on the size of the firmware and on the radio environment and can take several minutes. Keep the ConBee connected until the update has completed. A running update can be aborted with Cancel. After an interrupted or failed update, Retry starts the process again.

Once all blocks have been transferred, the OTA updater reports Firmware updated successfully. The device then restarts on its own. The new firmware version appears in the device list again after the restart.

The OTA updater draws its firmware files from the same maintained firmware index as deCONZ (see How it Works and Notes) and verifies every file by its SHA-512 checksum before transferring it.

OTA Update via deCONZ

Prerequisites

At least deCONZ version V.2.33.0
ConBee II, ConBee III, or RaspBee II
An internet connection is required to download the OTA firmware files

Performing the OTA Update

Pair the Zigbee device to be updated with the Zigbee network. To do this in deCONZ, open the Control panel via the Panels tab, select Pairing, and activate Enable permit join. The network will remain open for 60 seconds to pair new Zigbee devices.
Open the OTA dialog at the push of a button.
Select the Zigbee device.
Click the Check Online button in the OTA dialog and wait a few seconds. deCONZ will now check if a new OTA file is available.
As soon as the status changes from No File to Update available, you can start the OTA process using the Update button. Sleeping Zigbee end devices such as buttons, switches, and sensors often need to be awakened manually by pressing a button for the update process to start.
The entire update process can take 10 to 30 minutes. During this time, the Zigbee device being updated must not be disconnected from power. After a successful update, the Zigbee device will restart automatically.

Done!

How it Works and Notes

Searching for new updates is never done automatically.
The initial loading of index.json completes once the Check online button is clicked. This also triggers an OTA Image Notify Request to the selected Zigbee devices to retrieve the currently installed firmware version, image type, etc.
If a newer firmware version is available for the Zigbee device, the progress column will display the status Update available.
After clicking the Update button, the update is queued and should start shortly thereafter.
Zigbee end devices such as buttons, switches, and sensors often need to be awakened manually by pressing a button or similar action.
After downloading the index.json file for the first time, updates will also be displayed for other Zigbee devices as long as the image type and manufacturer code are known. Many Zigbee devices regularly query the OTA server, e.g., Philips Hue devices.
Existing firmware files are not downloaded again because all local files are indexed by their SHA-512 checksum and compared against the SHA-512 in the index.json file.
Currently, only upgrades are supported. For downgrades, you must manually select a file from your hard drive or device storage beforehand. In the future, this will be added to the deCONZ user interface to allow selecting the firmware version from a list.
By default, OTA files are sourced from the well-maintained JSON index Koenkk/zigbee-OTA, which contains links to original OTA files as well as a GitHub-based mirror. The most recent JSON index with all OTA files can be found here.