aws_iot_ota_agent.h

Go to the documentation of this file.

/*
 * FreeRTOS OTA V1.2.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.
 *
 * http://aws.amazon.com/freertos
 * http://www.FreeRTOS.org
 */
 
#ifndef _AWS_IOT_OTA_AGENT_H_
#define _AWS_IOT_OTA_AGENT_H_
 
/* Standard includes. */
/* For FILE type in OTA_FileContext_t.*/
#include <stdio.h>
#include <stdbool.h>
 
/* Includes required by the FreeRTOS timers structure. */
#include "FreeRTOS.h"
#include "timers.h"
 
/* Evaluates to the length of a constant string defined like 'static const char str[]= "xyz"; */
#define CONST_STRLEN( s )    ( ( ( uint32_t ) sizeof( s ) ) - 1UL )
 
/* The OTA signature algorithm string is specified by the PAL. */
#define OTA_FILE_SIG_KEY_STR_MAX_LENGTH    32
extern const char cOTA_JSON_FileSignatureKey[ OTA_FILE_SIG_KEY_STR_MAX_LENGTH ];
 
#define OTA_DEBUG_LOG_LEVEL    1
#if OTA_DEBUG_LOG_LEVEL >= 1
    #define DEFINE_OTA_METHOD_NAME( name )      \
    static const char OTA_METHOD_NAME[] = name; \
    ( void ) OTA_METHOD_NAME;
    #define OTA_LOG_L1         vLoggingPrintf
#else
    #define DEFINE_OTA_METHOD_NAME( name )
    #define OTA_LOG_L1( ... )
#endif
#if OTA_DEBUG_LOG_LEVEL >= 2
    #define DEFINE_OTA_METHOD_NAME_L2( name )   \
    static const char OTA_METHOD_NAME[] = name; \
    ( void ) OTA_METHOD_NAME;
    #define OTA_LOG_L2    vLoggingPrintf
#else
    #define DEFINE_OTA_METHOD_NAME_L2( name )
    #define OTA_LOG_L2( ... )
#endif
#if OTA_DEBUG_LOG_LEVEL >= 3
    #define DEFINE_OTA_METHOD_NAME_L3( name )   \
    static const char OTA_METHOD_NAME[] = name; \
    ( void ) OTA_METHOD_NAME;
    #define OTA_LOG_L3    vLoggingPrintf
#else
    #define DEFINE_OTA_METHOD_NAME_L3( name )
    #define OTA_LOG_L3( ... )
#endif
 
/*-------------------------- OTA enumerated types --------------------------*/
 
typedef enum
{
    eOTA_AgentState_NoTransition = -1,
    eOTA_AgentState_Init = 0,
    eOTA_AgentState_Ready,
    eOTA_AgentState_RequestingJob,
    eOTA_AgentState_WaitingForJob,
    eOTA_AgentState_CreatingFile,
    eOTA_AgentState_RequestingFileBlock,
    eOTA_AgentState_WaitingForFileBlock,
    eOTA_AgentState_ClosingFile,
    eOTA_AgentState_Suspended,
    eOTA_AgentState_ShuttingDown,
    eOTA_AgentState_Stopped,
    eOTA_AgentState_All
} OTA_State_t;
 
typedef enum
{
    eOTA_AgentEvent_Start = 0,
    eOTA_AgentEvent_StartSelfTest,
    eOTA_AgentEvent_RequestJobDocument,
    eOTA_AgentEvent_ReceivedJobDocument,
    eOTA_AgentEvent_CreateFile,
    eOTA_AgentEvent_RequestFileBlock,
    eOTA_AgentEvent_ReceivedFileBlock,
    eOTA_AgentEvent_RequestTimer,
    eOTA_AgentEvent_CloseFile,
    eOTA_AgentEvent_Suspend,
    eOTA_AgentEvent_Resume,
    eOTA_AgentEvent_UserAbort,
    eOTA_AgentEvent_Shutdown,
    eOTA_AgentEvent_Max
} OTA_Event_t;
 
typedef enum
{
    eOTA_PAL_ImageState_Unknown = 0,
    eOTA_PAL_ImageState_PendingCommit,
    eOTA_PAL_ImageState_Valid,
    eOTA_PAL_ImageState_Invalid,
} OTA_PAL_ImageState_t;
 
typedef enum
{
    eOTA_JobParseErr_Unknown = -1,        /* The error code has not yet been set by a logic path. */
    eOTA_JobParseErr_None = 0,            /* Signifies no error has occurred. */
    eOTA_JobParseErr_BusyWithExistingJob, /* We're busy with a job but received a new job document. */
    eOTA_JobParseErr_NullJob,             /* A null job was reported (no job ID). */
    eOTA_JobParseErr_UpdateCurrentJob,    /* We're already busy with the reported job ID. */
    eOTA_JobParseErr_ZeroFileSize,        /* Job document specified a zero sized file. This is not allowed. */
    eOTA_JobParseErr_NonConformingJobDoc, /* The job document failed to fulfill the model requirements. */
    eOTA_JobParseErr_BadModelInitParams,  /* There was an invalid initialization parameter used in the document model. */
    eOTA_JobParseErr_NoContextAvailable,  /* There wasn't an OTA context available. */
    eOTA_JobParseErr_NoActiveJobs,        /* No active jobs are available in the service. */
} OTA_JobParseErr_t;
 
 
typedef enum
{
    eOTA_JobEvent_Activate = 0,  
    eOTA_JobEvent_Fail = 1,      
    eOTA_JobEvent_StartTest = 2, 
    eOTA_LastJobEvent = eOTA_JobEvent_StartTest
} OTA_JobEvent_t;
 
 
typedef enum
{
    eOTA_ImageState_Unknown = 0,  
    eOTA_ImageState_Testing = 1,  
    eOTA_ImageState_Accepted = 2, 
    eOTA_ImageState_Rejected = 3, 
    eOTA_ImageState_Aborted = 4,  
    eOTA_LastImageState = eOTA_ImageState_Aborted
} OTA_ImageState_t;
 
 
/*------------------------- OTA callbacks --------------------------*/
 
/* Forward delcaration of OTA_FileContext_t. */
typedef struct OTA_FileContext   OTA_FileContext_t;
 
typedef uint32_t                 OTA_Err_t;
 
typedef void (* pxOTACompleteCallback_t)( OTA_JobEvent_t eEvent );
 
typedef OTA_Err_t (* pxOTAPALAbortCallback_t)( OTA_FileContext_t * const C );
 
typedef OTA_Err_t (* pxOTAPALActivateNewImageCallback_t)( uint32_t ulServerFileID );
 
typedef OTA_Err_t (* pxOTAPALCloseFileCallback_t)( OTA_FileContext_t * const C );
 
typedef OTA_Err_t (* pxOTAPALCreateFileForRxCallback_t)( OTA_FileContext_t * const C );
 
typedef OTA_PAL_ImageState_t (* pxOTAPALGetPlatformImageStateCallback_t)( uint32_t ulServerFileID );
 
typedef OTA_Err_t (* pxOTAPALResetDeviceCallback_t)( uint32_t ulServerFileID );
 
typedef OTA_Err_t (* pxOTAPALSetPlatformImageStateCallback_t)( uint32_t ulServerFileID,
                                                               OTA_ImageState_t eState );
 
typedef int16_t (* pxOTAPALWriteBlockCallback_t)( OTA_FileContext_t * const C,
                                                  uint32_t iOffset,
                                                  uint8_t * const pacData,
                                                  uint32_t iBlockSize );
 
typedef OTA_JobParseErr_t (* pxOTACustomJobCallback_t)( const char * pcJSON,
                                                        uint32_t ulMsgLen );
 
 
/*--------------------------- OTA structs ----------------------------*/
 
/* A composite cryptographic signature structure able to hold our largest supported signature. */
 
#define kOTA_MaxSignatureSize    256        /* Max bytes supported for a file signature (2048 bit RSA is 256 bytes). */
 
typedef struct
{
    uint16_t usSize;                         /* Size, in bytes, of the signature. */
    uint8_t ucData[ kOTA_MaxSignatureSize ]; /* The binary signature data. */
} Sig256_t;
 
typedef struct OTA_FileContext
{
    uint8_t * pucFilePath; 
    union
    {
        int32_t lFileHandle;    
        #if WIN32
            FILE * pxFile;      
        #endif
        uint8_t * pucFile;      
    };
    uint32_t ulFileSize;        
    uint32_t ulBlocksRemaining; 
    uint32_t ulFileAttributes;  
    uint32_t ulServerFileID;    
    uint8_t * pucJobName;       
    uint8_t * pucStreamName;    
    Sig256_t * pxSignature;     
    uint8_t * pucRxBlockBitmap; 
    uint8_t * pucCertFilepath;  
    uint8_t * pucUpdateUrlPath; 
    uint8_t * pucAuthScheme;    
    uint32_t ulUpdaterVersion;  
    bool bIsInSelfTest;         
    uint8_t * pucProtocols;     
} OTA_FileContext_t;
 
typedef struct
{
    void * pvControlClient;
    const void * pxNetworkInterface;
    void * pvNetworkCredentials;
} OTA_ConnectionContext_t;
 
typedef struct
{
    pxOTAPALAbortCallback_t xAbort;                                 /* OTA Abort callback pointer */
    pxOTAPALActivateNewImageCallback_t xActivateNewImage;           /* OTA Activate New Image callback pointer */
    pxOTAPALCloseFileCallback_t xCloseFile;                         /* OTA Close File callback pointer */
    pxOTAPALCreateFileForRxCallback_t xCreateFileForRx;             /* OTA Create File for Receive callback pointer */
    pxOTAPALGetPlatformImageStateCallback_t xGetPlatformImageState; /* OTA Get Platform Image State callback pointer */
    pxOTAPALResetDeviceCallback_t xResetDevice;                     /* OTA Reset Device callback pointer */
    pxOTAPALSetPlatformImageStateCallback_t xSetPlatformImageState; /* OTA Set Platform Image State callback pointer */
    pxOTAPALWriteBlockCallback_t xWriteBlock;                       /* OTA Write Block callback pointer */
    pxOTACompleteCallback_t xCompleteCallback;                      /* OTA Job Completed callback pointer */
    pxOTACustomJobCallback_t xCustomJobCallback;                    /* OTA Custom Job callback pointer */
} OTA_PAL_Callbacks_t;
 
 
/*------------------------- OTA defined constants --------------------------*/
 
/* @[define_ota_err_codes] */
#define kOTA_Err_Panic                   0xfe000000UL     
#define kOTA_Err_Uninitialized           0xff000000UL     
#define kOTA_Err_None                    0x00000000UL
#define kOTA_Err_SignatureCheckFailed    0x01000000UL     
#define kOTA_Err_BadSignerCert           0x02000000UL     
#define kOTA_Err_OutOfMemory             0x03000000UL     
#define kOTA_Err_ActivateFailed          0x04000000UL     
#define kOTA_Err_CommitFailed            0x05000000UL     
#define kOTA_Err_RejectFailed            0x06000000UL     
#define kOTA_Err_AbortFailed             0x07000000UL     
#define kOTA_Err_PublishFailed           0x08000000UL     
#define kOTA_Err_BadImageState           0x09000000UL     
#define kOTA_Err_NoActiveJob             0x0a000000UL     
#define kOTA_Err_NoFreeContext           0x0b000000UL     
#define kOTA_Err_HTTPInitFailed          0x0c000000UL     
#define kOTA_Err_HTTPRequestFailed       0x0d000000UL     
#define kOTA_Err_FileAbort               0x10000000UL     
#define kOTA_Err_FileClose               0x11000000UL     
#define kOTA_Err_RxFileCreateFailed      0x12000000UL     
#define kOTA_Err_BootInfoCreateFailed    0x13000000UL     
#define kOTA_Err_RxFileTooLarge          0x14000000UL     
#define kOTA_Err_NullFilePtr             0x20000000UL     
#define kOTA_Err_MomentumAbort           0x21000000UL     
#define kOTA_Err_DowngradeNotAllowed     0x22000000UL     
#define kOTA_Err_SameFirmwareVersion     0x23000000UL     
#define kOTA_Err_JobParserError          0x24000000UL     
#define kOTA_Err_FailedToEncodeCBOR      0x25000000UL     
#define kOTA_Err_ImageStateMismatch      0x26000000UL     
#define kOTA_Err_GenericIngestError      0x27000000UL     
#define kOTA_Err_UserAbort               0x28000000UL     
#define kOTA_Err_ResetNotSupported       0x29000000UL     
#define kOTA_Err_TopicTooLarge           0x2a000000UL     
#define kOTA_Err_SelfTestTimerFailed     0x2b000000UL     
#define kOTA_Err_EventQueueSendFailed    0x2c000000UL     
#define kOTA_Err_InvalidDataProtocol     0x2d000000UL     
#define kOTA_Err_OTAAgentStopped         0x2e000000UL     
/* @[define_ota_err_codes] */
 
/* @[define_ota_err_code_helpers] */
#define kOTA_PAL_ErrMask             0xffffffUL       
#define kOTA_Main_ErrMask            0xff000000UL     
#define kOTA_MainErrShiftDownBits    24U              
/* @[define_ota_err_code_helpers] */
 
 
/*------------------------- OTA Public API --------------------------*/
 
OTA_State_t OTA_AgentInit( void * pvConnectionContext,
                           const uint8_t * pucThingName,
                           pxOTACompleteCallback_t xFunc,
                           TickType_t xTicksToWait );
 
OTA_State_t OTA_AgentInit_internal( void * pvConnectionContext,
                                    const uint8_t * pucThingName,
                                    const OTA_PAL_Callbacks_t * pxCallbacks,
                                    TickType_t xTicksToWait );
 
OTA_State_t OTA_AgentShutdown( TickType_t xTicksToWait );
 
OTA_State_t OTA_GetAgentState( void );
 
OTA_Err_t OTA_ActivateNewImage( void );
 
OTA_Err_t OTA_SetImageState( OTA_ImageState_t eState );
 
OTA_ImageState_t OTA_GetImageState( void );
 
OTA_Err_t OTA_CheckForUpdate( void );
 
OTA_Err_t OTA_Suspend( void );
 
OTA_Err_t OTA_Resume( void * pxConnection );
 
/*---------------------------------------------------------------------------*/
/*                          Statistics API                                   */
/*---------------------------------------------------------------------------*/
 
uint32_t OTA_GetPacketsReceived( void );
 
uint32_t OTA_GetPacketsQueued( void );
 
uint32_t OTA_GetPacketsProcessed( void );
 
uint32_t OTA_GetPacketsDropped( void );
 
#endif /* ifndef _AWS_IOT_OTA_AGENT_H_ */