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:
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.
Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
This notice may not be removed or altered from any source distribution.
/***************************************************************************/
#ifndef _OTA_UNICAST_BOOTLOADER_SERVER_H_
#define _OTA_UNICAST_BOOTLOADER_SERVER_H_
#include "ota-unicast-bootloader/ota-unicast-bootloader-protocol.h"
#include "ota-unicast-bootloader/ota-unicast-bootloader-types.h"
#define EMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_MAX_STACK_ERRORS 8
#define EMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_MAX_UNICAST_ERRORS 4
#define EMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_RESPONSE_TIMEOUT_MS 250
//------------------------------------------------------------------------------
// APIs
EmberAfOtaUnicastBootloaderStatus emberAfPluginOtaUnicastBootloaderServerInitiateImageDistribution(
EmberNodeId targetId,
uint32_t imageSize,
uint8_t imageTag
);
EmberAfOtaUnicastBootloaderStatus emberAfPluginUnicastBootloaderServerInitiateRequestTargetBootload(
uint32_t bootloadDelayMs,
uint8_t imageTag,
EmberNodeId targetId
);
EmberAfOtaUnicastBootloaderStatus emberAfPluginOtaUnicastBootloaderServerAbortCurrentProcess(
void
);
bool emberAfPluginOtaUnicastBootloaderServerGetImageSegmentCallback(
uint32_t startIndex,
uint32_t endIndex,
uint8_t imageTag,
uint8_t *imageSegment
);
void emberAfPluginOtaUnicastBootloaderServerImageDistributionCompleteCallback(
EmberAfOtaUnicastBootloaderStatus status
);
void emberAfPluginOtaUnicastBootloaderServerRequestTargetBootloadCompleteCallback(
EmberAfOtaUnicastBootloaderStatus status
);
#endif // _OTA_UNICAST_BOOTLOADER_SERVER_H_
Callbacks#
A callback invoked during an image distribution process to retrieve a contiguous segment of the image being distributed.
A callback invoked when the image distribution process is terminated.
A callback invoked when a bootload request process has completed.
Macros#
The number of consecutive stack message submission errors or stack related errors such as CSMA failures after which the plugin gives up.
The number of consecutive unicast attempts after which a target is declared unreachable. Legal values for this are in the [0,7] range.
The time in milliseconds after which the server gives up waiting for a response from a client.
Functions#
Initiate the image distribution process.
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.
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.
| [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.
159 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.hemberAfPluginOtaUnicastBootloaderServerImageDistributionCompleteCallback#
void emberAfPluginOtaUnicastBootloaderServerImageDistributionCompleteCallback (EmberAfOtaUnicastBootloaderStatus status)
A callback invoked when the image distribution process is terminated.
| [in] | status | An EmberAfOtaUnicastBootloaderStatus value of:
|
188 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.hemberAfPluginOtaUnicastBootloaderServerRequestTargetBootloadCompleteCallback#
void emberAfPluginOtaUnicastBootloaderServerRequestTargetBootloadCompleteCallback (EmberAfOtaUnicastBootloaderStatus status)
A callback invoked when a bootload request process has completed.
| [in] | status | An EmberAfOtaUnicastBootloaderStatus value of:
|
207 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.hMacro Definition Documentation#
EMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_MAX_STACK_ERRORS#
#define EMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_MAX_STACK_ERRORSValue:
8
The number of consecutive stack message submission errors or stack related errors such as CSMA failures after which the plugin gives up.
51 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.hEMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_MAX_UNICAST_ERRORS#
#define EMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_MAX_UNICAST_ERRORSValue:
4
The number of consecutive unicast attempts after which a target is declared unreachable. Legal values for this are in the [0,7] range.
57 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.hEMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_RESPONSE_TIMEOUT_MS#
#define EMBER_AF_PLUGIN_OTA_UNICAST_BOOTLOADER_SERVER_RESPONSE_TIMEOUT_MSValue:
250
The time in milliseconds after which the server gives up waiting for a response from a client.
63 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.hFunction Documentation#
emberAfPluginOtaUnicastBootloaderServerInitiateImageDistribution#
EmberAfOtaUnicastBootloaderStatus emberAfPluginOtaUnicastBootloaderServerInitiateImageDistribution (EmberNodeId targetId, uint32_t imageSize, uint8_t imageTag)
Initiate the image distribution process.
| [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
An EmberAfOtaUnicastBootloaderStatus value of:
EMBER_OTA_UNICAST_BOOTLOADER_STATUS_BUSY if an image distribution is already in progress
EMBER_OTA_UNICAST_BOOTLOADER_STATUS_INVALID_CALL if the given target or the image size is invalid
EMBER_OTA_UNICAST_BOOTLOADER_STATUS_SUCCESS if the image distribution was successfully initiated.
87 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.hemberAfPluginUnicastBootloaderServerInitiateRequestTargetBootload#
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.
| [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
An EmberAfOtaUnicastBootloaderStatus value of:
EMBER_OTA_UNICAST_BOOTLOADER_STATUS_SUCCESS if the plugin successfully started the process to request a target and initiate a bootload. If this is the case, the corresponding callback emberAfPluginOtaUnicastBootloaderServerRequestTargetBootloadCompleteCallback() is invoked when the request process is completed.
EMBER_OTA_UNICAST_BOOTLOADER_STATUS_INVALID_CALL if some of the passed parameters are invalid.
EMBER_OTA_UNICAST_BOOTLOADER_STATUS_BUSY if the server is currently involved in another over-the-air process.
116 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.hemberAfPluginOtaUnicastBootloaderServerAbortCurrentProcess#
EmberAfOtaUnicastBootloaderStatus emberAfPluginOtaUnicastBootloaderServerAbortCurrentProcess (void )
Abort the ongoing process, such as image distribution or bootload request.
| N/A |
Returns
An EmberAfOtaUnicastBootloaderStatus value of:
EMBER_OTA_UNICAST_BOOTLOADER_STATUS_SUCCESS if the current ongoing process was successfully aborted.
EMBER_OTA_UNICAST_BOOTLOADER_STATUS_INVALID_CALL if the server is not currently involved in any process.
131 of file /mnt/raid/workspaces/ws.SZ9MaSA5u/overlay/gsdk/protocol/flex/ota-unicast-bootloader/ota-unicast-bootloader-server/ota-unicast-bootloader-server.h