aws_ota_agent.h

Go to the documentation of this file.

/*
 * FreeRTOS
 * Copyright (C) 2017 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_OTA_AGENT_H_
#define _AWS_OTA_AGENT_H_

/* Type definitions for OTA Agent */
#include "aws_ota_types.h"

/* Includes required by the FreeRTOS timers structure. */
#include "FreeRTOS.h"
#include "timers.h"

/* Include for console serial output. */
#include "aws_logging_task.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 pcOTA_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;
#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;
#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;
#define OTA_LOG_L3 vLoggingPrintf
#else
#define DEFINE_OTA_METHOD_NAME_L3(name)
#define OTA_LOG_L3(...)
#endif

typedef enum {
    eOTA_AgentState_Unknown = -1,       
    eOTA_AgentState_NotReady = 0,       
    eOTA_AgentState_Ready = 1,          
    eOTA_AgentState_Active = 2,         
    eOTA_AgentState_ShuttingDown = 3,   
    eOTA_NumAgentStates = 4
} OTA_State_t;

/* 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 uint32_t OTA_Err_t;

#define kOTA_PAL_ErrMask 0xffffffUL     
#define kOTA_Main_ErrMask 0xff000000UL  
#define kOTA_MainErrShiftDownBits 24U   
#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_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      
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;


typedef struct {

    uint8_t        *pacFilepath;        
    union {
                                    
        int32_t     iFileHandle;        
#if WIN32
        FILE       *pstFile;            
#endif
        uint8_t    *pucFile;            
    };
    TimerHandle_t   pvRequestTimer;     
    uint32_t        ulFileSize;         
    uint32_t        ulBlocksRemaining;  
    uint32_t        ulFileAttributes;   
    uint32_t        ulServerFileID;     
    uint32_t        ulRequestMomentum;  
    uint8_t        *pacJobName;         
    uint8_t        *pacStreamName;      
    Sig256_t       *pxSignature;        
    uint8_t        *pacRxBlockBitmap;   
    uint8_t        *pacCertFilepath;    
    uint32_t        ulUpdaterVersion;   
    bool_t          bIsInSelfTest;      
} OTA_FileContext_t;


typedef void (*pxOTACompleteCallback_t)( OTA_JobEvent_t eEvent );

/*---------------------------------------------------------------------------*/
/*                              Public API                                   */
/*---------------------------------------------------------------------------*/

OTA_State_t OTA_AgentInit( void *pvClient, const uint8_t *pcThingName, pxOTACompleteCallback_t xFunc, 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);

/* @brief Request for the next available OTA job from the job service via MQTT.
 *
 * @return kOTA_Err_None if successful, otherwise an error code prefixed with 'kOTA_Err_' from the
 * list above.
 */
OTA_Err_t OTA_CheckForUpdate( void );

/*---------------------------------------------------------------------------*/
/*                          Statistics API                                   */
/*---------------------------------------------------------------------------*/

uint32_t OTA_GetPacketsReceived( void );

uint32_t OTA_GetPacketsQueued( void );

uint32_t OTA_GetPacketsProcessed( void );

uint32_t OTA_GetPacketsDropped( void );

/* _AWS_OTA_AGENT_H_ */
#endif