OTA Agent Interface. More...

#include <stdio.h>
#include <stdbool.h>
#include "FreeRTOS.h"
#include "timers.h"

Data Structures
struct	Sig256_t

struct	OTA_FileContext_t
	OTA File Context Information. More...

struct	OTA_ConnectionContext_t
	OTA Connection context. More...

struct	OTA_PAL_Callbacks_t
	OTA PAL callback structure. More...

Macros
#define	CONST_STRLEN(s) ( ( ( uint32_t ) sizeof( s ) ) - 1UL )

#define	OTA_FILE_SIG_KEY_STR_MAX_LENGTH 32

#define	OTA_DEBUG_LOG_LEVEL 1
	Special OTA Agent printing definition.

#define	DEFINE_OTA_METHOD_NAME(name)

#define	OTA_LOG_L1 vLoggingPrintf

#define	DEFINE_OTA_METHOD_NAME_L2(name)

#define	OTA_LOG_L2(...)

#define	DEFINE_OTA_METHOD_NAME_L3(name)

#define	OTA_LOG_L3(...)

#define	kOTA_MaxSignatureSize 256 /* Max bytes supported for a file signature (2048 bit RSA is 256 bytes). */

#define	kOTA_Err_Panic 0xfe000000UL
	OTA Agent error codes returned by OTA agent API. More...

#define	kOTA_Err_Uninitialized 0xff000000UL

#define	kOTA_Err_None 0x00000000UL

#define	kOTA_Err_SignatureCheckFailed 0x01000000UL

#define	kOTA_Err_BadSignerCert 0x02000000UL

#define	kOTA_Err_OutOfMemory 0x03000000UL

#define	kOTA_Err_ActivateFailed 0x04000000UL

#define	kOTA_Err_CommitFailed 0x05000000UL

#define	kOTA_Err_RejectFailed 0x06000000UL

#define	kOTA_Err_AbortFailed 0x07000000UL

#define	kOTA_Err_PublishFailed 0x08000000UL

#define	kOTA_Err_BadImageState 0x09000000UL

#define	kOTA_Err_NoActiveJob 0x0a000000UL

#define	kOTA_Err_NoFreeContext 0x0b000000UL

#define	kOTA_Err_HTTPInitFailed 0x0c000000UL

#define	kOTA_Err_HTTPRequestFailed 0x0d000000UL

#define	kOTA_Err_FileAbort 0x10000000UL

#define	kOTA_Err_FileClose 0x11000000UL

#define	kOTA_Err_RxFileCreateFailed 0x12000000UL

#define	kOTA_Err_BootInfoCreateFailed 0x13000000UL

#define	kOTA_Err_RxFileTooLarge 0x14000000UL

#define	kOTA_Err_NullFilePtr 0x20000000UL

#define	kOTA_Err_MomentumAbort 0x21000000UL

#define	kOTA_Err_DowngradeNotAllowed 0x22000000UL

#define	kOTA_Err_SameFirmwareVersion 0x23000000UL

#define	kOTA_Err_JobParserError 0x24000000UL

#define	kOTA_Err_FailedToEncodeCBOR 0x25000000UL

#define	kOTA_Err_ImageStateMismatch 0x26000000UL

#define	kOTA_Err_GenericIngestError 0x27000000UL

#define	kOTA_Err_UserAbort 0x28000000UL

#define	kOTA_Err_ResetNotSupported 0x29000000UL

#define	kOTA_Err_TopicTooLarge 0x2a000000UL

#define	kOTA_Err_SelfTestTimerFailed 0x2b000000UL

#define	kOTA_Err_EventQueueSendFailed 0x2c000000UL

#define	kOTA_Err_InvalidDataProtocol 0x2d000000UL

#define	kOTA_Err_OTAAgentStopped 0x2e000000UL

#define	kOTA_PAL_ErrMask 0xffffffUL

#define	kOTA_Main_ErrMask 0xff000000UL

#define	kOTA_MainErrShiftDownBits 24U

Typedefs
typedef struct OTA_FileContext	OTA_FileContext_t

typedef uint32_t	OTA_Err_t
	OTA Error type.

typedef void(*	pxOTACompleteCallback_t) (OTA_JobEvent_t eEvent)
	OTA update complete callback function typedef. More...

typedef OTA_Err_t(*	pxOTAPALAbortCallback_t) (OTA_FileContext_t *const C)
	OTA abort callback function typedef. More...

typedef OTA_Err_t(*	pxOTAPALActivateNewImageCallback_t) (uint32_t ulServerFileID)
	OTA new image received callback function typedef. More...

typedef OTA_Err_t(*	pxOTAPALCloseFileCallback_t) (OTA_FileContext_t *const C)
	OTA close file callback function typedef. More...

typedef OTA_Err_t(*	pxOTAPALCreateFileForRxCallback_t) (OTA_FileContext_t *const C)
	OTA create file to store received data callback function typedef. More...

typedef OTA_PAL_ImageState_t(*	pxOTAPALGetPlatformImageStateCallback_t) (uint32_t ulServerFileID)
	OTA Get Platform Image State callback function typedef. More...

typedef OTA_Err_t(*	pxOTAPALResetDeviceCallback_t) (uint32_t ulServerFileID)
	OTA Reset Device callback function typedef. More...

typedef OTA_Err_t(*	pxOTAPALSetPlatformImageStateCallback_t) (uint32_t ulServerFileID, OTA_ImageState_t eState)
	OTA Set Platform Image State callback function typedef. More...

typedef int16_t(*	pxOTAPALWriteBlockCallback_t) (OTA_FileContext_t const C, uint32_t iOffset, uint8_t const pacData, uint32_t iBlockSize)
	OTA Write Block callback function typedef. More...

typedef OTA_JobParseErr_t(*	pxOTACustomJobCallback_t) (const char *pcJSON, uint32_t ulMsgLen)
	Custom Job callback function typedef. More...

Enumerations
enum	OTA_State_t { eOTA_AgentState_NoTransition = -1, eOTA_AgentState_Init = 0, eOTA_AgentState_Ready, eOTA_AgentState_RequestingJob, eOTA_AgentState_WaitingForJob, eOTA_AgentState_CreatingFile, eOTA_AgentState_RequestingFileBlock, eOTA_AgentState_WaitingForFileBlock, eOTA_AgentState_ClosingFile, eOTA_AgentState_Suspended, eOTA_AgentState_ShuttingDown, eOTA_AgentState_Stopped, eOTA_AgentState_All }
	OTA Agent states. More...

enum	OTA_Event_t { eOTA_AgentEvent_Start = 0, eOTA_AgentEvent_StartSelfTest, eOTA_AgentEvent_RequestJobDocument, eOTA_AgentEvent_ReceivedJobDocument, eOTA_AgentEvent_CreateFile, eOTA_AgentEvent_RequestFileBlock, eOTA_AgentEvent_ReceivedFileBlock, eOTA_AgentEvent_RequestTimer, eOTA_AgentEvent_CloseFile, eOTA_AgentEvent_Suspend, eOTA_AgentEvent_Resume, eOTA_AgentEvent_UserAbort, eOTA_AgentEvent_Shutdown, eOTA_AgentEvent_Max }
	OTA Agent Events. More...

enum	OTA_PAL_ImageState_t { eOTA_PAL_ImageState_Unknown = 0, eOTA_PAL_ImageState_PendingCommit, eOTA_PAL_ImageState_Valid, eOTA_PAL_ImageState_Invalid }
	OTA Platform Image State. More...

enum	OTA_JobParseErr_t { eOTA_JobParseErr_Unknown = -1, eOTA_JobParseErr_None = 0, eOTA_JobParseErr_BusyWithExistingJob, eOTA_JobParseErr_NullJob, eOTA_JobParseErr_UpdateCurrentJob, eOTA_JobParseErr_ZeroFileSize, eOTA_JobParseErr_NonConformingJobDoc, eOTA_JobParseErr_BadModelInitParams, eOTA_JobParseErr_NoContextAvailable, eOTA_JobParseErr_NoActiveJobs }
	OTA job document parser error codes.

enum	OTA_JobEvent_t { eOTA_JobEvent_Activate = 0, eOTA_JobEvent_Fail = 1, eOTA_JobEvent_StartTest = 2, eOTA_LastJobEvent = eOTA_JobEvent_StartTest }
	OTA Job callback events. More...

enum	OTA_ImageState_t { eOTA_ImageState_Unknown = 0, eOTA_ImageState_Testing = 1, eOTA_ImageState_Accepted = 2, eOTA_ImageState_Rejected = 3, eOTA_ImageState_Aborted = 4, eOTA_LastImageState = eOTA_ImageState_Aborted }
	OTA Image states. More...

Functions
OTA_State_t	OTA_AgentInit (void pvConnectionContext, const uint8_t pucThingName, pxOTACompleteCallback_t xFunc, TickType_t xTicksToWait)
	OTA Agent initialization function. More...

OTA_State_t	OTA_AgentInit_internal (void pvConnectionContext, const uint8_t pucThingName, const OTA_PAL_Callbacks_t *pxCallbacks, TickType_t xTicksToWait)
	Internal OTA Agent initialization function. More...

OTA_State_t	OTA_AgentShutdown (TickType_t xTicksToWait)
	Signal to the OTA Agent to shut down. More...

OTA_State_t	OTA_GetAgentState (void)
	Get the current state of the OTA agent. More...

OTA_Err_t	OTA_ActivateNewImage (void)
	Activate the newest MCU image received via OTA. More...

OTA_Err_t	OTA_SetImageState (OTA_ImageState_t eState)
	Set the state of the current MCU image. More...

OTA_ImageState_t	OTA_GetImageState (void)
	Get the state of the currently running MCU image. More...

OTA_Err_t	OTA_CheckForUpdate (void)
	Request for the next available OTA job from the job service. More...

OTA_Err_t	OTA_Suspend (void)
	Suspend OTA agent operations . More...

OTA_Err_t	OTA_Resume (void *pxConnection)
	Resume OTA agent operations . More...

uint32_t	OTA_GetPacketsReceived (void)
	Get the number of OTA message packets received by the OTA agent. More...

uint32_t	OTA_GetPacketsQueued (void)
	Get the number of OTA message packets queued by the OTA agent. More...

uint32_t	OTA_GetPacketsProcessed (void)
	Get the number of OTA message packets processed by the OTA agent. More...

uint32_t	OTA_GetPacketsDropped (void)
	Get the number of OTA message packets dropped by the OTA agent. More...

Variables
const char	cOTA_JSON_FileSignatureKey [OTA_FILE_SIG_KEY_STR_MAX_LENGTH]

Detailed Description

OTA Agent Interface.

Macro Definition Documentation

◆ DEFINE_OTA_METHOD_NAME

#define DEFINE_OTA_METHOD_NAME ( name )

Value:

static const char OTA_METHOD_NAME[] = name; \

( void ) OTA_METHOD_NAME;

◆ kOTA_MaxSignatureSize

#define kOTA_MaxSignatureSize 256 /* Max bytes supported for a file signature (2048 bit RSA is 256 bytes). */

@structs{ota,OTA library}

◆ kOTA_Err_Panic

#define kOTA_Err_Panic 0xfe000000UL

OTA Agent error codes returned by OTA agent API.

@constantspage{ota,OTA library}

OTA Error Codes

#define kOTA_Err_Panic                   0xfe000000UL     
#define kOTA_Err_Uninitialized           0xff000000UL     
#define kOTA_Err_None                    0x00000000UL
#define kOTA_Err_SignatureCheckFailed    0x01000000UL     
#define kOTA_Err_BadSignerCert           0x02000000UL     
#define kOTA_Err_OutOfMemory             0x03000000UL     
#define kOTA_Err_ActivateFailed          0x04000000UL     
#define kOTA_Err_CommitFailed            0x05000000UL     
#define kOTA_Err_RejectFailed            0x06000000UL     
#define kOTA_Err_AbortFailed             0x07000000UL     
#define kOTA_Err_PublishFailed           0x08000000UL     
#define kOTA_Err_BadImageState           0x09000000UL     
#define kOTA_Err_NoActiveJob             0x0a000000UL     
#define kOTA_Err_NoFreeContext           0x0b000000UL     
#define kOTA_Err_HTTPInitFailed          0x0c000000UL     
#define kOTA_Err_HTTPRequestFailed       0x0d000000UL     
#define kOTA_Err_FileAbort               0x10000000UL     
#define kOTA_Err_FileClose               0x11000000UL     
#define kOTA_Err_RxFileCreateFailed      0x12000000UL     
#define kOTA_Err_BootInfoCreateFailed    0x13000000UL     
#define kOTA_Err_RxFileTooLarge          0x14000000UL     
#define kOTA_Err_NullFilePtr             0x20000000UL     
#define kOTA_Err_MomentumAbort           0x21000000UL     
#define kOTA_Err_DowngradeNotAllowed     0x22000000UL     
#define kOTA_Err_SameFirmwareVersion     0x23000000UL     
#define kOTA_Err_JobParserError          0x24000000UL     
#define kOTA_Err_FailedToEncodeCBOR      0x25000000UL     
#define kOTA_Err_ImageStateMismatch      0x26000000UL     
#define kOTA_Err_GenericIngestError      0x27000000UL     
#define kOTA_Err_UserAbort               0x28000000UL     
#define kOTA_Err_ResetNotSupported       0x29000000UL     
#define kOTA_Err_TopicTooLarge           0x2a000000UL     
#define kOTA_Err_SelfTestTimerFailed     0x2b000000UL     
#define kOTA_Err_EventQueueSendFailed    0x2c000000UL     
#define kOTA_Err_InvalidDataProtocol     0x2d000000UL     
#define kOTA_Err_OTAAgentStopped         0x2e000000UL     

OTA agent error codes are in the upper 8 bits of the 32 bit OTA error word, OTA_Err_t.

OTA Error Code Helper constants

OTA Error code helper constant for extracting the error code from the OTA error returned.

#define kOTA_PAL_ErrMask             0xffffffUL       
#define kOTA_Main_ErrMask            0xff000000UL     
#define kOTA_MainErrShiftDownBits    24U              

OTA error codes consist of an agent code in the upper 8 bits of a 32 bit word and sometimes merged with a platform specific code in the lower 24 bits. You must refer to the platform PAL layer in use to determine the meaning of the lower 24 bits. Unrecoverable FW error. Probably should log error and reboot.

◆ kOTA_Err_Uninitialized

#define kOTA_Err_Uninitialized 0xff000000UL

The error code has not yet been set by a logic path.

◆ kOTA_Err_SignatureCheckFailed

#define kOTA_Err_SignatureCheckFailed 0x01000000UL

The signature check failed for the specified file.

◆ kOTA_Err_BadSignerCert

#define kOTA_Err_BadSignerCert 0x02000000UL

The signer certificate was not readable or zero length.

◆ kOTA_Err_OutOfMemory

#define kOTA_Err_OutOfMemory 0x03000000UL

General out of memory error.

◆ kOTA_Err_ActivateFailed

#define kOTA_Err_ActivateFailed 0x04000000UL

The activation of the new OTA image failed.

◆ kOTA_Err_CommitFailed

#define kOTA_Err_CommitFailed 0x05000000UL

The acceptance commit of the new OTA image failed.

◆ kOTA_Err_RejectFailed

#define kOTA_Err_RejectFailed 0x06000000UL

Error trying to reject the OTA image.

◆ kOTA_Err_AbortFailed

#define kOTA_Err_AbortFailed 0x07000000UL

Error trying to abort the OTA.

◆ kOTA_Err_PublishFailed

#define kOTA_Err_PublishFailed 0x08000000UL

Attempt to publish a MQTT message failed.

◆ kOTA_Err_BadImageState

#define kOTA_Err_BadImageState 0x09000000UL

The specified OTA image state was out of range.

◆ kOTA_Err_NoActiveJob

#define kOTA_Err_NoActiveJob 0x0a000000UL

Attempt to set final image state without an active job.

◆ kOTA_Err_NoFreeContext

#define kOTA_Err_NoFreeContext 0x0b000000UL

There wasn't an OTA file context available for processing.

◆ kOTA_Err_HTTPInitFailed

#define kOTA_Err_HTTPInitFailed 0x0c000000UL

Error initializing the HTTP connection.

◆ kOTA_Err_HTTPRequestFailed

#define kOTA_Err_HTTPRequestFailed 0x0d000000UL

Error sending the HTTP request.

◆ kOTA_Err_FileAbort

#define kOTA_Err_FileAbort 0x10000000UL

Error in low level file abort.

◆ kOTA_Err_FileClose

#define kOTA_Err_FileClose 0x11000000UL

Error in low level file close.

◆ kOTA_Err_RxFileCreateFailed

#define kOTA_Err_RxFileCreateFailed 0x12000000UL

The PAL failed to create the OTA receive file.

◆ kOTA_Err_BootInfoCreateFailed

#define kOTA_Err_BootInfoCreateFailed 0x13000000UL

The PAL failed to create the OTA boot info file.

◆ kOTA_Err_RxFileTooLarge

#define kOTA_Err_RxFileTooLarge 0x14000000UL

The OTA receive file is too big for the platform to support.

◆ kOTA_Err_NullFilePtr

#define kOTA_Err_NullFilePtr 0x20000000UL

Attempt to use a null file pointer.

◆ kOTA_Err_MomentumAbort

#define kOTA_Err_MomentumAbort 0x21000000UL

Too many OTA stream requests without any response.

◆ kOTA_Err_DowngradeNotAllowed

#define kOTA_Err_DowngradeNotAllowed 0x22000000UL

Firmware version is older than the previous version.

◆ kOTA_Err_SameFirmwareVersion

#define kOTA_Err_SameFirmwareVersion 0x23000000UL

Firmware version is the same as previous. New firmware could have failed to commit.

◆ kOTA_Err_JobParserError

#define kOTA_Err_JobParserError 0x24000000UL

An error occurred during job document parsing. See reason sub-code.

◆ kOTA_Err_FailedToEncodeCBOR

#define kOTA_Err_FailedToEncodeCBOR 0x25000000UL

Failed to encode CBOR object.

◆ kOTA_Err_ImageStateMismatch

#define kOTA_Err_ImageStateMismatch 0x26000000UL

The OTA job was in Self Test but the platform image state was not. Possible tampering.

◆ kOTA_Err_GenericIngestError

#define kOTA_Err_GenericIngestError 0x27000000UL

A failure in block ingestion not caused by the PAL. See the error sub code.

◆ kOTA_Err_UserAbort

#define kOTA_Err_UserAbort 0x28000000UL

User aborted the active OTA.

◆ kOTA_Err_ResetNotSupported

#define kOTA_Err_ResetNotSupported 0x29000000UL

We tried to reset the device but the device doesn't support it.

◆ kOTA_Err_TopicTooLarge

#define kOTA_Err_TopicTooLarge 0x2a000000UL

Attempt to build a topic string larger than the supplied buffer.

◆ kOTA_Err_SelfTestTimerFailed

#define kOTA_Err_SelfTestTimerFailed 0x2b000000UL

Attempt to start self-test timer faield.

◆ kOTA_Err_EventQueueSendFailed

#define kOTA_Err_EventQueueSendFailed 0x2c000000UL

Posting event message to the event queue failed.

◆ kOTA_Err_InvalidDataProtocol

#define kOTA_Err_InvalidDataProtocol 0x2d000000UL

Job does not have a valid protocol for data transfer.

◆ kOTA_Err_OTAAgentStopped

#define kOTA_Err_OTAAgentStopped 0x2e000000UL

Returned when operations are performed that requires OTA Agent running & its stopped.

◆ kOTA_PAL_ErrMask

#define kOTA_PAL_ErrMask 0xffffffUL

The PAL layer uses the signed low 24 bits of the OTA error code.

◆ kOTA_Main_ErrMask

#define kOTA_Main_ErrMask 0xff000000UL

Mask out all but the OTA Agent error code (high 8 bits).

◆ kOTA_MainErrShiftDownBits

#define kOTA_MainErrShiftDownBits 24U

The OTA Agent error code is the highest 8 bits of the word.

Typedef Documentation

◆ OTA_FileContext_t

typedef struct OTA_FileContext OTA_FileContext_t

@functionpointers{ota,OTA library}

◆ pxOTACompleteCallback_t

typedef void(* pxOTACompleteCallback_t) (OTA_JobEvent_t eEvent)

OTA update complete callback function typedef.

The user may register a callback function when initializing the OTA Agent. This callback is used to notify the main application when the OTA update job is complete. Typically, it is used to reset the device after a successful update by calling ota_function_activatenewimage and may also be used to kick off user specified self tests during the Self Test phase. If the user does not supply a custom callback function, a default callback handler is used that automatically calls ota_function_activatenewimage after a successful update.

The callback function is called with one of the following arguments:

 eOTA_JobEvent_Activate      OTA update is authenticated and ready to activate.
 eOTA_JobEvent_Fail          OTA update failed. Unable to use this update.
 eOTA_JobEvent_StartTest     OTA job is now ready for optional user self tests.

When eOTA_JobEvent_Activate is received, the job status details have been updated with the state as ready for Self Test. After reboot, the new firmware will (normally) be notified that it is in the Self Test phase via the callback and the application may then optionally run its own tests before committing the new image.

If the callback function is called with a result of eOTA_JobEvent_Fail, the OTA update job has failed in some way and should be rejected.

Parameters

[in] eEvent An OTA update event from the OTA_JobEvent_t enum.

◆ pxOTAPALAbortCallback_t

typedef OTA_Err_t(* pxOTAPALAbortCallback_t) (OTA_FileContext_t *const C)

OTA abort callback function typedef.

The user may register a callback function when initializing the OTA Agent. This callback is used to override the behavior of how a job is aborted.

Parameters

[in] C File context of the job being aborted

◆ pxOTAPALActivateNewImageCallback_t

typedef OTA_Err_t(* pxOTAPALActivateNewImageCallback_t) (uint32_t ulServerFileID)

OTA new image received callback function typedef.

The user may register a callback function when initializing the OTA Agent. This callback is used to override the behavior of what happens when a new image is activated.

Parameters

[in] ulServerFileID File ID of the image received

◆ pxOTAPALCloseFileCallback_t

typedef OTA_Err_t(* pxOTAPALCloseFileCallback_t) (OTA_FileContext_t *const C)

OTA close file callback function typedef.

The user may register a callback function when initializing the OTA Agent. This callback is used to override the behavior of what happens when a file is closed.

Parameters

[in] C File context of the job being aborted

◆ pxOTAPALCreateFileForRxCallback_t

typedef OTA_Err_t(* pxOTAPALCreateFileForRxCallback_t) (OTA_FileContext_t *const C)

OTA create file to store received data callback function typedef.

The user may register a callback function when initializing the OTA Agent. This callback is used to override the behavior of how a new file is created.

Parameters

[in] C File context of the job being aborted

◆ pxOTAPALGetPlatformImageStateCallback_t

typedef OTA_PAL_ImageState_t(* pxOTAPALGetPlatformImageStateCallback_t) (uint32_t ulServerFileID)

OTA Get Platform Image State callback function typedef.

The user may register a callback function when initializing the OTA Agent. This callback is used to override the behavior of returning the platform image state.

Parameters

[in] ulServerFileID File ID of the image received

◆ pxOTAPALResetDeviceCallback_t

typedef OTA_Err_t(* pxOTAPALResetDeviceCallback_t) (uint32_t ulServerFileID)

OTA Reset Device callback function typedef.

The user may register a callback function when initializing the OTA Agent. This callback is used to override the behavior of what happens when the OTA agent resets the device.

Parameters

[in] ulServerFileID File ID of the image received

◆ pxOTAPALSetPlatformImageStateCallback_t

typedef OTA_Err_t(* pxOTAPALSetPlatformImageStateCallback_t) (uint32_t ulServerFileID, OTA_ImageState_t eState)

OTA Set Platform Image State callback function typedef.

The user may register a callback function when initializing the OTA Agent. This callback is used to override the behavior of how a platform image state is stored.

Parameters

[in]	ulServerFileID	File ID of the image received
[in]	eState	Platform Image State to be state

◆ pxOTAPALWriteBlockCallback_t

typedef int16_t(* pxOTAPALWriteBlockCallback_t) (OTA_FileContext_t *const C, uint32_t iOffset, uint8_t *const pacData, uint32_t iBlockSize)

OTA Write Block callback function typedef.

The user may register a callback function when initializing the OTA Agent. This callback is used to override the behavior of how a block is written to a file.

Parameters

[in]	C	File context of the job being aborted
[in]	iOffset	Offset into the file to write the data
[in]	pacData	Data to be written at the offset
[in]	iBlocksize	Block size of the data to be written

◆ pxOTACustomJobCallback_t

typedef OTA_JobParseErr_t(* pxOTACustomJobCallback_t) (const char *pcJSON, uint32_t ulMsgLen)

Custom Job callback function typedef.

The user may register a callback function when initializing the OTA Agent. This callback will be called when the OTA agent cannot parse a job document.

Parameters

[in]	pcJSON	Pointer to the json document received by the OTA agent
[in]	ulMsgLen	Length of the json document received by the agent

Enumeration Type Documentation

◆ OTA_State_t

enum OTA_State_t

OTA Agent states.

@enums{ota,OTA library}

The current state of the OTA Task (OTA Agent).

Note: There is currently support only for a single OTA context.

◆ OTA_Event_t

enum OTA_Event_t

OTA Agent Events.

The events sent to OTA agent.

◆ OTA_PAL_ImageState_t

enum OTA_PAL_ImageState_t

OTA Platform Image State.

The image state set by platform implementation.

◆ OTA_JobEvent_t

enum OTA_JobEvent_t

OTA Job callback events.

After an OTA update image is received and authenticated, the agent calls the user callback (set with the ota_function_init API) with the value eOTA_JobEvent_Activate to signal that the device must be rebooted to activate the new image. When the device boots, if the OTA job status is in self test mode, the agent calls the user callback with the value eOTA_JobEvent_StartTest, signaling that any additional self tests should be performed.

If the OTA receive fails for any reason, the agent calls the user callback with the value eOTA_JobEvent_Fail instead to allow the user to log the failure and take any action deemed appropriate by the user code.

See the OTA_ImageState_t type for more information.

Enumerator
eOTA_JobEvent_Activate	OTA receive is authenticated and ready to activate.
eOTA_JobEvent_Fail	OTA receive failed. Unable to use this update.
eOTA_JobEvent_StartTest	OTA job is now in self test, perform user tests.

◆ OTA_ImageState_t

enum OTA_ImageState_t

OTA Image states.

After an OTA update image is received and authenticated, it is logically moved to the Self Test state by the OTA agent pending final acceptance. After the image is activated and tested by your user code, you should put it into either the Accepted or Rejected state by calling ota_function_setimagestate( eOTA_ImageState_Accepted ) or ota_function_setimagestate( eOTA_ImageState_Rejected ). If the image is accepted, it becomes the main firmware image to be booted from then on. If it is rejected, the image is no longer valid and shall not be used, reverting to the last known good image.

If you want to abort an active OTA transfer, you may do so by calling the API ota_function_setimagestate( eOTA_ImageState_Aborted ).

Enumerator
eOTA_ImageState_Unknown	The initial state of the OTA MCU Image.
eOTA_ImageState_Testing	The state of the OTA MCU Image post successful download and reboot.
eOTA_ImageState_Accepted	The state of the OTA MCU Image post successful download and successful self_test.
eOTA_ImageState_Rejected	The state of the OTA MCU Image when the job has been rejected.
eOTA_ImageState_Aborted	The state of the OTA MCU Image after a timeout publish to the stream request fails. Also if the OTA MCU image is aborted in the middle of a stream.

Function Documentation

◆ OTA_AgentInit()

OTA_State_t OTA_AgentInit	(	void *	pvConnectionContext,
		const uint8_t *	pucThingName,
		pxOTACompleteCallback_t	xFunc,
		TickType_t	xTicksToWait
	)

OTA Agent initialization function.

@functionspage{ota,OTA library}

@functionname{ota_function_init}
@functionname{ota_function_shutdown}
@functionname{ota_function_getagentstate}
@functionname{ota_function_activatenewimage}
@functionname{ota_function_setimagestate}
@functionname{ota_function_getimagestate}
@functionname{ota_function_checkforupdate}
@functionname{ota_function_suspend}
@functionname{ota_function_resume}
@functionname{ota_function_getpacketsreceived}
@functionname{ota_function_getpacketsqueued}
@functionname{ota_function_getpacketsprocessed}
@functionname{ota_function_getpacketsdropped} @functionpage{OTA_AgentInit,ota,init} @functionpage{OTA_AgentShutdown,ota,shutdown} @functionpage{OTA_GetAgentState,ota,getagentstate} @functionpage{OTA_ActivateNewImage,ota,activatenewimage} @functionpage{OTA_SetImageState,ota,setimagestate} @functionpage{OTA_GetImageState,ota,getimagestate} @functionpage{OTA_CheckForUpdate,ota,checkforupdate} @functionpage{OTA_Suspend,ota,suspend} @functionpage{OTA_Resume,ota,resume} @functionpage{OTA_GetPacketsReceived,ota,getpacketsreceived} @functionpage{OTA_GetPacketsQueued,ota,getpacketsqueued} @functionpage{OTA_GetPacketsProcessed,ota,getpacketsprocessed} @functionpage{OTA_GetPacketsDropped,ota,getpacketsdropped}

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_function_checkforupdate. Only one OTA Agent may exist.

Parameters

[in]	pvConnectionContext	A pointer to a OTA_ConnectionContext_t object.
[in]	pucThingName	A pointer to a C string holding the Thing name.
[in]	xFunc	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.
[in]	xTicksToWait	The number of ticks to wait until the OTA Task signals that it is ready. If this is set to zero, then the function will return immediately after creating the OTA task but the OTA task may not be ready to operate yet. The state may be queried with ota_function_getagentstate.

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

◆ OTA_AgentInit_internal()

OTA_State_t OTA_AgentInit_internal	(	void *	pvConnectionContext,
		const uint8_t *	pucThingName,
		const OTA_PAL_Callbacks_t *	pxCallbacks,
		TickType_t	xTicksToWait
	)

Internal 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 MQTT messaging client context before calling ota_function_checkforupdate. Only one OTA Agent may exist.

Parameters

[in]	pvConnectionContext	A pointer to a OTA_ConnectionContext_t object.
[in]	pucThingName	A pointer to a C string holding the Thing name.
[in]	pxCallbacks	Static callback structure for various OTA events. This function will have input of the state of the OTA image after download and during self-test.
[in]	xTicksToWait	The number of ticks to wait until the OTA Task signals that it is ready. If this is set to zero, then the function will return immediately after creating the OTA task but the OTA task may not be ready to operate yet. The state may be queried with ota_function_getagentstate.

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

◆ OTA_AgentShutdown()

OTA_State_t OTA_AgentShutdown ( TickType_t xTicksToWait )

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] xTicksToWait 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 OTA_State_t enum. A normal shutdown will return eOTA_AgentState_NotReady. Otherwise, refer to the OTA_State_t enum for details.

◆ OTA_GetAgentState()

OTA_State_t OTA_GetAgentState ( void )

Get the current state of the OTA agent.

Returns: The current state of the OTA agent.

◆ OTA_ActivateNewImage()

OTA_Err_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 eOTA_JobEvent_Activate event is passed to the users application via the OTA Job Complete Callback mechanism. Refer to the ota_function_init function for more information about configuring the callback.

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

◆ OTA_SetImageState()

OTA_Err_t OTA_SetImageState ( OTA_ImageState_t eState )

Set the state of the current MCU image.

The states are eOTA_ImageState_Testing, eOTA_ImageState_Accepted, eOTA_ImageState_Aborted or eOTA_ImageState_Rejected; see OTA_ImageState_t documentation. This will update the status of the current image and publish to the active job status topic.

Parameters

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

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

◆ OTA_GetImageState()

OTA_ImageState_t OTA_GetImageState ( void )

Get the state of the currently running MCU image.

The states are eOTA_ImageState_Testing, eOTA_ImageState_Accepted, eOTA_ImageState_Aborted or eOTA_ImageState_Rejected; see OTA_ImageState_t documentation.

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

◆ OTA_CheckForUpdate()

OTA_Err_t OTA_CheckForUpdate ( void )

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

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

◆ OTA_Suspend()

OTA_Err_t OTA_Suspend ( void )

Suspend OTA agent operations .

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

◆ OTA_Resume()

OTA_Err_t OTA_Resume ( void * pxConnection )

Resume OTA agent operations .

Parameters

[in] pxConnection Update connection context.

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

◆ OTA_GetPacketsReceived()

uint32_t OTA_GetPacketsReceived ( void )

Get the number of OTA message packets received by the OTA agent.

Note: Calling ota_function_init will reset this statistic.

Returns: The number of OTA packets that have been received but not necessarily queued for processing by the OTA agent.

◆ OTA_GetPacketsQueued()

uint32_t OTA_GetPacketsQueued ( void )

Get the number of OTA message packets queued by the OTA agent.

Note: Calling ota_function_init will reset this statistic.

Returns: 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.

◆ OTA_GetPacketsProcessed()

uint32_t OTA_GetPacketsProcessed ( void )

Get the number of OTA message packets processed by the OTA agent.

Note: Calling ota_function_init will reset this statistic.

Returns: the number of OTA packets that have actually been processed.

◆ OTA_GetPacketsDropped()

uint32_t OTA_GetPacketsDropped ( void )

Get the number of OTA message packets dropped by the OTA agent.

Note: Calling ota_function_init will reset this statistic.

Returns: the number of OTA packets that have been dropped because of either no queue or at shutdown cleanup.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ DEFINE_OTA_METHOD_NAME

◆ kOTA_MaxSignatureSize

◆ kOTA_Err_Panic

OTA Error Codes

OTA Error Code Helper constants

◆ kOTA_Err_Uninitialized

◆ kOTA_Err_SignatureCheckFailed

◆ kOTA_Err_BadSignerCert

◆ kOTA_Err_OutOfMemory

◆ kOTA_Err_ActivateFailed

◆ kOTA_Err_CommitFailed

◆ kOTA_Err_RejectFailed

◆ kOTA_Err_AbortFailed

◆ kOTA_Err_PublishFailed

◆ kOTA_Err_BadImageState

◆ kOTA_Err_NoActiveJob

◆ kOTA_Err_NoFreeContext

◆ kOTA_Err_HTTPInitFailed

◆ kOTA_Err_HTTPRequestFailed

◆ kOTA_Err_FileAbort

◆ kOTA_Err_FileClose

◆ kOTA_Err_RxFileCreateFailed

◆ kOTA_Err_BootInfoCreateFailed

◆ kOTA_Err_RxFileTooLarge

◆ kOTA_Err_NullFilePtr

◆ kOTA_Err_MomentumAbort

◆ kOTA_Err_DowngradeNotAllowed

◆ kOTA_Err_SameFirmwareVersion

◆ kOTA_Err_JobParserError

◆ kOTA_Err_FailedToEncodeCBOR

◆ kOTA_Err_ImageStateMismatch

◆ kOTA_Err_GenericIngestError

◆ kOTA_Err_UserAbort

◆ kOTA_Err_ResetNotSupported

◆ kOTA_Err_TopicTooLarge

◆ kOTA_Err_SelfTestTimerFailed

◆ kOTA_Err_EventQueueSendFailed

◆ kOTA_Err_InvalidDataProtocol

◆ kOTA_Err_OTAAgentStopped

◆ kOTA_PAL_ErrMask

◆ kOTA_Main_ErrMask

◆ kOTA_MainErrShiftDownBits

Typedef Documentation

◆ OTA_FileContext_t

◆ pxOTACompleteCallback_t

◆ pxOTAPALAbortCallback_t

◆ pxOTAPALActivateNewImageCallback_t

◆ pxOTAPALCloseFileCallback_t

◆ pxOTAPALCreateFileForRxCallback_t

◆ pxOTAPALGetPlatformImageStateCallback_t

◆ pxOTAPALResetDeviceCallback_t

◆ pxOTAPALSetPlatformImageStateCallback_t

◆ pxOTAPALWriteBlockCallback_t

◆ pxOTACustomJobCallback_t

Enumeration Type Documentation

◆ OTA_State_t

◆ OTA_Event_t

◆ OTA_PAL_ImageState_t

◆ OTA_JobEvent_t

◆ OTA_ImageState_t

Function Documentation

◆ OTA_AgentInit()

◆ OTA_AgentInit_internal()

◆ OTA_AgentShutdown()

◆ OTA_GetAgentState()

◆ OTA_ActivateNewImage()

◆ OTA_SetImageState()

◆ OTA_GetImageState()

◆ OTA_CheckForUpdate()

◆ OTA_Suspend()

◆ OTA_Resume()

◆ OTA_GetPacketsReceived()