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>