ota_private.h

Go to the documentation of this file.

/*
 * AWS IoT Over-the-air Update v2.0.0 (Release Candidate)
 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
#ifndef OTA_PRIVATE_H
#define OTA_PRIVATE_H
 
/* Standard includes. */
/* For FILE type in OtaFileContext_t.*/
#include <stdio.h>
#include <stdint.h>
#include <stdbool.h>
 
/* OTA_DO_NOT_USE_CUSTOM_CONFIG allows building the OTA library
 * without a custom config. If a custom config is provided, the
 * OTA_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */
#ifndef OTA_DO_NOT_USE_CUSTOM_CONFIG
    #include "ota_config.h"
#endif
 
/* Include config defaults header to get default values of configs not defined
 * in ota_config.h file. */
#include "ota_config_defaults.h"
 
/* General constants. */
#define LOG2_BITS_PER_BYTE           3U                                                   
#define BITS_PER_BYTE                ( ( uint32_t ) 1U << LOG2_BITS_PER_BYTE )            
#define OTA_FILE_BLOCK_SIZE          ( ( uint32_t ) 1U << otaconfigLOG2_FILE_BLOCK_SIZE ) 
#define OTA_MAX_FILES                1U                                                   
#define OTA_MAX_BLOCK_BITMAP_SIZE    128U                                                 
#define OTA_REQUEST_MSG_MAX_SIZE     ( 3U * OTA_MAX_BLOCK_BITMAP_SIZE )                   
#define OTA_REQUEST_URL_MAX_SIZE     ( 1500 )                                             
#define OTA_ERASED_BLOCKS_VAL        0xffU                                                
#ifdef configOTA_NUM_MSG_Q_ENTRIES
    #define OTA_NUM_MSG_Q_ENTRIES    configOTA_NUM_MSG_Q_ENTRIES
#else
    #define OTA_NUM_MSG_Q_ENTRIES    20U                   
#endif
/* Job document parser constants. */
#define OTA_MAX_JSON_TOKENS         64U                                                                         
#define OTA_MAX_JSON_STR_LEN        256U                                                                        
#define OTA_DOC_MODEL_MAX_PARAMS    32U                                                                         
#define OTA_JOB_PARAM_REQUIRED      true                                                                        
#define OTA_JOB_PARAM_OPTIONAL      false                                                                       
#define OTA_DONT_STORE_PARAM        0xffff                                                                      
#define OTA_STORE_NESTED_JSON       0x1fffU                                                                     
#define OTA_DATA_BLOCK_SIZE         ( ( 1U << otaconfigLOG2_FILE_BLOCK_SIZE ) + OTA_REQUEST_URL_MAX_SIZE + 30 ) 
/* OTA Agent task event flags. */
#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 )
 
#define OTA_JOB_ID_MAX_SIZE    ( 72UL + 1UL )
 
#define kOTA_MaxSignatureSize           256 /* Max bytes supported for a file signature (2048 bit RSA is 256 bytes). */
 
#define OTA_JSON_SEPARATOR              "."                                                        
#define OTA_JSON_CLIENT_TOKEN_KEY       "clientToken"                                              
#define OTA_JSON_TIMESTAMP_KEY          "timestamp"                                                
#define OTA_JSON_EXECUTION_KEY          "execution"                                                
#define OTA_JSON_JOB_ID_KEY             OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "jobId"          
#define OTA_JSON_STATUS_DETAILS_KEY     OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "statusDetails"  
#define OTA_JSON_SELF_TEST_KEY          OTA_JSON_STATUS_DETAILS_KEY OTA_JSON_SEPARATOR "self_test" 
#define OTA_JSON_UPDATED_BY_KEY         OTA_JSON_STATUS_DETAILS_KEY OTA_JSON_SEPARATOR "updatedBy" 
#define OTA_JSON_UPDATED_BY_KEY_ONLY    "updatedBy"                                                
#define OTA_JSON_SELF_TEST_KEY_ONLY     "self_test"                                                
#define OTA_JSON_JOB_DOC_KEY            OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "jobDocument"    
#define OTA_JSON_OTA_UNIT_KEY           OTA_JSON_JOB_DOC_KEY OTA_JSON_SEPARATOR "afr_ota"          
#define OTA_JSON_PROTOCOLS_KEY          OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "protocols"       
#define OTA_JSON_FILE_GROUP_KEY         OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "files"           
#define OTA_JSON_STREAM_NAME_KEY        OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "streamname"      
#define OTA_JSON_FILE_PATH_KEY          "filepath"                                                 
#define OTA_JSON_FILE_SIZE_KEY          "filesize"                                                 
#define OTA_JSON_FILE_ID_KEY            "fileid"                                                   
#define OTA_JSON_FILE_ATTRIBUTE_KEY     "attr"                                                     
#define OTA_JSON_FILE_CERT_NAME_KEY     "certfile"                                                 
#define OTA_JSON_UPDATE_DATA_URL_KEY    "update_data_url"                                          
#define OTA_JSON_AUTH_SCHEME_KEY        "auth_scheme"                                              
#define OTA_JSON_FILETYPE_KEY           "fileType"                                                 
typedef enum
{
    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   
} IngestResult_t;
 
typedef enum
{
    DocParseErrUnknown = -1,          
    DocParseErrNone = 0,              
    DocParseErrOutOfMemory,           
    DocParseErrUserBufferInsuffcient, 
    DocParseErrFieldTypeMismatch,     
    DocParseErrBase64Decode,          
    DocParseErrInvalidNumChar,        
    DocParseErrDuplicatesNotAllowed,  
    DocParseErrMalformedDoc,          
    DocParseErr_InvalidJSONBuffer,    
    DocParseErrNullModelPointer,      
    DocParseErrNullBodyPointer,       
    DocParseErrNullDocPointer,        
    DocParseErrTooManyParams,         
    DocParseErrParamKeyNotInModel,    
    DocParseErrInvalidModelParamType, 
    DocParseErrInvalidToken           
} DocParseErr_t;
 
typedef enum
{
    ModelParamTypeStringCopy,
    ModelParamTypeStringInDoc, /* Only use this type if you can process before freeing the document memory. */
    ModelParamTypeObject,
    ModelParamTypeArray,
    ModelParamTypeUInt32,
    ModelParamTypeSigBase64,
    ModelParamTypeIdent,
    ModelParamTypeArrayCopy
} ModelParamType_t;
 
typedef enum
{
    JobStatusInProgress = 0,
    JobStatusFailed,
    JobStatusSucceeded,
    JobStatusRejected,      /* Not possible today using the "get next job" feature. FUTURE! */
    JobStatusFailedWithVal, /* This shows 2 numeric reason codes. */
    NumJobStatusMappings
} OtaJobStatus_t;
 
typedef enum
{
    JobReasonReceiving = 0,  /* Update progress status. */
    JobReasonSigCheckPassed, /* Set status details to Self Test Ready. */
    JobReasonSelfTestActive, /* Set status details to Self Test Active. */
    JobReasonAccepted,       /* Set job state to Succeeded. */
    JobReasonRejected,       /* Set job state to Failed. */
    JobReasonAborted,        /* Set job state to Failed. */
    NumJobReasons
} OtaJobReason_t;
 
typedef struct
{
    const char * pSrcKey;                  
    const bool required;                   
    uint16_t pDestOffset;                  
    uint16_t pDestSizeOffset;              
    const ModelParamType_t modelParamType; 
} JsonDocParam_t;
 
typedef struct
{
    void * contextBase;              
    uint32_t contextSize;            
    const JsonDocParam_t * pBodyDef; 
    uint16_t numModelParams;         
    uint32_t paramsReceivedBitmap;   
    uint32_t paramsRequiredBitmap;   
} JsonDocModel_t;
 
typedef struct OtaAgentStatistics
{
    uint32_t otaPacketsReceived;  
    uint32_t otaPacketsQueued;    
    uint32_t otaPacketsProcessed; 
    uint32_t otaPacketsDropped;   
} OtaAgentStatistics_t;
 
typedef enum OtaImageState
{
    OtaImageStateUnknown = 0,  
    OtaImageStateTesting = 1,  
    OtaImageStateAccepted = 2, 
    OtaImageStateRejected = 3, 
    OtaImageStateAborted = 4,  
    OtaLastImageState = OtaImageStateAborted
} OtaImageState_t;
 
typedef enum OtaPalImageState
{
    OtaPalImageStateUnknown = 0,   
    OtaPalImageStatePendingCommit, 
    OtaPalImageStateValid,         
    OtaPalImageStateInvalid        
} OtaPalImageState_t;
 
typedef enum OtaEvent
{
    OtaAgentEventStart = 0,           
    OtaAgentEventStartSelfTest,       
    OtaAgentEventRequestJobDocument,  
    OtaAgentEventReceivedJobDocument, 
    OtaAgentEventCreateFile,          
    OtaAgentEventRequestFileBlock,    
    OtaAgentEventReceivedFileBlock,   
    OtaAgentEventRequestTimer,        
    OtaAgentEventCloseFile,           
    OtaAgentEventSuspend,             
    OtaAgentEventResume,              
    OtaAgentEventUserAbort,           
    OtaAgentEventShutdown,            
    OtaAgentEventMax                  
} OtaEvent_t;
 
typedef struct
{
    uint16_t size;                         
    uint8_t data[ kOTA_MaxSignatureSize ]; 
} Sig256_t;
 
typedef struct OtaFileContext
{
    uint8_t * pFilePath;          
    uint16_t filePathMaxSize;     
    #if defined( WIN32 ) || defined( __linux__ )
        FILE * pFile;             
    #else
        uint8_t * pFile;          
    #endif
    uint32_t fileSize;            
    uint32_t blocksRemaining;     
    uint32_t fileAttributes;      
    uint32_t serverFileID;        
    uint8_t * pJobName;           
    uint16_t jobNameMaxSize;      
    uint8_t * pStreamName;        
    uint16_t streamNameMaxSize;   
    uint8_t * pRxBlockBitmap;     
    uint16_t blockBitmapMaxSize;  
    uint8_t * pCertFilepath;      
    uint16_t certFilePathMaxSize; 
    uint8_t * pUpdateUrlPath;     
    uint16_t updateUrlMaxSize;    
    uint8_t * pAuthScheme;        
    uint16_t authSchemeMaxSize;   
    uint32_t updaterVersion;      
    bool isInSelfTest;            
    uint8_t * pProtocols;         
    uint16_t protocolMaxSize;     
    uint8_t * pDecodeMem;         
    uint32_t decodeMemMaxSize;    
    uint32_t fileType;            
    Sig256_t * pSignature;        
} OtaFileContext_t;
 
typedef struct OtaEventData
{
    uint8_t data[ OTA_DATA_BLOCK_SIZE ]; 
    uint32_t dataLength;                 
    bool bufferUsed;                     
} OtaEventData_t;
 
typedef struct OtaEventMsg
{
    OtaEventData_t * pEventData; 
    OtaEvent_t eventId;          
} OtaEventMsg_t;
 
#endif /* ifndef OTA_PRIVATE_H */