AWS IoT Over-the-air Update
v3.1.0
Client library for AWS IoT OTA
|
|
Guide for porting OTA to a new platform.
A port to a new platform must provide the following components:
- Configuration Macros
- Ports for PAL
- OS Interface
- MQTT Interface
- 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.
uint16_t topicFilterLength,
uint8_t ucQoS );
- OTA MQTT Unsubscribe: A function that is used to unsubscribe from a given topic filter using provided QoS.
uint16_t topicFilterLength,
uint8_t ucQoS );
- OTA MQTT Publish: A function that is used to publish a message to a given topic filter and QoS.
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:
struct OtaEventContext OtaEventContext_t
Type definition for Event Context.
Definition: ota_os_interface.h:82
OtaOsStatus_t(* OtaReceiveEvent_t)(OtaEventContext_t *pEventCtx, void *pEventMsg, uint32_t timeout)
Receive an OTA event.
Definition: ota_os_interface.h:156
OTA File Context Information.
Definition: ota_private.h:382
OtaImageState_t
OTA Image states.
Definition: ota_private.h:314
void(* OtaTimerCallback_t)(OtaTimerId_t otaTimerId)
Timer callback.
Definition: ota_os_interface.h:183
OtaOsStatus_t(* OtaSendEvent_t)(OtaEventContext_t *pEventCtx, const void *pEventMsg, unsigned int timeout)
Sends an OTA event.
Definition: ota_os_interface.h:138
OtaMqttStatus_t(* OtaMqttUnsubscribe_t)(const char *pTopicFilter, uint16_t topicFilterLength, uint8_t ucQoS)
Unsubscribe to the Mqtt topics.
Definition: ota_mqtt_interface.h:130
void(* OtaFree_t)(void *ptr)
Free memory.
Definition: ota_os_interface.h:255
OtaMqttStatus_t(* OtaMqttSubscribe_t)(const char *pTopicFilter, uint16_t topicFilterLength, uint8_t ucQoS)
Subscribe to the Mqtt topics.
Definition: ota_mqtt_interface.h:111
OtaOsStatus_t(* OtaDeinitEvent_t)(OtaEventContext_t *pEventCtx)
Deinitialize the OTA Events mechanism.
Definition: ota_os_interface.h:171
OtaMqttStatus_t
The OTA MQTT interface return status.
Definition: ota_mqtt_interface.h:88
OtaTimerId_t
Enumeration for tracking multiple timers.
Definition: ota_os_interface.h:88
OtaHttpStatus_t(* OtaHttpRequest_t)(uint32_t rangeStart, uint32_t rangeEnd)
Request file block over Http.
Definition: ota_http_interface.h:117
OtaOsStatus_t
The OTA OS interface return status.
Definition: ota_os_interface.h:99
OtaPalImageState_t
OTA Platform Image State.
Definition: ota_private.h:331
OtaHttpStatus_t(* OtaHttpInit_t)(char *pUrl)
Init OTA Http interface.
Definition: ota_http_interface.h:103
OtaOsStatus_t(* OtaDeleteTimer_t)(OtaTimerId_t otaTimerId)
Delete a timer.
Definition: ota_os_interface.h:228
OtaHttpStatus_t(* OtaHttpDeinit)(void)
Deinit OTA Http interface.
Definition: ota_http_interface.h:128
OtaOsStatus_t(* OtaInitEvent_t)(OtaEventContext_t *pEventCtx)
Initialize the OTA events.
Definition: ota_os_interface.h:122
OtaOsStatus_t(* OtaStopTimer_t)(OtaTimerId_t otaTimerId)
Stop timer.
Definition: ota_os_interface.h:216
OtaHttpStatus_t
The OTA HTTP interface return status.
Definition: ota_http_interface.h:86
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:201