Zigbee Firmware Updates

Allow Homey to update the firmware of Zigbee devices using the Zigbee Over-the-Air Upgrade Cluster.

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.

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.

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_id>/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.

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.)

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).

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).

• 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). 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/<driver_id>/assets/firmware/<file name>.

• integrity: A hash of the file in the format <hash_name>:<hex_encoded_hash>.

  • The following hash types are supported: sha256, sha384, sha512, sha512-256, sha3-256, sha3-384, sha3-512, blake2b512, blake2s256.

The homey app driver firmware command will automatically fill in these fields for you, and copy the firmware file to the correct location.

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)

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.

Example

Putting everything together, a driver.firmware.compose.json file with a single update will look like this:

/driver/<driver_id>/driver.firmware.compose.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"
        }
      ]
    }
  ]
}

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.