AWS IoT Over-the-air Update v3.3.0
Client library for AWS IoT OTA
ota.h
Go to the documentation of this file.
1/*
2 * AWS IoT Over-the-air Update v3.3.0
3 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
6 * this software and associated documentation files (the "Software"), to deal in
7 * the Software without restriction, including without limitation the rights to
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9 * the Software, and to permit persons to whom the Software is furnished to do so,
10 * subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in all
13 * copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 */
22
28#ifndef OTA_H
29#define OTA_H
30
31/* *INDENT-OFF* */
32#ifdef __cplusplus
33 extern "C" {
34#endif
35/* *INDENT-ON* */
36
37/* Standard includes. */
38/* For FILE type in OtaFileContext_t.*/
39#include <stdio.h>
40#include <stdint.h>
41
42/* OTA Library Interface include. */
43#include "ota_private.h"
44#include "ota_os_interface.h"
45#include "ota_mqtt_interface.h"
46#include "ota_http_interface.h"
48
53#define CONST_STRLEN( s ) ( ( ( uint32_t ) sizeof( s ) ) - 1UL )
54
55
56#define OTA_FILE_SIG_KEY_STR_MAX_LENGTH 32
65/* MISRA rule 8.6 requires identifier with external linkage to have exact one external definition.
66 * However, this variable is defined in OTA platform abstraction layer implementation, which is
67 * not in this repository but in C-SDK and amazon-freertos repo, so it's a false positive. */
68/* coverity[misra_c_2012_rule_8_6_violation] */
70
71/*-------------------------- OTA enumerated types --------------------------*/
72
78typedef enum OtaErr
79{
105
114typedef enum OtaState
115{
116 OtaAgentStateNoTransition = -1,
117 OtaAgentStateInit = 0,
118 OtaAgentStateReady,
119 OtaAgentStateRequestingJob,
120 OtaAgentStateWaitingForJob,
121 OtaAgentStateCreatingFile,
122 OtaAgentStateRequestingFileBlock,
123 OtaAgentStateWaitingForFileBlock,
124 OtaAgentStateClosingFile,
125 OtaAgentStateSuspended,
126 OtaAgentStateShuttingDown,
127 OtaAgentStateStopped,
128 OtaAgentStateAll
129} OtaState_t;
130
135typedef enum OtaJobParseErr
136{
137 OtaJobParseErrUnknown = -1, /* @brief The error code has not yet been set by a logic path. */
138 OtaJobParseErrNone = 0, /* @brief Signifies no error has occurred. */
139 OtaJobParseErrNullJob, /* @brief A null job was reported (no job ID). */
140 OtaJobParseErrUpdateCurrentJob, /* @brief We're already busy with the reported job ID. */
141 OtaJobParseErrZeroFileSize, /* @brief Job document specified a zero sized file. This is not allowed. */
142 OtaJobParseErrNonConformingJobDoc, /* @brief The job document failed to fulfill the model requirements. */
143 OtaJobParseErrBadModelInitParams, /* @brief There was an invalid initialization parameter used in the document model. */
144 OtaJobParseErrNoContextAvailable, /* @brief There was not an OTA context available. */
145 OtaJobParseErrNoActiveJobs /* @brief No active jobs are available in the service. */
147
165typedef enum OtaJobEvent
166{
175 OtaLastJobEvent = OtaJobEventStartTest
177
183typedef enum
184{
185 JobStatusInProgress = 0,
186 JobStatusFailed,
187 JobStatusSucceeded,
188 JobStatusRejected, /* Not possible today using the "get next job" feature. FUTURE! */
189 JobStatusFailedWithVal, /* This shows 2 numeric reason codes. */
190 NumJobStatusMappings
192
201typedef struct OtaJobDocument
202{
203 const uint8_t * pJobDocJson;
205 const uint8_t * pJobId;
206 size_t jobIdLength;
207 uint32_t fileTypeId;
210 int32_t reason;
211 int32_t subReason;
213
214/*------------------------- OTA callbacks --------------------------*/
215
244typedef void (* OtaAppCallback_t)( OtaJobEvent_t eEvent,
245 const void * pData );
246
247/*--------------------------- OTA structs ----------------------------*/
248
249
257typedef struct OtaInterface
258{
264
271typedef struct OtaAppBuffer
272{
273 uint8_t * pUpdateFilePath;
275 uint8_t * pCertFilePath;
277 uint8_t * pStreamName;
278 uint16_t streamNameSize;
279 uint8_t * pDecodeMemory;
281 uint8_t * pFileBitmap;
282 uint16_t fileBitmapSize;
283 uint8_t * pUrl;
284 uint16_t urlSize;
285 uint8_t * pAuthScheme;
286 uint16_t authSchemeSize;
288
294typedef struct OtaAgentContext
295{
297 uint8_t pThingName[ otaconfigMAX_THINGNAME_LEN + 1U ];
299 uint32_t fileIndex;
300 uint32_t serverFileID;
301 uint8_t pActiveJobName[ OTA_JOB_ID_MAX_SIZE ];
312
313/*------------------------- OTA Public API --------------------------*/
314
395/* @[declare_ota_init] */
396OtaErr_t OTA_Init( OtaAppBuffer_t * pOtaBuffer,
397 const OtaInterfaces_t * pOtaInterfaces,
398 const uint8_t * pThingName,
399 OtaAppCallback_t OtaAppCallback );
400/* @[declare_ota_init] */
401
439/* @[declare_ota_shutdown] */
440OtaState_t OTA_Shutdown( uint32_t ticksToWait,
441 uint8_t unsubscribeFlag );
442/* @[declare_ota_shutdown] */
443
463/* @[declare_ota_getstate] */
465/* @[declare_ota_getstate] */
466
501/* @[declare_ota_activatenewimage] */
503/* @[declare_ota_activatenewimage] */
504
539/* @[declare_ota_setimagestate] */
541/* @[declare_ota_setimagestate] */
542
551/* @[declare_ota_getimagestate] */
553/* @[declare_ota_getimagestate] */
554
561/* @[declare_ota_checkforupdate] */
563/* @[declare_ota_checkforupdate] */
564
607/* @[declare_ota_suspend] */
608OtaErr_t OTA_Suspend( void );
609/* @[declare_ota_suspend] */
610
650/* @[declare_ota_resume] */
651OtaErr_t OTA_Resume( void );
652/* @[declare_ota_resume] */
653
668/* @[declare_ota_eventprocessingtask] */
669void OTA_EventProcessingTask( void * pUnused );
670/* @[declare_ota_eventprocessingtask] */
671
672
714/* @[declare_ota_signalevent] */
715bool OTA_SignalEvent( const OtaEventMsg_t * const pEventMsg );
716/* @[declare_ota_signalevent] */
717
718/*---------------------------------------------------------------------------*/
719/* Statistics API */
720/*---------------------------------------------------------------------------*/
721
760/* @[declare_ota_getstatistics] */
762/* @[declare_ota_getstatistics] */
763
771/* @[declare_ota_err_strerror] */
772const char * OTA_Err_strerror( OtaErr_t err );
773/* @[declare_ota_err_strerror] */
774
782/* @[declare_ota_jobparse_strerror] */
783const char * OTA_JobParse_strerror( OtaJobParseErr_t err );
784/* @[declare_ota_jobparse_strerror] */
785
793/* @[declare_ota_palstatus_strerror] */
794const char * OTA_PalStatus_strerror( OtaPalMainStatus_t status );
795/* @[declare_ota_palstatus_strerror] */
796
804/* @[declare_ota_osstatus_strerror] */
805const char * OTA_OsStatus_strerror( OtaOsStatus_t status );
806/* @[declare_ota_osstatus_strerror] */
807
808/* *INDENT-OFF* */
809#ifdef __cplusplus
810 }
811#endif
812/* *INDENT-ON* */
813
814#endif /* ifndef OTA_H */
void(* OtaAppCallback_t)(OtaJobEvent_t eEvent, const void *pData)
OTA update complete callback function typedef.
Definition: ota.h:244
OtaState_t
OTA Agent states.
Definition: ota.h:115
OtaErr_t
The OTA API return status. OTA agent error codes are in the upper 8 bits of the 32 bit OTA error word...
Definition: ota.h:79
OtaPalMainStatus_t
The OTA platform interface main status.
Definition: ota_platform_interface.h:79
OtaJobEvent_t
OTA Job callback events.
Definition: ota.h:166
OtaJobParseErr_t
OTA job document parser error codes.
Definition: ota.h:136
OtaJobStatus_t
Gives the status of the job operation.
Definition: ota.h:184
OtaImageState_t
OTA Image states.
Definition: ota_private.h:314
OtaOsStatus_t
The OTA OS interface return status.
Definition: ota_os_interface.h:99
@ OtaErrInvalidDataProtocol
Job does not have a valid protocol for data transfer.
Definition: ota.h:93
@ OtaErrPanic
Unrecoverable Firmware error. Probably should log error and reboot.
Definition: ota.h:82
@ OtaErrUninitialized
The error code has not yet been set by a logic path.
Definition: ota.h:81
@ OtaErrNone
No error occurred during the operation.
Definition: ota.h:80
@ OtaErrDowngradeNotAllowed
Firmware version is older than the previous version.
Definition: ota.h:95
@ OtaErrFileSizeOverflow
Firmware file size greater than the max allowed size.
Definition: ota.h:103
@ OtaErrAgentStopped
Returned when operations are performed that requires OTA Agent running & its stopped.
Definition: ota.h:84
@ OtaErrImageStateMismatch
The OTA job was in Self Test but the platform image state was not. Possible tampering.
Definition: ota.h:97
@ OtaErrMomentumAbort
Too many OTA stream requests without any response.
Definition: ota.h:94
@ OtaErrRequestJobFailed
Failed to request the job document.
Definition: ota.h:86
@ OtaErrJobParserError
An error occurred during job document parsing. See reason sub-code.
Definition: ota.h:92
@ OtaErrRequestFileBlockFailed
Failed to request file block.
Definition: ota.h:88
@ OtaErrInitFileTransferFailed
Failed to update the OTA job status.
Definition: ota.h:87
@ OtaErrNoActiveJob
Attempt to set final image state without an active job.
Definition: ota.h:98
@ OtaErrFailedToDecodeCbor
Failed to decode CBOR object from streaming service response.
Definition: ota.h:101
@ OtaErrSignalEventFailed
Failed to send event to OTA state machine.
Definition: ota.h:85
@ OtaErrCleanupControlFailed
Failed to clean up the control plane.
Definition: ota.h:89
@ OtaErrUpdateJobStatusFailed
Failed to update the OTA job status.
Definition: ota.h:91
@ OtaErrFailedToEncodeCbor
Failed to encode CBOR object for requesting data block from streaming service.
Definition: ota.h:100
@ OtaErrSameFirmwareVersion
Firmware version is the same as previous. New firmware could have failed to commit.
Definition: ota.h:96
@ OtaErrCleanupDataFailed
Failed to clean up the data plane.
Definition: ota.h:90
@ OtaErrInvalidArg
API called with invalid argument.
Definition: ota.h:83
@ OtaErrActivateFailed
Failed to activate the new image.
Definition: ota.h:102
@ OtaErrUserAbort
User aborted the active OTA.
Definition: ota.h:99
@ OtaJobEventStartTest
OTA job is now in self test, perform user tests.
Definition: ota.h:169
@ OtaJobEventSelfTestFailed
OTA self-test failed for current job.
Definition: ota.h:171
@ OtaJobEventUpdateComplete
OTA event when the update is completed.
Definition: ota.h:174
@ OtaJobEventFail
OTA receive failed. Unable to use this update.
Definition: ota.h:168
@ OtaJobEventReceivedJob
OTA event when a new valid AFT-OTA job is received.
Definition: ota.h:173
@ OtaJobEventParseCustomJob
OTA event for parsing custom job document.
Definition: ota.h:172
@ OtaJobEventActivate
OTA receive is authenticated and ready to activate.
Definition: ota.h:167
@ OtaJobEventProcessed
OTA event queued by OTA_SignalEvent is processed.
Definition: ota.h:170
OtaErr_t OTA_CheckForUpdate(void)
Request for the next available OTA job from the job service.
Definition: ota.c:3249
bool OTA_SignalEvent(const OtaEventMsg_t *const pEventMsg)
Signal event to the OTA Agent task.
Definition: ota.c:2934
const char * OTA_Err_strerror(OtaErr_t err)
Error code to string conversion for OTA errors.
Definition: ota.c:3440
const char OTA_JsonFileSignatureKey[OTA_FILE_SIG_KEY_STR_MAX_LENGTH]
The OTA signature algorithm string is specified by the PAL.
const char * OTA_OsStatus_strerror(OtaOsStatus_t status)
Status code to string conversion for OTA OS status.
Definition: ota.c:3596
OtaErr_t OTA_ActivateNewImage(void)
Activate the newest MCU image received via OTA.
Definition: ota.c:3277
const char * OTA_PalStatus_strerror(OtaPalMainStatus_t status)
Status code to string conversion for OTA PAL status.
Definition: ota.c:3650
OtaErr_t OTA_GetStatistics(OtaAgentStatistics_t *pStatistics)
Get the statistics of OTA message packets.
Definition: ota.c:3236
OtaErr_t OTA_Suspend(void)
Suspend OTA agent operations .
Definition: ota.c:3378
OtaState_t OTA_GetState(void)
Get the current state of the OTA agent.
Definition: ota.c:3228
#define OTA_FILE_SIG_KEY_STR_MAX_LENGTH
Definition: ota.h:56
OtaErr_t OTA_Init(OtaAppBuffer_t *pOtaBuffer, const OtaInterfaces_t *pOtaInterfaces, const uint8_t *pThingName, OtaAppCallback_t OtaAppCallback)
OTA Agent initialization function.
Definition: ota.c:3075
OtaImageState_t OTA_GetImageState(void)
Get the state of the currently running MCU image.
Definition: ota.c:3367
const char * OTA_JobParse_strerror(OtaJobParseErr_t err)
Error code to string conversion for OTA Job Parsing errors.
Definition: ota.c:3546
void OTA_EventProcessingTask(void *pUnused)
OTA agent event processing loop.
Definition: ota.c:2919
OtaErr_t OTA_SetImageState(OtaImageState_t state)
Set the state of the current MCU image.
Definition: ota.c:3313
OtaState_t OTA_Shutdown(uint32_t ticksToWait, uint8_t unsubscribeFlag)
Signal to the OTA Agent to shut down.
Definition: ota.c:3169
OtaErr_t OTA_Resume(void)
Resume OTA agent operations .
Definition: ota.c:3411
#define otaconfigMAX_THINGNAME_LEN
The maximum allowed length of the thing name used by the OTA agent.
Definition: ota_config_defaults.h:138
Contains OTA HTTP Statuses, function type definitions and http interface structure.
Contains OTA MQTT Statuses, function type definitions and mqtt interface structure.
Contains OTA OS Functional Interface statuses, type definitions and structures to store interface rou...
Contains PAL interface statuses, type definitions and structure to store interface routines.
Macros, enums, variables, and definitions internal to the OTA Agent module and shared by other OTA mo...
#define OTA_JOB_ID_MAX_SIZE
Maximum size of the Job ID.
Definition: ota_private.h:109
The OTA agent is a singleton today. The structure keeps it nice and organized.
Definition: ota.h:295
uint32_t numOfBlocksToReceive
Definition: ota.h:305
uint8_t * pClientTokenFromJob
Definition: ota.h:302
uint32_t timestampFromJob
Definition: ota.h:303
OtaState_t state
Definition: ota.h:296
OtaAgentStatistics_t statistics
Definition: ota.h:306
OtaImageState_t imageState
Definition: ota.h:304
uint32_t fileIndex
Definition: ota.h:299
uint8_t unsubscribeOnShutdown
Definition: ota.h:310
uint32_t requestMomentum
Definition: ota.h:307
OtaAppCallback_t OtaAppCallback
Definition: ota.h:309
const OtaInterfaces_t * pOtaInterface
Definition: ota.h:308
uint32_t serverFileID
Definition: ota.h:300
OtaFileContext_t fileContext
Definition: ota.h:298
This is the OTA statistics structure to hold useful info.
Definition: ota_private.h:291
OTA Application Buffer size information.
Definition: ota.h:272
uint16_t authSchemeSize
Maximum size of the auth scheme.
Definition: ota.h:286
uint8_t * pUpdateFilePath
Path to store the files.
Definition: ota.h:273
uint16_t urlSize
Maximum size of the URL.
Definition: ota.h:284
uint16_t updateFilePathsize
Maximum size of the file path.
Definition: ota.h:274
uint8_t * pAuthScheme
Authentication scheme used to validate download.
Definition: ota.h:285
uint8_t * pUrl
Presigned url to download files from S3.
Definition: ota.h:283
uint32_t decodeMemorySize
Maximum size of the decoded files buffer.
Definition: ota.h:280
uint16_t certFilePathSize
Maximum size of the certificate file path.
Definition: ota.h:276
uint8_t * pCertFilePath
Path to certificate file.
Definition: ota.h:275
uint8_t * pFileBitmap
Bitmap of the parameters received.
Definition: ota.h:281
uint8_t * pStreamName
Name of stream to download the files.
Definition: ota.h:277
uint8_t * pDecodeMemory
Place to store the decoded files.
Definition: ota.h:279
uint16_t fileBitmapSize
Maximum size of the bitmap.
Definition: ota.h:282
uint16_t streamNameSize
Maximum size of the stream name.
Definition: ota.h:278
Stores information about the event message.
Definition: ota_private.h:430
OTA File Context Information.
Definition: ota_private.h:382
OTA Event Interface structure.
Definition: ota_http_interface.h:136
OTA Interface for referencing different components.
Definition: ota.h:258
OtaPalInterface_t pal
OTA PAL callback structure.
Definition: ota.h:262
OtaMqttInterface_t mqtt
MQTT interface that references the publish subscribe methods and callbacks.
Definition: ota.h:260
OtaOSInterface_t os
OS interface to store event, timers and memory operations.
Definition: ota.h:259
OtaHttpInterface_t http
HTTP interface to request data.
Definition: ota.h:261
OTA Job document.
Definition: ota.h:202
size_t jobIdLength
Length of job ID in bytes.
Definition: ota.h:206
int32_t reason
Job status reason.
Definition: ota.h:210
uint32_t fileTypeId
File Type ID from the job document.
Definition: ota.h:207
const uint8_t * pJobDocJson
Job document in JSON format.
Definition: ota.h:203
OtaJobStatus_t status
Job status.
Definition: ota.h:209
int32_t subReason
Job status subreason.
Definition: ota.h:211
const uint8_t * pJobId
Job ID associated with the job document.
Definition: ota.h:205
OtaJobParseErr_t parseErr
Job parsing status.
Definition: ota.h:208
size_t jobDocLength
Job document length in bytes.
Definition: ota.h:204
OTA Event Interface structure.
Definition: ota_mqtt_interface.h:162
OTA OS Interface.
Definition: ota_os_interface.h:305
OTA pal Interface structure.
Definition: ota_platform_interface.h:298