OTA Information for Manufacturers

Manufacturer OTA Firmware Update Support

Zigpy is capable of providing OTA updates to devices on the network. Currently, this is done by periodically downloading firmware metadata from a manufacturer-hosted static JSON endpoint in response to device OTA:QueryNextImageCommand commands.

Index file format

We expect the format of the JSON response to match this schema:

[
    {
        "binary_url": "https://example.org/path/to/firmware1.bin",
        "file_version": 4294967295,
        "image_type": 1234,
        "manufacturer_id": 5678,
        "changelog": "Text explaining what changed in this release",
        "checksum": "sha3-256:<hash-of-contents-encoded-as-hex>",

        // If your OTA file is not restricted to certain hardware versions, omit these keys
        "min_hardware_version": 1,
        "max_hardware_version": 3
    },
    {
        "binary_url": "https://example.org/path/to/firmware2.bin",
        ...

The keys in the firmware schema correspond to the metadata contained in the Zigbee OTA header, which allows us to quickly match OTA images to devices based on the fields in their sent OTA:QueryNextImageCommand (cluster 0x0019, command 0x01). The OTA files themselves are downloaded on-demand.

Note: ensure the OTA file's file_version (and thus the metadata's file_version) is always greater than the device's current_file_version! Otherwise, the update will be considered a downgrade and ignored.

Creation

To help programatically generate this JSON metadata, we've created an example script to create this JSON structure from a list of .ota files:

$ pip install zigpy-cli
$ zigpy ota generate-index --ota-url-root="https://example.org/fw" path/to/firmwares/**/*.ota

Make sure your OTA files are properly parsed by this tool, as it parses them using zigpy. Proprietary OTA wrappers will either need to be stripped, or the OTA parsing in zigpy updated to account for the wrapper.

Testing

Before an OTA provider is included in zigpy, test your OTA files with ZHA by placing them into a directory specified in your Home Assistant configuration.yaml file:

logger:
  default: info
  logs:
    homeassistant.core: debug
    homeassistant.components.zha: debug
    zigpy: debug
    bellows: debug
    zigpy_znp: debug
    zigpy_deconz: debug
    zhaquirks: debug

zha:
  zigpy_config:
    ota:
      otau_directory: /path/to/.homeassistant/zigpy_ota/

After ZHA is reloaded and is aware of the OTA file, you will then be able to send an image notification command to the device to ask it to check for new firmware.

This can be done from ZHA's cluster interface with the following parameters (set query_jitter to 100):

Zigpy will begin the OTA upgrade and log the progress:

2023-02-14 14:44:07.237 DEBUG (MainThread) [zigpy.zcl] [0x9253:1:0x0019] Received command 0x01 (TSN 59): QueryNextImageCommand(field_control=<FieldControl.0: 0>, manufacturer_code=4659, image_type=54185, current_file_version=21)
2023-02-14 14:44:07.244 DEBUG (MainThread) [zigpy.zcl] [0x9253:1:0x0019] OTA query_next_image handler for 'Third Reality, Inc 3RTHS24BZ': field_control=FieldControl.0, manufacturer_id=4659, image_type=54185, current_file_version=21, hardware_version=None, model='3RTHS24BZ'
2023-02-14 14:44:07.588 DEBUG (MainThread) [zigpy.ota.provider] ThirdReality: Finished downloading firmware update list
2023-02-14 14:44:07.591 DEBUG (MainThread) [zigpy.ota.provider] Downloading https://tr-zha.s3.amazonaws.com/firmwares/TRTL_ThermalSensor_PROD_OTA_V21_1.00.21.ota for ImageKey(manufacturer_id=4659, image_type=54185)
2023-02-14 14:44:07.947 DEBUG (MainThread) [zigpy.ota.provider] Finished downloading from https://tr-zha.s3.amazonaws.com/firmwares/TRTL_ThermalSensor_PROD_OTA_V21_1.00.21.ota for ImageKey(manufacturer_id=4659, image_type=54185) ver 1.00.21
2023-02-14 14:44:07.949 DEBUG (MainThread) [zigpy.zcl] [0x9253:1:0x0019] OTA image version: 33, size: 124946. Update needed: True
2023-02-14 14:44:07.949 INFO (MainThread) [zigpy.zcl] [0x9253:1:0x0019] Updating: Third Reality, Inc 3RTHS24BZ

...

2023-02-14 14:52:07.671 DEBUG (MainThread) [zigpy.zcl] [0x9253:1:0x0019] Received command 0x03 (TSN 232): ImageBlockCommand(field_control=<FieldControl.MinimumBlockPeriod: 2>, manufacturer_code=4659, image_type=54185, file_version=33, file_offset=57280, maximum_data_size=48, minimum_block_period=0)
2023-02-14 14:52:07.678 DEBUG (MainThread) [zigpy.zcl] [0x9253:1:0x0019] OTA upgrade progress: 45.8