AWS IoT Over-the-air Update  v2.0.0 (Release Candidate)
Client library for AWS IoT OTA
ota_private.h File Reference

Macros, enums, variables, and definitions internal to the OTA Agent module and shared by other OTA modules and testing files. More...

#include <stdio.h>
#include <stdint.h>
#include <stdbool.h>
#include "ota_config.h"
#include "ota_config_defaults.h"

Go to the source code of this file.

Data Structures

struct  JsonDocParam_t
 JSON document parameter to store the details of keys and where to store them. More...
 
struct  JsonDocModel_t
 JSON document model to store the details of parameters expected in the job document. More...
 
struct  OtaAgentStatistics_t
 This is the OTA statistics structure to hold useful info. More...
 
struct  Sig256_t
 OTA File Signature info. More...
 
struct  OtaFileContext_t
 OTA File Context Information. More...
 
struct  OtaEventData_t
 The OTA Agent event and data structures. More...
 
struct  OtaEventMsg_t
 Stores information about the event message. More...
 

Macros

#define LOG2_BITS_PER_BYTE   3U
 Log base 2 of bits per byte.
 
#define BITS_PER_BYTE   ( ( uint32_t ) 1U << LOG2_BITS_PER_BYTE )
 Number of bits in a byte. This is used by the block bitmap implementation.
 
#define OTA_FILE_BLOCK_SIZE   ( ( uint32_t ) 1U << otaconfigLOG2_FILE_BLOCK_SIZE )
 Data section size of the file data block message (excludes the header).
 
#define OTA_MAX_FILES   1U
 [MUST REMAIN 1! Future support.] Maximum number of concurrent OTA files.
 
#define OTA_MAX_BLOCK_BITMAP_SIZE   128U
 Max allowed number of bytes to track all blocks of an OTA file. Adjust block size if more range is needed.
 
#define OTA_REQUEST_MSG_MAX_SIZE   ( 3U * OTA_MAX_BLOCK_BITMAP_SIZE )
 Maximum size of the message.
 
#define OTA_REQUEST_URL_MAX_SIZE   ( 1500 )
 Maximum size of the S3 presigned URL.
 
#define OTA_ERASED_BLOCKS_VAL   0xffU
 The starting state of a group of erased blocks in the Rx block bitmap.
 
#define OTA_NUM_MSG_Q_ENTRIES   20U
 
#define OTA_MAX_JSON_TOKENS   64U
 Number of JSON tokens supported in a single parser call.
 
#define OTA_MAX_JSON_STR_LEN   256U
 Limit our JSON string compares to something small to avoid going into the weeds.
 
#define OTA_DOC_MODEL_MAX_PARAMS   32U
 The parameter list is backed by a 32 bit longword bitmap by design.
 
#define OTA_JOB_PARAM_REQUIRED   true
 Used to denote a required document model parameter.
 
#define OTA_JOB_PARAM_OPTIONAL   false
 Used to denote an optional document model parameter.
 
#define OTA_DONT_STORE_PARAM   0xffff
 If destOffset in the model is 0xffffffff, do not store the value.
 
#define OTA_STORE_NESTED_JSON   0x1fffU
 Store the reference to a nested JSON in a separate pointer.
 
#define OTA_DATA_BLOCK_SIZE   ( ( 1U << otaconfigLOG2_FILE_BLOCK_SIZE ) + OTA_REQUEST_URL_MAX_SIZE + 30 )
 Header is 19 bytes.
 
#define OTA_EVT_MASK_JOB_MSG_READY   0x00000001UL
 
#define OTA_EVT_MASK_DATA_MSG_READY   0x00000002UL
 
#define OTA_EVT_MASK_SHUTDOWN   0x00000004UL
 
#define OTA_EVT_MASK_REQ_TIMEOUT   0x00000008UL
 
#define OTA_EVT_MASK_USER_ABORT   0x000000016UL
 
#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 )
 
#define OTA_NUM_JOB_PARAMS   ( 21 )
 Number of parameters in the job document.
 
#define OTA_JOB_ID_MAX_SIZE   ( 72UL + 1UL )
 Maximum size of the Job ID.
 
#define kOTA_MaxSignatureSize   256 /* Max bytes supported for a file signature (2048 bit RSA is 256 bytes). */
 A composite cryptographic signature structure able to hold our largest supported signature.
 
#define OTA_JSON_SEPARATOR   "."
 Separator used to define nested keys.
 
#define OTA_JSON_CLIENT_TOKEN_KEY   "clientToken"
 Client token.
 
#define OTA_JSON_TIMESTAMP_KEY   "timestamp"
 Used to calculate timeout and time spent on the operation.
 
#define OTA_JSON_EXECUTION_KEY   "execution"
 Contains job execution parameters .
 
#define OTA_JSON_JOB_ID_KEY   OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "jobId"
 Name of the job.
 
#define OTA_JSON_STATUS_DETAILS_KEY   OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "statusDetails"
 Current status of the job.
 
#define OTA_JSON_SELF_TEST_KEY   OTA_JSON_STATUS_DETAILS_KEY OTA_JSON_SEPARATOR "self_test"
 Specifies if the platform and service is is selftest.
 
#define OTA_JSON_UPDATED_BY_KEY   OTA_JSON_STATUS_DETAILS_KEY OTA_JSON_SEPARATOR "updatedBy"
 Parameter to specify update status.
 
#define OTA_JSON_UPDATED_BY_KEY_ONLY   "updatedBy"
 Specifies if the platform and service is is selftest. Not searched in sub fields.
 
#define OTA_JSON_SELF_TEST_KEY_ONLY   "self_test"
 Parameter to specify update status. Not searched in sub fields.
 
#define OTA_JSON_JOB_DOC_KEY   OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "jobDocument"
 Parameters that specify the nature of the job.
 
#define OTA_JSON_OTA_UNIT_KEY   OTA_JSON_JOB_DOC_KEY OTA_JSON_SEPARATOR "afr_ota"
 afr-ota.
 
#define OTA_JSON_PROTOCOLS_KEY   OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "protocols"
 Protocols over which the download can take place.
 
#define OTA_JSON_FILE_GROUP_KEY   OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "files"
 Parameters for specifying file configurations.
 
#define OTA_JSON_STREAM_NAME_KEY   OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "streamname"
 Name of the stream used for download.
 
#define OTA_JSON_FILE_PATH_KEY   "filepath"
 Path to store the image on the device.
 
#define OTA_JSON_FILE_SIZE_KEY   "filesize"
 Size of the file to be downloaded.
 
#define OTA_JSON_FILE_ID_KEY   "fileid"
 Used to identify the file in case of multiple file downloads.
 
#define OTA_JSON_FILE_ATTRIBUTE_KEY   "attr"
 Additional file attributes.
 
#define OTA_JSON_FILE_CERT_NAME_KEY   "certfile"
 Location of the certificate on the device to find code signing.
 
#define OTA_JSON_UPDATE_DATA_URL_KEY   "update_data_url"
 S3 bucket presigned url to fetch the image from .
 
#define OTA_JSON_AUTH_SCHEME_KEY   "auth_scheme"
 Authentication scheme for downloading a the image over HTTP.
 
#define OTA_JSON_FILETYPE_KEY   "fileType"
 Used to identify the file in case of multi file type support.
 

Enumerations

enum  IngestResult_t {
  IngestResultFileComplete = -1, IngestResultSigCheckFail = -2, IngestResultFileCloseFail = -3, IngestResultNullContext = -4,
  IngestResultBadFileHandle = -5, IngestResultUnexpectedBlock = -6, IngestResultBlockOutOfRange = -7, IngestResultBadData = -8,
  IngestResultWriteBlockFailed = -9, IngestResultNullResultPointer = -10, IngestResultNoDecodeMemory = -11, IngestResultUninitialized = -127,
  IngestResultAccepted_Continue = 0, IngestResultDuplicate_Continue = 1
}
 Data ingest results. More...
 
enum  DocParseErr_t {
  DocParseErrUnknown = -1, DocParseErrNone = 0, DocParseErrOutOfMemory, DocParseErrUserBufferInsuffcient,
  DocParseErrFieldTypeMismatch, DocParseErrBase64Decode, DocParseErrInvalidNumChar, DocParseErrDuplicatesNotAllowed,
  DocParseErrMalformedDoc, DocParseErr_InvalidJSONBuffer, DocParseErrNullModelPointer, DocParseErrNullBodyPointer,
  DocParseErrNullDocPointer, DocParseErrTooManyParams, DocParseErrParamKeyNotInModel, DocParseErrInvalidModelParamType,
  DocParseErrInvalidToken
}
 Generic JSON document parser errors. More...
 
enum  ModelParamType_t {
  ModelParamTypeStringCopy, ModelParamTypeStringInDoc, ModelParamTypeObject, ModelParamTypeArray,
  ModelParamTypeUInt32, ModelParamTypeSigBase64, ModelParamTypeIdent, ModelParamTypeArrayCopy
}
 Document model parameter types used by the JSON document parser.
 
enum  OtaJobStatus_t {
  JobStatusInProgress = 0, JobStatusFailed, JobStatusSucceeded, JobStatusRejected,
  JobStatusFailedWithVal, NumJobStatusMappings
}
 Gives the status of the job parsing operation.
 
enum  OtaJobReason_t {
  JobReasonReceiving = 0, JobReasonSigCheckPassed, JobReasonSelfTestActive, JobReasonAccepted,
  JobReasonRejected, JobReasonAborted, NumJobReasons
}
 Gives the reason to set for job parsing operation.
 
enum  OtaImageState_t {
  OtaImageStateUnknown = 0, OtaImageStateTesting = 1, OtaImageStateAccepted = 2, OtaImageStateRejected = 3,
  OtaImageStateAborted = 4, OtaLastImageState = OtaImageStateAborted
}
 OTA Image states. More...
 
enum  OtaPalImageState_t { OtaPalImageStateUnknown = 0, OtaPalImageStatePendingCommit, OtaPalImageStateValid, OtaPalImageStateInvalid }
 OTA Platform Image State. More...
 
enum  OtaEvent_t {
  OtaAgentEventStart = 0, OtaAgentEventStartSelfTest, OtaAgentEventRequestJobDocument, OtaAgentEventReceivedJobDocument,
  OtaAgentEventCreateFile, OtaAgentEventRequestFileBlock, OtaAgentEventReceivedFileBlock, OtaAgentEventRequestTimer,
  OtaAgentEventCloseFile, OtaAgentEventSuspend, OtaAgentEventResume, OtaAgentEventUserAbort,
  OtaAgentEventShutdown, OtaAgentEventMax
}
 OTA Agent Events. More...
 

Detailed Description

Macros, enums, variables, and definitions internal to the OTA Agent module and shared by other OTA modules and testing files.

Enumeration Type Documentation

◆ IngestResult_t

Data ingest results.

The negative error codes represent actual error in ingesting the data block whereas the positive error codes represent success and other conditions that are not ingest errors like duplicate block is received.

Enumerator
IngestResultFileComplete 

The file transfer is complete and the signature check passed.

IngestResultSigCheckFail 

The file transfer is complete but the signature check failed.

IngestResultFileCloseFail 

There was a problem trying to close the receive file.

IngestResultNullContext 

The specified OTA context pointer is null.

IngestResultBadFileHandle 

The receive file pointer is invalid.

IngestResultUnexpectedBlock 

We were asked to ingest a block but were not expecting one.

IngestResultBlockOutOfRange 

The received block is out of the expected range.

IngestResultBadData 

The data block from the server was malformed.

IngestResultWriteBlockFailed 

The PAL layer failed to write the file block.

IngestResultNullResultPointer 

The pointer to the close result pointer was null.

IngestResultNoDecodeMemory 

Memory could not be allocated for decoding .

IngestResultUninitialized 

Software BUG: We forgot to set the result code.

IngestResultAccepted_Continue 

The block was accepted and we're expecting more.

IngestResultDuplicate_Continue 

The block was a duplicate but that's OK. Continue.

◆ DocParseErr_t

Generic JSON document parser errors.

Enumerator
DocParseErrUnknown 

The error code has not yet been set by a logic path.

DocParseErrNone 

No error in parsing the document.

DocParseErrOutOfMemory 

We failed to allocate enough dynamic memory for a field.

DocParseErrUserBufferInsuffcient 

The supplied user buffer is insufficient for a field.

DocParseErrFieldTypeMismatch 

The field type parsed does not match the document model.

DocParseErrBase64Decode 

There was an error decoding the base64 data.

DocParseErrInvalidNumChar 

There was an invalid character in a numeric value field.

DocParseErrDuplicatesNotAllowed 

A duplicate parameter was found in the job document.

DocParseErrMalformedDoc 

The document didn't fulfill the model requirements.

DocParseErr_InvalidJSONBuffer 

When the JSON is malformed and not parsed correctly.

DocParseErrNullModelPointer 

The pointer to the document model was NULL.

DocParseErrNullBodyPointer 

The document model's internal body pointer was NULL.

DocParseErrNullDocPointer 

The pointer to the JSON document was NULL.

DocParseErrTooManyParams 

The document model has more parameters than we can handle.

DocParseErrParamKeyNotInModel 

The document model does not include the specified parameter key.

DocParseErrInvalidModelParamType 

The document model specified an invalid parameter type.

DocParseErrInvalidToken 

The Jasmine token was invalid, producing a NULL pointer.