AWS IoT Over-the-air Update v2.0.0 (Release Candidate)
Client library for AWS IoT OTA
Enumerated Types

Enumerated types of the OTA library. 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...
 
enum  OtaHttpStatus_t { OtaHttpSuccess = 0 , OtaHttpInitFailed = 0xc0 , OtaHttpDeinitFailed , OtaHttpRequestFailed }
 The OTA HTTP interface return status. More...
 
enum  OtaMqttStatus_t { OtaMqttSuccess = 0 , OtaMqttPublishFailed = 0xa0 , OtaMqttSubscribeFailed , OtaMqttUnsubscribeFailed }
 The OTA MQTT interface return status. More...
 
enum  OtaOsStatus_t {
  OtaOsSuccess = 0 , OtaOsEventQueueCreateFailed = 0x80U , OtaOsEventQueueSendFailed , OtaOsEventQueueReceiveFailed ,
  OtaOsEventQueueDeleteFailed , OtaOsTimerCreateFailed , OtaOsTimerStartFailed , OtaOsTimerRestartFailed ,
  OtaOsTimerStopFailed , OtaOsTimerDeleteFailed
}
 The OTA OS interface return status. More...
 
enum  OtaPalMainStatus_t {
  OtaPalSuccess = 0 , OtaPalUninitialized = 0xe0 , OtaPalOutOfMemory , OtaPalNullFileContext ,
  OtaPalSignatureCheckFailed , OtaPalRxFileCreateFailed , OtaPalRxFileTooLarge , OtaPalBootInfoCreateFailed ,
  OtaPalBadSignerCert , OtaPalBadImageState , OtaPalAbortFailed , OtaPalRejectFailed ,
  OtaPalCommitFailed , OtaPalActivateFailed , OtaPalFileAbort , OtaPalFileClose
}
 The OTA platform interface main status. More...
 
enum  OtaImageState_t {
  OtaImageStateUnknown = 0 , OtaImageStateTesting = 1 , OtaImageStateAccepted = 2 , OtaImageStateRejected = 3 ,
  OtaImageStateAborted = 4 , OtaLastImageState = OtaImageStateAborted
}
 OTA Image states. More...
 
enum  OtaPalImageState_t { OtaPalImageStateUnknown = 0 , OtaPalImageStatePendingCommit , OtaPalImageStateValid , OtaPalImageStateInvalid }
 OTA Platform Image State. More...
 
enum  OtaEvent_t {
  OtaAgentEventStart = 0 , OtaAgentEventStartSelfTest , OtaAgentEventRequestJobDocument , OtaAgentEventReceivedJobDocument ,
  OtaAgentEventCreateFile , OtaAgentEventRequestFileBlock , OtaAgentEventReceivedFileBlock , OtaAgentEventRequestTimer ,
  OtaAgentEventCloseFile , OtaAgentEventSuspend , OtaAgentEventResume , OtaAgentEventUserAbort ,
  OtaAgentEventShutdown , OtaAgentEventMax
}
 OTA Agent Events. More...
 

Detailed Description

Enumerated types of the OTA library.

Enumeration Type Documentation

◆ OtaErr_t

enum OtaErr_t

The OTA API return status. OTA agent error codes are in the upper 8 bits of the 32 bit OTA error word, OtaErr_t.

Enumerator
OtaErrNone 

No error occurred during the operation.

OtaErrUninitialized 

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

OtaErrPanic 

Unrecoverable Firmware error. Probably should log error and reboot.

OtaErrInvalidArg 

API called with invalid argument.

OtaErrAgentStopped 

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

OtaErrSignalEventFailed 

Failed to send event to OTA state machine.

OtaErrRequestJobFailed 

Failed to request the job document.

OtaErrInitFileTransferFailed 

Failed to update the OTA job status.

OtaErrRequestFileBlockFailed 

Failed to request file block.

OtaErrCleanupControlFailed 

Failed to clean up the control plane.

OtaErrCleanupDataFailed 

Failed to clean up the data plane.

OtaErrUpdateJobStatusFailed 

Failed to update the OTA job status.

OtaErrJobParserError 

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

OtaErrInvalidDataProtocol 

Job does not have a valid protocol for data transfer.

OtaErrMomentumAbort 

Too many OTA stream requests without any response.

OtaErrDowngradeNotAllowed 

Firmware version is older than the previous version.

OtaErrSameFirmwareVersion 

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

OtaErrImageStateMismatch 

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

OtaErrNoActiveJob 

Attempt to set final image state without an active job.

OtaErrUserAbort 

User aborted the active OTA.

OtaErrFailedToEncodeCbor 

Failed to encode CBOR object for requesting data block from streaming service.

OtaErrFailedToDecodeCbor 

Failed to decode CBOR object from streaming service response.

OtaErrActivateFailed 

Failed to activate the new image.

◆ OtaState_t

enum OtaState_t

OTA Agent states.

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

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

◆ OtaJobEvent_t

OTA Job callback events.

After an OTA update image is received and authenticated, the agent calls the user callback (set with the OTA_Init API) with the value OtaJobEventActivate 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 OtaJobEventStartTest, 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 OtaJobEventFail instead to allow the user to log the failure and take any action deemed appropriate by the user code.

See the OtaImageState_t type for more information.

Enumerator
OtaJobEventActivate 

OTA receive is authenticated and ready to activate.

OtaJobEventFail 

OTA receive failed. Unable to use this update.

OtaJobEventStartTest 

OTA job is now in self test, perform user tests.

OtaJobEventProcessed 

OTA event queued by OTA_SignalEvent is processed.

OtaJobEventSelfTestFailed 

OTA self-test failed for current job.

◆ OtaHttpStatus_t

The OTA HTTP interface return status.

Enumerator
OtaHttpSuccess 

OTA HTTP interface success.

OtaHttpInitFailed 

Error initializing the HTTP connection.

OtaHttpDeinitFailed 

Error deinitializing the HTTP connection.

OtaHttpRequestFailed 

Error sending the HTTP request.

◆ OtaMqttStatus_t

The OTA MQTT interface return status.

Enumerator
OtaMqttSuccess 

OTA MQTT interface success.

OtaMqttPublishFailed 

Attempt to publish a MQTT message failed.

OtaMqttSubscribeFailed 

Failed to subscribe to a topic.

OtaMqttUnsubscribeFailed 

Failed to unsubscribe from a topic.

◆ OtaOsStatus_t

The OTA OS interface return status.

Enumerator
OtaOsSuccess 

OTA OS interface success.

OtaOsEventQueueCreateFailed 

Failed to create the event queue.

OtaOsEventQueueSendFailed 

Posting event message to the event queue failed.

OtaOsEventQueueReceiveFailed 

Failed to receive from the event queue.

OtaOsEventQueueDeleteFailed 

Failed to delete the event queue.

OtaOsTimerCreateFailed 

Failed to create the timer.

OtaOsTimerStartFailed 

Failed to create the timer.

OtaOsTimerRestartFailed 

Failed to restart the timer.

OtaOsTimerStopFailed 

Failed to stop the timer.

OtaOsTimerDeleteFailed 

Failed to delete the timer.

◆ OtaPalMainStatus_t

The OTA platform interface main status.

Enumerator
OtaPalSuccess 

OTA platform interface success.

OtaPalUninitialized 

Result is not yet initialized from PAL.

OtaPalOutOfMemory 

Out of memory.

OtaPalNullFileContext 

The PAL is called with a NULL file context.

OtaPalSignatureCheckFailed 

The signature check failed for the specified file.

OtaPalRxFileCreateFailed 

The PAL failed to create the OTA receive file.

OtaPalRxFileTooLarge 

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

OtaPalBootInfoCreateFailed 

The PAL failed to create the OTA boot info file.

OtaPalBadSignerCert 

The signer certificate was not readable or zero length.

OtaPalBadImageState 

The specified OTA image state was out of range.

OtaPalAbortFailed 

Error trying to abort the OTA.

OtaPalRejectFailed 

Error trying to reject the OTA image.

OtaPalCommitFailed 

The acceptance commit of the new OTA image failed.

OtaPalActivateFailed 

The activation of the new OTA image failed.

OtaPalFileAbort 

Error in low level file abort.

OtaPalFileClose 

Error in low level file close.

◆ OtaImageState_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 ( OtaImageStateAccepted ) or OTA_SetImageState ( OtaImageStateRejected ). 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 ( OtaImageStateAborted ).

Enumerator
OtaImageStateUnknown 

The initial state of the OTA MCU Image.

OtaImageStateTesting 

The state of the OTA MCU Image post successful download and reboot.

OtaImageStateAccepted 

The state of the OTA MCU Image post successful download and successful self_test.

OtaImageStateRejected 

The state of the OTA MCU Image when the job has been rejected.

OtaImageStateAborted 

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.

◆ OtaPalImageState_t

OTA Platform Image State.

The image state set by platform implementation.

Enumerator
OtaPalImageStateUnknown 

The initial state of the OTA PAL Image.

OtaPalImageStatePendingCommit 

OTA PAL Image awaiting update.

OtaPalImageStateValid 

OTA PAL Image is valid.

OtaPalImageStateInvalid 

OTA PAL Image is invalid.

◆ OtaEvent_t

enum OtaEvent_t

OTA Agent Events.

The events sent to OTA agent.

Enumerator
OtaAgentEventStart 

Start the OTA state machine.

OtaAgentEventStartSelfTest 

Event to trigger self test.

OtaAgentEventRequestJobDocument 

Event for requesting job document.

OtaAgentEventReceivedJobDocument 

Event when job document is received.

OtaAgentEventCreateFile 

Event to create a file.

OtaAgentEventRequestFileBlock 

Event to request file blocks.

OtaAgentEventReceivedFileBlock 

Event to trigger when file block is received.

OtaAgentEventRequestTimer 

Event to request event timer.

OtaAgentEventCloseFile 

Event to trigger closing file.

OtaAgentEventSuspend 

Event to suspend ota task.

OtaAgentEventResume 

Event to resume suspended task.

OtaAgentEventUserAbort 

Event triggered by user to stop agent.

OtaAgentEventShutdown 

Event to trigger ota shutdown.

OtaAgentEventMax 

Last event specifier.