AWS IoT Over-the-air Update  v2.0.0 (Release Candidate)
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 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:

OtaPalStatus_t
uint32_t OtaPalStatus_t
The OTA platform interface return status. Composed of main and sub status.
Definition: ota_platform_interface.h:61
OtaEventContext_t
struct OtaEventContext OtaEventContext_t
Type definition for Event Context.
Definition: ota_os_interface.h:76
OtaReceiveEvent_t
OtaOsStatus_t(* OtaReceiveEvent_t)(OtaEventContext_t *pEventCtx, void *pEventMsg, uint32_t timeout)
Receive an OTA event.
Definition: ota_os_interface.h:157
OtaPalCreateFileForRx_t
OtaPalStatus_t(* OtaPalCreateFileForRx_t)(OtaFileContext_t *const pFileContext)
Create a new receive file for the data chunks as they come in.
Definition: ota_platform_interface.h:158
OtaFileContext_t
OTA File Context Information.
Definition: ota_private.h:390
OtaImageState_t
OtaImageState_t
OTA Image states.
Definition: ota_private.h:322
OtaTimerCallback_t
void(* OtaTimerCallback_t)(OtaTimerId_t otaTimerId)
Timer callback.
Definition: ota_os_interface.h:184
OtaSendEvent_t
OtaOsStatus_t(* OtaSendEvent_t)(OtaEventContext_t *pEventCtx, const void *pEventMsg, unsigned int timeout)
Sends an OTA event.
Definition: ota_os_interface.h:139
OtaMqttUnsubscribe_t
OtaMqttStatus_t(* OtaMqttUnsubscribe_t)(const char *pTopicFilter, uint16_t topicFilterLength, uint8_t ucQoS)
Unsubscribe to the Mqtt topics.
Definition: ota_mqtt_interface.h:124
OtaFree_t
void(* OtaFree_t)(void *ptr)
Free memory.
Definition: ota_os_interface.h:256
OtaPalActivateNewImage_t
OtaPalStatus_t(* OtaPalActivateNewImage_t)(OtaFileContext_t *const pFileContext)
Activate the newest MCU image received via OTA.
Definition: ota_platform_interface.h:222
OtaMqttSubscribe_t
OtaMqttStatus_t(* OtaMqttSubscribe_t)(const char *pTopicFilter, uint16_t topicFilterLength, uint8_t ucQoS)
Subscribe to the Mqtt topics.
Definition: ota_mqtt_interface.h:105
OtaDeinitEvent_t
OtaOsStatus_t(* OtaDeinitEvent_t)(OtaEventContext_t *pEventCtx)
Deinitialize the OTA Events mechanism.
Definition: ota_os_interface.h:172
OtaPalAbort_t
OtaPalStatus_t(* OtaPalAbort_t)(OtaFileContext_t *const pFileContext)
Abort an OTA transfer.
Definition: ota_platform_interface.h:133
OtaMqttStatus_t
OtaMqttStatus_t
The OTA MQTT interface return status.
Definition: ota_mqtt_interface.h:82
OtaTimerId_t
OtaTimerId_t
Enumeration for tracking multiple timers.
Definition: ota_os_interface.h:89
OtaHttpRequest_t
OtaHttpStatus_t(* OtaHttpRequest_t)(uint32_t rangeStart, uint32_t rangeEnd)
Request file block over Http.
Definition: ota_http_interface.h:111
OtaOsStatus_t
OtaOsStatus_t
The OTA OS interface return status.
Definition: ota_os_interface.h:100
OtaPalImageState_t
OtaPalImageState_t
OTA Platform Image State.
Definition: ota_private.h:339
OtaHttpInit_t
OtaHttpStatus_t(* OtaHttpInit_t)(char *pUrl)
Init OTA Http interface.
Definition: ota_http_interface.h:97
OtaPalGetPlatformImageState_t
OtaPalImageState_t(* OtaPalGetPlatformImageState_t)(OtaFileContext_t *const pFileContext)
Get the state of the OTA update image.
Definition: ota_platform_interface.h:285
OtaDeleteTimer_t
OtaOsStatus_t(* OtaDeleteTimer_t)(OtaTimerId_t otaTimerId)
Delete a timer.
Definition: ota_os_interface.h:229
OtaPalCloseFile_t
OtaPalStatus_t(* OtaPalCloseFile_t)(OtaFileContext_t *const pFileContext)
Authenticate and close the underlying receive file in the specified OTA context.
Definition: ota_platform_interface.h:184
OtaHttpDeinit
OtaHttpStatus_t(* OtaHttpDeinit)(void)
Deinit OTA Http interface.
Definition: ota_http_interface.h:122
OtaPalWriteBlock_t
int16_t(* OtaPalWriteBlock_t)(OtaFileContext_t *const pFileContext, uint32_t offset, uint8_t *const pData, uint32_t blockSize)
Write a block of data to the specified file at the given offset.
Definition: ota_platform_interface.h:205
OtaInitEvent_t
OtaOsStatus_t(* OtaInitEvent_t)(OtaEventContext_t *pEventCtx)
Initialize the OTA events.
Definition: ota_os_interface.h:123
OtaStopTimer_t
OtaOsStatus_t(* OtaStopTimer_t)(OtaTimerId_t otaTimerId)
Stop timer.
Definition: ota_os_interface.h:217
OtaHttpStatus_t
OtaHttpStatus_t
The OTA HTTP interface return status.
Definition: ota_http_interface.h:80
OtaPalSetPlatformImageState_t
OtaPalStatus_t(* OtaPalSetPlatformImageState_t)(OtaFileContext_t *const pFileContext, OtaImageState_t eState)
Attempt to set the state of the OTA update image.
Definition: ota_platform_interface.h:259
OtaStartTimer_t
OtaOsStatus_t(* OtaStartTimer_t)(OtaTimerId_t otaTimerId, const char *const pTimerName, const uint32_t timeout, OtaTimerCallback_t callback)
Start timer.
Definition: ota_os_interface.h:202
OtaPalResetDevice_t
OtaPalStatus_t(* OtaPalResetDevice_t)(OtaFileContext_t *const pFileContext)
Reset the device.
Definition: ota_platform_interface.h:236