AWS IoT Over-the-air Update v3.4.0
Client library for AWS IoT OTA
ota_config_defaults.h File Reference

This represents the default values for the configuration macros for the OTA library. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define OTA_DO_NOT_USE_CUSTOM_CONFIG
 Define this macro to build the OTA library without the custom config file ota_config.h. More...
 
#define otaconfigSTACK_SIZE   "Please set otaconfigSTACK_SIZE"
 The number of words allocated to the stack for the OTA agent. More...
 
#define otaconfigAGENT_PRIORITY   "Please set otaconfigAGENT_PRIORITY"
 The OTA agent task priority. Normally it runs at a low priority. More...
 
#define otaconfigLOG2_FILE_BLOCK_SIZE   12UL
 Log base 2 of the size of the file data block message (excluding the header). More...
 
#define otaconfigSELF_TEST_RESPONSE_WAIT_MS   16000U
 Milliseconds to wait for the self test phase to succeed before we force reset. More...
 
#define otaconfigFILE_REQUEST_WAIT_MS   10000U
 Milliseconds to wait before requesting data blocks from the OTA service if nothing is happening. More...
 
#define otaconfigMAX_THINGNAME_LEN   64U
 The maximum allowed length of the thing name used by the OTA agent. More...
 
#define otaconfigMAX_NUM_BLOCKS_REQUEST   1U
 The maximum number of data blocks requested from OTA streaming service. More...
 
#define otaconfigMAX_NUM_REQUEST_MOMENTUM   32U
 The maximum number of requests allowed to send without a response before we abort. More...
 
#define otaconfigOTA_UPDATE_STATUS_FREQUENCY   64U
 How frequently the device will report its OTA progress to the cloud. More...
 
#define otaconfigMAX_NUM_OTA_DATA_BUFFERS   1U
 The number of data buffers reserved by the OTA agent. More...
 
#define otaconfigOTA_FILE_TYPE   uint8_t
 Data type to represent a file. More...
 
#define otaconfigAllowDowngrade   0U
 Flag to enable booting into updates that have an identical or lower version than the current version. More...
 
#define configOTA_FIRMWARE_UPDATE_FILE_TYPE_ID   0U
 The file type id received in the job document. More...
 
#define configENABLED_CONTROL_PROTOCOL   ( OTA_CONTROL_OVER_MQTT )
 The protocol selected for OTA control operations. More...
 
#define configENABLED_DATA_PROTOCOLS   ( OTA_DATA_OVER_MQTT )
 The protocol selected for OTA data operations. More...
 
#define configOTA_PRIMARY_DATA_PROTOCOL   ( OTA_DATA_OVER_MQTT )
 The preferred protocol selected for OTA data operations. More...
 
#define configOTA_POLLING_EVENTS_TIMEOUT_MS   ( 1000U )
 The polling timeout (milliseconds) to receive messages from event queue. More...
 
#define LogError(message)
 Macro that is called in the OTA library for logging "Error" level messages. More...
 
#define LogWarn(message)
 Macro that is called in the OTA library for logging "Warning" level messages. More...
 
#define LogInfo(message)
 Macro that is called in the OTA library for logging "Info" level messages. More...
 
#define LogDebug(message)
 Macro that is called in the OTA library for logging "Debug" level messages. More...
 

Detailed Description

This represents the default values for the configuration macros for the OTA library.

Note
This file SHOULD NOT be modified. If custom values are needed for any configuration macro, an ota_config.h file should be provided to the OTA library to override the default values defined in this file. To use the custom config file, the OTA_DO_NOT_USE_CUSTOM_CONFIG preprocessor macro SHOULD NOT be set.

Macro Definition Documentation

◆ OTA_DO_NOT_USE_CUSTOM_CONFIG

#define OTA_DO_NOT_USE_CUSTOM_CONFIG

Define this macro to build the OTA library without the custom config file ota_config.h.

Without the custom config, the OTA library builds with default values of config macros defined in ota_config_defaults.h file.

If a custom config is provided, then OTA_DO_NOT_USE_CUSTOM_CONFIG should not be defined.

◆ otaconfigSTACK_SIZE

#define otaconfigSTACK_SIZE   "Please set otaconfigSTACK_SIZE"

The number of words allocated to the stack for the OTA agent.

The configuration parameter specifies the size of the stack that will be allocated to the task being created (the size is specified in words, not bytes!). The amount of stack required is dependent on the application specific parameters, for more information Link

Possible values: Any positive 32 bit integer.
Default value: Varies by platform

◆ otaconfigAGENT_PRIORITY

#define otaconfigAGENT_PRIORITY   "Please set otaconfigAGENT_PRIORITY"

The OTA agent task priority. Normally it runs at a low priority.

For more information Link.

Possible values: 0 to ( configMAX_PRIORITIES - 1 )
Default value: Varies by platform.

◆ otaconfigLOG2_FILE_BLOCK_SIZE

#define otaconfigLOG2_FILE_BLOCK_SIZE   12UL

Log base 2 of the size of the file data block message (excluding the header).

Possible values: Any unsigned 32 integer.
Default value: '12'

◆ otaconfigSELF_TEST_RESPONSE_WAIT_MS

#define otaconfigSELF_TEST_RESPONSE_WAIT_MS   16000U

Milliseconds to wait for the self test phase to succeed before we force reset.

Possible values: Any unsigned 32 integer.
Default value: '16000'

◆ otaconfigFILE_REQUEST_WAIT_MS

#define otaconfigFILE_REQUEST_WAIT_MS   10000U

Milliseconds to wait before requesting data blocks from the OTA service if nothing is happening.

Note
The wait timer is reset whenever a data block is received from the OTA service so we will only send the request message after being idle for this amount of time.

Possible values: Any unsigned 32 integer.
Default value: '10000'

◆ otaconfigMAX_THINGNAME_LEN

#define otaconfigMAX_THINGNAME_LEN   64U

The maximum allowed length of the thing name used by the OTA agent.

Note
AWS IoT requires Thing names to be unique for each device that connects to the broker. Likewise, the OTA agent requires the developer to construct and pass in the Thing name when initializing the OTA agent. The agent uses this size to allocate static storage for the Thing name used in all OTA base topics. Namely $aws/things/thingName

Possible values: Any unsigned 32 integer.
Default value: '64'

◆ otaconfigMAX_NUM_BLOCKS_REQUEST

#define otaconfigMAX_NUM_BLOCKS_REQUEST   1U

The maximum number of data blocks requested from OTA streaming service.

Note
This configuration parameter is sent with data requests and represents the maximum number of data blocks the service will send in response. The maximum limit for this must be calculated from the maximum data response limit (128 KB from service) divided by the block size. For example if block size is set as 1 KB then the maximum number of data blocks that we can request is 128/1 = 128 blocks. Configure this parameter to this maximum limit or lower based on how many data blocks response is expected for each data requests.

Possible values: Any unsigned 32 integer value greater than 0.
Default value: '1'

◆ otaconfigMAX_NUM_REQUEST_MOMENTUM

#define otaconfigMAX_NUM_REQUEST_MOMENTUM   32U

The maximum number of requests allowed to send without a response before we abort.

Note
This configuration parameter sets the maximum number of times the requests are made over the selected communication channel before aborting and returning error.

Possible values: Any unsigned 32 integer.
Default value: '32'

◆ otaconfigOTA_UPDATE_STATUS_FREQUENCY

#define otaconfigOTA_UPDATE_STATUS_FREQUENCY   64U

How frequently the device will report its OTA progress to the cloud.

Note
Device will update the job status with the number of blocks it has received every certain number of blocks it receives. For example, 64 means device will update job status every 64 blocks it receives.

Possible values: Any unsigned 32 integer.
Default value: '64'

◆ otaconfigMAX_NUM_OTA_DATA_BUFFERS

#define otaconfigMAX_NUM_OTA_DATA_BUFFERS   1U

The number of data buffers reserved by the OTA agent.

Note
This configurations parameter sets the maximum number of static data buffers used by the OTA agent for job and file data blocks received.

Possible values: Any unsigned 32 integer.
Default value: '1'

◆ otaconfigOTA_FILE_TYPE

#define otaconfigOTA_FILE_TYPE   uint8_t

Data type to represent a file.

It is used to represent a file received via OTA. The file is declared as the pointer of this type: otaconfigOTA_FILE_TYPE * pFile.

Possible values: Any data type.
Default value: FILE on Windows or Linux, uint8_t on other platforms.

◆ otaconfigAllowDowngrade

#define otaconfigAllowDowngrade   0U

Flag to enable booting into updates that have an identical or lower version than the current version.

Note
Set this configuration parameter to '1' to disable version checks. This allows updates to an identical or lower version. This is provided for testing purpose and it's recommended to always update to higher version and keep this configuration disabled.

Possible values: Any unsigned 32 integer.
Default value: '0'

◆ configOTA_FIRMWARE_UPDATE_FILE_TYPE_ID

#define configOTA_FIRMWARE_UPDATE_FILE_TYPE_ID   0U

The file type id received in the job document.

Note
The file type id received in the job document that allows devices to identify the type of file received from the cloud. This configuration defines the file type id used for firmware updates. If this is changed then the updated value must be used while creating firmware update jobs.

◆ configENABLED_CONTROL_PROTOCOL

#define configENABLED_CONTROL_PROTOCOL   ( OTA_CONTROL_OVER_MQTT )

The protocol selected for OTA control operations.

Note
This configurations parameter sets the default protocol for all the OTA control operations like requesting OTA job, updating the job status etc.
Only MQTT is supported at this time for control operations.

Possible values: OTA_CONTROL_OVER_MQTT
Default value: 'OTA_CONTROL_OVER_MQTT'

◆ configENABLED_DATA_PROTOCOLS

#define configENABLED_DATA_PROTOCOLS   ( OTA_DATA_OVER_MQTT )

The protocol selected for OTA data operations.

Note
This configurations parameter sets the protocols selected for the data operations like requesting file blocks from the service.

Possible values:
Enable data over MQTT - ( OTA_DATA_OVER_MQTT )
Enable data over HTTP - ( OTA_DATA_OVER_HTTP )
Enable data over both MQTT & HTTP - ( OTA_DATA_OVER_MQTT | OTA_DATA_OVER_HTTP )
Default value: 'OTA_DATA_OVER_MQTT'

◆ configOTA_PRIMARY_DATA_PROTOCOL

#define configOTA_PRIMARY_DATA_PROTOCOL   ( OTA_DATA_OVER_MQTT )

The preferred protocol selected for OTA data operations.

Note
Primary data protocol will be the protocol used for downloading file if more than one protocol is selected while creating OTA job.

Possible values:
Data over MQTT - ( OTA_DATA_OVER_MQTT )
Data over HTTP - ( OTA_DATA_OVER_HTTP )
Default value: 'OTA_DATA_OVER_MQTT'

◆ configOTA_POLLING_EVENTS_TIMEOUT_MS

#define configOTA_POLLING_EVENTS_TIMEOUT_MS   ( 1000U )

The polling timeout (milliseconds) to receive messages from event queue.

Possible values: Any unsigned 32 integer.
Default value: '1000'

◆ LogError

#define LogError (   message)

Macro that is called in the OTA library for logging "Error" level messages.

To enable error level logging in the OTA library, this macro should be mapped to the application-specific logging implementation that supports error logging.

Note
This logging macro is called in the OTA library with parameters wrapped in double parentheses to be ISO C89/C90 standard compliant. For a reference POSIX implementation of the logging macros, refer to the ota default config file, and the logging-stack in demos folder of the AWS IoT Embedded C SDK repository.

Default value: Error logging is turned off, and no code is generated for calls to the macro in the OTA library on compilation.

◆ LogWarn

#define LogWarn (   message)

Macro that is called in the OTA library for logging "Warning" level messages.

To enable warning level logging in the OTA library, this macro should be mapped to the application-specific logging implementation that supports warning logging.

Note
This logging macro is called in the OTA library with parameters wrapped in double parentheses to be ISO C89/C90 standard compliant. For a reference POSIX implementation of the logging macros, refer to the ota default config file, and the logging-stack in demos folder of the AWS IoT Embedded C SDK repository.

Default value: Warning logging is turned off, and no code is generated for calls to the macro in the OTA library on compilation.

◆ LogInfo

#define LogInfo (   message)

Macro that is called in the OTA library for logging "Info" level messages.

To enable info level logging in the OTA library, this macro should be mapped to the application-specific logging implementation that supports info logging.

Note
This logging macro is called in the OTA library with parameters wrapped in double parentheses to be ISO C89/C90 standard compliant. For a reference POSIX implementation of the logging macros, refer to the ota default config file, and the logging-stack in demos folder of the AWS IoT Embedded C SDK repository.

Default value: Info logging is turned off, and no code is generated for calls to the macro in the OTA library on compilation.

◆ LogDebug

#define LogDebug (   message)

Macro that is called in the OTA library for logging "Debug" level messages.

To enable Debug level logging in the OTA library, this macro should be mapped to the application-specific logging implementation that supports debug logging.

Note
This logging macro is called in the OTA library with parameters wrapped in double parentheses to be ISO C89/C90 standard compliant. For a reference POSIX implementation of the logging macros, refer to the ota default config file, and the logging-stack in demos folder of the AWS IoT Embedded C SDK repository.

Default value: Debug logging is turned off, and no code is generated for calls to the macro in the OTA library on compilation.