AWS IoT Over-the-air Update v3.4.0
Client library for AWS IoT OTA
Porting Guide

Guide for porting OTA to a new platform.

A port to a new platform must provide the following components:

  1. Configuration Macros
  2. Ports for PAL
  3. OS Interface
  4. MQTT Interface
  5. HTTP Interface

Configuration Macros

Settings that must be set as macros in the config header ota_config.h, or passed in as compiler options.

Note
If a custom configuration header ota_config.h is not provided, then the OTA_DO_NOT_USE_CUSTOM_CONFIG macro must be defined.
See also
Configurations

The following optional logging macros are used throughout the library:

OTA PAL requirements:

The OTA library relies on portable abstraction layer (PAL) callbacks that must be implemented to store the download as it is streamed.

See also
OTA PAL documentation

The OTA PAL interface used by the OTA library is defined in ota_platform_interface.h. A port must implement functions corresponding to the following function pointers:

OTA OS Functional Interface requirements:

The OTA library relies on several functionalities that are commonly provided by operating systems. This includes timers, events, and memory allocation. This interface must be implemented to provide these functionalities to the OTA library.

See also
OTA OS Functional Interface documentation The OTA OS Functional Interface used by the OTA library is defined in ota_os_interface.h. A port must implement functions corresponding to the following function pointers:

OTA MQTT requirements:

The OTA library relies on a MQTT library to manage control and data operations.

The OTA library needs to connect to AWS IoT using MQTT PUBLISH messages to receive notifications and file blocks. This is done by Subscribing to different notification topics.

See also
OTA MQTT documentation

The OTA MQTT API used by the OTA library is defined in ota_mqtt_interface.h. A library must implement functions corresponding to the following function pointers:

  • OTA MQTT Subscribe: A function that is used to subscribe to a given topic filter and QoS.
    OtaMqttStatus_t ( * OtaMqttSubscribe_t ) ( const char * pTopicFilter,
    uint16_t topicFilterLength,
    uint8_t ucQoS );
    OtaMqttStatus_t
    The OTA MQTT interface return status.
    Definition: ota_mqtt_interface.h:90
    OtaMqttStatus_t(* OtaMqttSubscribe_t)(const char *pTopicFilter, uint16_t topicFilterLength, uint8_t ucQoS)
    Subscribe to the Mqtt topics.
    Definition: ota_mqtt_interface.h:113
  • OTA MQTT Unsubscribe: A function that is used to unsubscribe from a given topic filter using provided QoS.
    OtaMqttStatus_t ( * OtaMqttUnsubscribe_t ) (const char * pTopicFilter,
    uint16_t topicFilterLength,
    uint8_t ucQoS );
    OtaMqttStatus_t(* OtaMqttUnsubscribe_t)(const char *pTopicFilter, uint16_t topicFilterLength, uint8_t ucQoS)
    Unsubscribe to the Mqtt topics.
    Definition: ota_mqtt_interface.h:132
  • OTA MQTT Publish: A function that is used to publish a message to a given topic filter and QoS.
    OtaMqttStatus_t ( * OtaMqttSubscribe_t ) ( const char * pTopicFilter,
    uint16_t topicFilterLength,
    uint8_t ucQoS );

OTA HTTP requirements:

The OTA library relies on a HTTP library to manage data operations.

To download a datablock over http, OTA library needs to connect to a pre-signed URL and request data blocks to download the update.

See also
OTA MQTT documentation

The OTA HTTP API used by the OTA library is defined in ota_http_interface.h.

A library must implement functions corresponding to the following function pointers: