Amazon FreeRTOS
Porting Guide

Porting the OTA Library

With Amazon FreeRTOS over-the-air (OTA) updates, you can do the following:

  • Deploy new firmware images to a single device, a group of devices, or your entire fleet.

  • Deploy firmware to devices as they are added to groups, are reset, or are reprovisioned.

  • Verify the authenticity and integrity of new firmware after it has been deployed to devices.

  • Monitor the progress of a deployment.

  • Debug a failed deployment.

  • Digitally sign firmware using Code Signing for AWS IoT.

For more information, see Amazon FreeRTOS Over-the-Air Updates in the Amazon FreeRTOS User Guide.

You can use the OTA agent library to integrate OTA functionality into your Amazon FreeRTOS applications. For more information, see Amazon FreeRTOS OTA Agent Library in the Amazon FreeRTOS User Guide.

Amazon FreeRTOS devices must enforce cryptographic code-signing verification on the OTA firmware images that they receive. We recommend the following algorithms:

  • Elliptic-Curve Digital Signature Algorithm (ECDSA)

  • NIST P256 curve

  • SHA-256 hash

Note

A port of the Amazon FreeRTOS OTA update library is currently not required for qualification.

Prerequisites

To port the OTA agent library, you need the following:

Porting

<amazon-freertos>/vendors/<vendor>/boards/<board>/ports/ota/aws_ota_pal.c contains empty definitions of a set of platform abstraction layer (PAL) functions. Implement at least the set of functions listed in this table.

Function Description
prvPAL_Abort Aborts an OTA update.
prvPAL_CreateFileForRx Creates a file to store the data chunks as they are received.
prvPAL_CloseFile Closes the specified file. This might authenticate the file if storage that implements cryptographic protection is being used.
prvPAL_WriteBlock Writes a block of data to the specified file at the given offset. On success, returns the number of bytes written. Otherwise, a negative error code.
prvPAL_ActivateNewImage Activates or launches the new firmware image. For some ports, if the device is programmatically reset synchronously, this function might not return.
prvPAL_SetPlatformImageState Does what is required by the platform to accept or reject the most recent OTA firmware image (or bundle). To determine how to implement this function, consult the documentation for your board (platform) details and architecture. .
prvPAL_GetPlatformImageState Gets the state of the OTA update image.

Implement the functions in this table if your device has built-in support for them.

Function Description
prvPAL_CheckFileSignature Verifies the signature of the specified file.
prvPAL_ReadAndAssumeCertificate Reads the specified signer certificate from the file system and returns it to the caller.

Make sure that you have a bootloader that can support OTA updates. For instructions on porting the bootloader demo application provided with Amazon FreeRTOS, see Porting the Bootloader Demo.

Testing

If you are using an IDE to build test projects, you need to set up your library port in the IDE project.

Setting Up the IDE Test Project

If you are using an IDE for porting and testing, you need to add some source files to the IDE test project before you can test your ported code.

Important

In the following steps, make sure that you add the source files to your IDE project from their on-disk location. Do not create duplicate copies of source files.

To set up the OTA library in the IDE project

  1. Add the source file <amazon-freertos>/vendors/<vendor>/boards/<board>/ports/ota/aws_ota_pal.c to the aws_tests IDE project.

  2. Add the following test source files to the aws_tests IDE project:

    • <amazon-freertos>/libraries/freertos_plus/aws/ota/test/aws_test_ota_cbor.c

    • <amazon-freertos>/libraries/freertos_plus/aws/ota/test/aws_test_ota_agent.c

    • <amazon-freertos>/libraries/freertos_plus/aws/ota/test/aws_test_ota_pal.c

    • /demos/ota/aws_iot_ota_update_demo.c

Configuring the CMakeLists.txt File

If you are using CMake to build your test project, you need to define a portable layer target for the library in your CMake list file.

To define a library's portable layer target in CMakeLists.txt, follow the instructions in Amazon FreeRTOS Portable Layers.

The CMakeLists.txt template list file under <amazon-freertos>/vendors/<vendor>/boards/<board>/CMakeLists.txt includes example portable layer target definitions. You can uncomment the definition for the library that you are porting, and modify it to fit your platform.

See below for an example portable layer target definition for the OTA library.

# OTA afr_mcu_port(ota) target_sources( AFR::ota::mcu_port INTERFACE "path/aws_ota_pal.c" )

There are two sets of tests for the OTA library port: OTA Agent and OTA PAL Tests and OTA End-to-End Tests.

OTA Agent and OTA PAL Tests

Setting Up Your Local Testing Environment

To configure the source and header files for the OTA agent and OTA PAL tests

  1. Open <amazon-freertos>/vendors/<vendor>/boards/<board>/aws_tests/config_files/aws_test_runner_config.h, and set the testrunnerFULL_OTA_AGENT_ENABLED and testrunnerFULL_OTA_PAL_ENABLED macros to 1 to enable the agent and PAL tests.

  2. Choose a signing certificate for your device from ota/test. The certificate are used in OTA tests for verification.

    Three types of signing certificates are available in the test code:

    • RSA/SHA1

    • RSA/SHA256

    • ECDSA/SHA256

    RSA/SHA1 and RSA/SHA256 are available for existing platforms only. ECDSA/SHA256 is recommended for OTA updates. If you have a different scheme, contact the Amazon FreeRTOS engineering team.

Running the Tests

To execute the OTA agent and OTA PAL tests

  1. Build the test project, and then flash it to your device for execution.

  2. Check the test results in the UART console.

    ...

OTA End-to-End Tests

To set up and run the end-to-end OTA tests

  1. Follow the setup instructions in the README file (<amazon-freertos>/tools/ota_e2e_test/README.md).

  2. Make sure that running the agent and PAL tests do not modify the aws_clientcredential.h, aws_clientcredential_keys.h, aws_application_version.h, or aws_ota_codesigner_certificate.h header files.

  3. To run the OTA end-to-end test script, follow the example in the README file (<amazon-freertos>/tools/ota_e2e_test/README.md).

Validation

To officially qualify a device for Amazon FreeRTOS, you need to validate the device's ported source code with AWS IoT Device Tester. Follow the instructions in Using AWS IoT Device Tester for Amazon FreeRTOS in the Amazon FreeRTOS User Guide to set up Device Tester for port validation. To test a specific library's port, the correct test group must be enabled in the device.json file in the Device Tester configs folder.

After you have ported the Amazon FreeRTOS OTA library and the bootloader demo, you can start porting the Bluetooth Low Energy library. For instructions, see Porting the Bluetooth Low Energy Library.

If your device does not support Bluetooth Low Energy functionality, then you are finished and can start the Amazon FreeRTOS qualification process. For more information, see the Amazon FreeRTOS Qualification Guide.