AWS IoT Over-the-air Update v3.0.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.0.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/* Standard includes. */
32/* For FILE type in OtaFileContext_t.*/
33#include <stdio.h>
34#include <stdint.h>
35
36/* OTA Library Interface include. */
37#include "ota_private.h"
38#include "ota_os_interface.h"
39#include "ota_mqtt_interface.h"
40#include "ota_http_interface.h"
42
47#define CONST_STRLEN( s ) ( ( ( uint32_t ) sizeof( s ) ) - 1UL )
48
49
50#define OTA_FILE_SIG_KEY_STR_MAX_LENGTH 32
59/* MISRA rule 8.6 requires identifier with external linkage to have exact one external definition.
60 * However, this variable is defined in OTA platform abstraction layer implementation, which is
61 * not in this repository but in C-SDK and amazon-freertos repo, so it's a false positive. */
62/* coverity[misra_c_2012_rule_8_6_violation] */
64
65/*-------------------------- OTA enumerated types --------------------------*/
66
72typedef enum OtaErr
73{
98
107typedef enum OtaState
108{
109 OtaAgentStateNoTransition = -1,
110 OtaAgentStateInit = 0,
111 OtaAgentStateReady,
112 OtaAgentStateRequestingJob,
113 OtaAgentStateWaitingForJob,
114 OtaAgentStateCreatingFile,
115 OtaAgentStateRequestingFileBlock,
116 OtaAgentStateWaitingForFileBlock,
117 OtaAgentStateClosingFile,
118 OtaAgentStateSuspended,
119 OtaAgentStateShuttingDown,
120 OtaAgentStateStopped,
121 OtaAgentStateAll
122} OtaState_t;
123
128typedef enum OtaJobParseErr
129{
130 OtaJobParseErrUnknown = -1, /* @brief The error code has not yet been set by a logic path. */
131 OtaJobParseErrNone = 0, /* @brief Signifies no error has occurred. */
132 OtaJobParseErrNullJob, /* @brief A null job was reported (no job ID). */
133 OtaJobParseErrUpdateCurrentJob, /* @brief We're already busy with the reported job ID. */
134 OtaJobParseErrZeroFileSize, /* @brief Job document specified a zero sized file. This is not allowed. */
135 OtaJobParseErrNonConformingJobDoc, /* @brief The job document failed to fulfill the model requirements. */
136 OtaJobParseErrBadModelInitParams, /* @brief There was an invalid initialization parameter used in the document model. */
137 OtaJobParseErrNoContextAvailable, /* @brief There was not an OTA context available. */
138 OtaJobParseErrNoActiveJobs /* @brief No active jobs are available in the service. */
140
158typedef enum OtaJobEvent
159{
168 OtaLastJobEvent = OtaJobEventStartTest
170
176typedef enum
177{
178 JobStatusInProgress = 0,
179 JobStatusFailed,
180 JobStatusSucceeded,
181 JobStatusRejected, /* Not possible today using the "get next job" feature. FUTURE! */
182 JobStatusFailedWithVal, /* This shows 2 numeric reason codes. */
183 NumJobStatusMappings
185
194typedef struct OtaJobDocument
195{
196 const uint8_t * pJobDocJson;
198 const uint8_t * pJobId;
199 size_t jobIdLength;
200 uint32_t fileTypeId;
203 int32_t reason;
204 int32_t subReason;
206
207/*------------------------- OTA callbacks --------------------------*/
208
239typedef void (* OtaAppCallback_t)( OtaJobEvent_t eEvent,
240 const void * pData );
241
242/*--------------------------- OTA structs ----------------------------*/
243
244
252typedef struct OtaInterface
253{
259
266typedef struct OtaAppBuffer
267{
268 uint8_t * pUpdateFilePath;
270 uint8_t * pCertFilePath;
272 uint8_t * pStreamName;
273 uint16_t streamNameSize;
274 uint8_t * pDecodeMemory;
276 uint8_t * pFileBitmap;
277 uint16_t fileBitmapSize;
278 uint8_t * pUrl;
279 uint16_t urlSize;
280 uint8_t * pAuthScheme;
281 uint16_t authSchemeSize;
283
289typedef struct OtaAgentContext
290{
292 uint8_t pThingName[ otaconfigMAX_THINGNAME_LEN + 1U ];
294 uint32_t fileIndex;
295 uint32_t serverFileID;
296 uint8_t pActiveJobName[ OTA_JOB_ID_MAX_SIZE ];
307
308/*------------------------- OTA Public API --------------------------*/
309
390/* @[declare_ota_init] */
391OtaErr_t OTA_Init( OtaAppBuffer_t * pOtaBuffer,
392 OtaInterfaces_t * pOtaInterfaces,
393 const uint8_t * pThingName,
394 OtaAppCallback_t OtaAppCallback );
395/* @[declare_ota_init] */
396
434/* @[declare_ota_shutdown] */
435OtaState_t OTA_Shutdown( uint32_t ticksToWait,
436 uint8_t unsubscribeFlag );
437/* @[declare_ota_shutdown] */
438
458/* @[declare_ota_getstate] */
460/* @[declare_ota_getstate] */
461
496/* @[declare_ota_activatenewimage] */
498/* @[declare_ota_activatenewimage] */
499
534/* @[declare_ota_setimagestate] */
536/* @[declare_ota_setimagestate] */
537
546/* @[declare_ota_getimagestate] */
548/* @[declare_ota_getimagestate] */
549
556/* @[declare_ota_checkforupdate] */
558/* @[declare_ota_checkforupdate] */
559
602/* @[declare_ota_suspend] */
603OtaErr_t OTA_Suspend( void );
604/* @[declare_ota_suspend] */
605
645/* @[declare_ota_resume] */
646OtaErr_t OTA_Resume( void );
647/* @[declare_ota_resume] */
648
663/* @[declare_ota_eventprocessingtask] */
664void OTA_EventProcessingTask( void * pUnused );
665/* @[declare_ota_eventprocessingtask] */
666
667
709/* @[declare_ota_signalevent] */
710bool OTA_SignalEvent( const OtaEventMsg_t * const pEventMsg );
711/* @[declare_ota_signalevent] */
712
713/*---------------------------------------------------------------------------*/
714/* Statistics API */
715/*---------------------------------------------------------------------------*/
716
755/* @[declare_ota_getstatistics] */
757/* @[declare_ota_getstatistics] */
758
766/* @[declare_ota_err_strerror] */
767const char * OTA_Err_strerror( OtaErr_t err );
768/* @[declare_ota_err_strerror] */
769
777/* @[declare_ota_jobparse_strerror] */
778const char * OTA_JobParse_strerror( OtaJobParseErr_t err );
779/* @[declare_ota_jobparse_strerror] */
780
788/* @[declare_ota_palstatus_strerror] */
789const char * OTA_PalStatus_strerror( OtaPalMainStatus_t status );
790/* @[declare_ota_palstatus_strerror] */
791
799/* @[declare_ota_osstatus_strerror] */
800const char * OTA_OsStatus_strerror( OtaOsStatus_t status );
801/* @[declare_ota_osstatus_strerror] */
802
803#endif /* ifndef OTA_H */
void(* OtaAppCallback_t)(OtaJobEvent_t eEvent, const void *pData)
OTA update complete callback function typedef.
Definition: ota.h:239
OtaState_t
OTA Agent states.
Definition: ota.h:108
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:73
OtaPalMainStatus_t
The OTA platform interface main status.
Definition: ota_platform_interface.h:73
OtaJobEvent_t
OTA Job callback events.
Definition: ota.h:159
OtaJobParseErr_t
OTA job document parser error codes.
Definition: ota.h:129
OtaJobStatus_t
Gives the status of the job operation.
Definition: ota.h:177
OtaImageState_t
OTA Image states.
Definition: ota_private.h:312
OtaOsStatus_t
The OTA OS interface return status.
Definition: ota_os_interface.h:93
@ OtaErrInvalidDataProtocol
Job does not have a valid protocol for data transfer.
Definition: ota.h:87
@ OtaErrPanic
Unrecoverable Firmware error. Probably should log error and reboot.
Definition: ota.h:76
@ OtaErrUninitialized
The error code has not yet been set by a logic path.
Definition: ota.h:75
@ OtaErrNone
No error occurred during the operation.
Definition: ota.h:74
@ OtaErrDowngradeNotAllowed
Firmware version is older than the previous version.
Definition: ota.h:89
@ OtaErrAgentStopped
Returned when operations are performed that requires OTA Agent running & its stopped.
Definition: ota.h:78
@ OtaErrImageStateMismatch
The OTA job was in Self Test but the platform image state was not. Possible tampering.
Definition: ota.h:91
@ OtaErrMomentumAbort
Too many OTA stream requests without any response.
Definition: ota.h:88
@ OtaErrRequestJobFailed
Failed to request the job document.
Definition: ota.h:80
@ OtaErrJobParserError
An error occurred during job document parsing. See reason sub-code.
Definition: ota.h:86
@ OtaErrRequestFileBlockFailed
Failed to request file block.
Definition: ota.h:82
@ OtaErrInitFileTransferFailed
Failed to update the OTA job status.
Definition: ota.h:81
@ OtaErrNoActiveJob
Attempt to set final image state without an active job.
Definition: ota.h:92
@ OtaErrFailedToDecodeCbor
Failed to decode CBOR object from streaming service response.
Definition: ota.h:95
@ OtaErrSignalEventFailed
Failed to send event to OTA state machine.
Definition: ota.h:79
@ OtaErrCleanupControlFailed
Failed to clean up the control plane.
Definition: ota.h:83
@ OtaErrUpdateJobStatusFailed
Failed to update the OTA job status.
Definition: ota.h:85
@ OtaErrFailedToEncodeCbor
Failed to encode CBOR object for requesting data block from streaming service.
Definition: ota.h:94
@ OtaErrSameFirmwareVersion
Firmware version is the same as previous. New firmware could have failed to commit.
Definition: ota.h:90
@ OtaErrCleanupDataFailed
Failed to clean up the data plane.
Definition: ota.h:84
@ OtaErrInvalidArg
API called with invalid argument.
Definition: ota.h:77
@ OtaErrActivateFailed
Failed to activate the new image.
Definition: ota.h:96
@ OtaErrUserAbort
User aborted the active OTA.
Definition: ota.h:93
@ OtaJobEventStartTest
OTA job is now in self test, perform user tests.
Definition: ota.h:162
@ OtaJobEventSelfTestFailed
OTA self-test failed for current job.
Definition: ota.h:164
@ OtaJobEventUpdateComplete
OTA event when the update is completed.
Definition: ota.h:167
@ OtaJobEventFail
OTA receive failed. Unable to use this update.
Definition: ota.h:161
@ OtaJobEventReceivedJob
OTA event when a new valid AFT-OTA job is received.
Definition: ota.h:166
@ OtaJobEventParseCustomJob
OTA event for parsing custom job document.
Definition: ota.h:165
@ OtaJobEventActivate
OTA receive is authenticated and ready to activate.
Definition: ota.h:160
@ OtaJobEventProcessed
OTA event queued by OTA_SignalEvent is processed.
Definition: ota.h:163
OtaErr_t OTA_CheckForUpdate(void)
Request for the next available OTA job from the job service.
Definition: ota.c:3237
bool OTA_SignalEvent(const OtaEventMsg_t *const pEventMsg)
Signal event to the OTA Agent task.
Definition: ota.c:2922
const char * OTA_Err_strerror(OtaErr_t err)
Error code to string conversion for OTA errors.
Definition: ota.c:3428
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:3584
OtaErr_t OTA_ActivateNewImage(void)
Activate the newest MCU image received via OTA.
Definition: ota.c:3265
const char * OTA_PalStatus_strerror(OtaPalMainStatus_t status)
Status code to string conversion for OTA PAL status.
Definition: ota.c:3638
OtaErr_t OTA_GetStatistics(OtaAgentStatistics_t *pStatistics)
Get the statistics of OTA message packets.
Definition: ota.c:3224
OtaErr_t OTA_Suspend(void)
Suspend OTA agent operations .
Definition: ota.c:3366
OtaState_t OTA_GetState(void)
Get the current state of the OTA agent.
Definition: ota.c:3216
#define OTA_FILE_SIG_KEY_STR_MAX_LENGTH
Definition: ota.h:50
OtaImageState_t OTA_GetImageState(void)
Get the state of the currently running MCU image.
Definition: ota.c:3355
const char * OTA_JobParse_strerror(OtaJobParseErr_t err)
Error code to string conversion for OTA Job Parsing errors.
Definition: ota.c:3534
void OTA_EventProcessingTask(void *pUnused)
OTA agent event processing loop.
Definition: ota.c:2907
OtaErr_t OTA_SetImageState(OtaImageState_t state)
Set the state of the current MCU image.
Definition: ota.c:3301
OtaState_t OTA_Shutdown(uint32_t ticksToWait, uint8_t unsubscribeFlag)
Signal to the OTA Agent to shut down.
Definition: ota.c:3157
OtaErr_t OTA_Init(OtaAppBuffer_t *pOtaBuffer, OtaInterfaces_t *pOtaInterfaces, const uint8_t *pThingName, OtaAppCallback_t OtaAppCallback)
OTA Agent initialization function.
Definition: ota.c:3063
OtaErr_t OTA_Resume(void)
Resume OTA agent operations .
Definition: ota.c:3399
#define otaconfigMAX_THINGNAME_LEN
The maximum allowed length of the thing name used by the OTA agent.
Definition: ota_config_defaults.h:132
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:107
The OTA agent is a singleton today. The structure keeps it nice and organized.
Definition: ota.h:290
OtaInterfaces_t * pOtaInterface
Definition: ota.h:303
uint32_t numOfBlocksToReceive
Definition: ota.h:300
uint8_t * pClientTokenFromJob
Definition: ota.h:297
uint32_t timestampFromJob
Definition: ota.h:298
OtaState_t state
Definition: ota.h:291
OtaAgentStatistics_t statistics
Definition: ota.h:301
OtaImageState_t imageState
Definition: ota.h:299
uint32_t fileIndex
Definition: ota.h:294
uint8_t unsubscribeOnShutdown
Definition: ota.h:305
uint32_t requestMomentum
Definition: ota.h:302
OtaAppCallback_t OtaAppCallback
Definition: ota.h:304
uint32_t serverFileID
Definition: ota.h:295
OtaFileContext_t fileContext
Definition: ota.h:293
This is the OTA statistics structure to hold useful info.
Definition: ota_private.h:289
OTA Application Buffer size information.
Definition: ota.h:267
uint16_t authSchemeSize
Maximum size of the auth scheme.
Definition: ota.h:281
uint8_t * pUpdateFilePath
Path to store the files.
Definition: ota.h:268
uint16_t urlSize
Maximum size of the URL.
Definition: ota.h:279
uint16_t updateFilePathsize
Maximum size of the file path.
Definition: ota.h:269
uint8_t * pAuthScheme
Authentication scheme used to validate download.
Definition: ota.h:280
uint8_t * pUrl
Presigned url to download files from S3.
Definition: ota.h:278
uint32_t decodeMemorySize
Maximum size of the decoded files buffer.
Definition: ota.h:275
uint16_t certFilePathSize
Maximum size of the certificate file path.
Definition: ota.h:271
uint8_t * pCertFilePath
Path to certificate file.
Definition: ota.h:270
uint8_t * pFileBitmap
Bitmap of the parameters received.
Definition: ota.h:276
uint8_t * pStreamName
Name of stream to download the files.
Definition: ota.h:272
uint8_t * pDecodeMemory
Place to store the decoded files.
Definition: ota.h:274
uint16_t fileBitmapSize
Maximum size of the bitmap.
Definition: ota.h:277
uint16_t streamNameSize
Maximum size of the stream name.
Definition: ota.h:273
Stores information about the event message.
Definition: ota_private.h:432
OTA File Context Information.
Definition: ota_private.h:380
OTA Event Interface structure.
Definition: ota_http_interface.h:130
OTA Interface for referencing different components.
Definition: ota.h:253
OtaPalInterface_t pal
OTA PAL callback structure.
Definition: ota.h:257
OtaMqttInterface_t mqtt
MQTT interface that references the publish subscribe methods and callbacks.
Definition: ota.h:255
OtaOSInterface_t os
OS interface to store event, timers and memory operations.
Definition: ota.h:254
OtaHttpInterface_t http
HTTP interface to request data.
Definition: ota.h:256
OTA Job document.
Definition: ota.h:195
size_t jobIdLength
Length of job ID in bytes.
Definition: ota.h:199
int32_t reason
Job status reason.
Definition: ota.h:203
uint32_t fileTypeId
File Type ID from the job document.
Definition: ota.h:200
const uint8_t * pJobDocJson
Job document in JSON format.
Definition: ota.h:196
OtaJobStatus_t status
Job status.
Definition: ota.h:202
int32_t subReason
Job status subreason.
Definition: ota.h:204
const uint8_t * pJobId
Job ID associated with the job document.
Definition: ota.h:198
OtaJobParseErr_t parseErr
Job parsing status.
Definition: ota.h:201
size_t jobDocLength
Job document length in bytes.
Definition: ota.h:197
OTA Event Interface structure.
Definition: ota_mqtt_interface.h:156
OTA OS Interface.
Definition: ota_os_interface.h:295
OTA pal Interface structure.
Definition: ota_platform_interface.h:292