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#
API#
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.
Set whether OTA clients use non TC servers.
Returns whether or not the device is allowed to discover OTA server services from devices other than the trust center.
Set whether OTA Clients will permit firmware downgrades.
Returns whether or not the device is allowed to downgrade its firmware.
Variables#
Macros#
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.
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).
How often the OTA client asks the OTA server if there is a new image available.
How many sequential query errors will cause a device to look for a new OTA server.
The maximum number of sequential errors when downloading an image that will trigger the OTA client to abort the download.
The delay between attempts to request to initiate the bootload of a successfully downloaded file.
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.
Page Request Size. Tested page sizes: 1024, 2048, and 4096.
The spacing requested by the client between the image blocks sent by the server to the client during a page request.
This is the time delay between calls to verifying the OTA image.
EUI64 of the allowed image signer. A NULL EUI64 is an invalid signer and will never match.
EUI64 of the allowed image signer. A NULL EUI64 is an invalid signer and will never match.
EUI64 of the allowed image signer. A NULL EUI64 is an invalid signer and will never match.
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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| 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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| 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
Macro Definition Documentation#
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_DOWNLOAD_DELAY_MS#
#define SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_DOWNLOAD_DELAY_MSValue:
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.
SL_ZIGBEE_AF_OTA_SERVER_DISCOVERY_DELAY_MS#
#define SL_ZIGBEE_AF_OTA_SERVER_DISCOVERY_DELAY_MSValue:
(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).
SL_ZIGBEE_AF_OTA_QUERY_DELAY_MS#
#define SL_ZIGBEE_AF_OTA_QUERY_DELAY_MSValue:
(5 * MINUTES_IN_MS)
How often the OTA client asks the OTA server if there is a new image available.
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_QUERY_ERROR_THRESHOLD#
#define SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_QUERY_ERROR_THRESHOLDValue:
10
How many sequential query errors will cause a device to look for a new OTA server.
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_DOWNLOAD_ERROR_THRESHOLD#
#define SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_DOWNLOAD_ERROR_THRESHOLDValue:
10
The maximum number of sequential errors when downloading an image that will trigger the OTA client to abort the download.
SL_ZIGBEE_AF_RUN_UPGRADE_REQUEST_DELAY_MS#
#define SL_ZIGBEE_AF_RUN_UPGRADE_REQUEST_DELAY_MSValue:
(10 * MINUTES_IN_MS)
The delay between attempts to request to initiate the bootload of a successfully downloaded file.
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_UPGRADE_WAIT_THRESHOLD#
#define SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_UPGRADE_WAIT_THRESHOLDValue:
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.
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_PAGE_REQUEST_SIZE#
#define SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_PAGE_REQUEST_SIZEValue:
1024
Page Request Size. Tested page sizes: 1024, 2048, and 4096.
SL_ZIGBEE_AF_OTA_CLIENT_PAGE_REQUEST_SPACING_MS#
#define SL_ZIGBEE_AF_OTA_CLIENT_PAGE_REQUEST_SPACING_MSValue:
50L
The spacing requested by the client between the image blocks sent by the server to the client during a page request.
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_VERIFY_DELAY_MS#
#define SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_VERIFY_DELAY_MSValue:
10L
This is the time delay between calls to verifying the OTA image.
Verification can take a while (especially in the case of signature checking for Smart Energy) so this provides the ability for other parts of the system to run.
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_SIGNER_EUI0#
#define SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_SIGNER_EUI0Value:
NULL_EUI64
EUI64 of the allowed image signer. A NULL EUI64 is an invalid signer and will never match.
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_SIGNER_EUI1#
#define SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_SIGNER_EUI1Value:
NULL_EUI64
EUI64 of the allowed image signer. A NULL EUI64 is an invalid signer and will never match.
SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_SIGNER_EUI2#
#define SL_ZIGBEE_AF_PLUGIN_OTA_CLIENT_SIGNER_EUI2Value:
NULL_EUI64
EUI64 of the allowed image signer. A NULL EUI64 is an invalid signer and will never match.
SL_ZIGBEE_AF_INVALID_HARDWARE_VERSION#
#define SL_ZIGBEE_AF_INVALID_HARDWARE_VERSIONValue:
0xFFFF
Invalid hardware version.
By default if hardware version is not defined, it is not used. Most products do not limit upgrade images based on the version. Instead they have different images for different hardware. However this can provide support for an image that only supports certain hardware revision numbers.