AWS IoT Over-the-air Update v3.3.0
Client library for AWS IoT OTA
Design

Architecture of the OTA library.

OTA Library Configurations

The OTA library also provides various configuration options you can fine tune depending on network type and conditions. The library is provided with sensible default values for these configuration options. As these configuration settings are C pre-processor constant, they can be set with a #define in the config file (ota_config.h). It is recommended to review the configuration options and update as per use case and application requirement. Because they are compile-time constants, a library must be rebuilt if a configuration setting is changed.

For more details on OTA configuration at Configurations

OTA Library

The OTA library provides OTA Agent APIs for application development. The OTA library components consists of the OTA Agent task which contains the OTA state machine, AWS Jobs and Streaming service support over MQTT/HTTP protocol. The library defines interfaces for Platform Abstraction Layer (PAL), Operating System, MQTT, and HTTP to enable the user to work with 3rd party libraries and various devices.

OTA Agent API’s

The OTA Agent APIs provides the programming interface to the application for OTA functionality like configuring the OTA Agent, controlling the OTA process and getting statistics. The implementation supports only one instance of the OTA Agent and attempts to start OTA Agent when it is already running will only reset the statistics.

OTA Platform Abstraction Layer

The OTA platform abstraction layer provides APIs for the portable platform specific functionality of the OTA library. This includes the platform specific file storage , certificate storage , crypto verification, bootloader flags and other platform drivers. Example of OTA Pal port is for the FreeRTOS Windows Simulator.

See also
Porting documentation for PAL for more information.

OTA OS Functional Abstraction

OTA Library can be ported to run in a variety of embedded C–based environments (e.g. real-time OS, embedded Linux). OTA Library uses queue for managing events in a state machine and timers for enabling timeouts for self test and file download. The memory allocation wrapper functions should be provided with signature similar to the standard c library malloc and free functions.

See also
Porting documentation for OS for more information.

OTA MQTT interface

The OTA library can be used with any 3rd party MQTT library. To enable this a set of function pointers for MQTT functionality (Publish, Subscribe and Unsubscribe) are be used within OTA library code. These function pointers are depicted as MQTT Interface.

See also
Porting documentation for MQTT for more information.

OTA HTTP interface

The OTA library can be used with any 3rd party HTTP library. To enable this a set of function pointers for HTTP functionality (Init, RequestData and DeInit) are be used within OTA library code. These function pointers are depicted as HTTP Interface.

See also
Porting documentation for HTTP for more information.

OTA Memory Allocation

OTA Library requires allocation memory for storing the Job and file decoding and download. OTA library uses user buffer provided by OTA Demo for storing data, but if those are not sufficient then OTA library will try to allocate dynamically using the memory abstraction functions defined by the OS Functional layer.

OTA Agent Task

The OTA Agent task is started when the OTA Library is initialized. The core functionality is implemented in the task as a state machine and can receive internal/external events. Depending on the type of event and the state , event handlers are called which can result in state transitions as defined in the transition table.

See also
OTA Agent Task for more information.

Job Parser

The OTA Library uses AWS IoT jobs service and has an inbuilt job parsing functionality. AWS IoT Jobs service defines a set of remote operations that are sent to and executed on one or more devices connected to AWS IoT. Example of such operation can be updating the firmware, certificate rotation etc. The jobs service also provide features like job rollout, where you can specify how quickly targets are notified of a pending job execution. This allows to create a staged rollout to better manage updates, reboots, and other operations. Other features like abort, timeout etc are also provided. Some of the important fields that a job document can contain are -

  1. Protocol to download the file, ex MQTT, HTTP
  2. File path for the update file to be stored on the device.
  3. File size in bytes
  4. File Id , default is 0
  5. Code signing certificate path on device
  6. Stream Id ( if MQTT protocol is selected for download )
  7. Pre-signed S3 URL ( if HTTP protocol is selected for download )
  8. Code signature
  9. Code signature type

More about the AWS IoT Jobs here (https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html).

OTA Control and Data Protocols

The OTA Library operations with respect to the AWS IoT Job service can be divided into control ( Job notification, status updates, abort etc.) and data (file download). The current implementation supports MQTT protocol for control as well as data operations. HTTP is supported for data operations only i.e downloading the update file from a pre-signed URL shared in the job document. The file download protocol is selected when creating the OTA job and the OTA configuration on device has preferred protocol in case multiple protocols are selected.

Note
HTTPS will only be used for file download from S3 pre-signed url , for control messages to the AWS cloud service it will use MQTT.