ota.h

Go to the documentation of this file.

/*
 * AWS IoT Over-the-air Update v3.0.0
 * 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_H
#define OTA_H
 
/* Standard includes. */
/* For FILE type in OtaFileContext_t.*/
#include <stdio.h>
#include <stdint.h>
 
/* OTA Library Interface include. */
#include "ota_private.h"
#include "ota_os_interface.h"
#include "ota_mqtt_interface.h"
#include "ota_http_interface.h"
#include "ota_platform_interface.h"
 
#define CONST_STRLEN( s )    ( ( ( uint32_t ) sizeof( s ) ) - 1UL )
 
 
#define OTA_FILE_SIG_KEY_STR_MAX_LENGTH    32 
/* MISRA rule 8.6 requires identifier with external linkage to have exact one external definition.
 * However, this variable is defined in OTA platform abstraction layer implementation, which is
 * not in this repository but in C-SDK and amazon-freertos repo, so it's a false positive. */
/* coverity[misra_c_2012_rule_8_6_violation] */
extern const char OTA_JsonFileSignatureKey[ OTA_FILE_SIG_KEY_STR_MAX_LENGTH ];
 
/*-------------------------- OTA enumerated types --------------------------*/
 
typedef enum OtaErr
{
    OtaErrNone = 0,               
    OtaErrUninitialized,          
    OtaErrPanic,                  
    OtaErrInvalidArg,             
    OtaErrAgentStopped,           
    OtaErrSignalEventFailed,      
    OtaErrRequestJobFailed,       
    OtaErrInitFileTransferFailed, 
    OtaErrRequestFileBlockFailed, 
    OtaErrCleanupControlFailed,   
    OtaErrCleanupDataFailed,      
    OtaErrUpdateJobStatusFailed,  
    OtaErrJobParserError,         
    OtaErrInvalidDataProtocol,    
    OtaErrMomentumAbort,          
    OtaErrDowngradeNotAllowed,    
    OtaErrSameFirmwareVersion,    
    OtaErrImageStateMismatch,     
    OtaErrNoActiveJob,            
    OtaErrUserAbort,              
    OtaErrFailedToEncodeCbor,     
    OtaErrFailedToDecodeCbor,     
    OtaErrActivateFailed          
} OtaErr_t;
 
typedef enum OtaState
{
    OtaAgentStateNoTransition = -1,
    OtaAgentStateInit = 0,
    OtaAgentStateReady,
    OtaAgentStateRequestingJob,
    OtaAgentStateWaitingForJob,
    OtaAgentStateCreatingFile,
    OtaAgentStateRequestingFileBlock,
    OtaAgentStateWaitingForFileBlock,
    OtaAgentStateClosingFile,
    OtaAgentStateSuspended,
    OtaAgentStateShuttingDown,
    OtaAgentStateStopped,
    OtaAgentStateAll
} OtaState_t;
 
typedef enum OtaJobParseErr
{
    OtaJobParseErrUnknown = -1,        /* @brief The error code has not yet been set by a logic path. */
    OtaJobParseErrNone = 0,            /* @brief Signifies no error has occurred. */
    OtaJobParseErrNullJob,             /* @brief A null job was reported (no job ID). */
    OtaJobParseErrUpdateCurrentJob,    /* @brief We're already busy with the reported job ID. */
    OtaJobParseErrZeroFileSize,        /* @brief Job document specified a zero sized file. This is not allowed. */
    OtaJobParseErrNonConformingJobDoc, /* @brief The job document failed to fulfill the model requirements. */
    OtaJobParseErrBadModelInitParams,  /* @brief There was an invalid initialization parameter used in the document model. */
    OtaJobParseErrNoContextAvailable,  /* @brief There was not an OTA context available. */
    OtaJobParseErrNoActiveJobs         /* @brief No active jobs are available in the service. */
} OtaJobParseErr_t;
 
typedef enum OtaJobEvent
{
    OtaJobEventActivate = 0,       
    OtaJobEventFail = 1,           
    OtaJobEventStartTest = 2,      
    OtaJobEventProcessed = 3,      
    OtaJobEventSelfTestFailed = 4, 
    OtaJobEventParseCustomJob = 5, 
    OtaJobEventReceivedJob = 6,    
    OtaJobEventUpdateComplete = 7, 
    OtaLastJobEvent = OtaJobEventStartTest
} OtaJobEvent_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 struct OtaJobDocument
{
    const uint8_t * pJobDocJson; 
    size_t jobDocLength;         
    const uint8_t * pJobId;      
    size_t jobIdLength;          
    uint32_t fileTypeId;         
    OtaJobParseErr_t parseErr;   
    OtaJobStatus_t status;       
    int32_t reason;              
    int32_t subReason;           
} OtaJobDocument_t;
 
/*------------------------- OTA callbacks --------------------------*/
 
typedef void (* OtaAppCallback_t)( OtaJobEvent_t eEvent,
                                   const void * pData );
 
/*--------------------------- OTA structs ----------------------------*/
 
 
typedef struct OtaInterface
{
    OtaOSInterface_t os;     
    OtaMqttInterface_t mqtt; 
    OtaHttpInterface_t http; 
    OtaPalInterface_t pal;   
} OtaInterfaces_t;
 
typedef struct OtaAppBuffer
{
    uint8_t * pUpdateFilePath;   
    uint16_t updateFilePathsize; 
    uint8_t * pCertFilePath;     
    uint16_t certFilePathSize;   
    uint8_t * pStreamName;       
    uint16_t streamNameSize;     
    uint8_t * pDecodeMemory;     
    uint32_t decodeMemorySize;   
    uint8_t * pFileBitmap;       
    uint16_t fileBitmapSize;     
    uint8_t * pUrl;              
    uint16_t urlSize;            
    uint8_t * pAuthScheme;       
    uint16_t authSchemeSize;     
} OtaAppBuffer_t;
 
typedef struct OtaAgentContext
{
    OtaState_t state;                                      
    uint8_t pThingName[ otaconfigMAX_THINGNAME_LEN + 1U ]; 
    OtaFileContext_t fileContext;                          
    uint32_t fileIndex;                                    
    uint32_t serverFileID;                                 
    uint8_t pActiveJobName[ OTA_JOB_ID_MAX_SIZE ];         
    uint8_t * pClientTokenFromJob;                         
    uint32_t timestampFromJob;                             
    OtaImageState_t imageState;                            
    uint32_t numOfBlocksToReceive;                         
    OtaAgentStatistics_t statistics;                       
    uint32_t requestMomentum;                              
    OtaInterfaces_t * pOtaInterface;                       
    OtaAppCallback_t OtaAppCallback;                       
    uint8_t unsubscribeOnShutdown;                         
} OtaAgentContext_t;
 
/*------------------------- OTA Public API --------------------------*/
 
/* @[declare_ota_init] */
OtaErr_t OTA_Init( OtaAppBuffer_t * pOtaBuffer,
                   OtaInterfaces_t * pOtaInterfaces,
                   const uint8_t * pThingName,
                   OtaAppCallback_t OtaAppCallback );
/* @[declare_ota_init] */
 
/* @[declare_ota_shutdown] */
OtaState_t OTA_Shutdown( uint32_t ticksToWait,
                         uint8_t unsubscribeFlag );
/* @[declare_ota_shutdown] */
 
/* @[declare_ota_getstate] */
OtaState_t OTA_GetState( void );
/* @[declare_ota_getstate] */
 
/* @[declare_ota_activatenewimage] */
OtaErr_t OTA_ActivateNewImage( void );
/* @[declare_ota_activatenewimage] */
 
/* @[declare_ota_setimagestate] */
OtaErr_t OTA_SetImageState( OtaImageState_t state );
/* @[declare_ota_setimagestate] */
 
/* @[declare_ota_getimagestate] */
OtaImageState_t OTA_GetImageState( void );
/* @[declare_ota_getimagestate] */
 
/* @[declare_ota_checkforupdate] */
OtaErr_t OTA_CheckForUpdate( void );
/* @[declare_ota_checkforupdate] */
 
/* @[declare_ota_suspend] */
OtaErr_t OTA_Suspend( void );
/* @[declare_ota_suspend] */
 
/* @[declare_ota_resume] */
OtaErr_t OTA_Resume( void );
/* @[declare_ota_resume] */
 
/* @[declare_ota_eventprocessingtask] */
void OTA_EventProcessingTask( void * pUnused );
/* @[declare_ota_eventprocessingtask] */
 
 
/* @[declare_ota_signalevent] */
bool OTA_SignalEvent( const OtaEventMsg_t * const pEventMsg );
/* @[declare_ota_signalevent] */
 
/*---------------------------------------------------------------------------*/
/*                          Statistics API                                   */
/*---------------------------------------------------------------------------*/
 
/* @[declare_ota_getstatistics] */
OtaErr_t OTA_GetStatistics( OtaAgentStatistics_t * pStatistics );
/* @[declare_ota_getstatistics] */
 
/* @[declare_ota_err_strerror] */
const char * OTA_Err_strerror( OtaErr_t err );
/* @[declare_ota_err_strerror] */
 
/* @[declare_ota_jobparse_strerror] */
const char * OTA_JobParse_strerror( OtaJobParseErr_t err );
/* @[declare_ota_jobparse_strerror] */
 
/* @[declare_ota_palstatus_strerror] */
const char * OTA_PalStatus_strerror( OtaPalMainStatus_t status );
/* @[declare_ota_palstatus_strerror] */
 
/* @[declare_ota_osstatus_strerror] */
const char * OTA_OsStatus_strerror( OtaOsStatus_t status );
/* @[declare_ota_osstatus_strerror] */
 
#endif /* ifndef OTA_H */