> For the complete documentation index, see [llms.txt](https://apps.developer.homey.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apps.developer.homey.app/wireless/zigbee/zigbee-firmware-updates.md). # Zigbee Firmware Updates Homey supports the Zigbee Over-the-Air Upgrade cluster. With this cluster it is possible for Homey to update the firmware that is running on Zigbee devices. Your app can provide firmware files, and Homey takes care of installing the firmware to the device. {% hint style="warning" %} Zigbee firmware updates are supported since Homey firmware v13.2.0, and is available for Homey Pro (Early 2023, 2026, mini), Homey Self-Hosted Server, and Homey Cloud. You need at least Homey Mobile App v9.10.0 or higher in order to start updates. {% endhint %} ## Getting Started You can add firmware updates to your drivers. To do this, you'll need to gather the firmware files for your devices and create a `/drivers//driver.firmware.compose.json` file. The `driver.firmware.compose.json` file contains metadata for Homey to be able to select the correct update for your devices. For more information on the Zigbee Over-the-Air Upgrade cluster and process, read chapter 11 of the [Zigbee Cluster Specification](https://etc.athom.com/zigbee_cluster_specification.pdf). {% hint style="info" %} The `homey app driver firmware` Homey CLI command will take you through creating or updating the `driver.firmware.compose.json` file. (Requires `homey` v4.3.0 or higher.) {% endhint %} ### File Structure The `driver.firmware.compose.json` contains the following fields: * `updates`: A list of all firmware updates for the devices of this driver. * `wakeInstruction`: A description of how a Sleepy End Device (e.g battery-powered devices) can be made active by the user to start the firmware update. This field is not required for non-sleepy devices (takes a [Translation Object](/the-basics/app/internationalization.md)). #### Updates Each item in `updates` describes a firmware update for specific Zigbee devices. Every update contains the following fields: * `changelog`: A brief description of the changes in this update (takes a [Translation Object](/the-basics/app/internationalization.md)). * `device`: An object with the `manufacturerName` and `productId` combination that identifies the target device(s) for this update. * A driver can target multiple devices (see [Zigbee Manifest](/wireless/zigbee.md#manifest)). This field allows making a firmware update only available for a specific subset of those devices. * `files`: A list of firmware update files included in this update. * In most cases, you'll only have a single file for your update. #### Update Files Each entry in `updates[].files` describes one firmware file. The following metadata fields are required for each file: * `fileVersion`: The version of the firmware file. Higher values represent newer firmware. *(Numeric, as defined in the Zigbee cluster specification.)* * `imageType`: A manufacturer-specific type that identifies the firmware image. *(Numeric, as defined in the Zigbee cluster specification.)* * `manufacturerCode`: The assigned manufacturer code of the vendor. *(Numeric, as defined in the Zigbee cluster specification.)* * `size`: The file size in bytes. * `name`: The file name. The file itself must be stored in `/drivers//assets/firmware/`. * `integrity`: A hash of the file in the format `:`. * The following hash types are supported: `sha256`, `sha384`, `sha512`, `sha512-256`, `sha3-256`, `sha3-384`, `sha3-512`, `blake2b512`, `blake2s256`. {% hint style="info" %} The `homey app driver firmware` command will automatically fill in these fields for you, and copy the firmware file to the correct location. {% endhint %} You can optionally add the following fields to limit when a firmware update is available: * `minFileVersion`: The minimum file version the device must currently report. *(Numeric)* * `maxFileVersion`: The maximum file version the device must currently report. *(Numeric)* * `minHardwareVersion`: The minimum hardware version the device must report. *(Numeric)* * `maxHardwareVersion`: The maximum hardware version the device must report. *(Numeric)* {% hint style="info" %} When you upload your Homey App, the firmware files are stored separately from your App. Only when Homey starts installing an update for a device, it will download the required files. {% endhint %} ### Example Putting everything together, a `driver.firmware.compose.json` file with a single update will look like this: {% code title="/driver/\/driver.firmware.compose.json" %} ```json { "wakeInstruction": { "en": "Hold the internal button for three seconds." }, "updates": [ { "changelog": { "en": "- Fixes issue X\n- Adds feature Y\n- Deprecates feature Z" }, "device": { "manufacturerName": "Company XYZ", "productId": ["AwesomeSensor", "AwesomeSensor Rev B"] }, "files": [ { "fileVersion": 1234, "imageType": 1000, "manufacturerCode": 5678, "size": 262144, "name": "AwesomeSensor_v1.3.4.bin", "integrity": "sha256:dac89981aeb5352a8ddce9fbb5ab3ad5bff88d17e2f7937cc90947301ccfedd2" } ] } ] } ``` {% endcode %} ### Firmware Files Homey Apps are responsible for delivering the correct firmware files to the appropriate devices. Before shipping a firmware update in your Homey App, ensure the following: * **Device targeting:** Verify that each firmware file is mapped to the correct device(s). Delivering a firmware file to an incompatible device can cause irreversible damage or render it unresponsive. * **End-to-end testing:** Test the full update flow on the intended physical hardware. Confirm that Homey can correctly initiate, transfer, and complete the firmware update process. * **Validation before release:** Do not add a firmware update to your app until both of the above have been verified. Untested firmware updates should never reach end users. ## Update Selection During the Zigbee OTA progress, a device will send a `queryNextImageRequest` command to Homey. In this command, the device provides Homey with the following information: * `manufacturerCode`: The device's assigned manufacturer code * `imageType`: Manufacturer-specific code * `fileVersion`: The device's current version of the firmware * (Optional) `hardwareVersion`: The device's current hardware version Homey will select the firmware for your device based on the following: 1. The `updates[].device` field, must match the device's reported manufacturer name and product id. 2. One of the files in an `update` should match the device's current reported `manufacturerCode` and `imageType`. 3. If provided, the `min/maxFileVersion` and `min/maxHardwareVersion` should match the device's `fileVersion` and `hardwareVersion`. 4. The `fileVersion` of the matched file should be higher than the current reported `fileVersion` of the device. If multiple updates are found for the device, the update with the highest `fileVersion` will be selected. #### Multiple Firmware Files Some devices might require multiple firmware files for a single update (e.g. when it also needs to update the firmware of another chip in the device). The device will do this by sending another `queryNextImageRequest` with a different `manufacturerCode`, `imageType` and `fileVersion`. Put secondary firmware upgrade files in the same `updates[].files` list to allow continuing the update without requiring the user to start the update. ## Update Failures Firmware updates can fail. Homey considers an update failed in the following cases: * **Explicit abort:** The device reports an error status during image transfer, actively aborting the update. * **Stalled transfer:** The device stops requesting firmware chunks before the transfer is complete. * **No reconnection:** The device fails to rejoin the Zigbee network within the expected timeframe after a file has been fully transferred. In all failure cases, the user will be notified via the firmware update screen and can retry the installation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://apps.developer.homey.app/wireless/zigbee/zigbee-firmware-updates.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.