OTA Client#

API and Callbacks for the OTA Cluster Client Component.

Silicon Labs implementation of the Zigbee Over-the-air Bootload Client Cluster (a multi-hop, application bootloader). This implementation finds the OTA server in the network, periodically queries the server for a new image to download, downloads the data, and then waits for the server command to tell it to upgrade. Optionally, it can cryptographically verify the image before upgrade.

Modules#

OTA Client

API#

void

Notify the server that the upgrade image has been received and validated successfully. This routine is automatically called by the OTA client state machine once the entire OTA image has been downloaded successfully. This API sends a message to the OTA server asking when the OTA image should be applied.

void

Set whether OTA clients use non TC servers.

bool

Returns whether or not the device is allowed to discover OTA server services from devices other than the trust center.

void

Set whether OTA Clients will permit firmware downgrades.

bool

Returns whether or not the device is allowed to downgrade its firmware.

Macros#

#define
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_DOWNLOAD_DELAY_MS 0L

How often the client will ask for a piece of an upgrade image being actively downloaded. A rate of 0 means the client will request the next block of data as fast as it can.

#define
SL_ZIGBEE_AF_OTA_SERVER_DISCOVERY_DELAY_MS (2 * MINUTES_IN_MS)

How often the OTA client looks for an OTA server when there is NOT one present in the network. Once it has found one, it queries the same one forever (or until it reboots).

#define
SL_ZIGBEE_AF_OTA_QUERY_DELAY_MS (5 * MINUTES_IN_MS)

How often the OTA client asks the OTA server if there is a new image available.

#define
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_QUERY_ERROR_THRESHOLD 10

How many sequential query errors will cause a device to look for a new OTA server.

#define
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_DOWNLOAD_ERROR_THRESHOLD 10

The maximum number of sequential errors when downloading an image that will trigger the OTA client to abort the download.

#define
SL_ZIGBEE_AF_RUN_UPGRADE_REQUEST_DELAY_MS (10 * MINUTES_IN_MS)

The delay between attempts to request to initiate the bootload of a successfully downloaded file.

#define
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_UPGRADE_WAIT_THRESHOLD 10

The maximum number of sequential errors when asking the OTA Server when to upgrade that will cause the OTA client to apply the upgrade without the server telling it to do so.

#define
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_PAGE_REQUEST_SIZE 1024

Page Request Size. Tested page sizes: 1024, 2048, and 4096.

#define
SL_ZIGBEE_AF_OTA_CLIENT_PAGE_REQUEST_SPACING_MS 50L

The spacing requested by the client between the image blocks sent by the server to the client during a page request.

#define
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_VERIFY_DELAY_MS 10L

This is the time delay between calls to verifying the OTA image.

#define
NULL_EUI64 { 0, 0, 0, 0, 0, 0, 0, 0 }
#define
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_SIGNER_EUI0 NULL_EUI64

EUI64 of the allowed image signer. A NULL EUI64 is an invalid signer and will never match.

#define
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_SIGNER_EUI1 NULL_EUI64

EUI64 of the allowed image signer. A NULL EUI64 is an invalid signer and will never match.

#define
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_SIGNER_EUI2 NULL_EUI64

EUI64 of the allowed image signer. A NULL EUI64 is an invalid signer and will never match.

#define
SECONDS_IN_MS (1000L)
#define
MINUTES_IN_MS (60 * SECONDS_IN_MS)
#define
HOURS_IN_MS (60 * MINUTES_IN_MS)
#define
SL_ZIGBEE_AF_INVALID_HARDWARE_VERSION 0xFFFF

Invalid hardware version.

API Documentation#

sl_zigbee_af_ota_server_send_upgrade_request#

void sl_zigbee_af_ota_server_send_upgrade_request ()

Notify the server that the upgrade image has been received and validated successfully. This routine is automatically called by the OTA client state machine once the entire OTA image has been downloaded successfully. This API sends a message to the OTA server asking when the OTA image should be applied.


sl_zigbee_af_ota_client_set_ignore_non_trust_center#

void sl_zigbee_af_ota_client_set_ignore_non_trust_center (bool ignoreNonTc)

Set whether OTA clients use non TC servers.

Parameters
TypeDirectionArgument NameDescription
bool[in]ignoreNonTc

a bool determining whether client should ignore any non Trust Center OTA servers.

Sets the behavior of OTA clients when determining whether or not to use non Trust Center OTA servers and abort any download that is in progress.


sl_zigbee_af_ota_client_get_ignore_non_trust_center#

bool sl_zigbee_af_ota_client_get_ignore_non_trust_center ()

Returns whether or not the device is allowed to discover OTA server services from devices other than the trust center.

Returns

  • Current value of ignoreNonTrustCenter for OTA clients.


sl_zigbee_af_set_disable_ota_downgrades#

void sl_zigbee_af_set_disable_ota_downgrades (bool isDisabled)

Set whether OTA Clients will permit firmware downgrades.

Parameters
TypeDirectionArgument NameDescription
bool[in]isDisabled

A bool value indicating whether or not downgrades will be disabled.


sl_zigbee_af_get_disable_ota_downgrades#

bool sl_zigbee_af_get_disable_ota_downgrades ()

Returns whether or not the device is allowed to downgrade its firmware.

Returns

  • The current value of disableOtaDowngrades.


Variable Documentation#

sli_zigbee_af_ota_client_stop_download_percentage#

uint8_t sli_zigbee_af_ota_client_stop_download_percentage