5.2.6.3.8. ZCL OTA Upgrade Cluster

This section provides the OTA upgrade cluster implementations in ZCL of ESP Zigbee Core.

5.2.6.3.8.1. OTA Upgrade Cluster

5.2.6.3.8.1.1. Header File

5.2.6.3.8.1.2. Functions

ezb_err_t ezb_zcl_ota_upgrade_cluster_desc_add_attr(ezb_zcl_cluster_desc_t cluster_desc, uint16_t attr_id, const void *value)

Add an attribute to an ota_upgrade cluster descriptor.

Parameters:

  • cluster_desc -- [in] The ota_upgrade cluster descriptor.

  • attr_id -- [in] The identifier of the attribute to be added to cluster_desc.

  • value -- [in] The pointer to the initial value of the attribute.

Returns:

Error code.

ezb_zcl_cluster_desc_t ezb_zcl_ota_upgrade_create_cluster_desc(const void *cluster_cfg, uint8_t role_mask)

Create an ota_upgrade cluster descriptor.

Parameters:

  • cluster_cfg -- [in] The pointer to the ota_upgrade cluster configuration structure. Use ezb_zcl_ota_upgrade_cluster_server_config_t for EZB_ZCL_CLUSTER_SERVER, use ezb_zcl_ota_upgrade_cluster_client_config_t for EZB_ZCL_CLUSTER_CLIENT, or use NULL for default configuration of the stack based on the role_mask.

  • role_mask -- [in] The role of the cluster to create.

Returns:

Created cluster descriptor.

void ezb_zcl_ota_upgrade_cluster_client_init(uint8_t ep_id)

Initialize the OTAUpgrade cluster client role for a given endpoint.

Parameters:

ep_id -- [in] The identifier of the endpoint hosting the cluster that needs initialization.

void ezb_zcl_ota_upgrade_cluster_server_init(uint8_t ep_id)

Initialize the OTAUpgrade cluster server role for a given endpoint.

Parameters:

ep_id -- [in] The identifier of the endpoint hosting the cluster that needs de-initialization.

5.2.6.3.8.1.3. Structures

struct ezb_zcl_ota_upgrade_cluster_server_config_s

Configuration mandatory attributes for the OTAUpgrade server cluster.

Public Members

uint8_t ota_upgrade_file_table_size

Configurable mandatory OTAUpgradeFileTableSize attribute

struct ezb_zcl_ota_upgrade_cluster_client_config_s

Configuration mandatory attributes for the OTAUpgrade client cluster.

Public Members

uint64_t upgrade_server_id

Configurable mandatory UpgradeServerID attribute

uint32_t file_offset

Configurable mandatory FileOffset attribute

uint8_t image_upgrade_status

Configurable mandatory ImageUpgradeStatus attribute

uint16_t manufacturer_id

Configurable mandatory ManufacturerID attribute

uint16_t image_type_id

Configurable mandatory ImageTypeID attribute

5.2.6.3.8.1.4. Macros

EZB_ZCL_OTA_UPGRADE_CLUSTER_REVISION

Cluster Revision of the ota_upgrade cluster implementation.

EZB_ZCL_OTA_UPGRADE_OTA_UPGRADE_FILE_TABLE_SIZE_DEFAULT_VALUE

Default value of OTAUpgradeFileTableSize in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_UPGRADE_SERVER_ID_DEFAULT_VALUE

Default value of UpgradeServerID in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_FILE_OFFSET_DEFAULT_VALUE

Default value of FileOffset in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_CURRENT_FILE_VERSION_DEFAULT_VALUE

Default value of CurrentFileVersion in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_CURRENT_ZIGBEE_STACK_VERSION_DEFAULT_VALUE

Default value of CurrentZigbeeStackVersion in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_DOWNLOADED_FILE_VERSION_DEFAULT_VALUE

Default value of DownloadedFileVersion in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_DOWNLOADED_ZIGBEE_STACK_VERSION_DEFAULT_VALUE

Default value of DownloadedZigbeeStackVersion in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_IMAGE_UPGRADE_STATUS_DEFAULT_VALUE

Default value of ImageUpgradeStatus in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_MINIMUM_BLOCK_PERIOD_DEFAULT_VALUE

Default value of MinimumBlockPeriod in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_MINIMUM_BLOCK_PERIOD_MIN_VALUE

Minimum value of MinimumBlockPeriod in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_MINIMUM_BLOCK_PERIOD_MAX_VALUE

Maximum value of MinimumBlockPeriod in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_UPGRADE_ACTIVATION_POLICY_DEFAULT_VALUE

Default value of UpgradeActivationPolicy in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_UPGRADE_ACTIVATION_POLICY_MIN_VALUE

Minimum value of UpgradeActivationPolicy in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_UPGRADE_ACTIVATION_POLICY_MAX_VALUE

Maximum value of UpgradeActivationPolicy in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_UPGRADE_TIMEOUT_POLICY_DEFAULT_VALUE

Default value of UpgradeTimeoutPolicy in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_UPGRADE_TIMEOUT_POLICY_MIN_VALUE

Minimum value of UpgradeTimeoutPolicy in OTAUpgrade cluster.

EZB_ZCL_OTA_UPGRADE_UPGRADE_TIMEOUT_POLICY_MAX_VALUE

Maximum value of UpgradeTimeoutPolicy in OTAUpgrade cluster.

EZB_ZCL_CLUSTER_ID_OTA_UPGRADE_CLIENT_ROLE_INIT
EZB_ZCL_CLUSTER_ID_OTA_UPGRADE_SERVER_ROLE_INIT

5.2.6.3.8.1.5. Type Definitions

typedef struct ezb_zcl_ota_upgrade_cluster_server_config_s ezb_zcl_ota_upgrade_cluster_server_config_t

Configuration mandatory attributes for the OTAUpgrade server cluster.

typedef struct ezb_zcl_ota_upgrade_cluster_client_config_s ezb_zcl_ota_upgrade_cluster_client_config_t

Configuration mandatory attributes for the OTAUpgrade client cluster.

typedef ezb_zcl_ota_upgrade_cluster_server_config_t ezb_zcl_ota_upgrade_cluster_config_t

5.2.6.3.8.1.6. Enumerations

enum ezb_zcl_ota_upgrade_server_attr_t

Attribute identifiers for the ota_upgrade server cluster.

Values:

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_OTA_UPGRADE_FILE_TABLE_SIZE_ID

OTAUpgradeFileTableSize attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_OTA_UPGRADE_FILE_TABLE_ID

OTAUpgradeFileTable attribute.

enum ezb_zcl_ota_upgrade_server_cmd_id_t

Received Command identifiers for the OTAUpgrade cluster.

Values:

enumerator EZB_ZCL_CMD_OTA_UPGRADE_QUERY_NEXT_IMAGE_REQUEST_ID

QueryNextImageRequest command.

enumerator EZB_ZCL_CMD_OTA_UPGRADE_IMAGE_BLOCK_REQUEST_ID

ImageBlockRequest command.

enumerator EZB_ZCL_CMD_OTA_UPGRADE_IMAGE_PAGE_REQUEST_ID

ImagePageRequest command.

enumerator EZB_ZCL_CMD_OTA_UPGRADE_UPGRADE_END_REQUEST_ID

UpgradeEndRequest command.

enumerator EZB_ZCL_CMD_OTA_UPGRADE_QUERY_DEVICE_SPECIFIC_FILE_REQUEST_ID

QueryDeviceSpecificFileRequest command.

enum ezb_zcl_ota_upgrade_client_attr_t

Attribute identifiers for the ota_upgrade client cluster.

Values:

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_UPGRADE_SERVER_ID_ID

UpgradeServerID attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_FILE_OFFSET_ID

FileOffset attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_CURRENT_FILE_VERSION_ID

CurrentFileVersion attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_CURRENT_ZIGBEE_STACK_VERSION_ID

CurrentZigbeeStackVersion attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_DOWNLOADED_FILE_VERSION_ID

DownloadedFileVersion attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_DOWNLOADED_ZIGBEE_STACK_VERSION_ID

DownloadedZigbeeStackVersion attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_IMAGE_UPGRADE_STATUS_ID

ImageUpgradeStatus attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_MANUFACTURER_ID_ID

ManufacturerID attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_IMAGE_TYPE_ID_ID

ImageTypeID attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_MINIMUM_BLOCK_PERIOD_ID

MinimumBlockPeriod attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_IMAGE_STAMP_ID

ImageStamp attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_UPGRADE_ACTIVATION_POLICY_ID

UpgradeActivationPolicy attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_UPGRADE_TIMEOUT_POLICY_ID

UpgradeTimeoutPolicy attribute.

enumerator EZB_ZCL_ATTR_OTA_UPGRADE_OTA_UPGRADE_DOWNLOADING_CONTEXT_ID

OTAUpgradeDownloadingContext attribute.

enum ezb_zcl_ota_upgrade_client_image_upgrade_status_t

Enumeration for ZCL ImageUpgradeStatus attribute of OTAUpgrade.

Values:

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_UPGRADE_STATUS_NORMAL

Normal

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_UPGRADE_STATUS_DOWNLOAD_IN_PROGRESS

DownloadInProgress

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_UPGRADE_STATUS_DOWNLOAD_COMPLETE

DownloadComplete

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_UPGRADE_STATUS_WAITING_TO_UPGRADE

WaitingToUpgrade

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_UPGRADE_STATUS_COUNT_DOWN

CountDown

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_UPGRADE_STATUS_WAIT_FOR_MORE

WaitForMore

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_UPGRADE_STATUS_WAITING_TO_UPGRADE_VIA_EXTERNAL_EVENT

WaitingToUpgradeViaExternalEvent

enum ezb_zcl_ota_upgrade_client_upgrade_activation_policy_t

Enumeration for ZCL UpgradeActivationPolicy attribute of OTAUpgrade.

Values:

enumerator EZB_ZCL_OTA_UPGRADE_UPGRADE_ACTIVATION_POLICY_OTA_SERVER_ACTIVATION_ALLOWED

OTAServerActivationAllowed

enumerator EZB_ZCL_OTA_UPGRADE_UPGRADE_ACTIVATION_POLICY_OUT_OF_BAND_ACTIVATION_ONLY

OutOfBandActivationOnly

enum ezb_zcl_ota_upgrade_client_upgrade_timeout_policy_t

Enumeration for ZCL UpgradeTimeoutPolicy attribute of OTAUpgrade.

Values:

enumerator EZB_ZCL_OTA_UPGRADE_UPGRADE_TIMEOUT_POLICY_APPLY_UPGRADE_AFTER_TIMEOUT

ApplyUpgradeAfterTimeout

enumerator EZB_ZCL_OTA_UPGRADE_UPGRADE_TIMEOUT_POLICY_DO_NOT_APPLY_UPGRADE_AFTER_TIMEOUT

DoNotApplyUpgradeAfterTimeout

enum ezb_zcl_ota_upgrade_client_cmd_id_t

Received Command identifiers for the OTAUpgrade cluster.

Values:

enumerator EZB_ZCL_CMD_OTA_UPGRADE_IMAGE_NOTIFY_ID

ImageNotify command.

enumerator EZB_ZCL_CMD_OTA_UPGRADE_QUERY_NEXT_IMAGE_RESPONSE_ID

QueryNextImageResponse command.

enumerator EZB_ZCL_CMD_OTA_UPGRADE_IMAGE_BLOCK_RESPONSE_ID

ImageBlockResponse command.

enumerator EZB_ZCL_CMD_OTA_UPGRADE_UPGRADE_END_RESPONSE_ID

UpgradeEndResponse command.

enumerator EZB_ZCL_CMD_OTA_UPGRADE_QUERY_DEVICE_SPECIFIC_FILE_RESPONSE_ID

QueryDeviceSpecificFileResponse command.

5.2.6.3.8.1.7. Header File

5.2.6.3.8.1.8. Functions

ezb_err_t ezb_zcl_ota_upgrade_image_notify_cmd_req(const ezb_zcl_ota_upgrade_image_notify_cmd_t *cmd_req)

Send ZCL OTA Upgrade ImageNotify command request.

Parameters:

cmd_req -- Pointer to the ImageNotify command request structure, ezb_zcl_ota_upgrade_image_notify_cmd_s.

Returns:

Error code.

ezb_zcl_ota_file_handle_t ezb_zcl_ota_upgrade_add_ota_file(uint8_t ep_id, const void *image, uint32_t image_size)

Add an OTA image file to the OTA server.

This function adds an OTA image file to the OTA server. Please ensure it remains available until it is removed from the OTA server via ezb_zcl_ota_upgrade_remove_ota_file().

Parameters:

  • ep_id -- Endpoint ID of the OTA server.

  • image -- Pointer to the image data (complete OTA file, including header).

  • image_size -- Size of the image in bytes.

Returns:

Handle of the OTA file (ezb_zcl_ota_file_handle_t).

void ezb_zcl_ota_upgrade_remove_ota_file(uint8_t ep_id, ezb_zcl_ota_file_handle_t ota_file)

Remove an OTA file from the OTA server.

Parameters:
ezb_err_t ezb_zcl_ota_upgrade_query_next_image_cmd_req(const ezb_zcl_ota_upgrade_query_next_image_req_cmd_t *cmd_req)

Send ZCL OTA Upgrade Query Next Image Request command request.

Parameters:

cmd_req -- Pointer to the Query Next Image Request command request structure, ezb_zcl_ota_upgrade_query_next_image_req_cmd_s.

Returns:

Error code.

ezb_err_t ezb_zcl_ota_upgrade_set_download_block_size(uint8_t ep_id, uint8_t allowed_block_size)

Set the maximum block size that the OTA client can receive.

It specifies the MaximumDataSize field of the ImageBlockRequest, indicating the maximum number of bytes the client can receive at once,.

Parameters:

  • ep_id -- Endpoint ID of the OTA client.

  • allowed_block_size -- Maximum allowed block size in bytes (default: EZB_ZCL_OTA_UPGRADE_DEFAULT_BLOCK_SIZE_DEFAULT).

Returns:

Error code.

ezb_err_t ezb_zcl_ota_upgrade_set_hw_version(uint8_t ep_id, uint16_t hw_version)

Set the hardware version on OTA client.

If it is set, the QueryNextImageRequest will be sent with hardware version to response the ImageNotify command.

Parameters:

  • ep_id -- Endpoint ID of the OTA client.

  • hw_version -- Hardware version (zero means no hardware version is set).

Returns:

Error code.

ezb_err_t ezb_zcl_ota_upgrade_set_download_retry(uint8_t ep_id, uint8_t retry, uint32_t timeout)

Set the retry number and timeout for downloading OTA image on OTA client.

Parameters:

  • ep_id -- Endpoint ID of the OTA client.

  • retry -- The number of retries for the OTA download failure.

  • timeout -- The timeout in milliseconds.

Returns:

Error code.

5.2.6.3.8.1.9. Structures

struct ezb_zcl_ota_upgrade_client_progress_start_t

Structure for the ZCL OTA Upgrade client start progress information.

Public Members

uint16_t manuf_code

Manufacturer code.

uint16_t image_type

Image type.

uint32_t file_version

File version.

uint32_t image_size

Image size in bytes.

struct ezb_zcl_ota_upgrade_client_progress_receiving_t

Structure for the ZCL OTA Upgrade client receiving progress information.

Public Members

uint32_t file_offset

Current file offset in bytes.

uint8_t block_size

Block size in bytes.

uint8_t *block

Pointer to the received block data.

struct ezb_zcl_ota_upgrade_client_progress_check_t

Structure for the ZCL OTA Upgrade client check progress information.

Public Members

uint16_t manuf_code

Manufacturer code

uint16_t image_type

Image type

uint32_t file_version

File version

struct ezb_zcl_ota_upgrade_client_progress_apply_t

Structure for the ZCL OTA Upgrade client apply progress information.

Public Members

uint16_t manuf_code

Manufacturer code

uint16_t image_type

Image type

uint32_t file_version

File version

struct ezb_zcl_ota_upgrade_client_progress_finish_t

Structure for the ZCL OTA Upgrade client finish progress information.

Public Members

uint32_t count_down_delay

Countdown delay in seconds before upgrade takes effect

struct ezb_zcl_ota_upgrade_client_progress_message_s

Message for the ZCL OTA Upgrade client progress message.

Public Members

ezb_zcl_message_info_t info

Basic information about the ZCL message.

const ezb_zcl_cmd_hdr_t *header

ZCL command header information. See ezb_zcl_cmd_hdr_s.

ezb_zcl_ota_upgrade_progress_t progress

Progress; ezb_zcl_ota_upgrade_progress_t. EZB_ZCL_OTA_UPGRADE_PROGRESS_START: Start OTA EZB_ZCL_OTA_UPGRADE_PROGRESS_RECEIVING: Receiving OTA image block EZB_ZCL_OTA_UPGRADE_PROGRESS_CHECK: Check completed OTA image EZB_ZCL_OTA_UPGRADE_PROGRESS_APPLY: Apply completed OTA image EZB_ZCL_OTA_UPGRADE_PROGRESS_FINISH: Finish OTA EZB_ZCL_OTA_UPGRADE_PROGRESS_ABORT: Abort OTA

ezb_zcl_ota_upgrade_client_progress_start_t start

Start information.

ezb_zcl_ota_upgrade_client_progress_receiving_t receiving

Receiving information.

ezb_zcl_ota_upgrade_client_progress_check_t check

Check information.

ezb_zcl_ota_upgrade_client_progress_apply_t apply

Apply information.

ezb_zcl_ota_upgrade_client_progress_finish_t finish

Finish information.

struct ezb_zcl_ota_upgrade_client_progress_message_s in

Input: OTA upgrade client progress information.

ezb_zcl_status_t result

Status of processing in application.

struct ezb_zcl_ota_upgrade_client_progress_message_s out

Output: result to send back.

struct ezb_zcl_ota_upgrade_new_image_t

Structure for the ZCL OTA Upgrade new image information.

Public Members

uint8_t status

Status; ezb_zcl_ota_upgrade_status_code_t.

ezb_extaddr_t server_address

Server extended address.

uint8_t ep_id

Endpoint ID.

uint16_t manuf_code

Manufacturer code.

uint16_t image_type

Image type.

uint32_t file_version

File version.

uint32_t size

Image size in bytes.

struct ezb_zcl_ota_upgrade_query_next_image_rsp_message_s

Message for the ZCL OTA Upgrade Query Next Image response message.

Public Members

ezb_zcl_message_info_t info

Basic information about the ZCL message.

const ezb_zcl_cmd_hdr_t *header

ZCL command header information. See ezb_zcl_cmd_hdr_s.

ezb_zcl_ota_upgrade_new_image_t image

New image information.

struct ezb_zcl_ota_upgrade_query_next_image_rsp_message_s in

Input: parsed fields from the request.

ezb_zcl_status_t result

Status of processing in application.

struct ezb_zcl_ota_upgrade_query_next_image_rsp_message_s out

Output: result to send back.

struct ezb_zcl_ota_upgrade_server_progress_start_t

Structure for the ZCL OTA Upgrade server start progress information.

Public Members

uint16_t short_address

Client short address

uint8_t ep_id

Endpoint ID

uint16_t manuf_code

Manufacturer code

uint16_t image_type

Image type

uint32_t file_version

File version

File version for policy

uint16_t hw_version

Hardware version

struct ezb_zcl_ota_upgrade_server_progress_start_t query

Query information.

struct ezb_zcl_ota_upgrade_server_progress_start_t policy

Policy information.

struct ezb_zcl_ota_upgrade_server_progress_sending_t

Structure for the ZCL OTA Upgrade server sending progress information.

Public Members

uint16_t manuf_code

Manufacturer code

uint16_t image_type

Image type

uint32_t file_version

File version

uint32_t file_offset

Current file offset in bytes

uint16_t block_delay

Block delay in milliseconds before next request

struct ezb_zcl_ota_upgrade_server_progress_finish_t

Structure for the ZCL OTA Upgrade server finish progress information.

Public Members

uint8_t status

Status code

uint16_t manuf_code

Manufacturer code

uint16_t image_type

Image type

uint32_t file_version

File version

struct ezb_zcl_ota_upgrade_server_progress_upgrade_time_t

Structure for the ZCL OTA Upgrade server finish progress upgrade time information.

Public Members

uint16_t current_time

Current time (server)

uint16_t upgrade_time

Upgrade time (when upgrade is scheduled)

struct ezb_zcl_ota_upgrade_server_progress_message_s

Message for the ZCL OTA Upgrade server progress message.

Public Members

ezb_zcl_message_info_t info

Basic information about the ZCL message.

const ezb_zcl_cmd_hdr_t *header

ZCL command header information. See ezb_zcl_cmd_hdr_s.

ezb_zcl_ota_upgrade_progress_t progress

Progress; ezb_zcl_ota_upgrade_progress_t; EZB_ZCL_OTA_UPGRADE_PROGRESS_START: Start OTA; EZB_ZCL_OTA_UPGRADE_PROGRESS_SENDING: Sending OTA image block; EZB_ZCL_OTA_UPGRADE_PROGRESS_FINISH: Finish OTA;

ezb_zcl_ota_upgrade_server_progress_start_t start

Start information.

ezb_zcl_ota_upgrade_server_progress_sending_t sending

Sending information.

ezb_zcl_ota_upgrade_server_progress_finish_t finish

Finish information.

struct ezb_zcl_ota_upgrade_server_progress_message_s in

Input: OTA upgrade server progress information.

ezb_zcl_status_t result

Status of processing in application.

ezb_zcl_ota_upgrade_server_progress_upgrade_time_t finish

Upgrade time from Upgrade End response.

struct ezb_zcl_ota_upgrade_server_progress_message_s out

Output: result to send back.

struct ezb_zcl_ota_upgrade_image_notify_payload_s

Payload for the ZCL OTA Upgrade ImageNotify command.

Public Members

uint8_t type

Payload type; see ezb_zcl_ota_upgrade_image_notify_payload_type_t.

uint8_t query_jitter

Query jitter value (0-255).

uint16_t manuf_code

Manufacturer code.

uint16_t image_type

Image type.

uint32_t file_version

File version.

struct ezb_zcl_ota_upgrade_image_notify_cmd_s

Structure for the ZCL OTA Upgrade ImageNotify command request.

Public Members

ezb_zcl_cluster_cmd_ctrl_t cmd_ctrl

Control information for the ZCL command.

ezb_zcl_ota_upgrade_image_notify_payload_t payload

Payload of the command.

struct ezb_zcl_ota_upgrade_query_next_image_req_payload_s

Payload for the ZCL OTA Upgrade Query Next Image Request command.

Public Members

uint8_t fc

Field control.

uint16_t manuf_code

Manufacturer code.

uint16_t image_type

Image type.

uint32_t file_version

File version.

uint16_t hw_version

Hardware version.

struct ezb_zcl_ota_upgrade_query_next_image_req_cmd_s

Structure for the ZCL OTA Upgrade Query Next Image Request command request.

Public Members

ezb_zcl_cluster_cmd_ctrl_t cmd_ctrl

Control information for the ZCL command.

ezb_zcl_ota_upgrade_query_next_image_req_payload_t payload

Payload of the command.

struct ezb_zcl_ota_upgrade_query_next_image_rsp_payload_s

Query Next Image Response payload (server response to Query Next Image).

Public Members

uint8_t status

Status code; ezb_zcl_ota_upgrade_status_code_t

uint16_t manuf_code

Manufacturer code

uint16_t image_type

Image type

uint32_t file_version

File version

uint32_t image_size

Image size in bytes

struct ezb_zcl_ota_upgrade_image_block_req_payload_t

Image Block Request payload (client requests a block of image data).

Public Members

uint8_t fc

Field control

uint16_t manuf_code

Manufacturer code

uint16_t image_type

Image type

uint32_t file_version

File version

uint32_t file_offset

File offset in bytes

uint8_t data_size_max

Maximum data size in bytes client can receive

ezb_extaddr_t node_addr

Node extended address (optional)

uint16_t block_delay

Block delay in ms (optional)

struct ezb_zcl_ota_upgrade_upgrade_end_req_payload_t

Upgrade End Request payload (client signals download complete and status).

Public Members

uint8_t status

Status code

uint16_t manuf_code

Manufacturer code

uint16_t image_type

Image type

uint32_t file_version

File version

struct ezb_zcl_ota_upgrade_upgrade_end_rsp_payload_t

Upgrade End Response payload (server responds with current/upgrade time).

Public Members

uint16_t manuf_code

Manufacturer code

uint16_t image_type

Image type

uint32_t file_version

File version

uint32_t current_time

Current time (server)

uint32_t upgrade_time

Upgrade time (when upgrade is scheduled)

struct ezb_zcl_ota_upgrade_image_block_rsp_payload_t

Image Block Response payload (server sends block data or Wait For Data).

Public Members

uint8_t status

Status; ezb_zcl_ota_upgrade_status_code_t.

uint16_t manuf_code

Manufacturer code

uint16_t image_type

Image type

uint32_t file_version

File version

uint32_t file_offset

File offset in bytes

uint8_t data_size

Data size in bytes

uint8_t *image_data

Pointer to image data

struct ezb_zcl_ota_upgrade_image_block_rsp_payload_t success

Success information.

uint32_t current_time

Current time

uint32_t request_time

Request time

uint16_t block_delay

Block delay in milliseconds

struct ezb_zcl_ota_upgrade_image_block_rsp_payload_t wait_for_data

Wait for data information.

union ezb_zcl_ota_upgrade_image_block_rsp_payload_t

Union of response information.

5.2.6.3.8.1.10. Macros

EZB_ZCL_OTA_UPGRADE_MAX_BLOCK_SIZE

Maximum image block size in bytes.

EZB_ZCL_OTA_UPGRADE_DEFAULT_BLOCK_SIZE_DEFAULT

Default image block size in bytes when not configured.

EZB_ZCL_OTA_UPGRADE_MAX_QUERY_JITTER_VALUE

Maximum query jitter value for Image Notify (0–255).

EZB_ZCL_OTA_UPGRADE_MANUF_CODE_WILD_CARD

Wild card: any manufacturer code when querying or matching.

EZB_ZCL_OTA_UPGRADE_FILE_VERSION_WILD_CARD

Wild card: any file version when querying or matching.

EZB_ZCL_OTA_UPGRADE_DEFAULT_UPGRADE_TIME

Default upgrade time (e.g. when server has no specific time).

EZB_ZCL_OTA_UPGRADE_DEFAULT_RETRY

Default retry number for the OTA download failure.

EZB_ZCL_OTA_UPGRADE_DEFAULT_TIMEOUT

Default timeout in milliseconds for the OTA download failure.

EZB_ZCL_OTA_FILE_INVALID_HANDLE

Invalid OTA file handle.

5.2.6.3.8.1.11. Type Definitions

typedef ezb_zcl_status_t ezb_zcl_ota_upgrade_status_code_t

Type for the ZCL OTA Upgrade status code. .

typedef struct ezb_zcl_ota_upgrade_client_progress_message_s ezb_zcl_ota_upgrade_client_progress_message_t

Message for the ZCL OTA Upgrade client progress message.

typedef struct ezb_zcl_ota_upgrade_query_next_image_rsp_message_s ezb_zcl_ota_upgrade_query_next_image_rsp_message_t

Message for the ZCL OTA Upgrade Query Next Image response message.

typedef struct ezb_zcl_ota_upgrade_server_progress_message_s ezb_zcl_ota_upgrade_server_progress_message_t

Message for the ZCL OTA Upgrade server progress message.

typedef struct ezb_zcl_ota_upgrade_image_notify_payload_s ezb_zcl_ota_upgrade_image_notify_payload_t

Payload for the ZCL OTA Upgrade ImageNotify command.

typedef struct ezb_zcl_ota_upgrade_image_notify_cmd_s ezb_zcl_ota_upgrade_image_notify_cmd_t

Structure for the ZCL OTA Upgrade ImageNotify command request.

typedef struct ezb_zcl_ota_upgrade_query_next_image_req_payload_s ezb_zcl_ota_upgrade_query_next_image_req_payload_t

Payload for the ZCL OTA Upgrade Query Next Image Request command.

typedef struct ezb_zcl_ota_upgrade_query_next_image_req_cmd_s ezb_zcl_ota_upgrade_query_next_image_req_cmd_t

Structure for the ZCL OTA Upgrade Query Next Image Request command request.

typedef struct ezb_zcl_ota_upgrade_query_next_image_rsp_payload_s ezb_zcl_ota_upgrade_query_next_image_rsp_payload_t

Query Next Image Response payload (server response to Query Next Image).

typedef void *ezb_zcl_ota_file_handle_t

Type for the OTA upgrade file. .

5.2.6.3.8.1.12. Enumerations

enum ezb_zcl_ota_upgrade_image_notify_payload_type_t

Enumeration for the ZCL OTA Upgrade image notify payload type. .

Values:

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_NOTIFY_PAYLOAD_TYPE_JITTER

Jitter

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_NOTIFY_PAYLOAD_TYPE_JITTER_CODE

Jitter code

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_NOTIFY_PAYLOAD_TYPE_JITTER_CODE_IMAGE

Jitter code image

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_NOTIFY_PAYLOAD_TYPE_JITTER_CODE_IMAGE_VERSION

Jitter code image version

enum ezb_zcl_ota_upgrade_progress_t

Enumeration for the ZCL OTA Upgrade progress type. .

Values:

enumerator EZB_ZCL_OTA_UPGRADE_PROGRESS_START

Progress: Start

enumerator EZB_ZCL_OTA_UPGRADE_PROGRESS_RECEIVING

Progress: Receiving

enumerator EZB_ZCL_OTA_UPGRADE_PROGRESS_SENDING

Progress: Sending

enumerator EZB_ZCL_OTA_UPGRADE_PROGRESS_CHECK

Progress: Check

enumerator EZB_ZCL_OTA_UPGRADE_PROGRESS_APPLY

Progress: Apply

enumerator EZB_ZCL_OTA_UPGRADE_PROGRESS_FINISH

Progress: Finish

enumerator EZB_ZCL_OTA_UPGRADE_PROGRESS_ABORT

Progress: Abort

enum ezb_zcl_ota_upgrade_query_next_image_fc_t

Enumeration bitmask for the field control for the Query Next Image Request.

Values:

enumerator EZB_ZCL_OTA_UPGRADE_QUERY_NEXT_IMAGE_FC_HW_VERSION_PRESENT

Hardware version present

enum ezb_zcl_ota_upgrade_image_block_fc_t

Enumeration bitmask for the field control for the Image Block Request.

Values:

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_BLOCK_FC_NODE_ADDR_PRESENT

Node address present

enumerator EZB_ZCL_OTA_UPGRADE_IMAGE_BLOCK_FC_DELAY_PRESENT

Delay present

5.2.6.3.8.2. OTA File

5.2.6.3.8.2.1. Header File

5.2.6.3.8.2.2. Structures

struct ezb_zcl_ota_file_sub_element_header_s

Structure for the ZCL OTA File sub-element.

Public Members

uint16_t tag_id

Tag ID

uint32_t length

Length in bytes

struct ezb_zcl_ota_file_image_s

Structure for the ZCL OTA File image information.

Public Members

ezb_zcl_ota_file_sub_element_header_t hdr

Header of the image sub-element

uint8_t image[]

Data of the image sub-element

struct ezb_zcl_ota_file_ecdsa_signature_s

Structure for the ZCL OTA File ECDSA signature sub-element.

Public Members

ezb_zcl_ota_file_sub_element_header_t hdr

Header of the ECDSA signature sub-element

ezb_extaddr_t address

Extended address

uint8_t signature[42]

ECDSA signature data (42 bytes)

struct ezb_zcl_ota_file_ecdsa_signature_certificate_s

Structure for the ZCL OTA File ECDSA signature certificate sub-element.

Public Members

ezb_zcl_ota_file_sub_element_header_t hdr

Header of the ECDSA signature certificate sub-element

uint8_t certificate[48]

ECDSA certificate data (48 bytes)

struct ezb_zcl_ota_file_ecdsa_signature_crypto_suite2_s

Structure for the ZCL OTA File ECDSA signature crypto suite 2 sub-element.

Public Members

ezb_zcl_ota_file_sub_element_header_t hdr

Header of the ECDSA signature crypto suite 2 sub-element

ezb_extaddr_t address

Extended address

uint8_t signature[72]

ECDSA signature data (72 bytes)

struct ezb_zcl_ota_file_ecdsa_signature_certificate_crypto_suite2_s

Structure for the ZCL OTA File ECDSA signature certificate crypto suite 2 sub-element.

Public Members

ezb_zcl_ota_file_sub_element_header_t hdr

Header of the ECDSA signature certificate crypto suite 2 sub-element

uint8_t certificate[74]

ECDSA certificate data (74 bytes)

struct ezb_zcl_ota_file_image_integrity_code_s

Structure for the ZCL OTA File image integrity code sub-element.

Public Members

ezb_zcl_ota_file_sub_element_header_t hdr

Header of the image integrity code sub-element

uint8_t integrity_code[16]

Image integrity code (16 bytes)

struct ezb_zcl_ota_upgrade_picture_data_s

Structure for the ZCL OTA File picture data sub-element.

Public Members

ezb_zcl_ota_file_sub_element_header_t hdr

Header of the picture data sub-element

uint8_t picture_data[16]

Picture data (16 bytes)

struct ezb_zcl_ota_file_header_s

Structure for the ZCL OTA File header mandatory fields.

Parsed from the first bytes of an OTA file; fc indicates which optional fields follow.

Public Members

uint32_t file_id

File identifier

uint16_t hdr_version

Header version

uint16_t hdr_length

Header length in bytes

uint16_t hdr_fc

Header field control bitmask

uint16_t manufacturer_code

Manufacturer code

uint16_t image_type

Image type

uint32_t file_version

File version

uint16_t stack_version

Stack version

char hdr_string[32]

Header string

uint32_t total_image_size

Total image size in bytes

struct ezb_zcl_ota_file_header_optional_s

Structure for the ZCL OTA File header optional fields.

Public Members

uint8_t security_credential_version

Security credential version.

ezb_extaddr_t upgrade_file_destination

Upgrade file destination extended address.

uint16_t minimum_hardware_version

Minimum hardware version.

uint16_t maximum_hardware_version

Maximum hardware version.

5.2.6.3.8.2.3. Macros

EZB_ZCL_OTA_FILE_IDENTIFIER

File identifier for the ZCL OTA File.

EZB_ZCL_OTA_FILE_HEADER_VERSION

Header version for the ZCL OTA File.

EZB_ZCL_OTA_FILE_VERSION_GET_APP_RELEASE(v)

Get the ZCL OTA File file version components.

App release.

EZB_ZCL_OTA_FILE_VERSION_GET_APP_BUILD(v)

App build.

EZB_ZCL_OTA_FILE_VERSION_GET_STACK_RELEASE(v)

Stack release.

EZB_ZCL_OTA_FILE_VERSION_GET_STACK_BUILD(v)

Stack build.

EZB_ZCL_OTA_FILE_VERSION_SET_APP_RELEASE(v, a)

Set the ZCL OTA File file version components.

App release.

EZB_ZCL_OTA_FILE_VERSION_SET_APP_BUILD(v, a)

App build.

EZB_ZCL_OTA_FILE_VERSION_SET_STACK_RELEASE(v, a)

Stack release.

EZB_ZCL_OTA_FILE_VERSION_SET_STACK_BUILD(v, a)

Stack build.

5.2.6.3.8.2.4. Type Definitions

typedef struct ezb_zcl_ota_file_sub_element_header_s ezb_zcl_ota_file_sub_element_header_t

Structure for the ZCL OTA File sub-element.

typedef struct ezb_zcl_ota_file_image_s ezb_zcl_ota_file_image_t

Structure for the ZCL OTA File image information.

typedef struct ezb_zcl_ota_file_ecdsa_signature_s ezb_zcl_ota_file_ecdsa_signature_t

Structure for the ZCL OTA File ECDSA signature sub-element.

typedef struct ezb_zcl_ota_file_ecdsa_signature_certificate_s ezb_zcl_ota_file_ecdsa_signature_certificate_t

Structure for the ZCL OTA File ECDSA signature certificate sub-element.

typedef struct ezb_zcl_ota_file_ecdsa_signature_crypto_suite2_s ezb_zcl_ota_file_ecdsa_signature_crypto_suite2_t

Structure for the ZCL OTA File ECDSA signature crypto suite 2 sub-element.

typedef struct ezb_zcl_ota_file_ecdsa_signature_certificate_crypto_suite2_s ezb_zcl_ota_file_ecdsa_signature_certificate_crypto_suite2_t

Structure for the ZCL OTA File ECDSA signature certificate crypto suite 2 sub-element.

typedef struct ezb_zcl_ota_file_image_integrity_code_s ezb_zcl_ota_file_image_integrity_code_t

Structure for the ZCL OTA File image integrity code sub-element.

typedef struct ezb_zcl_ota_upgrade_picture_data_s ezb_zcl_ota_file_picture_data_t

Structure for the ZCL OTA File picture data sub-element.

typedef struct ezb_zcl_ota_file_header_s ezb_zcl_ota_file_header_t

Structure for the ZCL OTA File header mandatory fields.

Parsed from the first bytes of an OTA file; fc indicates which optional fields follow.

typedef struct ezb_zcl_ota_file_header_optional_s ezb_zcl_ota_file_header_optional_t

Structure for the ZCL OTA File header optional fields.

5.2.6.3.8.2.5. Enumerations

enum ezb_zcl_ota_file_header_fc_t

Enumeration bitmask for the ZCL OTA File header field control.

Indicates which optional fields are present in the OTA file header.

Values:

enumerator EZB_ZCL_OTA_FILE_HEADER_FC_SECURITY_CREDENTIAL_VERSION_PRESENT

Security credential version present.

enumerator EZB_ZCL_OTA_FILE_HEADER_FC_DEVICE_SPECIFIC

Device specific.

enumerator EZB_ZCL_OTA_FILE_HEADER_FC_HW_VERSION_PRESENT

Hardware version.

enum ezb_zcl_ota_file_image_type_t

Enumeration for the ZCL OTA File image type.

Standard types for security credentials, configuration, log; wild card for any type.

Values:

enumerator EZB_ZCL_OTA_FILE_IMAGE_TYPE_CLIENT_SECURITY_CREDENTIALS

Client security credentials.

enumerator EZB_ZCL_OTA_FILE_IMAGE_TYPE_CLIENT_CONFIGURATION

Client configuration.

enumerator EZB_ZCL_OTA_FILE_IMAGE_TYPE_SERVER_LOG

Server log.

enumerator EZB_ZCL_OTA_FILE_IMAGE_TYPE_PICTURE

Picture.

enumerator EZB_ZCL_OTA_FILE_IMAGE_TYPE_WILD_CARD

Wild card.

enum ezb_zcl_ota_file_stack_version_t

Enumeration for the ZCL OTA File stack version.

Values:

enumerator EZB_ZCL_OTA_FILE_STACK_VERSION_2006

Zigbee Version 2006.

enumerator EZB_ZCL_OTA_FILE_STACK_VERSION_2007

Zigbee Version 2007.

enumerator EZB_ZCL_OTA_FILE_STACK_VERSION_PRO

Zigbee Version PRO.

enumerator EZB_ZCL_OTA_FILE_STACK_VERSION_IP

Zigbee Version IP.

enum ezb_zcl_ota_file_security_credential_version_t

Enumeration for the ZCL OTA File security credential version.

Values:

enumerator EZB_ZCL_OTA_FILE_SECURITY_CREDENTIAL_VERSION_SE1_0

Security credential version SE1.0

enumerator EZB_ZCL_OTA_FILE_SECURITY_CREDENTIAL_VERSION_SE1_1

Security credential version SE1.1

enumerator EZB_ZCL_OTA_FILE_SECURITY_CREDENTIAL_VERSION_SE2_0

Security credential version SE2.0

enumerator EZB_ZCL_OTA_FILE_SECURITY_CREDENTIAL_VERSION_SE1_2

Security credential version SE1.2

enum ezb_zcl_ota_file_tag_id_t

Enumeration tag ID for the ZCL OTA File sub-element.

Tags 0xf000–0xffff are manufacturer-specific.

Values:

enumerator EZB_ZCL_OTA_FILE_TAG_ID_UPGRADE_IMAGE

Upgrade image

enumerator EZB_ZCL_OTA_FILE_TAG_ID_ECDSA_SIGNATURE_CS1

ECDSA signature (Crypto Suite 1)

enumerator EZB_ZCL_OTA_FILE_TAG_ID_ECDSA_SIGNATURE_CERTIFICATE_CS1

ECDSA signature certificate (Crypto Suite 1)

enumerator EZB_ZCL_OTA_FILE_TAG_ID_IMAGE_INTEGRITY_CODE

Image integrity code

enumerator EZB_ZCL_OTA_FILE_TAG_ID_PICTURE_DATA

Picture data

enumerator EZB_ZCL_OTA_FILE_TAG_ID_ECDSA_SIGNATURE_CS2

ECDSA signature (Crypto Suite 2)

enumerator EZB_ZCL_OTA_FILE_TAG_ID_ECDSA_SIGNATURE_CERTIFICATE_CS2

ECDSA signature certificate (Crypto Suite 2)

enumerator EZB_ZCL_OTA_FILE_TAG_ID_MANUF_SPECIFIC_MIN

Manufacturer specific min

enumerator EZB_ZCL_OTA_FILE_TAG_ID_MANUF_HEADER

Manufacturer header

enumerator EZB_ZCL_OTA_FILE_TAG_ID_MANUF_SPECIFIC_MAX

Manufacturer specific max