Ota Unicast Bootloader Client Plugin
Connect Application Framework API Reference

APIs/callbacks for ota-unicast-bootloader clients. More...

Functions

bool emberAfPluginOtaUnicastBootloaderClientNewIncomingImageCallback ( EmberNodeId serverId, uint8_t imageTag, uint32_t imageSize, uint32_t *startIndex)
A callback invoked when the client starts receiving a new image. The application can choose to start receiving the image or ignore it. If the application chooses to receive the image, other images sent out by other servers shall be ignored until the client completes the download. More...
void emberAfPluginOtaUnicastBootloaderClientIncomingImageSegmentCallback ( EmberNodeId serverId, uint32_t startIndex, uint32_t endIndex, uint8_t imageTag, uint8_t *imageSegment)
A callback invoked when an image segment that is part of an image the application chose to download was received. More...
void emberAfPluginOtaUnicastBootloaderClientImageDownloadCompleteCallback ( EmberAfOtaUnicastBootloaderStatus status, uint8_t imageTag, uint32_t imageSize)
A callback invoked to indicate that an image download has completed. More...
EmberAfOtaUnicastBootloaderStatus emberAfPluginOtaUnicastBootloaderClientAbortImageDownload (uint8_t imageTag)
An API for aborting an ongoing image download process. More...
bool emberAfPluginOtaUnicastBootloaderClientIncomingRequestBootloadCallback ( EmberNodeId serverId, uint8_t imageTag, uint32_t bootloadDelayMs)
A callback invoked to indicate that a server has requested to perform a bootload operation at a certain point in time in the future. More...

Detailed Description

APIs/callbacks for ota-unicast-bootloader clients.

OTA bootloading plugins are usable to send firmware images Over The Air when the application is running. When the firmware is downloaded to a device, a bootloader can be started to replace the application in the flash to the one just downloaded.

All Connect bootloader related code relies on the Gecko Bootloader for bootloading and it must be installed on the device for these plugins to work. For details on the Gecko Bootloader, see UG266.

The Unicast OTA plugins implement the OTA download operation in a unicast, addressed way, so only a single client can be addressed from a server in an OTA session, and downloading images to multiple devices will require the server to send the image multiple times. Communication relies on standard unicast data messages, which also means that the routing provided by the Connect stack is availble.

Although bootloading sleepy end devices is theoretically possible with polling, it is not very effective, and it's probably simpler to reconnect as a normal end device while the OTA is active.

Unicast OTA uses a plugin configurable endpoint, which is 13 by default.

Security can be also enabled as plugin configuration on the server, as well as the interval of the messages. The client has a timeout plugin configuration after which it stops the OTA session with an error.

See UG235.06 for further details.

Note
OTA Unicast Bootloading plugins are not available in MAC mode due to the lack of endpoints.

See ota-unicast-bootloader-client.h and ota-unicast-bootloader-client.c for source code.

Function Documentation

◆ emberAfPluginOtaUnicastBootloaderClientAbortImageDownload()

EmberAfOtaUnicastBootloaderStatus emberAfPluginOtaUnicastBootloaderClientAbortImageDownload ( uint8_t imageTag )

An API for aborting an ongoing image download process.

Parameters
[in] imageTag A 1-byte tag that identifies the image the client should no longer download.
Returns
An EmberAfOtaUnicastBootloaderStatus value of:

◆ emberAfPluginOtaUnicastBootloaderClientImageDownloadCompleteCallback()

void emberAfPluginOtaUnicastBootloaderClientImageDownloadCompleteCallback ( EmberAfOtaUnicastBootloaderStatus status,
uint8_t imageTag,
uint32_t imageSize
)

A callback invoked to indicate that an image download has completed.

Parameters
[in] status An EmberAfOtaUnicastBootloaderStatus value of:
[in] imageTag A 1-byte tag of the image this callback refers to.
[in] imageSize The total size of the downloaded image in bytes. This parameter is meaningful only in case the status parameter is set to EMBER_OTA_UNICAST_BOOTLOADER_STATUS_SUCCESS .

◆ emberAfPluginOtaUnicastBootloaderClientIncomingImageSegmentCallback()

void emberAfPluginOtaUnicastBootloaderClientIncomingImageSegmentCallback ( EmberNodeId serverId,
uint32_t startIndex,
uint32_t endIndex,
uint8_t imageTag,
uint8_t * imageSegment
)

A callback invoked when an image segment that is part of an image the application chose to download was received.

Parameters
[in] serverId The node ID of the server that initiated the image distribution process.
[in] startIndex The index of the first byte of the passed segment.
[in] endIndex The index of the last byte of the passed segment.
[in] imageTag A 1-byte tag of the image the passed segment belongs to.
[in] imageSegment An array containing the image segment.

◆ emberAfPluginOtaUnicastBootloaderClientIncomingRequestBootloadCallback()

bool emberAfPluginOtaUnicastBootloaderClientIncomingRequestBootloadCallback ( EmberNodeId serverId,
uint8_t imageTag,
uint32_t bootloadDelayMs
)

A callback invoked to indicate that a server has requested to perform a bootload operation at a certain point in time in the future.

Parameters
[in] serverId The ID of the server the request came from.
[in] imageTag A 1-byte tag of the image this callback refers to.
[in] bootloadDelayMs The delay in milliseconds after which the client has been requested to perform a bootload operation.
Returns
Return true if the application accepted the request of bootloading the specified image at the requested time, false otherwise.

◆ emberAfPluginOtaUnicastBootloaderClientNewIncomingImageCallback()

bool emberAfPluginOtaUnicastBootloaderClientNewIncomingImageCallback ( EmberNodeId serverId,
uint8_t imageTag,
uint32_t imageSize,
uint32_t * startIndex
)

A callback invoked when the client starts receiving a new image. The application can choose to start receiving the image or ignore it. If the application chooses to receive the image, other images sent out by other servers shall be ignored until the client completes the download.

Parameters
[in] serverId The node ID of the server that initiated the new image distribution process.
[in] imageTag A 1-byte tag that identifies the incoming image.
[in] imageSize The size in bytes of the new image.
[out] startIndex The index of the first byte at which the image download shall be started/resumed. The client can use this argument to resume a partially downloaded image. If this value is not set, it defaults to 0 (that is, the download starts at the beginning of the image). Note, this is ignored in case the server does not support download resume.
Returns
Return true to accept the image or false to ignore it.