Universal Tuya docsHomeSupported devicesRequest a deviceFAQChangelogArchitectureKnowledge baseCreditsSourcesContributing

OTA audit (P2932, 2026-10-21)

Scope: master, stable-v5 and bastien-home. lib/ota/ is the same on the three branches except one case-insensitive lookup (ciGet) that is on master only.

How OTA really works on Homey

Source: Homey SDK, "Zigbee Firmware Updates" (https://apps.developer.homey.app/wireless/zigbee/zigbee-firmware-updates), read 21/10.

Consequence for the asked items:

ItemOwner on HomeyStatus
imageNotify / queryNextImage / imageBlock / imagePage / upgradeEndHomey firmwareNothing for the app to implement. The app-side code that sent queryNextImageRequest TO the device (wrong direction) is removed, see below
Bounded block size, page requests, retries with backoffHomey firmware (device-driven block size)Not implementable in the app
Resume after sleep (battery devices)Homey + wakeInstructionAdded on water_leak_sensor. The two TRVs already had it
Progress and flowsHomey Device Updates screenExisting ota_update_available trigger and ota_has_update condition only cover discovery. Homey has no progress event for apps
Never forcedHomey (user starts it)The app only notifies, with a 6 h discovery that lists and never flashes

Gaps found and fixed (master, P2932)

  1. OTAUpdateManager.performUpdate downloaded the image, sent a notification that the firmware update had started, then called queryNextImageRequest on the device's own otaUpdate cluster. That is a client→server command, sent in the wrong direction. It now returns OTA_USE_HOMEY_DEVICE_UPDATES with the shipped version when the driver ships a matching image, and OTA_NOT_BUNDLED otherwise. It sends nothing to the device and no false "started" notice.
  2. findBundledNativeUpdate() is new. It applies the SDK selection rules: exact manufacturerName/productId, same manufacturerCode and imageType, min/max file version, strictly newer.
  3. fetchAndVerifyImage() is new. It fetches an indexed image on demand with the index SHA512, then checks the OTA header: magic 0x0BEEF11E, manufacturer code, image type and a newer version. It is bounded by OTARepository (HTTPS only, 2 MB, 60 s) and is for diagnostics only, never for flashing.
  4. Tuya MCU OTA over EF00: 0x12 mcuOtaNotify, 0x13 mcuOtaBlockDataRequest, 0x14 mcuOtaBlockDataResponse and 0x15 mcuOtaResult. The layout comes from Koenkk/zigbee-herdsman cluster.ts (manuSpecificTuya). Before, 0x13/0x15 reached the "unknown command → parse as DP" path of TuyaBoundCluster and could show up as phantom DP values. They are now recognised by lib/ota/TuyaMcuOtaFrames.js, logged and passed to _onRawFrame, and never DP-parsed. The app does not serve MCU images, because there is no public Tuya MCU image index.
  5. 0x0B: in the Tuya serial (UART) MCU protocol, 0x0A starts an MCU OTA and 0x0B transfers a package, with an MTU of 256/512/1024 chosen by the MCU (Tuya developer docs "MCU OTA Update", MCU standard protocol). That traffic stays between the Tuya radio module and the MCU. It is not an EF00 Zigbee command, and zigbee-herdsman has no 0x0B on EF00. The otaQuery label in TuyaZigbeeProtocolProfile.js stays a lead (unsourced). Its existing handling is unchanged.
  6. Manifests:
  7. thermostatic_radiator_valve listed only _tze200_ckud7u2l. The Koenkk index and the devices use _TZE200_ckud7u2l, which is now added. Homey matches manufacturerName exactly, so the update was probably never offered.
  8. water_leak_sensor (battery, _TZE284_2se8efxh) had no wakeInstruction. It now has one in en/fr/nl.
  9. scripts/maintenance/ota-images.js (--audit, --fetch, --index, --json) checks every listed image: present, size, integrity, OTA header against the manifest, the Koenkk index entry (version/code/type) and that our manufacturerName is inside the index target. It also lists bins that no manifest references. --fetch downloads missing images from the index URL and writes them only after SHA512 + integrity + header pass. Tested by deleting a bin and re-fetching it: byte-identical.

Audit result 21/10: 9/9 listed images OK against the Koenkk index (985 entries). 1 orphan: drivers/plug_smart/assets/firmware/1715138033-tk_common_link_lp_OTA_1.0.13.bin (227 KB), referenced by no manifest. Not deleted, see below.

Package size: proposal (not done here; package size and .github/ belong to the other worker)

Sources consulted (credited, no code copied)

← Knowledge base index · source