Ota Broadcast Bootloader Server Plugin#

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

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-server.h and ota-broadcast-bootloader-server.c for source code.

Callbacks#

bool
emberAfPluginOtaBootloaderServerGetImageSegmentCallback(uint32_t startIndex, uint32_t endIndex, uint8_t imageTag, uint8_t *imageSegment)

A callback invoked on the OTA Bootloader Server during an image distribution process to retrieve a contiguous segment of the image being distributed.

void

A callback invoked on the OTA Bootloader Server when the image distribution process is terminated. The application can use the emberAfPluginBootloaderServerGetTargetStatus() API to retrieve the status reported by each target device.

void

A callback invoked on the OTA Bootloader Server when bootload request process has completed. Within this callback, the application should use the emberAfPluginBootloaderServerGetTargetStatus() API to retrieve the status and application status reported by each target.

void

A callback invoked on the OTA Bootloader Server when a bootload request process has completed. Within this callback, the application should use the emberAfPluginBootloaderServerGetTargetStatus() API to retrieve the status and the application status reported by each target.

Functions#

emberAfPluginOtaBootloaderServerInitiateImageDistribution(uint32_t imageSize, uint8_t imageTag, EmberNodeId *targetList, uint16_t targetListLength)

Initiate the image distribution process. The application can use the emberAfPluginBootloaderServerGetTargetStatus() API at any time during the image distribution process to check the status of each target.

emberAfPluginBootloaderServerInitiateRequestTargetsStatus(EmberNodeId *targetList, uint16_t targetListLength, uint8_t applicationServerStatus)

Initiate the process to request the status of a set of target devices. The application can use the emberAfPluginBootloaderServerGetTargetStatus() API at any time during the target status request process to check the status of each target.

emberAfPluginBootloaderServerInitiateRequestTargetsBootload(uint32_t bootloadDelayMs, uint8_t imageTag, EmberNodeId *targetList, uint16_t targetListLength)

Start the process where a server requests a set of target devices to initiate the bootload of a received image at some point in the future. The application can use the emberAfPluginBootloaderServerGetTargetStatus() API at any time during the bootload request process to check the status of each target.

emberAfPluginBootloaderServerGetTargetStatus(EmberNodeId targetId, uint8_t *applicationTargetStatus)

Retrieve the locally stored status of an individual target in the distribution list. The locally stored status can be updated by calling emberAfPluginBootloaderServerInitiateRequestTargetsStatus().

Abort the ongoing process (image distribution, status request or bootload request). Note that aborting a bootload request process likely results in some targets performing the bootload while some others do not.

Macros#

#define

The number of consecutive stack message submission errors or stack-related errors, such as CSMA failures, after which the plugin gives up.

#define

The number of consecutive unicast attempts after which a target is declared unreachable. Legal values for this are in the [0,7] range.

#define

The time in milliseconds after which the server gives up waiting for a response from a client.

#define

The maximum number of image broadcast rounds the server performs before declaring an image distribution process failed.

Callbacks Documentation#

emberAfPluginOtaBootloaderServerGetImageSegmentCallback#

bool emberAfPluginOtaBootloaderServerGetImageSegmentCallback (uint32_t startIndex, uint32_t endIndex, uint8_t imageTag, uint8_t * imageSegment)

A callback invoked on the OTA Bootloader Server during an image distribution process to retrieve a contiguous segment of the image being distributed.

Parameters
[in]startIndex

The index of the first byte the application should copy into the passed array.

[in]endIndex

The index of the last byte the application should copy into the passed array.

[in]imageTag

A 1-byte tag of the image for which a segment is being requested.

[out]imageSegment

An array of (endIndex - startIndex + 1) length to which the application should copy the requested image segment.

Returns

  • A boolean indicating whether the application successfully copied the requested bytes into the passed array. If the application returns false, the OTA Server plugin aborts the ongoing distribution process.


Definition at line 267 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

emberAfPluginOtaBootloaderServerImageDistributionCompleteCallback#

void emberAfPluginOtaBootloaderServerImageDistributionCompleteCallback (EmberAfOtaBootloaderStatus status)

A callback invoked on the OTA Bootloader Server when the image distribution process is terminated. The application can use the emberAfPluginBootloaderServerGetTargetStatus() API to retrieve the status reported by each target device.

Parameters
[in]status

An EmberAfOtaBootloaderStatus value of:


Definition at line 298 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

emberAfPluginBootloaderServerRequestTargetsStatusCompleteCallback#

void emberAfPluginBootloaderServerRequestTargetsStatusCompleteCallback (EmberAfOtaBootloaderStatus status)

A callback invoked on the OTA Bootloader Server when bootload request process has completed. Within this callback, the application should use the emberAfPluginBootloaderServerGetTargetStatus() API to retrieve the status and application status reported by each target.

Parameters
[in]status

An EmberAfOtaBootloaderStatus value of:


Definition at line 317 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

emberAfPluginBootloaderServerRequestTargetsBootloadCompleteCallback#

void emberAfPluginBootloaderServerRequestTargetsBootloadCompleteCallback (EmberAfOtaBootloaderStatus status)

A callback invoked on the OTA Bootloader Server when a bootload request process has completed. Within this callback, the application should use the emberAfPluginBootloaderServerGetTargetStatus() API to retrieve the status and the application status reported by each target.

Parameters
[in]status

An EmberAfOtaBootloaderStatus value of:


Definition at line 336 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

Function Documentation#

emberAfPluginOtaBootloaderServerInitiateImageDistribution#

EmberAfOtaBootloaderStatus emberAfPluginOtaBootloaderServerInitiateImageDistribution (uint32_t imageSize, uint8_t imageTag, EmberNodeId * targetList, uint16_t targetListLength)

Initiate the image distribution process. The application can use the emberAfPluginBootloaderServerGetTargetStatus() API at any time during the image distribution process to check the status of each target.

Parameters
[in]imageSize

The image size in bytes to be distributed.

[in]imageTag

A 1-byte tag that will be embedded in the server-to-client over-the-air messages. The application can use the image tag for versioning purposes and/or for distinguishing between different image types.

[out]targetList

An array of EmberNodeId indicating the node IDs of the target devices.

[in]targetListLength

The length of the passed targetList

Returns


Definition at line 104 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

emberAfPluginBootloaderServerInitiateRequestTargetsStatus#

EmberAfOtaBootloaderStatus emberAfPluginBootloaderServerInitiateRequestTargetsStatus (EmberNodeId * targetList, uint16_t targetListLength, uint8_t applicationServerStatus)

Initiate the process to request the status of a set of target devices. The application can use the emberAfPluginBootloaderServerGetTargetStatus() API at any time during the target status request process to check the status of each target.

Parameters
[in]targetList

An array of EmberNodeId indicating the node IDs of the target devices that are queried for their status.

[in]targetListLength

The length of the passed targetlist.

[in]applicationServerStatus

The application can set a status here which will be sent to the clients in emberAfPluginOtaBootloaderClientIncomingRequestStatusCallback()

Returns


Definition at line 135 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

emberAfPluginBootloaderServerInitiateRequestTargetsBootload#

EmberAfOtaBootloaderStatus emberAfPluginBootloaderServerInitiateRequestTargetsBootload (uint32_t bootloadDelayMs, uint8_t imageTag, EmberNodeId * targetList, uint16_t targetListLength)

Start the process where a server requests a set of target devices to initiate the bootload of a received image at some point in the future. The application can use the emberAfPluginBootloaderServerGetTargetStatus() API at any time during the bootload request process to check the status of each target.

Parameters
[in]bootloadDelayMs

The delay in milliseconds after which all the targets should perform an image bootload.

[in]imageTag

A 1-byte tag that identifies the image to be bootloaded at the target devices.

[in]targetList

An array of EmberNodeId indicating the node IDs of the target devices that is requested to bootload an image.

[in]targetListLength

The length of the passed targetlist.

Returns


Definition at line 167 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

emberAfPluginBootloaderServerGetTargetStatus#

EmberAfOtaBootloaderTargetStatus emberAfPluginBootloaderServerGetTargetStatus (EmberNodeId targetId, uint8_t * applicationTargetStatus)

Retrieve the locally stored status of an individual target in the distribution list. The locally stored status can be updated by calling emberAfPluginBootloaderServerInitiateRequestTargetsStatus().

Parameters
[in]targetId

The node ID of the target device whose status is being requested.

[out]applicationTargetStatus

The application status reported by the client side application. This parameter is valid only for certain return status codes (see return status documentation).

Returns


Definition at line 223 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

emberAfPluginOtaBootloaderServerAbortCurrentProcess#

EmberAfOtaBootloaderStatus emberAfPluginOtaBootloaderServerAbortCurrentProcess (void )

Abort the ongoing process (image distribution, status request or bootload request). Note that aborting a bootload request process likely results in some targets performing the bootload while some others do not.

Parameters
N/A

Returns


Definition at line 237 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

Macro Definition Documentation#

EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_MAX_STACK_ERRORS#

#define EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_MAX_STACK_ERRORS
Value:
8

The number of consecutive stack message submission errors or stack-related errors, such as CSMA failures, after which the plugin gives up.


Definition at line 51 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_MAX_UNICAST_ERRORS#

#define EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_MAX_UNICAST_ERRORS
Value:
4

The number of consecutive unicast attempts after which a target is declared unreachable. Legal values for this are in the [0,7] range.


Definition at line 57 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_RESPONSE_TIMEOUT_MS#

#define EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_RESPONSE_TIMEOUT_MS
Value:
250

The time in milliseconds after which the server gives up waiting for a response from a client.


Definition at line 63 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h

EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_MAX_BROADCAST_ROUNDS#

#define EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_MAX_BROADCAST_ROUNDS
Value:
5

The maximum number of image broadcast rounds the server performs before declaring an image distribution process failed.


Definition at line 69 of file /mnt/raid/workspaces/ws.Iq463TQni/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h