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"

Data Structures
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, const void *pData)
	OTA update complete callback function typedef. More...

typedef OtaJobParseErr_t(*	OtaCustomJobCallback_t) (const char *pcJSON, uint32_t ulMsgLen)
	Custom Job 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 }
	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 , OtaJobParseErrBusyWithExistingJob , 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 , OtaLastJobEvent = OtaJobEventStartTest }
	OTA Job callback events. More...

Functions
OtaErr_t	OTA_Init (OtaAppBuffer_t pOtaBuffer, OtaInterfaces_t pOtaInterfaces, const uint8_t *pThingName, OtaAppCallback_t OtaAppCallback)
	OTA Agent initialization function. More...

OtaState_t	OTA_Shutdown (uint32_t ticksToWait)
	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 (void *pUnused)
	OTA agent event processing loop. 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.

Detailed Description

OTA Agent Interface.

Macro Definition Documentation

◆ OTA_FILE_SIG_KEY_STR_MAX_LENGTH

#define OTA_FILE_SIG_KEY_STR_MAX_LENGTH 32

Maximum length of the file signature key.

Function Documentation

◆ OTA_Init()

OtaErr_t OTA_Init	(	OtaAppBuffer_t *	pOtaBuffer,
		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.

Parameters

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

Returns: OtaErr_t The state of the OTA Agent upon return from the OtaState_t enum. If the agent was successfully initialized and ready to operate, the state will be OtaAgentStateReady. Otherwise, it will be one of the other OtaState_t enum values.

◆ OTA_Shutdown()

OtaState_t OTA_Shutdown ( uint32_t ticksToWait )

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.

Parameters

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

Returns: One of the OTA agent states from the OtaState_t enum. A normal shutdown will return OtaAgentStateNotReady. Otherwise, refer to the OtaState_t enum for details.

◆ OTA_GetState()

OtaState_t OTA_GetState ( void )

Get the current state of the OTA agent.

Returns: The current state of the OTA agent.

◆ OTA_ActivateNewImage()

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.

Returns: OtaErrNone if successful, otherwise an error code prefixed with 'kOTA_Err_' from the list above.

◆ OTA_SetImageState()

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.

Parameters

[in] state The state to set of the OTA image.

Returns: OtaErrNone if successful, otherwise an error code prefixed with 'kOTA_Err_' from the list above.

◆ OTA_GetImageState()

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.

Returns: The state of the current context's OTA image.

◆ OTA_CheckForUpdate()

OtaErr_t OTA_CheckForUpdate ( void )

Request for the next available OTA job from the job service.

Returns: OtaErrNone if successful, otherwise an error code prefixed with 'kOTA_Err_' from the list above.

◆ OTA_Suspend()

OtaErr_t OTA_Suspend ( void )

Suspend OTA agent operations .

Returns: OtaErrNone if successful, otherwise an error code prefixed with 'kOTA_Err_' from the list above.

◆ OTA_Resume()

OtaErr_t OTA_Resume ( void )

Resume OTA agent operations .

Returns: OtaErrNone if successful, otherwise an error code prefixed with 'kOTA_Err_' from the list above.

◆ OTA_EventProcessingTask()

void OTA_EventProcessingTask ( 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.

Parameters

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

◆ OTA_SignalEvent()

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.

Parameters

[in] pEventMsg Event to be added to the queue

Returns: true If operation is successful, false If the event can not be added

◆ OTA_GetStatistics()

OtaErr_t OTA_GetStatistics ( OtaAgentStatistics_t * pStatistics )

Get the statistics of OTA message packets.

Packet statistics are:

Received: The number of OTA packets that have been received but not necessarily queued for processing by the OTA agent.
Queued: The number of OTA packets that have been queued for processing. This implies there was a free message queue entry so it can be passed to the agent for processing.
Processed: The number of OTA packets that have actually been processed.
Dropped: The number of OTA packets that have been dropped because of either no queue or at shutdown cleanup.

Note: Calling OTA_Init will reset this statistic.

Returns: OtaErrNone if the statistics can be received successfully.

◆ OTA_Err_strerror()

const char * OTA_Err_strerror ( OtaErr_t err )

Error code to string conversion for OTA errors.

Parameters

[in] err The error to convert to a string.

Returns: The string representation of the error.

◆ OTA_JobParse_strerror()

const char * OTA_JobParse_strerror ( OtaJobParseErr_t err )

Error code to string conversion for OTA Job Parsing errors.

Parameters

[in] err The error to convert to a string.

Returns: The string representation of the error.

◆ OTA_PalStatus_strerror()

const char * OTA_PalStatus_strerror ( OtaPalMainStatus_t status )

Status code to string conversion for OTA PAL status.

Parameters

[in] status The status to convert to a string.

Returns: The string representation of the status.

◆ OTA_OsStatus_strerror()

const char * OTA_OsStatus_strerror ( OtaOsStatus_t status )

Status code to string conversion for OTA OS status.

Parameters

[in] status The status to convert to a string.

Returns: The string representation of the status.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ OTA_FILE_SIG_KEY_STR_MAX_LENGTH

Function Documentation

◆ OTA_Init()

◆ OTA_Shutdown()

◆ OTA_GetState()

◆ OTA_ActivateNewImage()

◆ OTA_SetImageState()

◆ OTA_GetImageState()

◆ OTA_CheckForUpdate()

◆ OTA_Suspend()

◆ OTA_Resume()

◆ OTA_EventProcessingTask()

◆ OTA_SignalEvent()

◆ OTA_GetStatistics()

◆ OTA_Err_strerror()

◆ OTA_JobParse_strerror()

◆ OTA_PalStatus_strerror()

◆ OTA_OsStatus_strerror()