AWS IoT Over-the-air Update Library

Getting Started With OTA

As mentioned in the previous 'Upcoming changes' section, the new "core" OTA
libraries have been released. These modular and composable libraries can be
utilized to implement an OTA 'orchestrator' which sequences the libraries to
achieve Over-The-Air Update functionality. The composable nature of the OTA
orchestrator will allow for new backing services, both supported by AWS and
not.

This library will remain available however it will not be developed further. Support will instead be focused on
the new composable libraries and example orchestrators.

For more information, see the following:

1. FreeRTOS.org webpage explaining the modular OTA concept
2. Example: Simple OTA Orchestrator
3. Example: OTA Agent Orchestrator
   1. This one is written to ease the transition of applications using this SDK.

And for the composable libraries, see:

1. Jobs Library which also contains additional support for [AWS IoT OTA jobs]()
2. MQTT Streaming Library for file block downloads over MQTT
3. coreHTTP for file block downloads over HTTP

Description

API Documentation Pages for current and previous releases of this library can be found here

The OTA library enables you to manage the notification of a newly available
update, download the update, and perform cryptographic verification of the
firmware update. Using the library, you can logically separate firmware updates
from the application running on your devices. The OTA library can share a
network connection with the application, saving memory in resource-constrained
devices. In addition, the OTA library lets you define application-specific logic
for testing, committing, or rolling back a firmware update. The library supports
different application protocols like Message Queuing Telemetry Transport (MQTT)
and Hypertext Transfer Protocol (HTTP), and provides various configuration
options you can fine tune depending on network type and conditions. This library
is distributed under the MIT Open Source License.

This library has gone through code quality checks including verification that no
function has a
GNU Complexity
score over 10. This library has also undergone static code analysis from
Coverity static analysis.

See memory requirements for this library
here.

AWS IoT Over-the-air Update Library v3.4.0
source code
is part of the
FreeRTOS 202210.00 LTS
release.

AWS IoT Over-the-air Update Library v3.3.0
source code
is part of the
FreeRTOS 202012.01 LTS
release.

Upcoming Changes

This library will be deprecated in 2024. Please see Getting Started With OTA

AWS IoT Over-the-air Updates Config File

The AWS IoT Over-the-air Updates library exposes configuration macros that are
required for building the library. A list of all the configurations and their
default values are defined in
ota_config_defaults.h. To provide custom
values for the configuration macros, a custom config file named ota_config.h
can be provided by the user application to the library.

By default, a ota_config.h custom config is required to build the library. To
disable this requirement and build the library with default configuration
values, provide OTA_DO_NOT_USE_CUSTOM_CONFIG as a compile time preprocessor
macro.

Building the Library

The otaFilePaths.cmake file contains the information of
all source files and the header include paths required to build the AWS IoT
Over-the-air Updates library.

As mentioned in the previous section, either a custom config file (i.e.
ota_config.h) OR the OTA_DO_NOT_USE_CUSTOM_CONFIG macro needs to be provided
to build the AWS IoT Over-the-air Updates library.

For a CMake example of building the AWS IoT Over-the-air Updates library with
the otaFilePaths.cmake file, refer to the coverity_analysis library target
in the test/CMakeLists.txt file.

Building Unit Tests

Checkout CMock Submodule

By default, the submodules in this repository are configured with update=none
in .gitmodules to avoid increasing clone time and disk space
usage of other repositories (like
AWS IoT Device SDK for Embedded C
that submodules this repository).

To build unit tests, the submodule dependency of CMock is required. Use the
following command to clone the submodule:

git submodule update --checkout --init --recursive test/unit-test/CMock source/dependency/coreJSON source/dependency/3rdparty/tinycbor

Platform Prerequisites

• Linux
• For building the library, CMake 3.13.0 or later and a C90 compiler.
• For running unit tests, Ruby 2.0.0 or later is additionally required for
  the CMock test framework (that we use).
• For running the coverage target, gcov and lcov are additionally
  required.

Steps to build unit tests

1. Go to the root directory of this repository. (Make sure that the CMock
   submodule is cloned as described above.)

2. Run the cmake command: cmake -S test -B build

3. Run this command to build the library and unit tests: make -C build all

4. The generated test executables will be present in build/bin/tests folder.

5. Run cd build && ctest to execute all tests and view the test run summary.

Migration Guide

How to migrate from v2.0.0 (Release Candidate) to v3.4.0

The following table lists equivalent API function signatures in v2.0.0 (Release
Candidate) and v3.4.0 declared in ota.h

How to migrate from version 1.0.0 to version 3.4.0 for OTA applications

Refer to
OTA Migration document
for the summary of updates to the API.
Migration document for OTA PAL
also provides a summary of updates required for upgrading the OTA-PAL to work
with v3.4.0 of the library.

Porting

In order to support AWS IoT Over-the-air Updates on your device, it is necessary
to provide the following components:

1. Port for the OTA Portable Abstraction Layer (PAL).

2. OS Interface

3. MQTT Interface

For enabling data transfer over HTTP dataplane the following component should
also be provided:

1. HTTP Interface

NOTE When using OTA over HTTP dataplane, MQTT is required for control plane
operations and should also be provided.

CBMC

To learn more about CBMC and proofs specifically, review the training material
here.

The test/cbmc/proofs directory contains CBMC proofs.

In order to run these proofs you will need to install CBMC and other tools by
following the instructions
here.

CBMC Locally

To run a single CBMC proof locally, you can build the Makefile in any of the
CBMC proofs. The Makefile is located in the
test/cbmc/proof/<the proof you want>/ directory.

Running make will produce a HTML-based report nearly identical to the one
produced by the CI step.

A couple notes about CBMC Proofs

• macOS doesn't implement POSIX message queues (mqueue.h);
• It is possible that macOS fails to recognize your loop unwinding identifiers
  for function from the C standard libraries. For this case, you'll want to use
  the __builtin___<function>_chk identifier, e.g., instead of using memcpy
  add __builtin___memcpy_chk.
  • For example, the requestJob_Mqtt proof fails on macOS with the following
    error:

Loop unwinding failures
[trace] __builtin___strncpy_chk.unwind.0 in line 36 in file <builtin-library-__builtin___strncpy_chk>

To solve this issue, replace strncpy with __builtin___strncpy_ch on
this line.

Reference examples

Please refer to the demos of the AWS IoT Over-the-air Updates library in the
following location for reference examples on POSIX and FreeRTOS:

Documentation

Existing Documentation

For pre-generated documentation, please see the documentation linked in the
locations below:

Note that the latest included version of coreMQTT may differ across
repositories.

Generating documentation

The Doxygen references were created using Doxygen version 1.9.2. To generate the
Doxygen pages, please run the following command from the root of this
repository:

doxygen docs/doxygen/config.doxyfile

Contributing

See CONTRIBUTING.md for information on
contributing.