OTA Agent Interface. More...
#include <stdio.h>
#include <stdint.h>
#include "ota_private.h"
#include "ota_os_interface.h"
#include "ota_mqtt_interface.h"
#include "ota_http_interface.h"
#include "ota_platform_interface.h"
Go to the source code of this file.
Data Structures | |
struct | OtaJobDocument_t |
OTA Job document. More... | |
struct | OtaInterfaces_t |
OTA Interface for referencing different components. More... | |
struct | OtaAppBuffer_t |
OTA Application Buffer size information. More... | |
struct | OtaAgentContext_t |
The OTA agent is a singleton today. The structure keeps it nice and organized. More... | |
Macros | |
#define | CONST_STRLEN(s) ( ( ( uint32_t ) sizeof( s ) ) - 1UL ) |
Evaluates to the length of a constant string defined like 'static const char str[]= "xyz";. | |
#define | OTA_FILE_SIG_KEY_STR_MAX_LENGTH 32 |
Typedefs | |
typedef void(* | OtaAppCallback_t) (OtaJobEvent_t eEvent, void *pData) |
OTA update complete callback function typedef. More... | |
Enumerations | |
enum | OtaErr_t { OtaErrNone = 0 , OtaErrUninitialized , OtaErrPanic , OtaErrInvalidArg , OtaErrAgentStopped , OtaErrSignalEventFailed , OtaErrRequestJobFailed , OtaErrInitFileTransferFailed , OtaErrRequestFileBlockFailed , OtaErrCleanupControlFailed , OtaErrCleanupDataFailed , OtaErrUpdateJobStatusFailed , OtaErrJobParserError , OtaErrInvalidDataProtocol , OtaErrMomentumAbort , OtaErrDowngradeNotAllowed , OtaErrSameFirmwareVersion , OtaErrImageStateMismatch , OtaErrNoActiveJob , OtaErrUserAbort , OtaErrFailedToEncodeCbor , OtaErrFailedToDecodeCbor , OtaErrActivateFailed , OtaErrFileSizeOverflow } |
The OTA API return status. OTA agent error codes are in the upper 8 bits of the 32 bit OTA error word, OtaErr_t. More... | |
enum | OtaState_t { OtaAgentStateNoTransition = -1 , OtaAgentStateInit = 0 , OtaAgentStateReady , OtaAgentStateRequestingJob , OtaAgentStateWaitingForJob , OtaAgentStateCreatingFile , OtaAgentStateRequestingFileBlock , OtaAgentStateWaitingForFileBlock , OtaAgentStateClosingFile , OtaAgentStateSuspended , OtaAgentStateShuttingDown , OtaAgentStateStopped , OtaAgentStateAll } |
OTA Agent states. More... | |
enum | OtaJobParseErr_t { OtaJobParseErrUnknown = -1 , OtaJobParseErrNone = 0 , OtaJobParseErrNullJob , OtaJobParseErrUpdateCurrentJob , OtaJobParseErrZeroFileSize , OtaJobParseErrNonConformingJobDoc , OtaJobParseErrBadModelInitParams , OtaJobParseErrNoContextAvailable , OtaJobParseErrNoActiveJobs } |
OTA job document parser error codes. | |
enum | OtaJobEvent_t { OtaJobEventActivate = 0 , OtaJobEventFail = 1 , OtaJobEventStartTest = 2 , OtaJobEventProcessed = 3 , OtaJobEventSelfTestFailed = 4 , OtaJobEventParseCustomJob = 5 , OtaJobEventReceivedJob = 6 , OtaJobEventUpdateComplete = 7 , OtaJobEventNoActiveJob = 8 , OtaLastJobEvent = OtaJobEventStartTest } |
OTA Job callback events. More... | |
enum | OtaJobStatus_t { JobStatusInProgress = 0 , JobStatusFailed , JobStatusSucceeded , JobStatusRejected , JobStatusFailedWithVal , NumJobStatusMappings } |
Gives the status of the job operation. | |
Functions | |
OtaErr_t | OTA_Init (const OtaAppBuffer_t *pOtaBuffer, const OtaInterfaces_t *pOtaInterfaces, const uint8_t *pThingName, OtaAppCallback_t OtaAppCallback) |
OTA Agent initialization function. More... | |
OtaState_t | OTA_Shutdown (uint32_t ticksToWait, uint8_t unsubscribeFlag) |
Signal to the OTA Agent to shut down. More... | |
OtaState_t | OTA_GetState (void) |
Get the current state of the OTA agent. More... | |
OtaErr_t | OTA_ActivateNewImage (void) |
Activate the newest MCU image received via OTA. More... | |
OtaErr_t | OTA_SetImageState (OtaImageState_t state) |
Set the state of the current MCU image. More... | |
OtaImageState_t | OTA_GetImageState (void) |
Get the state of the currently running MCU image. More... | |
OtaErr_t | OTA_CheckForUpdate (void) |
Request for the next available OTA job from the job service. More... | |
OtaErr_t | OTA_Suspend (void) |
Suspend OTA agent operations . More... | |
OtaErr_t | OTA_Resume (void) |
Resume OTA agent operations . More... | |
void | OTA_EventProcessingTask (const void *pUnused) |
OTA agent event processing loop. More... | |
OtaState_t | OTA_EventProcess (void) |
OTA agent event process cycler. More... | |
bool | OTA_SignalEvent (const OtaEventMsg_t *const pEventMsg) |
Signal event to the OTA Agent task. More... | |
OtaErr_t | OTA_GetStatistics (OtaAgentStatistics_t *pStatistics) |
Get the statistics of OTA message packets. More... | |
const char * | OTA_Err_strerror (OtaErr_t err) |
Error code to string conversion for OTA errors. More... | |
const char * | OTA_JobParse_strerror (OtaJobParseErr_t err) |
Error code to string conversion for OTA Job Parsing errors. More... | |
const char * | OTA_PalStatus_strerror (OtaPalMainStatus_t status) |
Status code to string conversion for OTA PAL status. More... | |
const char * | OTA_OsStatus_strerror (OtaOsStatus_t status) |
Status code to string conversion for OTA OS status. More... | |
Variables | |
const char | OTA_JsonFileSignatureKey [OTA_FILE_SIG_KEY_STR_MAX_LENGTH] |
The OTA signature algorithm string is specified by the PAL. | |
OTA Agent Interface.
#define OTA_FILE_SIG_KEY_STR_MAX_LENGTH 32 |
Maximum length of the file signature key.
OtaErr_t OTA_Init | ( | const OtaAppBuffer_t * | pOtaBuffer, |
const OtaInterfaces_t * | pOtaInterfaces, | ||
const uint8_t * | pThingName, | ||
OtaAppCallback_t | OtaAppCallback | ||
) |
OTA Agent initialization function.
Initialize the OTA engine by starting the OTA Agent ("OTA Task") in the system. This function must be called with the connection client context before calling OTA_CheckForUpdate. Only one OTA Agent may exist.
[in] | pOtaBuffer | Buffers used by the agent to store different params. |
[in] | pOtaInterfaces | A pointer to the OS context. |
[in] | pThingName | A pointer to a C string holding the Thing name. |
[in] | OtaAppCallback | Static callback function for when an OTA job is complete. This function will have input of the state of the OTA image after download and during self-test. |
Example
OtaState_t OTA_Shutdown | ( | uint32_t | ticksToWait, |
uint8_t | unsubscribeFlag | ||
) |
Signal to the OTA Agent to shut down.
Signals the OTA agent task to shut down. The OTA agent will unsubscribe from all MQTT job notification topics, stop in progress OTA jobs, if any, and clear all resources.
OTA needs a processing task running OTA_EventProcessingTask to handle shutdown event, or OTA will shutdown after the processing task is created and scheduled.
[in] | ticksToWait | The number of ticks to wait for the OTA Agent to complete the shutdown process. If this is set to zero, the function will return immediately without waiting. The actual state is returned to the caller. The agent does not sleep for this while but used for busy looping. |
[in] | unsubscribeFlag | Flag to indicate if unsubscribe operations should be performed from the job topics when shutdown is called. If the flag is 0 then unsubscribe operations are not called for job topics If application requires it to be unsubscribed from the job topics then flag must be set to 1 when calling OTA_Shutdown. |
Example
OtaState_t OTA_GetState | ( | void | ) |
Get the current state of the OTA agent.
Example Check if OTA agent is in suspended state.
OtaErr_t OTA_ActivateNewImage | ( | void | ) |
Activate the newest MCU image received via OTA.
This function should reset the MCU and cause a reboot of the system to execute the newly updated firmware. It should be called by the user code sometime after the OtaJobEventActivate event is passed to the users application via the OTA Job Complete Callback mechanism. Refer to the OTA_Init function for more information about configuring the callback.
Example
OtaErr_t OTA_SetImageState | ( | OtaImageState_t | state | ) |
Set the state of the current MCU image.
The states are OtaImageStateTesting, OtaImageStateAccepted, OtaImageStateAborted or OtaImageStateRejected; see OtaImageState_t documentation. This will update the status of the current image and publish to the active job status topic.
[in] | state | The state to set of the OTA image. |
Example Set image state to reflect new image is accepted in application callback.
OtaImageState_t OTA_GetImageState | ( | void | ) |
Get the state of the currently running MCU image.
The states are OtaImageStateTesting, OtaImageStateAccepted, OtaImageStateAborted or OtaImageStateRejected; see OtaImageState_t documentation.
OtaErr_t OTA_CheckForUpdate | ( | void | ) |
Request for the next available OTA job from the job service.
OtaErr_t OTA_Suspend | ( | void | ) |
Suspend OTA agent operations .
Example Suspend the OTA agent when a network error occurs.
OtaErr_t OTA_Resume | ( | void | ) |
Resume OTA agent operations .
Example Resume the OTA agent after the network errors are resolved.
void OTA_EventProcessingTask | ( | const void * | pUnused | ) |
OTA agent event processing loop.
This is the main event loop to handle events for OTA update and needs to be called by the application task. This loop will continue to handle and execute events received for OTA Update until this tasks is terminated by the application.
[in] | pUnused | Can be used to pass down functionality to the agent task, Unused for now. This can be a function pointer that executes as the first routine when the event loop starts. |
For a Posix based reference of creating a thread with this task, please see the demos in AWS IoT Embedded C SDK repository.
OtaState_t OTA_EventProcess | ( | void | ) |
OTA agent event process cycler.
This is the main agent event handler for OTA update and needs to be called repeatedly by an application task. This is functionally equivalent to OTA_EventProcessingTask, except instead of forever looping internally, the user is responsible for periodically calling this function.
bool OTA_SignalEvent | ( | const OtaEventMsg_t *const | pEventMsg | ) |
Signal event to the OTA Agent task.
This function adds the event to the back of event queue and used by internal OTA modules to signal agent task.
[in] | pEventMsg | Event to be added to the queue |
Example Signal OTA agent that a new file block has been received over the http connection.
OtaErr_t OTA_GetStatistics | ( | OtaAgentStatistics_t * | pStatistics | ) |
Get the statistics of OTA message packets.
Packet statistics are:
Example
const char * OTA_Err_strerror | ( | OtaErr_t | err | ) |
Error code to string conversion for OTA errors.
[in] | err | The error to convert to a string. |
const char * OTA_JobParse_strerror | ( | OtaJobParseErr_t | err | ) |
Error code to string conversion for OTA Job Parsing errors.
[in] | err | The error to convert to a string. |
const char * OTA_PalStatus_strerror | ( | OtaPalMainStatus_t | status | ) |
Status code to string conversion for OTA PAL status.
[in] | status | The status to convert to a string. |
const char * OTA_OsStatus_strerror | ( | OtaOsStatus_t | status | ) |
Status code to string conversion for OTA OS status.
[in] | status | The status to convert to a string. |