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