Ota Unicast Bootloader Server Plugin#

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

Callbacks#

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

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

void

A callback invoked when the image distribution process is terminated.

void

A callback invoked when a bootload request process has completed.

Functions#

emberAfPluginOtaUnicastBootloaderServerInitiateImageDistribution(EmberNodeId targetId, uint32_t imageSize, uint8_t imageTag)

Initiate the image distribution process.

emberAfPluginUnicastBootloaderServerInitiateRequestTargetBootload(uint32_t bootloadDelayMs, uint8_t imageTag, EmberNodeId targetId)

Request a target device to initiate the bootload of a received image at some point in the future.

Abort the ongoing process, such as image distribution or bootload request.

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.

Callbacks Documentation#

emberAfPluginOtaUnicastBootloaderServerGetImageSegmentCallback#

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

A callback invoked 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 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 server will abort the ongoing distribution process.


Definition at line 159 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.h

emberAfPluginOtaUnicastBootloaderServerImageDistributionCompleteCallback#

void emberAfPluginOtaUnicastBootloaderServerImageDistributionCompleteCallback (EmberAfOtaUnicastBootloaderStatus status)

A callback invoked when the image distribution process is terminated.

Parameters
[in]status

An EmberAfOtaUnicastBootloaderStatus value of:


Definition at line 188 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.h

emberAfPluginOtaUnicastBootloaderServerRequestTargetBootloadCompleteCallback#

void emberAfPluginOtaUnicastBootloaderServerRequestTargetBootloadCompleteCallback (EmberAfOtaUnicastBootloaderStatus status)

A callback invoked when a bootload request process has completed.

Parameters
[in]status

An EmberAfOtaUnicastBootloaderStatus value of:


Definition at line 207 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.h

Function Documentation#

emberAfPluginOtaUnicastBootloaderServerInitiateImageDistribution#

EmberAfOtaUnicastBootloaderStatus emberAfPluginOtaUnicastBootloaderServerInitiateImageDistribution (EmberNodeId targetId, uint32_t imageSize, uint8_t imageTag)

Initiate the image distribution process.

Parameters
[in]targetId

The node ID of the target.

[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.

Returns


Definition at line 87 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.h

emberAfPluginUnicastBootloaderServerInitiateRequestTargetBootload#

EmberAfOtaUnicastBootloaderStatus emberAfPluginUnicastBootloaderServerInitiateRequestTargetBootload (uint32_t bootloadDelayMs, uint8_t imageTag, EmberNodeId targetId)

Request a target device to initiate the bootload of a received image at some point in the future.

Parameters
[in]bootloadDelayMs

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

[in]imageTag

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

[in]targetId

The node ID of the target.

Returns


Definition at line 116 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.h

emberAfPluginOtaUnicastBootloaderServerAbortCurrentProcess#

EmberAfOtaUnicastBootloaderStatus emberAfPluginOtaUnicastBootloaderServerAbortCurrentProcess (void )

Abort the ongoing process, such as image distribution or bootload request.

Parameters
N/A

Returns


Definition at line 131 of file /mnt/raid/workspaces/ws.Q8qnkBLX2/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.h

Macro Definition Documentation#

EMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_MAX_STACK_ERRORS#

#define EMBER_AF_PLUGIN_OTA_UNICAST_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.Q8qnkBLX2/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.h

EMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_MAX_UNICAST_ERRORS#

#define EMBER_AF_PLUGIN_OTA_UNICAST_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.Q8qnkBLX2/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.h

EMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_RESPONSE_TIMEOUT_MS#

#define EMBER_AF_PLUGIN_OTA_UNICAST_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.Q8qnkBLX2/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.h