OTA Agent Interface. More...

#include "aws_ota_types.h"
#include "FreeRTOS.h"
#include "timers.h"
#include "aws_logging_task.h"

Data Structures
struct	Sig256_t

struct	OTA_FileContext_t
	OTA File Context Information. 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) static const char 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_PAL_ErrMask 0xffffffUL

#define	kOTA_Main_ErrMask 0xff000000UL

#define	kOTA_MainErrShiftDownBits 24U

#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_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

Typedefs
typedef uint32_t	OTA_Err_t
	OTA Error type.

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

Enumerations
enum	OTA_State_t { eOTA_AgentState_Unknown = -1, eOTA_AgentState_NotReady = 0, eOTA_AgentState_Ready = 1, eOTA_AgentState_Active = 2, eOTA_AgentState_ShuttingDown = 3, eOTA_NumAgentStates = 4 }
	OTA Agent states. More...

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 pvClient, const uint8_t pcThingName, pxOTACompleteCallback_t xFunc, TickType_t xTicksToWait)
	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)

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	pcOTA_JSON_FileSignatureKey [OTA_FILE_SIG_KEY_STR_MAX_LENGTH]

Detailed Description

OTA Agent Interface.

Definition in file aws_ota_agent.h.

Macro Definition Documentation

◆ kOTA_Err_AbortFailed

#define kOTA_Err_AbortFailed 0x07000000UL

Error trying to abort the OTA.

Definition at line 134 of file aws_ota_agent.h.

◆ kOTA_Err_ActivateFailed

#define kOTA_Err_ActivateFailed 0x04000000UL

The activation of the new OTA image failed.

Definition at line 131 of file aws_ota_agent.h.

◆ kOTA_Err_BadImageState

#define kOTA_Err_BadImageState 0x09000000UL

The specified OTA image state was out of range.

Definition at line 136 of file aws_ota_agent.h.

◆ kOTA_Err_BadSignerCert

#define kOTA_Err_BadSignerCert 0x02000000UL

The signer certificate was not readable or zero length.

Definition at line 129 of file aws_ota_agent.h.

◆ kOTA_Err_BootInfoCreateFailed

#define kOTA_Err_BootInfoCreateFailed 0x13000000UL

The PAL failed to create the OTA boot info file.

Definition at line 142 of file aws_ota_agent.h.

◆ kOTA_Err_CommitFailed

#define kOTA_Err_CommitFailed 0x05000000UL

The acceptance commit of the new OTA image failed.

Definition at line 132 of file aws_ota_agent.h.

◆ kOTA_Err_DowngradeNotAllowed

#define kOTA_Err_DowngradeNotAllowed 0x22000000UL

Firmware version is older than the previous version.

Definition at line 146 of file aws_ota_agent.h.

◆ kOTA_Err_FailedToEncodeCBOR

#define kOTA_Err_FailedToEncodeCBOR 0x25000000UL

Failed to encode CBOR object.

Definition at line 149 of file aws_ota_agent.h.

◆ kOTA_Err_FileAbort

#define kOTA_Err_FileAbort 0x10000000UL

Error in low level file abort.

Definition at line 139 of file aws_ota_agent.h.

◆ kOTA_Err_FileClose

#define kOTA_Err_FileClose 0x11000000UL

Error in low level file close.

Definition at line 140 of file aws_ota_agent.h.

◆ kOTA_Err_GenericIngestError

#define kOTA_Err_GenericIngestError 0x27000000UL

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

Definition at line 151 of file aws_ota_agent.h.

◆ kOTA_Err_ImageStateMismatch

#define kOTA_Err_ImageStateMismatch 0x26000000UL

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

Definition at line 150 of file aws_ota_agent.h.

◆ kOTA_Err_JobParserError

#define kOTA_Err_JobParserError 0x24000000UL

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

Definition at line 148 of file aws_ota_agent.h.

◆ kOTA_Err_MomentumAbort

#define kOTA_Err_MomentumAbort 0x21000000UL

Too many OTA stream requests without any response.

Definition at line 145 of file aws_ota_agent.h.

◆ kOTA_Err_NoActiveJob

#define kOTA_Err_NoActiveJob 0x0a000000UL

Attempt to set final image state without an active job.

Definition at line 137 of file aws_ota_agent.h.

◆ kOTA_Err_NoFreeContext

#define kOTA_Err_NoFreeContext 0x0b000000UL

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

Definition at line 138 of file aws_ota_agent.h.

◆ kOTA_Err_NullFilePtr

#define kOTA_Err_NullFilePtr 0x20000000UL

Attempt to use a null file pointer.

Definition at line 144 of file aws_ota_agent.h.

◆ kOTA_Err_OutOfMemory

#define kOTA_Err_OutOfMemory 0x03000000UL

General out of memory error.

Definition at line 130 of file aws_ota_agent.h.

◆ kOTA_Err_Panic

#define kOTA_Err_Panic 0xfe000000UL

Unrecoverable FW error. Probably should log error and reboot.

Definition at line 125 of file aws_ota_agent.h.

◆ kOTA_Err_PublishFailed

#define kOTA_Err_PublishFailed 0x08000000UL

Attempt to publish a MQTT message failed.

Definition at line 135 of file aws_ota_agent.h.

◆ kOTA_Err_RejectFailed

#define kOTA_Err_RejectFailed 0x06000000UL

Error trying to reject the OTA image.

Definition at line 133 of file aws_ota_agent.h.

◆ kOTA_Err_ResetNotSupported

#define kOTA_Err_ResetNotSupported 0x29000000UL

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

Definition at line 153 of file aws_ota_agent.h.

◆ kOTA_Err_RxFileCreateFailed

#define kOTA_Err_RxFileCreateFailed 0x12000000UL

The PAL failed to create the OTA receive file.

Definition at line 141 of file aws_ota_agent.h.

◆ kOTA_Err_RxFileTooLarge

#define kOTA_Err_RxFileTooLarge 0x14000000UL

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

Definition at line 143 of file aws_ota_agent.h.

◆ kOTA_Err_SameFirmwareVersion

#define kOTA_Err_SameFirmwareVersion 0x23000000UL

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

Definition at line 147 of file aws_ota_agent.h.

◆ kOTA_Err_SignatureCheckFailed

#define kOTA_Err_SignatureCheckFailed 0x01000000UL

The signature check failed for the specified file.

Definition at line 128 of file aws_ota_agent.h.

◆ kOTA_Err_TopicTooLarge

#define kOTA_Err_TopicTooLarge 0x2a000000UL

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

Definition at line 154 of file aws_ota_agent.h.

◆ kOTA_Err_Uninitialized

#define kOTA_Err_Uninitialized 0xff000000UL

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

Definition at line 126 of file aws_ota_agent.h.

◆ kOTA_Err_UserAbort

#define kOTA_Err_UserAbort 0x28000000UL

User aborted the active OTA.

Definition at line 152 of file aws_ota_agent.h.

◆ kOTA_Main_ErrMask

#define kOTA_Main_ErrMask 0xff000000UL

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

Definition at line 116 of file aws_ota_agent.h.

◆ kOTA_MainErrShiftDownBits

#define kOTA_MainErrShiftDownBits 24U

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

Definition at line 117 of file aws_ota_agent.h.

◆ kOTA_PAL_ErrMask

#define kOTA_PAL_ErrMask 0xffffffUL

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

Definition at line 115 of file aws_ota_agent.h.

Typedef Documentation

◆ 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_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_ActivateNewImage() after a successful update.

Note: :

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.

Definition at line 269 of file aws_ota_agent.h.

Enumeration Type Documentation

◆ 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_SetImageState( eOTA_ImageState_Accepted ) or OTA_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_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.

Definition at line 194 of file aws_ota_agent.h.

◆ 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_AgentInit 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.

Definition at line 172 of file aws_ota_agent.h.

◆ OTA_State_t

enum OTA_State_t

OTA Agent states.

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

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

Enumerator
eOTA_AgentState_Unknown	The OTA agent state is not yet known.
eOTA_AgentState_NotReady	The OTA agent task is not running.
eOTA_AgentState_Ready	The OTA agent task is running and ready to transfer.
eOTA_AgentState_Active	The OTA agent is actively receiving an update.
eOTA_AgentState_ShuttingDown	The OTA agent task is performing shut down activities.

Definition at line 84 of file aws_ota_agent.h.

Function Documentation

◆ 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_AgentInit() 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_AgentInit()

OTA_State_t OTA_AgentInit	(	void *	pvClient,
		const uint8_t *	pcThingName,
		pxOTACompleteCallback_t	xFunc,
		TickType_t	xTicksToWait
	)

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_CheckForUpdate(). Only one OTA Agent may exist.

Parameters

[in]	pvClient	The messaging protocol client context (e.g. an MQTT context).
[in]	pcThingName	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_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_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_GetPacketsDropped()

uint32_t OTA_GetPacketsDropped ( void )

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

Note: Calling OTA_AgentInit() will reset this statistic.

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

◆ OTA_GetPacketsProcessed()

uint32_t OTA_GetPacketsProcessed ( void )

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

Note: Calling OTA_AgentInit() will reset this statistic.

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

◆ OTA_GetPacketsQueued()

uint32_t OTA_GetPacketsQueued ( void )

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

Note: Calling OTA_AgentInit() 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_GetPacketsReceived()

uint32_t OTA_GetPacketsReceived ( void )

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

Note: Calling OTA_AgentInit() 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_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.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ kOTA_Err_AbortFailed

◆ kOTA_Err_ActivateFailed

◆ kOTA_Err_BadImageState

◆ kOTA_Err_BadSignerCert

◆ kOTA_Err_BootInfoCreateFailed

◆ kOTA_Err_CommitFailed

◆ kOTA_Err_DowngradeNotAllowed

◆ kOTA_Err_FailedToEncodeCBOR

◆ kOTA_Err_FileAbort

◆ kOTA_Err_FileClose

◆ kOTA_Err_GenericIngestError

◆ kOTA_Err_ImageStateMismatch

◆ kOTA_Err_JobParserError

◆ kOTA_Err_MomentumAbort

◆ kOTA_Err_NoActiveJob

◆ kOTA_Err_NoFreeContext

◆ kOTA_Err_NullFilePtr

◆ kOTA_Err_OutOfMemory

◆ kOTA_Err_Panic

◆ kOTA_Err_PublishFailed

◆ kOTA_Err_RejectFailed

◆ kOTA_Err_ResetNotSupported

◆ kOTA_Err_RxFileCreateFailed

◆ kOTA_Err_RxFileTooLarge

◆ kOTA_Err_SameFirmwareVersion

◆ kOTA_Err_SignatureCheckFailed

◆ kOTA_Err_TopicTooLarge

◆ kOTA_Err_Uninitialized

◆ kOTA_Err_UserAbort

◆ kOTA_Main_ErrMask

◆ kOTA_MainErrShiftDownBits

◆ kOTA_PAL_ErrMask

Typedef Documentation

◆ pxOTACompleteCallback_t

Enumeration Type Documentation

◆ OTA_ImageState_t

◆ OTA_JobEvent_t

◆ OTA_State_t

Function Documentation

◆ OTA_ActivateNewImage()

◆ OTA_AgentInit()

◆ OTA_AgentShutdown()

◆ OTA_GetAgentState()

◆ OTA_GetImageState()

◆ OTA_GetPacketsDropped()

◆ OTA_GetPacketsProcessed()

◆ OTA_GetPacketsQueued()

◆ OTA_GetPacketsReceived()

◆ OTA_SetImageState()