AWS IoT Over-the-air Update v3.1.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.1.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{
104
113typedef enum OtaState
114{
115 OtaAgentStateNoTransition = -1,
116 OtaAgentStateInit = 0,
117 OtaAgentStateReady,
118 OtaAgentStateRequestingJob,
119 OtaAgentStateWaitingForJob,
120 OtaAgentStateCreatingFile,
121 OtaAgentStateRequestingFileBlock,
122 OtaAgentStateWaitingForFileBlock,
123 OtaAgentStateClosingFile,
124 OtaAgentStateSuspended,
125 OtaAgentStateShuttingDown,
126 OtaAgentStateStopped,
127 OtaAgentStateAll
128} OtaState_t;
129
134typedef enum OtaJobParseErr
135{
136 OtaJobParseErrUnknown = -1, /* @brief The error code has not yet been set by a logic path. */
137 OtaJobParseErrNone = 0, /* @brief Signifies no error has occurred. */
138 OtaJobParseErrNullJob, /* @brief A null job was reported (no job ID). */
139 OtaJobParseErrUpdateCurrentJob, /* @brief We're already busy with the reported job ID. */
140 OtaJobParseErrZeroFileSize, /* @brief Job document specified a zero sized file. This is not allowed. */
141 OtaJobParseErrNonConformingJobDoc, /* @brief The job document failed to fulfill the model requirements. */
142 OtaJobParseErrBadModelInitParams, /* @brief There was an invalid initialization parameter used in the document model. */
143 OtaJobParseErrNoContextAvailable, /* @brief There was not an OTA context available. */
144 OtaJobParseErrNoActiveJobs /* @brief No active jobs are available in the service. */
146
164typedef enum OtaJobEvent
165{
174 OtaLastJobEvent = OtaJobEventStartTest
176
182typedef enum
183{
184 JobStatusInProgress = 0,
185 JobStatusFailed,
186 JobStatusSucceeded,
187 JobStatusRejected, /* Not possible today using the "get next job" feature. FUTURE! */
188 JobStatusFailedWithVal, /* This shows 2 numeric reason codes. */
189 NumJobStatusMappings
191
200typedef struct OtaJobDocument
201{
202 const uint8_t * pJobDocJson;
204 const uint8_t * pJobId;
205 size_t jobIdLength;
206 uint32_t fileTypeId;
209 int32_t reason;
210 int32_t subReason;
212
213/*------------------------- OTA callbacks --------------------------*/
214
243typedef void (* OtaAppCallback_t)( OtaJobEvent_t eEvent,
244 const void * pData );
245
246/*--------------------------- OTA structs ----------------------------*/
247
248
256typedef struct OtaInterface
257{
263
270typedef struct OtaAppBuffer
271{
272 uint8_t * pUpdateFilePath;
274 uint8_t * pCertFilePath;
276 uint8_t * pStreamName;
277 uint16_t streamNameSize;
278 uint8_t * pDecodeMemory;
280 uint8_t * pFileBitmap;
281 uint16_t fileBitmapSize;
282 uint8_t * pUrl;
283 uint16_t urlSize;
284 uint8_t * pAuthScheme;
285 uint16_t authSchemeSize;
287
293typedef struct OtaAgentContext
294{
296 uint8_t pThingName[ otaconfigMAX_THINGNAME_LEN + 1U ];
298 uint32_t fileIndex;
299 uint32_t serverFileID;
300 uint8_t pActiveJobName[ OTA_JOB_ID_MAX_SIZE ];
311
312/*------------------------- OTA Public API --------------------------*/
313
394/* @[declare_ota_init] */
395OtaErr_t OTA_Init( OtaAppBuffer_t * pOtaBuffer,
396 const OtaInterfaces_t * pOtaInterfaces,
397 const uint8_t * pThingName,
398 OtaAppCallback_t OtaAppCallback );
399/* @[declare_ota_init] */
400
438/* @[declare_ota_shutdown] */
439OtaState_t OTA_Shutdown( uint32_t ticksToWait,
440 uint8_t unsubscribeFlag );
441/* @[declare_ota_shutdown] */
442
462/* @[declare_ota_getstate] */
464/* @[declare_ota_getstate] */
465
500/* @[declare_ota_activatenewimage] */
502/* @[declare_ota_activatenewimage] */
503
538/* @[declare_ota_setimagestate] */
540/* @[declare_ota_setimagestate] */
541
550/* @[declare_ota_getimagestate] */
552/* @[declare_ota_getimagestate] */
553
560/* @[declare_ota_checkforupdate] */
562/* @[declare_ota_checkforupdate] */
563
606/* @[declare_ota_suspend] */
607OtaErr_t OTA_Suspend( void );
608/* @[declare_ota_suspend] */
609
649/* @[declare_ota_resume] */
650OtaErr_t OTA_Resume( void );
651/* @[declare_ota_resume] */
652
667/* @[declare_ota_eventprocessingtask] */
668void OTA_EventProcessingTask( void * pUnused );
669/* @[declare_ota_eventprocessingtask] */
670
671
713/* @[declare_ota_signalevent] */
714bool OTA_SignalEvent( const OtaEventMsg_t * const pEventMsg );
715/* @[declare_ota_signalevent] */
716
717/*---------------------------------------------------------------------------*/
718/* Statistics API */
719/*---------------------------------------------------------------------------*/
720
759/* @[declare_ota_getstatistics] */
761/* @[declare_ota_getstatistics] */
762
770/* @[declare_ota_err_strerror] */
771const char * OTA_Err_strerror( OtaErr_t err );
772/* @[declare_ota_err_strerror] */
773
781/* @[declare_ota_jobparse_strerror] */
782const char * OTA_JobParse_strerror( OtaJobParseErr_t err );
783/* @[declare_ota_jobparse_strerror] */
784
792/* @[declare_ota_palstatus_strerror] */
793const char * OTA_PalStatus_strerror( OtaPalMainStatus_t status );
794/* @[declare_ota_palstatus_strerror] */
795
803/* @[declare_ota_osstatus_strerror] */
804const char * OTA_OsStatus_strerror( OtaOsStatus_t status );
805/* @[declare_ota_osstatus_strerror] */
806
807/* *INDENT-OFF* */
808#ifdef __cplusplus
809 }
810#endif
811/* *INDENT-ON* */
812
813#endif /* ifndef OTA_H */
void(* OtaAppCallback_t)(OtaJobEvent_t eEvent, const void *pData)
OTA update complete callback function typedef.
Definition: ota.h:243
OtaState_t
OTA Agent states.
Definition: ota.h:114
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:165
OtaJobParseErr_t
OTA job document parser error codes.
Definition: ota.h:135
OtaJobStatus_t
Gives the status of the job operation.
Definition: ota.h:183
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
@ 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:168
@ OtaJobEventSelfTestFailed
OTA self-test failed for current job.
Definition: ota.h:170
@ OtaJobEventUpdateComplete
OTA event when the update is completed.
Definition: ota.h:173
@ OtaJobEventFail
OTA receive failed. Unable to use this update.
Definition: ota.h:167
@ OtaJobEventReceivedJob
OTA event when a new valid AFT-OTA job is received.
Definition: ota.h:172
@ OtaJobEventParseCustomJob
OTA event for parsing custom job document.
Definition: ota.h:171
@ OtaJobEventActivate
OTA receive is authenticated and ready to activate.
Definition: ota.h:166
@ OtaJobEventProcessed
OTA event queued by OTA_SignalEvent is processed.
Definition: ota.h:169
OtaErr_t OTA_CheckForUpdate(void)
Request for the next available OTA job from the job service.
Definition: ota.c:3236
bool OTA_SignalEvent(const OtaEventMsg_t *const pEventMsg)
Signal event to the OTA Agent task.
Definition: ota.c:2921
const char * OTA_Err_strerror(OtaErr_t err)
Error code to string conversion for OTA errors.
Definition: ota.c:3427
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:3583
OtaErr_t OTA_ActivateNewImage(void)
Activate the newest MCU image received via OTA.
Definition: ota.c:3264
const char * OTA_PalStatus_strerror(OtaPalMainStatus_t status)
Status code to string conversion for OTA PAL status.
Definition: ota.c:3637
OtaErr_t OTA_GetStatistics(OtaAgentStatistics_t *pStatistics)
Get the statistics of OTA message packets.
Definition: ota.c:3223
OtaErr_t OTA_Suspend(void)
Suspend OTA agent operations .
Definition: ota.c:3365
OtaState_t OTA_GetState(void)
Get the current state of the OTA agent.
Definition: ota.c:3215
#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:3062
OtaImageState_t OTA_GetImageState(void)
Get the state of the currently running MCU image.
Definition: ota.c:3354
const char * OTA_JobParse_strerror(OtaJobParseErr_t err)
Error code to string conversion for OTA Job Parsing errors.
Definition: ota.c:3533
void OTA_EventProcessingTask(void *pUnused)
OTA agent event processing loop.
Definition: ota.c:2906
OtaErr_t OTA_SetImageState(OtaImageState_t state)
Set the state of the current MCU image.
Definition: ota.c:3300
OtaState_t OTA_Shutdown(uint32_t ticksToWait, uint8_t unsubscribeFlag)
Signal to the OTA Agent to shut down.
Definition: ota.c:3156
OtaErr_t OTA_Resume(void)
Resume OTA agent operations .
Definition: ota.c:3398
#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:294
uint32_t numOfBlocksToReceive
Definition: ota.h:304
uint8_t * pClientTokenFromJob
Definition: ota.h:301
uint32_t timestampFromJob
Definition: ota.h:302
OtaState_t state
Definition: ota.h:295
OtaAgentStatistics_t statistics
Definition: ota.h:305
OtaImageState_t imageState
Definition: ota.h:303
uint32_t fileIndex
Definition: ota.h:298
uint8_t unsubscribeOnShutdown
Definition: ota.h:309
uint32_t requestMomentum
Definition: ota.h:306
OtaAppCallback_t OtaAppCallback
Definition: ota.h:308
const OtaInterfaces_t * pOtaInterface
Definition: ota.h:307
uint32_t serverFileID
Definition: ota.h:299
OtaFileContext_t fileContext
Definition: ota.h:297
This is the OTA statistics structure to hold useful info.
Definition: ota_private.h:291
OTA Application Buffer size information.
Definition: ota.h:271
uint16_t authSchemeSize
Maximum size of the auth scheme.
Definition: ota.h:285
uint8_t * pUpdateFilePath
Path to store the files.
Definition: ota.h:272
uint16_t urlSize
Maximum size of the URL.
Definition: ota.h:283
uint16_t updateFilePathsize
Maximum size of the file path.
Definition: ota.h:273
uint8_t * pAuthScheme
Authentication scheme used to validate download.
Definition: ota.h:284
uint8_t * pUrl
Presigned url to download files from S3.
Definition: ota.h:282
uint32_t decodeMemorySize
Maximum size of the decoded files buffer.
Definition: ota.h:279
uint16_t certFilePathSize
Maximum size of the certificate file path.
Definition: ota.h:275
uint8_t * pCertFilePath
Path to certificate file.
Definition: ota.h:274
uint8_t * pFileBitmap
Bitmap of the parameters received.
Definition: ota.h:280
uint8_t * pStreamName
Name of stream to download the files.
Definition: ota.h:276
uint8_t * pDecodeMemory
Place to store the decoded files.
Definition: ota.h:278
uint16_t fileBitmapSize
Maximum size of the bitmap.
Definition: ota.h:281
uint16_t streamNameSize
Maximum size of the stream name.
Definition: ota.h:277
Stores information about the event message.
Definition: ota_private.h:434
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:257
OtaPalInterface_t pal
OTA PAL callback structure.
Definition: ota.h:261
OtaMqttInterface_t mqtt
MQTT interface that references the publish subscribe methods and callbacks.
Definition: ota.h:259
OtaOSInterface_t os
OS interface to store event, timers and memory operations.
Definition: ota.h:258
OtaHttpInterface_t http
HTTP interface to request data.
Definition: ota.h:260
OTA Job document.
Definition: ota.h:201
size_t jobIdLength
Length of job ID in bytes.
Definition: ota.h:205
int32_t reason
Job status reason.
Definition: ota.h:209
uint32_t fileTypeId
File Type ID from the job document.
Definition: ota.h:206
const uint8_t * pJobDocJson
Job document in JSON format.
Definition: ota.h:202
OtaJobStatus_t status
Job status.
Definition: ota.h:208
int32_t subReason
Job status subreason.
Definition: ota.h:210
const uint8_t * pJobId
Job ID associated with the job document.
Definition: ota.h:204
OtaJobParseErr_t parseErr
Job parsing status.
Definition: ota.h:207
size_t jobDocLength
Job document length in bytes.
Definition: ota.h:203
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