License#

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

SPDX-License-Identifier: Zlib

The licensor of this software is Silicon Laboratories Inc.

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

  3. This notice may not be removed or altered from any source distribution.

/***************************************************************************/
#ifndef _OTA_BROADCAST_BOOTLOADER_SERVER_H_
#define _OTA_BROADCAST_BOOTLOADER_SERVER_H_

#include "ota-broadcast-bootloader/ota-broadcast-bootloader-protocol.h"
#include "ota-broadcast-bootloader/ota-broadcast-bootloader-types.h"

#define EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_MAX_STACK_ERRORS       8

#define EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_MAX_UNICAST_ERRORS     4

#define EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_RESPONSE_TIMEOUT_MS  250

#define EMBER_AF_PLUGIN_OTA_BROADCAST_BOOTLOADER_SERVER_MAX_BROADCAST_ROUNDS   5

//------------------------------------------------------------------------------
// APIs

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

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

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

EmberAfOtaBootloaderTargetStatus emberAfPluginBootloaderServerGetTargetStatus(EmberNodeId targetId,
                                                                              uint8_t *applicationTargetStatus);

EmberAfOtaBootloaderStatus emberAfPluginOtaBootloaderServerAbortCurrentProcess(void);

//------------------------------------------------------------------------------
// Callbacks

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

void emberAfPluginOtaBootloaderServerImageDistributionCompleteCallback(EmberAfOtaBootloaderStatus status);

void emberAfPluginBootloaderServerRequestTargetsStatusCompleteCallback(EmberAfOtaBootloaderStatus status);

void emberAfPluginBootloaderServerRequestTargetsBootloadCompleteCallback(EmberAfOtaBootloaderStatus status);

#endif // _OTA_BROADCAST_BOOTLOADER_SERVER_H_

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.

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.

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.

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.tfWcRzYcf/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.tfWcRzYcf/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.tfWcRzYcf/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.tfWcRzYcf/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.tfWcRzYcf/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.tfWcRzYcf/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.tfWcRzYcf/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.tfWcRzYcf/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.tfWcRzYcf/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.tfWcRzYcf/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.tfWcRzYcf/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.tfWcRzYcf/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.tfWcRzYcf/overlay/gsdk/protocol/flex/ota-broadcast-bootloader/ota-broadcast-bootloader-server/ota-broadcast-bootloader-server.h