ZigBee OTA Upgrade Records¶
These records either directly correspond or are related to definitions in the Zigbee OTA Upgrade Cluster Specification, and are used primarily by methods in the Zigbee OTA Upgrade Cluster Interface.
OTA_Header¶
ZCL OTA firmware images begin with a header describing the image contents.
Parameters
| Parameter | Type | Description |
|---|---|---|
| header_version* | int | 16-bit version (major/minor) of the OTA Header for compatibility purposes. Defaults to 0x0100. |
| field_control* | int | 16-bit bitmask describing optional elements included in the OTA header. If bit 0 is set include security_credential_version. If bit 1 is set include upgrade_file_destination for a Device Specific File. If bit 2 is set include min_hardware_version and max_hardware_version to match supported devices the image can be installed on. Defaults to 0x0 (no optional fields). |
| manufacturer_id* | int | 16-bit manufacturer identifier used to match supported devices. Defaults to 0xFFFF (match all). |
| image_type* | int | 16-bit image type. Defaults to 0xFFFF (match all). |
| file_version* | int | 32-bit integer representing the file version. Can be in the recommended format (8-bit app release, 8-bit app build, 8 bit stack release, 8-bit stack build), simple increasing version, or an unsupported version format. If in an unsupported version format the OTA Cluster will not be able to compare file versions. Defaults to 0x0000. |
| zigbee_stack_version* | int | 8-bit identifier of the zigbee stack version. Defaults to 0x02 for ZigBee Pro. |
| header_string* | int | 32-byte string used by each manufacturer as they see fit but recommended to be human readable. |
| total_image_size* | int | 32-bit unsigned integer representing the total image size in bytes. The image size must include the header, all sub-element tags, and the sub-elements themselves. If desired a dummy value can be used when constructing the header and total_image_size calculated later based on header_length. Defaults to 0x0. |
| security_credential_version* | int | 8-bit identifier of the Security Credential Version. Defaults to not included. |
| upgrade_file_destination* | MAC | 64-bit extended address of the device to which this image is specific. Defaults to not include, image is available to all devices. |
| minimum_hardware_version* | int | 8-bit integer representing the earliest hardware platorm this image can be used on. |
| maximum_hardware_version* | int | 8-bit integer representing the latest hardware platorm this image can be used on. |
Example
<record type="OTA_Header">
<header_version type="int">0x100</header_version>
<field_control type="int">0x0</field_control>
<manufacturer_id type="int">0xFFFF</manufacturer_id>
<image_type type="int">0xFFFF</image_type>
<file_version type="int">0x0</file_version>
<zigbee_stack_version type="int">0x2</zigbee_stack_version>
<header_string type="string">********************************</header_string>
<total_image_size type="int">0x6D</total_image_size>
<header_length type="int">0x38</header_length>
</record>
OTA_Device¶
Indicates known status of a device currently downloading a firmware image from a local server.
Parameters
| Parameter | Type | Description |
|---|---|---|
| addr_extended | MAC | 64-bit version extended address of the device. |
| endpoint_id | int | 8-bit identifier of the endpoint on the device downloading the firmware image. |
| status* | int | 16-bit integer indicating last known status of the device. Defaults to 0x0 (normal). |
| bytes_downloaded* | int | Total bytes of data sent to and acknowledged by the device. Will over-count if the device overlaps or duplicates requests. |
Example
<record type="OTA_Device">
<status type="int">0x1</status>
<addr_extended type="MAC">00:11:22:33:44:55:66:77</addr_extended>
<endpoint_id type="int">0xA</endpoint_id>
<bytes_downloaded type="int">0x1234</bytes_downloaded>
</record>
Upgrade_End_Request_payload¶
Sent by an OTA client when download completes successfully and permission is needed to install. May also be sent when the client wishes to abort the download or otherwise encounters an error. The image_type, file_version, and manufacturer_id parameters indicate which image the request is for.
Parameters
| Parameter | Type | Description |
|---|---|---|
| status* | int | 8-bit status of the downloaded image. Default to 0 (success). |
| image_type | int | 16-bit image type. |
| file_version | int | 32-bit integer representing the file version. |
| manufacturer_id | int | 16-bit manufacturer identifier. |
Example
<record type="Upgrade_End_Request_payload">
<status type="int">0x0</status>
<image_type type="int">0xABCD</image_type>
<manufacturer_id type="int">0x1234</manufacturer_id>
<file_version type="int">0x1</file_version>
</record>