AWS IoT Over-the-air Update v3.4.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.4.0
3 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * SPDX-License-Identifier: MIT
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy of
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
10 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
21 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 */
24
30#ifndef OTA_H
31#define OTA_H
32
33/* *INDENT-OFF* */
34#ifdef __cplusplus
35 extern "C" {
36#endif
37/* *INDENT-ON* */
38
39/* Standard includes. */
40/* For FILE type in OtaFileContext_t.*/
41#include <stdio.h>
42#include <stdint.h>
43
44/* OTA Library Interface include. */
45#include "ota_private.h"
46#include "ota_os_interface.h"
47#include "ota_mqtt_interface.h"
48#include "ota_http_interface.h"
50
55#define CONST_STRLEN( s ) ( ( ( uint32_t ) sizeof( s ) ) - 1UL )
56
57
58#define OTA_FILE_SIG_KEY_STR_MAX_LENGTH 32
67/* MISRA Ref 8.6.1 [External linkage] */
68/* More details at: https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/main/MISRA.md#rule-86 */
69/* coverity[misra_c_2012_rule_8_6_violation] */
71
72/*-------------------------- OTA enumerated types --------------------------*/
73
79typedef enum OtaErr
80{
106
115typedef enum OtaState
116{
117 OtaAgentStateNoTransition = -1,
118 OtaAgentStateInit = 0,
119 OtaAgentStateReady,
120 OtaAgentStateRequestingJob,
121 OtaAgentStateWaitingForJob,
122 OtaAgentStateCreatingFile,
123 OtaAgentStateRequestingFileBlock,
124 OtaAgentStateWaitingForFileBlock,
125 OtaAgentStateClosingFile,
126 OtaAgentStateSuspended,
127 OtaAgentStateShuttingDown,
128 OtaAgentStateStopped,
129 OtaAgentStateAll
130} OtaState_t;
131
136typedef enum OtaJobParseErr
137{
138 OtaJobParseErrUnknown = -1, /* @brief The error code has not yet been set by a logic path. */
139 OtaJobParseErrNone = 0, /* @brief Signifies no error has occurred. */
140 OtaJobParseErrNullJob, /* @brief A null job was reported (no job ID). */
141 OtaJobParseErrUpdateCurrentJob, /* @brief We're already busy with the reported job ID. */
142 OtaJobParseErrZeroFileSize, /* @brief Job document specified a zero sized file. This is not allowed. */
143 OtaJobParseErrNonConformingJobDoc, /* @brief The job document failed to fulfill the model requirements. */
144 OtaJobParseErrBadModelInitParams, /* @brief There was an invalid initialization parameter used in the document model. */
145 OtaJobParseErrNoContextAvailable, /* @brief There was not an OTA context available. */
146 OtaJobParseErrNoActiveJobs /* @brief No active jobs are available in the service. */
148
166typedef enum OtaJobEvent
167{
177 OtaLastJobEvent = OtaJobEventStartTest
179
185typedef enum
186{
187 JobStatusInProgress = 0,
188 JobStatusFailed,
189 JobStatusSucceeded,
190 JobStatusRejected, /* Not possible today using the "get next job" feature. FUTURE! */
191 JobStatusFailedWithVal, /* This shows 2 numeric reason codes. */
192 NumJobStatusMappings
194
203typedef struct OtaJobDocument
204{
205 const uint8_t * pJobDocJson;
207 const uint8_t * pJobId;
208 size_t jobIdLength;
209 uint32_t fileTypeId;
212 int32_t reason;
213 int32_t subReason;
215
216/*------------------------- OTA callbacks --------------------------*/
217
288typedef void (* OtaAppCallback_t)( OtaJobEvent_t eEvent,
289 void * pData );
290
291/*--------------------------- OTA structs ----------------------------*/
292
293
301typedef struct OtaInterface
302{
308
315typedef struct OtaAppBuffer
316{
317 uint8_t * pUpdateFilePath;
319 uint8_t * pCertFilePath;
321 uint8_t * pStreamName;
322 uint16_t streamNameSize;
323 uint8_t * pDecodeMemory;
325 uint8_t * pFileBitmap;
326 uint16_t fileBitmapSize;
327 uint8_t * pUrl;
328 uint16_t urlSize;
329 uint8_t * pAuthScheme;
330 uint16_t authSchemeSize;
332
338typedef struct OtaAgentContext
339{
341 uint8_t pThingName[ otaconfigMAX_THINGNAME_LEN + 1U ];
343 uint32_t fileIndex;
344 uint32_t serverFileID;
345 uint8_t pActiveJobName[ OTA_JOB_ID_MAX_SIZE ];
357
358/*------------------------- OTA Public API --------------------------*/
359
440/* @[declare_ota_init] */
441OtaErr_t OTA_Init( const OtaAppBuffer_t * pOtaBuffer,
442 const OtaInterfaces_t * pOtaInterfaces,
443 const uint8_t * pThingName,
444 OtaAppCallback_t OtaAppCallback );
445/* @[declare_ota_init] */
446
487/* @[declare_ota_shutdown] */
488OtaState_t OTA_Shutdown( uint32_t ticksToWait,
489 uint8_t unsubscribeFlag );
490/* @[declare_ota_shutdown] */
491
511/* @[declare_ota_getstate] */
513/* @[declare_ota_getstate] */
514
549/* @[declare_ota_activatenewimage] */
551/* @[declare_ota_activatenewimage] */
552
587/* @[declare_ota_setimagestate] */
589/* @[declare_ota_setimagestate] */
590
599/* @[declare_ota_getimagestate] */
601/* @[declare_ota_getimagestate] */
602
609/* @[declare_ota_checkforupdate] */
611/* @[declare_ota_checkforupdate] */
612
655/* @[declare_ota_suspend] */
656OtaErr_t OTA_Suspend( void );
657/* @[declare_ota_suspend] */
658
698/* @[declare_ota_resume] */
699OtaErr_t OTA_Resume( void );
700/* @[declare_ota_resume] */
701
716/* @[declare_ota_eventprocessingtask] */
717void OTA_EventProcessingTask( const void * pUnused );
718/* @[declare_ota_eventprocessingtask] */
719
720
733/* @[declare_ota_eventprocess] */
735/* @[declare_ota_eventprocess] */
736
778/* @[declare_ota_signalevent] */
779bool OTA_SignalEvent( const OtaEventMsg_t * const pEventMsg );
780/* @[declare_ota_signalevent] */
781
782/*---------------------------------------------------------------------------*/
783/* Statistics API */
784/*---------------------------------------------------------------------------*/
785
824/* @[declare_ota_getstatistics] */
826/* @[declare_ota_getstatistics] */
827
835/* @[declare_ota_err_strerror] */
836const char * OTA_Err_strerror( OtaErr_t err );
837/* @[declare_ota_err_strerror] */
838
846/* @[declare_ota_jobparse_strerror] */
847const char * OTA_JobParse_strerror( OtaJobParseErr_t err );
848/* @[declare_ota_jobparse_strerror] */
849
857/* @[declare_ota_palstatus_strerror] */
858const char * OTA_PalStatus_strerror( OtaPalMainStatus_t status );
859/* @[declare_ota_palstatus_strerror] */
860
868/* @[declare_ota_osstatus_strerror] */
869const char * OTA_OsStatus_strerror( OtaOsStatus_t status );
870/* @[declare_ota_osstatus_strerror] */
871
872/* *INDENT-OFF* */
873#ifdef __cplusplus
874 }
875#endif
876/* *INDENT-ON* */
877
878#endif /* ifndef OTA_H */
void(* OtaAppCallback_t)(OtaJobEvent_t eEvent, void *pData)
OTA update complete callback function typedef.
Definition: ota.h:288
uint32_t OtaPalMainStatus_t
The OTA platform interface main status.
Definition: ota_platform_interface.h:80
OtaState_t
OTA Agent states.
Definition: ota.h:116
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:80
OtaJobEvent_t
OTA Job callback events.
Definition: ota.h:167
OtaJobParseErr_t
OTA job document parser error codes.
Definition: ota.h:137
OtaJobStatus_t
Gives the status of the job operation.
Definition: ota.h:186
OtaImageState_t
OTA Image states.
Definition: ota_private.h:316
OtaOsStatus_t
The OTA OS interface return status.
Definition: ota_os_interface.h:101
@ OtaErrInvalidDataProtocol
Job does not have a valid protocol for data transfer.
Definition: ota.h:94
@ OtaErrPanic
Unrecoverable Firmware error. Probably should log error and reboot.
Definition: ota.h:83
@ OtaErrUninitialized
The error code has not yet been set by a logic path.
Definition: ota.h:82
@ OtaErrNone
No error occurred during the operation.
Definition: ota.h:81
@ OtaErrDowngradeNotAllowed
Firmware version is older than the previous version.
Definition: ota.h:96
@ OtaErrFileSizeOverflow
Firmware file size greater than the max allowed size.
Definition: ota.h:104
@ OtaErrAgentStopped
Returned when operations are performed that requires OTA Agent running & its stopped.
Definition: ota.h:85
@ OtaErrImageStateMismatch
The OTA job was in Self Test but the platform image state was not. Possible tampering.
Definition: ota.h:98
@ OtaErrMomentumAbort
Too many OTA stream requests without any response.
Definition: ota.h:95
@ OtaErrRequestJobFailed
Failed to request the job document.
Definition: ota.h:87
@ OtaErrJobParserError
An error occurred during job document parsing. See reason sub-code.
Definition: ota.h:93
@ OtaErrRequestFileBlockFailed
Failed to request file block.
Definition: ota.h:89
@ OtaErrInitFileTransferFailed
Failed to update the OTA job status.
Definition: ota.h:88
@ OtaErrNoActiveJob
Attempt to set final image state without an active job.
Definition: ota.h:99
@ OtaErrFailedToDecodeCbor
Failed to decode CBOR object from streaming service response.
Definition: ota.h:102
@ OtaErrSignalEventFailed
Failed to send event to OTA state machine.
Definition: ota.h:86
@ OtaErrCleanupControlFailed
Failed to clean up the control plane.
Definition: ota.h:90
@ OtaErrUpdateJobStatusFailed
Failed to update the OTA job status.
Definition: ota.h:92
@ OtaErrFailedToEncodeCbor
Failed to encode CBOR object for requesting data block from streaming service.
Definition: ota.h:101
@ OtaErrSameFirmwareVersion
Firmware version is the same as previous. New firmware could have failed to commit.
Definition: ota.h:97
@ OtaErrCleanupDataFailed
Failed to clean up the data plane.
Definition: ota.h:91
@ OtaErrInvalidArg
API called with invalid argument.
Definition: ota.h:84
@ OtaErrActivateFailed
Failed to activate the new image.
Definition: ota.h:103
@ OtaErrUserAbort
User aborted the active OTA.
Definition: ota.h:100
@ OtaJobEventStartTest
OTA job is now in self test, perform user tests.
Definition: ota.h:170
@ OtaJobEventNoActiveJob
OTA event when no active job is pending.
Definition: ota.h:176
@ OtaJobEventSelfTestFailed
OTA self-test failed for current job.
Definition: ota.h:172
@ OtaJobEventUpdateComplete
OTA event when the update is completed.
Definition: ota.h:175
@ OtaJobEventFail
OTA receive failed. Unable to use this update.
Definition: ota.h:169
@ OtaJobEventReceivedJob
OTA event when a new valid AFT-OTA job is received.
Definition: ota.h:174
@ OtaJobEventParseCustomJob
OTA event for parsing custom job document.
Definition: ota.h:173
@ OtaJobEventActivate
OTA receive is authenticated and ready to activate.
Definition: ota.h:168
@ OtaJobEventProcessed
OTA event queued by OTA_SignalEvent is processed.
Definition: ota.h:171
OtaErr_t OTA_CheckForUpdate(void)
Request for the next available OTA job from the job service.
Definition: ota.c:3413
OtaErr_t OTA_Init(const OtaAppBuffer_t *pOtaBuffer, const OtaInterfaces_t *pOtaInterfaces, const uint8_t *pThingName, OtaAppCallback_t OtaAppCallback)
OTA Agent initialization function.
Definition: ota.c:3236
bool OTA_SignalEvent(const OtaEventMsg_t *const pEventMsg)
Signal event to the OTA Agent task.
Definition: ota.c:3066
const char * OTA_Err_strerror(OtaErr_t err)
Error code to string conversion for OTA errors.
Definition: ota.c:3623
const char OTA_JsonFileSignatureKey[OTA_FILE_SIG_KEY_STR_MAX_LENGTH]
The OTA signature algorithm string is specified by the PAL.
void OTA_EventProcessingTask(const void *pUnused)
OTA agent event processing loop.
Definition: ota.c:3025
const char * OTA_OsStatus_strerror(OtaOsStatus_t status)
Status code to string conversion for OTA OS status.
Definition: ota.c:3779
OtaErr_t OTA_ActivateNewImage(void)
Activate the newest MCU image received via OTA.
Definition: ota.c:3441
const char * OTA_PalStatus_strerror(OtaPalMainStatus_t status)
Status code to string conversion for OTA PAL status.
Definition: ota.c:3833
OtaErr_t OTA_GetStatistics(OtaAgentStatistics_t *pStatistics)
Get the statistics of OTA message packets.
Definition: ota.c:3400
OtaErr_t OTA_Suspend(void)
Suspend OTA agent operations .
Definition: ota.c:3542
OtaState_t OTA_GetState(void)
Get the current state of the OTA agent.
Definition: ota.c:3392
OtaState_t OTA_EventProcess(void)
OTA agent event process cycler.
Definition: ota.c:3047
#define OTA_FILE_SIG_KEY_STR_MAX_LENGTH
Definition: ota.h:58
OtaImageState_t OTA_GetImageState(void)
Get the state of the currently running MCU image.
Definition: ota.c:3531
const char * OTA_JobParse_strerror(OtaJobParseErr_t err)
Error code to string conversion for OTA Job Parsing errors.
Definition: ota.c:3729
OtaErr_t OTA_SetImageState(OtaImageState_t state)
Set the state of the current MCU image.
Definition: ota.c:3477
OtaState_t OTA_Shutdown(uint32_t ticksToWait, uint8_t unsubscribeFlag)
Signal to the OTA Agent to shut down.
Definition: ota.c:3339
OtaErr_t OTA_Resume(void)
Resume OTA agent operations .
Definition: ota.c:3578
#define otaconfigMAX_THINGNAME_LEN
The maximum allowed length of the thing name used by the OTA agent.
Definition: ota_config_defaults.h:140
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:111
The OTA agent is a singleton today. The structure keeps it nice and organized.
Definition: ota.h:339
uint32_t numOfBlocksToReceive
Definition: ota.h:349
uint8_t isOtaInterfaceInited
Definition: ota.h:355
uint8_t * pClientTokenFromJob
Definition: ota.h:346
uint32_t timestampFromJob
Definition: ota.h:347
OtaState_t state
Definition: ota.h:340
OtaAgentStatistics_t statistics
Definition: ota.h:350
OtaImageState_t imageState
Definition: ota.h:348
uint32_t fileIndex
Definition: ota.h:343
uint8_t unsubscribeOnShutdown
Definition: ota.h:354
uint32_t requestMomentum
Definition: ota.h:351
OtaAppCallback_t OtaAppCallback
Definition: ota.h:353
const OtaInterfaces_t * pOtaInterface
Definition: ota.h:352
uint32_t serverFileID
Definition: ota.h:344
OtaFileContext_t fileContext
Definition: ota.h:342
This is the OTA statistics structure to hold useful info.
Definition: ota_private.h:293
OTA Application Buffer size information.
Definition: ota.h:316
uint16_t authSchemeSize
Maximum size of the auth scheme.
Definition: ota.h:330
uint8_t * pUpdateFilePath
Path to store the files.
Definition: ota.h:317
uint16_t urlSize
Maximum size of the URL.
Definition: ota.h:328
uint16_t updateFilePathsize
Maximum size of the file path.
Definition: ota.h:318
uint8_t * pAuthScheme
Authentication scheme used to validate download.
Definition: ota.h:329
uint8_t * pUrl
Presigned url to download files from S3.
Definition: ota.h:327
uint32_t decodeMemorySize
Maximum size of the decoded files buffer.
Definition: ota.h:324
uint16_t certFilePathSize
Maximum size of the certificate file path.
Definition: ota.h:320
uint8_t * pCertFilePath
Path to certificate file.
Definition: ota.h:319
uint8_t * pFileBitmap
Bitmap of the parameters received.
Definition: ota.h:325
uint8_t * pStreamName
Name of stream to download the files.
Definition: ota.h:321
uint8_t * pDecodeMemory
Place to store the decoded files.
Definition: ota.h:323
uint16_t fileBitmapSize
Maximum size of the bitmap.
Definition: ota.h:326
uint16_t streamNameSize
Maximum size of the stream name.
Definition: ota.h:322
Stores information about the event message.
Definition: ota_private.h:432
OTA File Context Information.
Definition: ota_private.h:384
OTA Event Interface structure.
Definition: ota_http_interface.h:138
OTA Interface for referencing different components.
Definition: ota.h:302
OtaPalInterface_t pal
OTA PAL callback structure.
Definition: ota.h:306
OtaMqttInterface_t mqtt
MQTT interface that references the publish subscribe methods and callbacks.
Definition: ota.h:304
OtaOSInterface_t os
OS interface to store event, timers and memory operations.
Definition: ota.h:303
OtaHttpInterface_t http
HTTP interface to request data.
Definition: ota.h:305
OTA Job document.
Definition: ota.h:204
size_t jobIdLength
Length of job ID in bytes.
Definition: ota.h:208
int32_t reason
Job status reason.
Definition: ota.h:212
uint32_t fileTypeId
File Type ID from the job document.
Definition: ota.h:209
const uint8_t * pJobDocJson
Job document in JSON format.
Definition: ota.h:205
OtaJobStatus_t status
Job status.
Definition: ota.h:211
int32_t subReason
Job status subreason.
Definition: ota.h:213
const uint8_t * pJobId
Job ID associated with the job document.
Definition: ota.h:207
OtaJobParseErr_t parseErr
Job parsing status.
Definition: ota.h:210
size_t jobDocLength
Job document length in bytes.
Definition: ota.h:206
OTA Event Interface structure.
Definition: ota_mqtt_interface.h:164
OTA OS Interface.
Definition: ota_os_interface.h:308
OTA pal Interface structure.
Definition: ota_platform_interface.h:302