feat: improve OTA by Nerivec · Pull Request #30566 · Koenkk/zigbee2mqtt

Nerivec · 2026-01-08T22:20:49Z

Design changes

[ZH/ZHC/Z2M/WindFront] OTA refactor zigbee-herdsman#1608
requires feat!: OTA refactor zigbee-herdsman#1612
Update API to match new features
Merge Zigbee/MQTT triggered update logic into single function for consistency
Rework OTA support check (from definition) to allow custom file/URL to always go through (check/update/schedule)
Add from/to file versions to update response payload to avoid weirdness with swBuildId/dateCode often unavailable
Add latest_source (URL/filesystem), latest_release_notes to OTA state payload
Allow passing data settings (timings/sizes) per request to override settings
Tweak the published OTA state based on return of update (clear available if update returned "no image")
Add ability to schedule with custom URL/filesystem
Add ability to send hex-formatted image to Z2M which will be automatically written to data dir (for use with update or schedule)
- Should allow using plain file over MQTT/WS assuming properly formatted upstream (e.g. frontend)
- With limitation that MQTT/WS must allow payloads of sufficient size (though most cases should be <1MB)

Due to MQTT request payloads still allowing simple string for OTA, it duplicates the code a bit for now (marked deprecated for 3.0).

@Koenkk

I'm thinking with this one, we might want to bump the settings version so we can trigger a migration to remove all cached OTA states?
How do you prefer to deal with null source/release_notes in #getEntityPublishPayload? I'm hesitating between null or undefined so it's taken out on stringify.

TODO:

remove restart required from OTA data settings in schema
change hex writes to ota subdir of data dir
new tests for full coverage
fix: cleanup OTA (moved to ZH) zigbee-herdsman-converters#11259
fix: docs for OTA refactor zigbee2mqtt.io#4760

Koenkk · 2026-01-10T09:37:27Z

I'm thinking with this one, we might want to bump the settings version so we can trigger a migration to remove all cached OTA states?

Agree

How do you prefer to deal with null source/release_notes in #getEntityPublishPayload? I'm hesitating between null or undefined so it's taken out on stringify.

I would propose to go for null (such that the attribute is always in the published payload)

lib/types/api.ts

lib/extension/otaUpdate.ts

Nerivec · 2026-01-16T03:02:48Z

@Koenkk can you take a closer look now that it's fully tested? In particular:

Left a few TODOs, not all quite related to this specifically.
I modified reInterview (previously only used if triggered by bridge request) to behave more like if it had been triggered from ZH Controller. Should provide better feedback and align the logic?
Image files as hex written to ota subdir of data dir, should be a bit cleaner. Files are auto-removed on unschedule, but not sure if we should also auto-remove on update end (tracing?)?

Note: we'll have to rebuild the all-settings page in docs for this one.

Koenkk · 2026-01-23T19:48:37Z

lib/extension/configure.ts


            await this.configure(data.device, "zigbee_event");
        });
+        // TODO: this is triggering for any `data.status`, but should only for `successful`? (relies on `device.definition?` early-return?)


I think that even when a device interview fails, it's worth configuring it as it might be due to a non crucial error and then the configure makes the device at least partially working.

Koenkk · 2026-01-23T19:49:45Z

lib/extension/homeassistant.ts

        this.eventBus.onGroupMembersChanged(this, this.onGroupMembersChanged);
        this.eventBus.onDeviceAnnounce(this, this.onZigbeeEvent);
        this.eventBus.onDeviceJoined(this, this.onZigbeeEvent);
+        // TODO: this is triggering for any `data.status`?


I think it makes sense to do this always, similar to https://github.com/Koenkk/zigbee2mqtt/pull/30566/changes#r2722613265 the error might be not critical and maybe all info needed to identify the device has been received, thus it can discovered.

Koenkk · 2026-01-23T19:50:22Z

lib/extension/onEvent.ts

        });
        this.eventBus.onDeviceInterview(this, async (data) => {
+            // TODO: this is triggering for any `data.status`, any use outside `successful`?
+            //       ZHC definition would skip from `device.definition?` but OnEvent from ZHC index wouldn't => triple triggering?


Interview failed doesn't (always) mean there is no definition, so I think this is fine.

The problem I was thinking for this and all above is the fact status is: "started" | "successful" | "failed". So it always triggers twice?
We can take a closer look in a separate PR though, just though it was worth a TODO comment when I passed by these 😁

It depends a bit wether we also want to trigger the onEvent on started, I guess not so only on failed or successful makes sense.

Yes, I think it's worth a look in a follow-up PR, same for the other 2 in HA and configure extensions, should de-dupe calls a bit.

lib/extension/otaUpdate.ts

lib/types/api.ts

Koenkk · 2026-01-23T20:00:59Z

Left a few TODOs, not all quite related to this specifically.

Replied!

I modified reInterview (previously only used if triggered by bridge request) to behave more like if it had been triggered from ZH Controller. Should provide better feedback and align the logic?

Look good

Image files as hex written to ota subdir of data dir, should be a bit cleaner. Files are auto-removed on unschedule, but not sure if we should also auto-remove on update end (tracing?)?

Let's keep them for now, these OTAs are fairly small so shouldn't be a problem.

Nerivec · 2026-01-24T00:36:29Z

lib/extension/otaUpdate.ts

+            device.zh.save();
+        }
+
+        await device.reInterview(this.eventBus);


I'm thinking we might want to decouple this from the update process? Currently it would count as an OTA failure (response/logs) if the interview fails. Although, we probably should avoid triggering this immediately in the background, because the early-return would also trigger the read swBuildId/dateCode (lots of requests at once).

@Koenkk what do you think?

dc155b4
I think that's about as best as we can do?

It should definitely not count towards an OTA failure indeed, I'm not sure if 5 sec is too long, maybe battery powered devices will fall asleep?

We might need to adjust this yes. I figure the call for read sw/date might it keep it awake long enough. Always tricky this sort of things we ZED anyway, probably, if it has to fail due to quick-sleep, it will fail the sw/date read... 😅

Bjk8kds · 2026-02-01T22:56:47Z

Thank you so much!
Now it is easier to update custom firmware such as ZigbeeTlc @pvvx, etc.

Co-authored-by: Koen Kanters <koenkanters94@gmail.com>

Nerivec force-pushed the ota-refactor branch 2 times, most recently from f87f504 to e2af075 Compare January 8, 2026 22:23

Koenkk reviewed Jan 10, 2026

View reviewed changes

lib/types/api.ts Outdated Show resolved Hide resolved

Koenkk approved these changes Jan 10, 2026

View reviewed changes

Nerivec force-pushed the ota-refactor branch from e5d6f5a to 1e8c356 Compare January 12, 2026 21:44

Nerivec commented Jan 13, 2026

View reviewed changes

lib/extension/otaUpdate.ts Show resolved Hide resolved

Nerivec force-pushed the ota-refactor branch from 1e8c356 to c845091 Compare January 15, 2026 23:45

Nerivec force-pushed the ota-refactor branch from 40df421 to d5806b3 Compare January 20, 2026 21:33

Koenkk reviewed Jan 23, 2026

View reviewed changes

lib/extension/otaUpdate.ts Outdated Show resolved Hide resolved

Koenkk reviewed Jan 23, 2026

View reviewed changes

lib/types/api.ts Show resolved Hide resolved

Koenkk approved these changes Jan 23, 2026

View reviewed changes

Nerivec added 12 commits January 23, 2026 23:44

feat: improve OTA

f767f2f

fix: use object for hex

cf1fd70

fix: add OTA cache reset migration

f9c7b75

fix: remove requiresRestart from OTA data settings

6aa0fe0

fix: force re-configure after re-interview

a792c7a

fix: use ota subdir of data dir for hex saving

dc37b69

fix: type import

9e60626

fix: add missing migration test coverage

cd3cbb6

fix: test coverage and code fixes/cleanup

b641f73

fix: exclude ota data subdir from backups

4cdad1f

fix: retrieve ota data settings on-site, remove class var

1535481

fix: ensure requests typed against null

eb98d7a

Nerivec force-pushed the ota-refactor branch from df90e2a to eb98d7a Compare January 23, 2026 22:44

fix: reset updating state to idle after restart

27bb8aa

Nerivec commented Jan 24, 2026

View reviewed changes

Nerivec mentioned this pull request Jan 24, 2026

fix: docs for OTA refactor Koenkk/zigbee2mqtt.io#4760

Merged

fix: decouple interview from OTA response

dc155b4

Nerivec marked this pull request as ready for review January 24, 2026 20:22

Merge branch 'dev' into ota-refactor

5d40f94

Koenkk merged commit dd1c449 into dev Jan 24, 2026
14 checks passed

Koenkk deleted the ota-refactor branch January 24, 2026 20:27

Koenkk mentioned this pull request Jan 24, 2026

chore(dev): release 2.8.0 #30420

Merged

Nerivec mentioned this pull request Jan 26, 2026

New OTA Koenkk/zigbee-herdsman#1627

Closed

f0b04707 mentioned this pull request Feb 2, 2026

Some Ubisys devices moved to ota.zigbeeOTA and no longer pick up updates Koenkk/zigbee-OTA#329

Closed

Koenkk added a commit that referenced this pull request Feb 3, 2026

feat: Improve OTA (#30566)

a585d11

Co-authored-by: Koen Kanters <koenkanters94@gmail.com>

Uh oh!

Conversation

Nerivec commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Design changes

Uh oh!

Koenkk commented Jan 10, 2026

Uh oh!

Uh oh!

Uh oh!

Nerivec commented Jan 16, 2026

Uh oh!

Koenkk Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Koenkk Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Koenkk Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Nerivec Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Koenkk Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

Nerivec Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Koenkk commented Jan 23, 2026

Uh oh!

Nerivec Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Koenkk Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

Nerivec Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Bjk8kds commented Feb 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Nerivec commented Jan 8, 2026 •

edited

Loading

Nerivec Jan 23, 2026 •

edited

Loading

Nerivec Jan 24, 2026 •

edited

Loading

Nerivec Jan 24, 2026 •

edited

Loading