Configurations of the OTA Library.

configpagestyle

Some configuration settings are C pre-processor constants, and some are function-like macros for logging. They can be set with a #define in the config file (ota_config.h) or by using a compiler option such as -D in gcc.

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

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

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

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

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

otaconfigMAX_NUM_BLOCKS_REQUEST

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'

Following two diagrams compare otaconfigLOG2_FILE_BLOCK_SIZE set to 10 (1 KB) and 12 (4 KB) with otaconfigMAX_NUM_BLOCKS_REQUEST set to maximum i.e 128 and 32 respectively.

otaconfigLOG2_FILE_BLOCK_SIZE is 10 ( 1KB )
otaconfigMAX_NUM_BLOCKS_REQUEST is 128

otaconfigLOG2_FILE_BLOCK_SIZE is 12 ( 4KB )
otaconfigMAX_NUM_BLOCKS_REQUEST is 32

otaconfigSELF_TEST_RESPONSE_WAIT_MS

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

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

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

AWS IoT Core limits the ThingName length to 128 characters maximum. For more, see the AWS IoT Core Quotas here - https://console.aws.amazon.com/servicequotas/home/services/iotcore/quotas/L-83BC2FA9

Possible values: Any unsigned 32 integer - though practical limit is 128
Default value: '128'

otaconfigMAX_NUM_REQUEST_MOMENTUM

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'

otaconfigMAX_NUM_OTA_DATA_BUFFERS

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_UPDATE_STATUS_FREQUENCY

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'

otaconfigAllowDowngrade

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'

configENABLED_CONTROL_PROTOCOL

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

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

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'

LogError

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

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

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

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.