AWS IoT Over-the-air Update v3.4.0
Client library for AWS IoT OTA
ota_private.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
31#ifndef OTA_PRIVATE_H
32#define OTA_PRIVATE_H
33
34/* *INDENT-OFF* */
35#ifdef __cplusplus
36 extern "C" {
37#endif
38/* *INDENT-ON* */
39
40/* Standard includes. */
41/* For FILE type in OtaFileContext_t.*/
42#include <stdio.h>
43#include <stdint.h>
44#include <stdbool.h>
45
46/* OTA_DO_NOT_USE_CUSTOM_CONFIG allows building the OTA library
47 * without a custom config. If a custom config is provided, the
48 * OTA_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */
49#ifndef OTA_DO_NOT_USE_CUSTOM_CONFIG
50 #include "ota_config.h"
51#endif
52
53/* Include config defaults header to get default values of configs not defined
54 * in ota_config.h file. */
55#include "ota_config_defaults.h"
56
61/* General constants. */
62#define LOG2_BITS_PER_BYTE 3U
63#define BITS_PER_BYTE ( ( uint32_t ) 1U << LOG2_BITS_PER_BYTE )
64#define OTA_FILE_BLOCK_SIZE ( ( uint32_t ) 1U << otaconfigLOG2_FILE_BLOCK_SIZE )
65#define OTA_MAX_FILES 1U
66#define OTA_MAX_BLOCK_BITMAP_SIZE 128U
67#define OTA_REQUEST_MSG_MAX_SIZE ( 3U * OTA_MAX_BLOCK_BITMAP_SIZE )
68#define OTA_REQUEST_URL_MAX_SIZE ( 1500 )
69#define OTA_ERASED_BLOCKS_VAL 0xffU
70#define OTA_MAX_FILE_SIZE UINT32_MAX - OTA_FILE_BLOCK_SIZE + 1U
77/* Job document parser constants. */
78#define OTA_MAX_JSON_TOKENS 64U
79#define OTA_MAX_JSON_STR_LEN 256U
80#define OTA_DOC_MODEL_MAX_PARAMS 32U
81#define OTA_JOB_PARAM_REQUIRED ( bool ) true
82#define OTA_JOB_PARAM_OPTIONAL ( bool ) false
83#define OTA_DONT_STORE_PARAM 0xffff
84#define OTA_STORE_NESTED_JSON 0x1fffU
85#define OTA_DATA_BLOCK_SIZE ( ( 1U << otaconfigLOG2_FILE_BLOCK_SIZE ) + OTA_REQUEST_URL_MAX_SIZE + 30 )
92/* OTA Agent task event flags. */
93#define OTA_EVT_MASK_JOB_MSG_READY 0x00000001UL
94#define OTA_EVT_MASK_DATA_MSG_READY 0x00000002UL
95#define OTA_EVT_MASK_SHUTDOWN 0x00000004UL
96#define OTA_EVT_MASK_REQ_TIMEOUT 0x00000008UL
97#define OTA_EVT_MASK_USER_ABORT 0x000000016UL
98#define OTA_EVT_MASK_ALL_EVENTS ( OTA_EVT_MASK_JOB_MSG_READY | OTA_EVT_MASK_DATA_MSG_READY | OTA_EVT_MASK_SHUTDOWN | OTA_EVT_MASK_REQ_TIMEOUT | OTA_EVT_MASK_USER_ABORT )
105#define OTA_NUM_JOB_PARAMS ( 21 )
106
111#define OTA_JOB_ID_MAX_SIZE ( 72UL + 1UL )
112
117#define OTA_PROTOCOL_BUFFER_SIZE 20U
118
124#define kOTA_MaxSignatureSize 384 /* Max bytes supported for a file signature (3072 bit RSA is 384 bytes). */
125
137#define OTA_JSON_SEPARATOR "."
138#define OTA_JSON_CLIENT_TOKEN_KEY "clientToken"
139#define OTA_JSON_TIMESTAMP_KEY "timestamp"
140#define OTA_JSON_EXECUTION_KEY "execution"
141#define OTA_JSON_JOB_ID_KEY OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "jobId"
142#define OTA_JSON_STATUS_DETAILS_KEY OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "statusDetails"
143#define OTA_JSON_SELF_TEST_KEY OTA_JSON_STATUS_DETAILS_KEY OTA_JSON_SEPARATOR "self_test"
144#define OTA_JSON_UPDATED_BY_KEY OTA_JSON_STATUS_DETAILS_KEY OTA_JSON_SEPARATOR "updatedBy"
145#define OTA_JSON_UPDATED_BY_KEY_ONLY "updatedBy"
146#define OTA_JSON_SELF_TEST_KEY_ONLY "self_test"
147#define OTA_JSON_JOB_DOC_KEY OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "jobDocument"
148#define OTA_JSON_OTA_UNIT_KEY OTA_JSON_JOB_DOC_KEY OTA_JSON_SEPARATOR "afr_ota"
149#define OTA_JSON_PROTOCOLS_KEY OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "protocols"
150#define OTA_JSON_FILE_GROUP_KEY OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "files"
151#define OTA_JSON_STREAM_NAME_KEY OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "streamname"
152#define OTA_JSON_FILE_PATH_KEY "filepath"
153#define OTA_JSON_FILE_SIZE_KEY "filesize"
154#define OTA_JSON_FILE_ID_KEY "fileid"
155#define OTA_JSON_FILE_ATTRIBUTE_KEY "attr"
156#define OTA_JSON_FILE_CERT_NAME_KEY "certfile"
157#define OTA_JSON_UPDATE_DATA_URL_KEY "update_data_url"
158#define OTA_JSON_AUTH_SCHEME_KEY "auth_scheme"
159#define OTA_JSON_FILETYPE_KEY "fileType"
169typedef enum
170{
185
191typedef enum
192{
211
217typedef enum
218{
219 ModelParamTypeStringCopy,
220 ModelParamTypeStringInDoc, /* Only use this type if you can process before freeing the document memory. */
221 ModelParamTypeObject,
222 ModelParamTypeArray,
223 ModelParamTypeUInt32,
224 ModelParamTypeSigBase64,
225 ModelParamTypeIdent,
226 ModelParamTypeArrayCopy
228
234typedef enum
235{
236 JobReasonReceiving = 0, /* Update progress status. */
237 JobReasonSigCheckPassed, /* Set status details to Self Test Ready. */
238 JobReasonSelfTestActive, /* Set status details to Self Test Active. */
239 JobReasonAccepted, /* Set job state to Succeeded. */
240 JobReasonRejected, /* Set job state to Failed. */
241 JobReasonAborted, /* Set job state to Failed. */
242 NumJobReasons
244
256typedef struct
257{
258 const char * pSrcKey;
259 const bool required;
260 uint16_t pDestOffset;
264
278typedef struct
279{
280 void * contextBase;
281 uint32_t contextSize;
283 uint16_t numModelParams;
287
292typedef struct OtaAgentStatistics
293{
299
315typedef enum OtaImageState
316{
323 OtaLastImageState = OtaImageStateAborted
325
332typedef enum OtaPalImageState
333{
339
346typedef enum OtaEvent
347{
363
370typedef struct
371{
372 uint16_t size;
373 uint8_t data[ kOTA_MaxSignatureSize ];
374} Sig_t;
375
383typedef struct OtaFileContext
384{
385 uint8_t * pFilePath;
388 uint32_t fileSize;
390 uint32_t fileAttributes;
391 uint32_t serverFileID;
392 uint8_t * pJobName;
393 uint16_t jobNameMaxSize;
394 uint8_t * pStreamName;
396 uint8_t * pRxBlockBitmap;
398 uint8_t * pCertFilepath;
400 uint8_t * pUpdateUrlPath;
402 uint8_t * pAuthScheme;
404 uint32_t updaterVersion;
406 uint8_t * pProtocols;
408 uint8_t * pDecodeMem;
410 uint32_t fileType;
413
419typedef struct OtaEventData
420{
421 uint8_t data[ OTA_DATA_BLOCK_SIZE ];
422 uint32_t dataLength;
425
431typedef struct OtaEventMsg
432{
436
437/* *INDENT-OFF* */
438#ifdef __cplusplus
439 }
440#endif
441/* *INDENT-ON* */
442
443#endif /* ifndef OTA_PRIVATE_H */
#define OTA_DATA_BLOCK_SIZE
Header is 19 bytes.
Definition: ota_private.h:85
#define kOTA_MaxSignatureSize
A composite cryptographic signature structure able to hold our largest supported signature.
Definition: ota_private.h:124
OtaEvent_t
OTA Agent Events.
Definition: ota_private.h:347
OtaPalImageState_t
OTA Platform Image State.
Definition: ota_private.h:333
OtaImageState_t
OTA Image states.
Definition: ota_private.h:316
@ OtaAgentEventRequestJobDocument
Event for requesting job document.
Definition: ota_private.h:350
@ OtaAgentEventReceivedJobDocument
Event when job document is received.
Definition: ota_private.h:351
@ OtaAgentEventMax
Last event specifier.
Definition: ota_private.h:361
@ OtaAgentEventReceivedFileBlock
Event to trigger when file block is received.
Definition: ota_private.h:354
@ OtaAgentEventUserAbort
Event triggered by user to stop agent.
Definition: ota_private.h:359
@ OtaAgentEventCreateFile
Event to create a file.
Definition: ota_private.h:352
@ OtaAgentEventStart
Start the OTA state machine.
Definition: ota_private.h:348
@ OtaAgentEventCloseFile
Event to trigger closing file.
Definition: ota_private.h:356
@ OtaAgentEventShutdown
Event to trigger ota shutdown.
Definition: ota_private.h:360
@ OtaAgentEventSuspend
Event to suspend ota task.
Definition: ota_private.h:357
@ OtaAgentEventRequestTimer
Event to request event timer.
Definition: ota_private.h:355
@ OtaAgentEventRequestFileBlock
Event to request file blocks.
Definition: ota_private.h:353
@ OtaAgentEventStartSelfTest
Event to trigger self test.
Definition: ota_private.h:349
@ OtaAgentEventResume
Event to resume suspended task.
Definition: ota_private.h:358
@ OtaPalImageStateInvalid
OTA PAL Image is invalid.
Definition: ota_private.h:337
@ OtaPalImageStateUnknown
The initial state of the OTA PAL Image.
Definition: ota_private.h:334
@ OtaPalImageStateValid
OTA PAL Image is valid.
Definition: ota_private.h:336
@ OtaPalImageStatePendingCommit
OTA PAL Image awaiting update.
Definition: ota_private.h:335
@ OtaImageStateRejected
The state of the OTA MCU Image when the job has been rejected.
Definition: ota_private.h:320
@ OtaImageStateTesting
The state of the OTA MCU Image post successful download and reboot.
Definition: ota_private.h:318
@ OtaImageStateAborted
The state of the OTA MCU Image after a timeout publish to the stream request fails....
Definition: ota_private.h:321
@ OtaImageStateAccepted
The state of the OTA MCU Image post successful download and successful self_test.
Definition: ota_private.h:319
@ OtaImageStateUnknown
The initial state of the OTA MCU Image.
Definition: ota_private.h:317
This represents the default values for the configuration macros for the OTA library.
#define otaconfigOTA_FILE_TYPE
Data type to represent a file.
Definition: ota_config_defaults.h:218
ModelParamType_t
Document model parameter types used by the JSON document parser.
Definition: ota_private.h:218
OtaJobReason_t
Gives the reason to set for job parsing operation.
Definition: ota_private.h:235
IngestResult_t
Data ingest results.
Definition: ota_private.h:170
@ IngestResultNoDecodeMemory
Definition: ota_private.h:180
@ IngestResultFileCloseFail
Definition: ota_private.h:173
@ IngestResultUnexpectedBlock
Definition: ota_private.h:176
@ IngestResultDuplicate_Continue
Definition: ota_private.h:183
@ IngestResultSigCheckFail
Definition: ota_private.h:172
@ IngestResultBadFileHandle
Definition: ota_private.h:175
@ IngestResultAccepted_Continue
Definition: ota_private.h:182
@ IngestResultWriteBlockFailed
Definition: ota_private.h:179
@ IngestResultBadData
Definition: ota_private.h:178
@ IngestResultUninitialized
Definition: ota_private.h:181
@ IngestResultNullInput
Definition: ota_private.h:174
@ IngestResultBlockOutOfRange
Definition: ota_private.h:177
@ IngestResultFileComplete
Definition: ota_private.h:171
DocParseErr_t
Generic JSON document parser errors.
Definition: ota_private.h:192
@ DocParseErrMalformedDoc
Definition: ota_private.h:201
@ DocParseErrParamKeyNotInModel
Definition: ota_private.h:207
@ DocParseErrNullBodyPointer
Definition: ota_private.h:204
@ DocParseErrInvalidModelParamType
Definition: ota_private.h:208
@ DocParseErrInvalidNumChar
Definition: ota_private.h:199
@ DocParseErrDuplicatesNotAllowed
Definition: ota_private.h:200
@ DocParseErrNullDocPointer
Definition: ota_private.h:205
@ DocParseErrOutOfMemory
Definition: ota_private.h:195
@ DocParseErrUserBufferInsuffcient
Definition: ota_private.h:196
@ DocParseErrNullModelPointer
Definition: ota_private.h:203
@ DocParseErrBase64Decode
Definition: ota_private.h:198
@ DocParseErrUnknown
Definition: ota_private.h:193
@ DocParseErrFieldTypeMismatch
Definition: ota_private.h:197
@ DocParseErrInvalidToken
Definition: ota_private.h:209
@ DocParseErr_InvalidJSONBuffer
Definition: ota_private.h:202
@ DocParseErrNone
Definition: ota_private.h:194
@ DocParseErrTooManyParams
Definition: ota_private.h:206
JSON document model to store the details of parameters expected in the job document.
Definition: ota_private.h:279
uint16_t numModelParams
Definition: ota_private.h:283
uint32_t paramsReceivedBitmap
Definition: ota_private.h:284
void * contextBase
Definition: ota_private.h:280
const JsonDocParam_t * pBodyDef
Definition: ota_private.h:282
uint32_t contextSize
Definition: ota_private.h:281
uint32_t paramsRequiredBitmap
Definition: ota_private.h:285
JSON document parameter to store the details of keys and where to store them.
Definition: ota_private.h:257
uint16_t pDestOffset
Definition: ota_private.h:260
const bool required
Definition: ota_private.h:259
uint16_t pDestSizeOffset
Definition: ota_private.h:261
const char * pSrcKey
Definition: ota_private.h:258
const ModelParamType_t modelParamType
Definition: ota_private.h:262
This is the OTA statistics structure to hold useful info.
Definition: ota_private.h:293
uint32_t otaPacketsReceived
Definition: ota_private.h:294
uint32_t otaPacketsQueued
Definition: ota_private.h:295
uint32_t otaPacketsProcessed
Definition: ota_private.h:296
uint32_t otaPacketsDropped
Definition: ota_private.h:297
The OTA Agent event and data structures.
Definition: ota_private.h:420
uint32_t dataLength
Definition: ota_private.h:422
bool bufferUsed
Definition: ota_private.h:423
Stores information about the event message.
Definition: ota_private.h:432
OtaEvent_t eventId
Definition: ota_private.h:434
OtaEventData_t * pEventData
Definition: ota_private.h:433
OTA File Context Information.
Definition: ota_private.h:384
uint16_t filePathMaxSize
Maximum size of the update file path.
Definition: ota_private.h:386
uint32_t decodeMemMaxSize
Maximum size of the decode memory.
Definition: ota_private.h:409
uint16_t jobNameMaxSize
Maximum size of the job name.
Definition: ota_private.h:393
uint8_t * pRxBlockBitmap
Bitmap of blocks received (for deduplicating and missing block request).
Definition: ota_private.h:396
uint32_t fileAttributes
Flags specific to the file being received (e.g. secure, bundle, archive).
Definition: ota_private.h:390
uint32_t blocksRemaining
How many blocks remain to be received (a code optimization).
Definition: ota_private.h:389
uint32_t fileSize
The size of the file in bytes.
Definition: ota_private.h:388
uint32_t fileType
The file type id set when creating the OTA job.
Definition: ota_private.h:410
uint16_t blockBitmapMaxSize
Maximum size of the block bitmap.
Definition: ota_private.h:397
bool isInSelfTest
True if the job is in self test mode.
Definition: ota_private.h:405
uint8_t * pStreamName
The stream associated with this file from the OTA service.
Definition: ota_private.h:394
uint8_t * pUpdateUrlPath
Url for the file.
Definition: ota_private.h:400
uint16_t authSchemeMaxSize
Maximum size of the auth scheme.
Definition: ota_private.h:403
uint8_t * pFilePath
Update file pathname.
Definition: ota_private.h:385
uint32_t updaterVersion
Used by OTA self-test detection, the version of Firmware that did the update.
Definition: ota_private.h:404
uint8_t * pCertFilepath
Pathname of the certificate file used to validate the receive file.
Definition: ota_private.h:398
uint16_t updateUrlMaxSize
Maximum size of the url.
Definition: ota_private.h:401
Sig_t * pSignature
Pointer to the file's signature structure.
Definition: ota_private.h:411
uint8_t * pAuthScheme
Authorization scheme.
Definition: ota_private.h:402
uint32_t serverFileID
The file is referenced by this numeric ID in the OTA job.
Definition: ota_private.h:391
uint16_t streamNameMaxSize
Maximum size of the stream name.
Definition: ota_private.h:395
uint8_t * pDecodeMem
Decode memory.
Definition: ota_private.h:408
uint16_t certFilePathMaxSize
Maximum certificate path size.
Definition: ota_private.h:399
uint16_t protocolMaxSize
Maximum size of the supported protocols string.
Definition: ota_private.h:407
otaconfigOTA_FILE_TYPE * pFile
File type after file is open for write.
Definition: ota_private.h:387
uint8_t * pProtocols
Authorization scheme.
Definition: ota_private.h:406
uint8_t * pJobName
The job name associated with this file from the job service.
Definition: ota_private.h:392
OTA File Signature info.
Definition: ota_private.h:371
uint16_t size
Size, in bytes, of the signature.
Definition: ota_private.h:372