Ota Broadcast Bootloader Client Plugin
Connect Application Framework API Reference

Set of APIs for ota-broadcast-bootloader-client. More...

Functions

EmberAfOtaBootloaderStatus emberAfPluginOtaBootloaderClientAbortImageDownload (uint8_t imageTag, uint8_t applicationErrorStatus)
Abort an ongoing image download process. More...
bool emberAfPluginOtaBootloaderClientNewIncomingImageCallback ( EmberNodeId serverId, EmberNodeId *alternateServerId, uint8_t imageTag)
A callback invoked when the OTA Bootloader Client starts receiving a new image. The application can choose to start receiving the image or it can ignore it. If the application chooses to receive the image, other images sent out by other servers are ignored until the client completes this download. More...
void emberAfPluginOtaBootloaderClientIncomingImageSegmentCallback ( 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 that the application elected to download, was received on the OTA Bootloader Client. More...
void emberAfPluginOtaBootloaderClientImageDownloadCompleteCallback ( EmberAfOtaBootloaderStatus status, uint8_t imageTag, uint32_t imageSize)
A callback invoked on an OTA Bootloader Client to indicate that an image downlaod is completed. More...
void emberAfPluginOtaBootloaderClientIncomingRequestStatusCallback ( EmberNodeId serverId, uint8_t applicationServerStatus, uint8_t *applicationStatus)
A callback invoked on the OTA Bootloader Client to indicate that an OTA Bootloader Server has requested the status of the client device. More...
bool emberAfPluginOtaBootloaderClientIncomingRequestBootloadCallback ( EmberNodeId serverId, uint8_t imageTag, uint32_t bootloadDelayMs, uint8_t *applicationStatus)
A callback invoked by the OTA Bootloader Client plugin to indicate that an OTA Bootloader Server has requested to perform a bootload operation at a certain point in time in the future. More...

Detailed Description

Set of APIs for ota-broadcast-bootloader-client.

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 Broadcast OTA plugins implement the OTA download operation in broadcast, so the same image can be sent to many devices at the same time. The server however requires to know the clients downloading the image, because it implements error handling by querying all clients for missing segments, and then the server will re-broadcast those segments.

Communication relies on standard broadcast data messages, which means routing is not available, and only clients that are in the range of the server can download. However, the same device can be both client and server, i.e. after downloading the image, a client can configure itself to be a server, and provide the image to another part of the network.

Sleepy end devices cannot be addressed in broadcast, but a sleepy end device can reconnect as a normal end device while the OTA is active.

Broadcast OTA uses a plugin configurable endpoint, which is 14 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 Broadcast Bootloading plugins are not available in MAC mode due to the lack of endpoints.

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

Function Documentation

◆ emberAfPluginOtaBootloaderClientAbortImageDownload()

EmberAfOtaBootloaderStatus emberAfPluginOtaBootloaderClientAbortImageDownload ( uint8_t imageTag,
uint8_t applicationErrorStatus
)

Abort an ongoing image download process.

Parameters
[in] imageTag A 1-byte tag that identifies the image the client should no longer download.
[in] applicationErrorStatus A 1-byte error code reported to the server.
Returns
An EmberAfOtaBootloaderStatus value of:

◆ emberAfPluginOtaBootloaderClientImageDownloadCompleteCallback()

void emberAfPluginOtaBootloaderClientImageDownloadCompleteCallback ( EmberAfOtaBootloaderStatus status,
uint8_t imageTag,
uint32_t imageSize
)

A callback invoked on an OTA Bootloader Client to indicate that an image downlaod is completed.

Parameters
[in] status An EmberAfOtaBootloaderStatus 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_BROADCAST_BOOTLOADER_STATUS_SUCCESS .

◆ emberAfPluginOtaBootloaderClientIncomingImageSegmentCallback()

void emberAfPluginOtaBootloaderClientIncomingImageSegmentCallback ( 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 that the application elected to download, was received on the OTA Bootloader Client.

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.

◆ emberAfPluginOtaBootloaderClientIncomingRequestBootloadCallback()

bool emberAfPluginOtaBootloaderClientIncomingRequestBootloadCallback ( EmberNodeId serverId,
uint8_t imageTag,
uint32_t bootloadDelayMs,
uint8_t * applicationStatus
)

A callback invoked by the OTA Bootloader Client plugin to indicate that an OTA Bootloader 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.
[out] applicationStatus A 1-byte status set by the client application that is reported to the server.
Returns
Return true if the application accepted the request of bootloading the specified image at the requested time, false otherwise.

◆ emberAfPluginOtaBootloaderClientIncomingRequestStatusCallback()

void emberAfPluginOtaBootloaderClientIncomingRequestStatusCallback ( EmberNodeId serverId,
uint8_t applicationServerStatus,
uint8_t * applicationStatus
)

A callback invoked on the OTA Bootloader Client to indicate that an OTA Bootloader Server has requested the status of the client device.

Parameters
[in] serverId The ID of the server the request came from.
[in] applicationServerStatus The server application status, which was set by emberAfPluginBootloaderServerInitiateRequestTargetsStatus()
[out] applicationStatus A 1-byte status set by the client application that is reported to the server.

◆ emberAfPluginOtaBootloaderClientNewIncomingImageCallback()

bool emberAfPluginOtaBootloaderClientNewIncomingImageCallback ( EmberNodeId serverId,
EmberNodeId * alternateServerId,
uint8_t imageTag
)

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

Parameters
[in] serverId The node ID of the server that initiated the new image distribution process.
[out] alternateServerId This node ID can be set by the application to include a well-known alternate server. If this is set to a valid address, the client allows segments also from this alternate server. If this is set to EMBER_BROADCAST_ADDRESS , the client accepts segments with the same image tag from any server.
[in] imageTag A 1-byte tag that identifies the incoming image.
Returns
Return true to accept the image or false to ignore it.