Zigbee OTA (Over-The-Air) firmware update support to Zigbee End Device component on the NRF52 platform? And try to make it expandable for future Zigbee OTA Upgrade Cluster support on ESP32 platform?

[Hedda]

Component name

zigbee

Link to component documentation on our website

https://esphome.io/components/zigbee/

Describe the enhancement

It it possible to add ability to support for native Zigbee OTA updates to the Zigbee End Device component on the NRF52 platform?

• https://esphome.io/components/ota/esphome/

That is, implement full support for the Zigbee ZCL OTA Upgrade Cluster (Zigbee Cluster Library's OTA Upgrade Cluster) and ZigBee Over-the-Air Upgrade (OTAU) firmware updates that enable wireless ESPHome OTA updates via the Zigbee protocol and preserving Zigbee connections after OTA updates.

Expect that a couple challanges would be the signifigant limited bandwith Zigbee has compared to WiFi

Anyway, this feature should allow users to update ESPHome devices configured as Zigbee devices over-the-air using standard Zigbee OTA.

Zigbee firmware over-the-air (Zigbee FOTA) library provides Zigbee endpoint definition, which implements clusters responsible for transferring a firmware file through the Zigbee network.

• https://docs.nordicsemi.com/bundle/ncs-2.1.3/page/nrf/libraries/zigbee/zigbee_fota.html

  • https://docs.nordicsemi.com/bundle/nrf5_sdk_thread_zigbee/page/zigbee_example_ota_server.html

Having native Zigbee OTA support is for sure a wanted feature in the long term, even if it will take a long time to get there.

In my personal opinion this core concept here to add native support for building Zigbee End Device with ESPHome is to allow you to built native Zigbee End Devices using ESPHome firmware, and when end-user have deployed/commisioning them they should not have to use the ESPHome protocol to perform OTA updates on them but instead use standard Zigbee protocol via pure Zigbee communication and be seen to the Zigbee gateway as standard Zigbee device that fully follows the official ZCL (Zigbee Cluster Library) specification.

Use cases

Use case is to be able to allow to update OTA image via Zigbee gateway that the device is connected to, e.g. ZHA or Zigbee2MQTT:

• https://www.home-assistant.io/integrations/zha#ota-updates-of-zigbee-device-firmware

• https://www.zigbee2mqtt.io/guide/usage/ota_updates.html

It is not user-friendly to if firmware updates of Zigbee devices require user to perform updates via Serial, Bluetooth or WiFi.

I imagine that if and when native Zigbee OTA support is added to ESPHome then it will create a new opportunity to make and sell finished Zigbee devices based on ESPHome that are not only meant for DIY enthusiasts but also for less advanced users who are just willing to buy an ESPHome device if it 100% works as a native Zigbee device, including supporting Zigbee OTA updates,

FYI; Apollo Automation (which is a commercial company that build devices using ESPHome and that also just last month was announced as the second official commercial partner to the Open Home Foundation) has several times expressed to their community that they want to be able to offer native Zigbee firmware for their devices as an option, so I would think it would be in their interest to make sure that some of their investments into ESPHome goes to adding Zigbee OTA support to it (i.e. they might be willing pay a developer to specificly work on that feature).

Anything else?

I believe that tomaszduda23 has recently put the fundamental prerequisites in place to achive this on Zephyr based devices like nrf52?

• [nrf52,ota] zephyr mcumgr ota esphome.io#5740

  • [nrf52, ota] ble and serial OTA based on mcumgr esphome#11932
  • [nrf52] allow to update OTA via cmd esphome#12344

• https://esphome.io/components/ota/

  • https://esphome.io/components/ota/zephyr_mcumgr/

So challenge might be more about how to build and package ESPHome firmware as native Zigbee OTAU file with correct metadata?

For reference; know that zigpy/zha project developers have some tools generating OTA index files and testing/checking them. Check out:

• https://github.com/zigpy/zigpy-cli

and

• https://github.com/zigpy/zigpy/wiki/OTA-Information-for-Manufacturers

I believe luar123 mentioned before that he have no current plans to implement Zigbee OTA Update Cluster for the ESP32 platform as of yet.

• Zigbee support on the ESP32-H2, ESP32-C6 and ESP32-C5 #1397

Espressif's upstream ESP Zigbee SDK does however at least have support for Zigbee OTA Upgrade Cluster related APIs. See:

https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/user-guide/zcl_ota_upgrade.html

and

https://docs.espressif.com/projects/esp-zigbee-sdk/en/latest/esp32/api-reference/esp_zigbee_ota.html

Again, Bluetooth for OTA firmware updates should probably only be used as a workaround until there is native support for Zigbee OTA Update Cluster for both these platforms, but probably a good idea to add support for Bluetooth OTA firmware updates regardless, especially if it is simpler to add support for in ESPHome than native architecture for Zigbee OTAU Firmware (ZigBee Over-the-Air Upgrade) inside ESPHome, but I believe that sooner or later ESPHome will also need to have native support for building Zigbee firmware update images and allow pushing them over native Zigbee OTA (Over-The-Air) updates,

[tomaszduda23]

I just noticed that z2m allow to use "custom firmware" for OTA. https://www.zigbee2mqtt.io/guide/usage/ota_updates.html#using-custom-firmware-files-or-index

[Hedda]

zha and zigpy does also support that:

• https://github.com/zigpy/zigpy/wiki/OTA-Configuration

I believe you could also generate custom OTA files for zigpy/zha with zigpy-cli that are Zigbee specification compliant? See:

• https://github.com/zigpy/zigpy-cli

and

• https://github.com/zigpy/zigpy/wiki/OTA-Information-for-Manufacturers

[tomaszduda23]

looking at the config values I guess it would generate image during building https://docs.nordicsemi.com/bundle/nrf5_sdk_thread_zigbee/page/zigbee_example_ota_server.html
I'm not sure though

[github-actions[bot]]

🏷️ I've automatically added the component: zigbee label to help categorize this feature request.

[Hedda]

Any new thougths on adding native Zigbee Over-The-Air (OTA) support to allow standard Zigbee Over-The-Air Update (OTAU) via ESPHome?

• https://esphome.io/components/ota/esphome/

An idea here could be to also reach out about possible collaboration on this with the developer working on an external Matter component for ESPHome since he (DavidvtWout) have a similar dilema for how to update ESPHome-based devices using standard Matter OTA:

• Support matter ota DavidvtWout/esphome-matter#69

[Hedda]

Tip! Z2M dev nerivec maintains"Zigbee OTA File Editor" open-source tool that let you inspect and edit Zigbee OTA images from your browser:

• https://nerivec.github.io/zigbee-ota-file-editor/

  • https://github.com/Nerivec/zigbee-ota-file-editor

And zigpy/zha devs published a repository with a Python library for parsing and genereating Silicon Labs EBL, GBLv3, and GBLv4 OTA images:

• https://github.com/zigpy/pygbl

FYI, both Home Assistant's ZHA and Zigbee2MQTT support standardized Zigbee Over-The-Air (OTA) images and each have their own repo:

ZHA

• https://www.home-assistant.io/integrations/zha/#ota-updates-of-zigbee-device-firmware

  • https://github.com/zigpy/zigpy/wiki/OTA-Information-for-Manufacturers

    • https://github.com/zigpy/zigpy/wiki/OTA-Configuration

    • Launch of the zigpy-ota repo zigpy/zigpy-ota#2

      • READ FIRST: Submitting new OTAs zigpy/zigpy-ota#1

Zigbee2MQTT

• https://www.zigbee2mqtt.io/guide/usage/ota_updates.html

  • https://www.zigbee2mqtt.io/guide/configuration/ota-device-updates.html

    • https://github.com/Koenkk/zigbee-OTA

[Marco Mornati (mmornati)]

Hi all, here is a working proof of concept of firmware updates over Zigbee for ESPHome's native Zigbee support (ESP32-C6/H2, esp-zigbee-lib 2.0.5), as a regular OTA platform:

ota:
  - platform: zigbee
    image_type: 0x0101   # one per kind of device

How it works

• It adds the ZCL OTA Upgrade client cluster (0x0019) to the first endpoint. The coordinator (Zigbee2MQTT, ZHA) is the OTA server.
• It writes the image through ESPHome's existing ESP-IDF OTA backend. App rollback, safe_mode and the on_begin / on_progress / on_end / on_error triggers all work as they do for the other OTA platforms.
• Every build also writes firmware.zigbee.ota next to firmware.ota.bin: a standard Zigbee OTA file with the image zlib-compressed, about 62 % of the size. The dashboard offers it as a download. file_version defaults to the build time, so each build is newer than the last.
• The zigbee component only gets a small listener hook in its existing action handler. Number and switch writes keep working.

Code, write-up and test kit: draft PR in my fork, mmornati/esphome#1 (mmornati/esphome#1), branch zigbee-ota. To try it:

external_components:
  - source: github://mmornati/esphome@zigbee-ota
    components: [zigbee]

Tested on hardware: XIAO ESP32-C6 as router, Zigbee2MQTT 2.14.2 (EmberZNet coordinator). The device updated itself from Z2M:

• 361 KB in about 32 min. That's Z2M's default of 50-byte blocks, so it is slow but works.
• It survived the late duplicate blocks you get on a busy mesh.
• It rebooted into the new image, and the bootloader rollback was armed.

Not done yet: sleepy end devices (they need fast polling during the download), delta images, a ZHA quirk, nRF52/Zephyr, docs.

Credit to jabla, whose esphome-hiflow-zigbee zigbee_ota component (MIT) showed the way for the file parsing and the block resync.

Would the maintainers (luar123 tomaszduda23) be open to a PR along these lines? I'm happy to adapt it to how you'd like Zigbee OTA to fit in.

Update (2026-10-29)

• Signed images work. The esp32 options signed_ota_verification (ECDSA) and enable_ota_downgrade_protection work through the same OTA backend. They were tested on hardware: a signed upgrade installed and rebooted, and the device refused both an unsigned image and a signed older version. Each time it fired on_error and kept running the old firmware.
• Known issue in Zigbee2MQTT. Z2M shows a rejected image as installed. The cause is esp-zigbee-lib 2.0.5, which sends Upgrade End with SUCCESS whatever the application returns. I reported it upstream: OTA Upgrade client: Upgrade End Request is sent with SUCCESS even when the application rejects the image at CHECK (TZ-2819) espressif/esp-zigbee-sdk#936.
• The full test log, with every run, timing and log excerpt, is in the PR: [zigbee] OTA updates over Zigbee (ota: - platform: zigbee) mmornati/esphome#1

[Marco Mornati (mmornati)]

Thanks luar123! I tested each point on hardware today: a XIAO ESP32-C6 as a router, Zigbee2MQTT 2.14.2 on EmberZNet. I also read the Z2M (zigbee-herdsman) and zigpy code to check the behaviour.

ZHA/Z2M integration: OTA index
Agreed that a file location is enough as a first step. I served a Z2M-format index over HTTP and pointed Z2M at it with ota_update/check / ota_update/update and a url. Z2M fetched the index and the image by itself, picked the right entry, and the device installed and confirmed it. jabla showed the same index works for ZHA through extra_providers: [{type: z2m, url: ...}].

• Z2M re-reads the index on every check, and it already has an MQTT API: bridge/request/device/ota_update/check|update|schedule.
• zigpy caches provider indexes for 24 h (INDEX_EXPIRATION_TIME). zigpy already has OTA.invalidate_provider_caches() and check_all_devices_for_ota() (zigpy#1799), but neither ZHA nor HA core exposes them yet. So the feature request would be a "check for updates now" action in ZHA/HA that calls those. I can open it.
• One more thing for Z2M: without a url, Z2M only offers OTA for devices whose definition has ota: true. ESPHome devices will need that in their Z2M definition, through an external converter or a generic definition in zigbee-herdsman-converters.

manufacturerID = 0
It works:

• The OTA header carries 0x0000, the interview is fine, and ota_update/check answers "no update" correctly.
• A delta update with code 0 installed and was confirmed.
• With an index, Z2M only offers entries whose manufacturer code matches the one in the device's Query Next Image. An index with only a 0x131B entry offered nothing to the code-0 device. Neither Z2M nor zigpy treats 0 specially.
• Pushed directly with a file (no index), Z2M doesn't check the header code. A mismatched image is ignored by the esp-zigbee stack, and Z2M times out.

One caveat: in the manufacturer code list Z2M uses (SiLabs' manufacturers.xml), 0x0000 is "Matter Standard", and 0xFFF1–0xFFF4 are test vendor codes. So 0 works, but it isn't an unused code. Combined with an ESPHome-specific image_type scheme it should be safe in practice, but this is probably a call for the maintainers.

Delta upgrade: the version of the running image
Yes, we can get it:

• Z2M already knows it: installed_version comes from the device's Query Next Image.
• It can also be read directly with zigbee2mqtt/<device>/set {"read":{"cluster":"genOta","attributes":["currentFileVersion"],"options":{"direction":1}}}. The direction is needed because the device has the OTA cluster as a client. Tested, and it returns the running build's version. It doesn't update installed_version though.

But I think the index can handle "one build on several devices" without asking Z2M/ZHA at all. The build keeps the previous images, writes a delta for each recent base, and lists each delta with minFileVersion = maxFileVersion = its base, followed by the full image. Z2M takes the first matching entry. In my test it picked the delta for the device on the base version, and the full image is the fallback for any other version. zigpy honours min/max too (it sorts by version and specificity rather than order). jabla ran the same delta over ZHA.

Splitting into small PRs
Fully agree. My proposal:

1. Basic OTA only: router, full image (zlib), block resync, rollback through the existing IDF backend and safe_mode, and the firmware.zigbee.ota output.
2. Manufacturer code and image type in the main zigbee component, as you suggested.
3. Confirming a new image only after the coordinator is reached.
4. Index generation (written next to the builds, maybe served by the dashboard).
5. Delta images.
6. Sleepy end devices. These work now: fast poll at 250 ms during the download, and a query after the boot check, so a scheduled Z2M update gets through.

Signed images already work through ESPHome's existing signed_ota_verification. The only gap is the esp-zigbee-sdk bug where a refused image is still reported as success (espressif/esp-zigbee-sdk#936).

I can take care about the small PR fixes if you want. The fork I created is still there and we can use it for all these tests to reach a final pushable version of everything.

[Hedda]

Each entry needs fileVersion, fileSize, manufacturerCode, imageType, sha512 and url. ESPHome could write that index next to the builds and serve it, e.g. from the dashboard. Catch: zigpy reads an index once a day, so a new build shows up after that or after a ZHA reload. Z2M re-reads it on every update check.

For reference, you can use zigpy-cli to generate Zigbee OTA JSON index files compatible with zha -> https://github.com/zigpy/zigpy-cli

[Marco Mornati (mmornati)]

Each entry needs fileVersion, fileSize, manufacturerCode, imageType, sha512 and url. ESPHome could write that index next to the builds and serve it, e.g. from the dashboard. Catch: zigpy reads an index once a day, so a new build shows up after that or after a ZHA reload. Z2M re-reads it on every update check.

For reference, you can use zigpy-cli to generate Zigbee OTA JSON index files compatible with zha -> https://github.com/zigpy/zigpy-cli

Ah cool, I missed it. And as the format is the same between zha and z2m that should be a good way to go

[Hedda]

Each entry needs fileVersion, fileSize, manufacturerCode, imageType, sha512 and url. ESPHome could write that index next to the builds and serve it, e.g. from the dashboard. Catch: zigpy reads an index once a day, so a new build shows up after that or after a ZHA reload. Z2M re-reads it on every update check.

For reference, you can use zigpy-cli to generate Zigbee OTA JSON index files compatible with zha -> https://github.com/zigpy/zigpy-cli

Ah cool, I missed it. And as the format is the same between zha and z2m that should be a good way to go

Yes that format is compatible with Zigbee2MQTT too, see -> https://github.com/zigpy/zigpy/wiki/OTA-Information-for-Manufacturers

Also check out all these as well for reference (or at least have an AI do it for you) as believe that all linked have some relevant information:

• https://github.com/zigpy/zigpy/wiki/OTA-Information-for-Manufacturers

• https://github.com/zigpy/zigpy/wiki/OTA-Configuration

  • Old: https://github.com/zigpy/zigpy/wiki/OTA-Device-Firmware-Updates

• Launch of the zigpy-ota repo zigpy/zigpy-ota#2

• https://github.com/zigpy/zigpy-ota/blob/dev/README.md

  • https://github.com/zigpy/zigpy-ota/blob/dev/CLAUDE.md

[luar123]

But I think the index can handle "one build on several devices" without asking Z2M/ZHA at all.

if it is not needed even better. I was thinking: what happens if I create multiple image versions without uploading (e.g. just testing if it compiles). How does it know what image to use as a base for the delta (->should be the one actually running). And there could be multiple devices on the network running different versions.

manufacturerID = 0 should be fine then. Still need to clarify with maintainers if there is a better option.

[Hedda]

Maybe consider collaborating with DavidvtWout from the esphome-matter project as a similar solution will be likely be needed for Matter as for Zigbee:

• https://github.com/DavidvtWout/esphome-matter

  • Support matter ota DavidvtWout/esphome-matter#69

[Marco Mornati (mmornati)]

Yes I guess we can "merge" but the way of working is completely different. I don't have any matter device to be sure about the workflow to follow. This is the way Z2M can work: we are not breaking anything at all just working like any other zigbee device

How about matter? (I can move on the other topic and make some tests with the ESP I've)

[Hedda]

Marco Mornati (@mmornati) luar123 tomaszduda23 unless you already have a working releasionship with the Zigbee2MQTT devceliopers then if possible recommend first focus on getting it working with Home Assistant's native ZHA (Zigbee Home Automation) integration as that is not only the Zigbee Gateway which is built-into HA but that whole zigpy and zha Zigbee stack plus all its codebase and dependencies are owned/governed by the Open Home Foundation whom has its own developers (TheJulianJES and puddly) working on making that work as good as possible out-of-the-box (and ESPHome is also owned/governed by the Open Home Foundation). Maybe try reaching out to TheJulianJES (@TheJulianJES) who works on zigpy-ota?

• https://www.home-assistant.io/integrations/zha/#ota-updates-of-zigbee-device-firmware

  • https://github.com/zigpy/zigpy/wiki/OTA-Information-for-Manufacturers

    • https://github.com/zigpy/zigpy/wiki/OTA-Configuration

      • Launch of the zigpy-ota repo zigpy/zigpy-ota#2

        • READ FIRST: Submitting new OTAs zigpy/zigpy-ota#1

FYI, their zigpy-cli tool also has some specific functions/features related to OTA for Zigbee developers -> https://github.com/zigpy/zigpy-cli

PS: If you want then also suggest reaching out to the co-funders of Apollo Automation for hardware samples to use as reference (like for example the official ESPHome Starter Kit, the ESPHome C6 Board, or their DEV-2 ESP32-C6 Development Board) since many of Apollo Automation's devices are based on ESP32-C6 (which as you know has a Zigbee radio) and read that they have several times informally expressed interest in using Zigbee on ESP32 in future commercial devices. I bet they would be glad to donate some hardware samples to you with no strings attached if it has the potential to help this cause.

[Marco Mornati (mmornati)]

Thanks Hedda, good points. Agreed that ZHA should work out of the box, since it's the built-in integration and lives under the OHF like ESPHome.

The good news is that we don't need to choose between ZHA and Z2M: the same index works for both.

• jabla installed an update (including a delta) over ZHA from a Z2M-format index, with zha: zigpy_config: ota: extra_providers: [{type: z2m, url: ...}] (or type: z2m_local with index_file: for a local file).
• I did the same over Z2M with ota_update/check|update and a url.
• ZHA creates the update entity from the OTA client cluster alone, with no quirk needed.

About zigpy-cli: I tried it on our images. zigpy ota info parses both the full and the delta .ota files fine. That's a useful check for the build output, and I'd like to add it to our tests.
zigpy ota generate-index writes zigpy's own index format (firmwares, binary_url, sha3-256 checksum, read by type: zigpy_local / zigpy_remote). Z2M can't read that format. It also has no min/max current-file-version fields, which the delta images need so that each delta is offered only to devices on its base. So I think ESPHome should write the Z2M-format index itself next to each build. It's a few lines in the build, both ZHA and Z2M read it, and it can describe the deltas.

The one thing that would really help ZHA users is a "check for updates now". zigpy caches provider indexes for 24 h. It already has OTA.invalidate_provider_caches() and check_all_devices_for_ota() (zigpy#1799), but ZHA/HA don't expose them yet. TheJulianJES (@TheJulianJES), would you be open to a small ZHA/HA action that calls those? Maybe later, an ESPHome provider in zigpy that reads the index straight from the dashboard.

Thanks also for the Apollo tip. For now a XIAO ESP32-C6 covers router and sleepy end device tests, but reference hardware (especially an H2 or a battery board) would be welcome to improve what implemented 💪

[Hedda]

The one thing that would really help ZHA users is a "check for updates now". zigpy caches provider indexes for 24 h. It already has OTA.invalidate_provider_caches() and check_all_devices_for_ota() (zigpy#1799), but ZHA/HA don't expose them yet. TheJulianJES (TheJulianJES (@TheJulianJES)), would you be open to a small ZHA/HA action that calls those? Maybe later, an ESPHome provider in zigpy that reads the index straight from the dashboard.

Marco Mornati (@mmornati) while a hack, for development that could maybe be done via zha-toolkit custom component from HACS?

• https://github.com/mdeweerd/zha-toolkit

  • https://github.com/mdeweerd/zha-toolkit/blob/main/README.md#ota_notify---downloadtrigger-device-fw-update

ota_notify - Download/Trigger Device FW update

ota_notify helps you update the firmware of a zigbee device without
restarting Home Assistant. It can use the already available firmware
images, or download them using
Koenkk/zigbee-OTA's list and
resources. It also notifies the device that it should issue a request to be
updated. That launches the update process.

OTA is the acronym for "Over the Air" and we implicitly add "update" or
"upgrade".

You must have configured the
otau_directory.
This is where ZHA/zigpy looks for firmware images, and where downloaded
firmware images will be placed.

ota_notify will indicate to the device that an update is available, which
will trigger the device to request this update from the coordinator (in
this case zigpy).

Prior to notifying the device, ota_notify will request all image
providers to update the list of available images. By default, this is only
done on startup, so when you add a new image to your local directory or
when a new update is available from a third party, you'd have to restart
HA. But with ota_notify no restart is required.

For details on how to setup your images sources, check the
zigpy wiki section.
Also read about the possibilities to enable logging, and that some devices
require to be re-associated.

To trigger the OTA update, use ota_notify instead. The debug log is
useful to check the update progress or indication that no update is
available.
When the update starts, be patient: it can take a while.

action: zha_toolkit.ota_notify
data:
  # Reference of the device that should be notified about an update.
  # Using one of the entity/sensor names is so much easier !
  ieee: sensor.lixee_zlinky_tic_00000000_electrical_measurement
  # Optional, when true download images from info at https://github.com/Koenkk/zigbee-OTA
  download: true
  # Optional, directory to write OTA files to (default: same as ZHA configuration)
  path: /config/zb_ota

[Marco Mornati (mmornati)]

On my side I can help on z2m. I moved away from zha mainly due to the network size that was creating me lot of problems. Z2M is more stable on my side.

I can help testing on zha with a different device: rpi with another zigbee sub device if you want 🤟