Running OTA Integrated with the MQTT Agent
Including Code Signing

Preamble

While this demo uses the AWS IoT OTA update service, FreeRTOS is generic MIT licensed open source software, and can be used with any OTA mechanism that works for you. We do however recommend you digitally sign your firmware whichever OTA method you choose. That way the devices that receive the new executable image can verify it came from an authorized source and had not been been modified. You can use Code Signing for AWS IoT to sign your firmware or you can sign with your own code-signing tools.

Introduction

This example uses the MQTT agent to receive notification of a pending OTA Update Job and to download the new firmware image. Use of the MQTT agent enables the OTA update functionality to run in the background, simultaneously with other tasks that are sharing the same MQTT connection.

The example also demonstrates the use of code signing to verify that the downloaded firmware image has not been tampered with and comes from a trusted sender.

See the comments at the top of each C file in the Source Directory for additional information.

Instructions

Getting started

Start by connecting one of the simple MQTT agent examples described on the main MQTT agent documentation page to the AWS IoT MQTT broker. That will ensure connectivity to AWS IoT is working correctly before moving on to set up the OTA service.

Once connectivity is working with a non OTA demo the following instructions show you how to:

Setting up the cloud services

Get started with the AWS console

This demo application uses the AWS console to create an IoT Thing, store a firmware image, and schedule an OTA job. An AWS account is required for you to be authorized to perform these operations. Click here to get started with creating and configuring an account.

Prerequisites for using the OTA Update Manager Service

Create a Thing

An AWS IoT Thing, or simply “Thing”, is the cloud representation of a device. By registering your physical device as a Thing, you are able to store security credentials for it, assign permissions to your device (what it can and cannot do or access in the cloud), and select it when sending an OTA update. For this demo, the FreeRTOS Windows Simulator “device” will be represented by an IoT Thing and will be sent an OTA job from the AWS Console.

You will have created a Thing when connecting one of the non OTA demos to AWS IoT, so there are no additional steps here.

Setting up the device (the OTA client)

If, as recommended above, you have already used one of the other MQTT agent examples to connect with AWS IoT then you already have the source files, and have configured the network and AWS IoT connection.

Application Version

For a client to accept an OTA update, the version number of the update it receives must be higher than the version of the firmware that it’s currently running.

The application version of the device software is set in the “ota_over_mqtt_demo.c” source file with the “APP_VERSION_MAJOR”, “APP_VERSION_MINOR”, and the “APP_VERSION_BUILD” macros. The default settings of these macros are 0, 9, and 2 respectively. These do not need to be changed for now, but they will be modified in a future step.

OTA Control Protocol

The OTA Control Protocol setting manages the protocol used for AWS IoT Service control operations such as job notifications, updating the job status, and reporting progress. For control operations, only MQTT is supported at this time.

This setting is controlled by the “configENABLED_CONTROL_PROTOCOL” macro that can be found in the “ota_config.h” header file. The default value for this macro is “OTA_CONTROL_OVER_MQTT” and does not need to be modified for this demo.

OTA Data Protocol

The OTA Data Protocol defines the format used to transfer data over-the-air to and from the device. Currently MQTT and HTTPS are supported.

This option is controlled by setting the “configENABLED_DATA_PROTOCOLS” macro that can be found in the “ota_config.h” header file. The default setting for this macro is “OTA_DATA_OVER_MQTT” and does not need to be changed for this demo.

Code Signing

Code signing is used to confirm the author and guarantee that the code was not tampered with or corrupted since it was signed. As part of the OTA process, the signature of the file is verified after being completely downloaded.

The certificate used to verify the file needs to be set before performing an over-the-air update. To configure the code signing certificate, set the “signingcredentialSIGNING_CERTIFICATE_PEM” variable in the “aws_ota_codesigner_certificate.h" header file.

Enable the OTA Demo

Set the “democonfigENABLE_OTA_UPDATE_DEMO” macro to “1” in the “demo_config.h” file to enable the OTA demo.

Enable Mutual Authentication

Set the “democonfigUSE_TLS” macro to “1” in the “demo_config.h” file to enable mutual authentication.

Verify that the project builds and runs successfully

Before you continue, verify that you are able to build and run the project. You can do this by pressing F5 in the Visual Studio demo project, or by navigating to the “Debug” tab and clicking “Start Debugging”.

Prepare for creating the OTA update job

To send an OTA job, there needs to be an updated firmware image stored in an S3 bucket. The AWS IoT OTA Manager service will read the image out of this bucket and send it to the device. For the device to accept the image the received image must have a higher version number than the image already being executed on the device. The FreeRTOS Windows Simulator is being used for both building and running the demo, which cannot be done at the same time. Due to this, we need the following workflow (documented below the bullet list):

Note: An example of a production workflow would be: Set the application version

To simulate having a “new” firmware image, increment the version number. For this demo, update the following macro values that can be found in the “ota_over_mqtt_demo.c” source file as shown here:

#define APP_VERSION_MAJOR 0
#define APP_VERSION_MINOR 9
#define APP_VERSION_BUILD 2

Build the “new” firmware image

Generate the firmware image by building the project. To do this, press “Ctrl+Shift+b” or navigate to the build tab and press build within the Visual Studio project. This will generate the following executable:

/build/VisualStudio/Demo/RTOSDemo.exe

Because the demo runs on the FreeRTOS Windows Simulator, the “firmware image” in this case is the Windows executable.

Verify that the project builds and runs successfully

It’s best practice to verify firmware locally before you send it via an OTA update. See the “Verify that the project builds and runs successfully” section.

Upload the firmware image to the S3 bucket

Lower the application version

Lower the application version. For this demo, update the following macro values that can be found in the “ota_over_mqtt_demo.c” source file as shown here:

#define APP_VERSION_MAJOR 0
#define APP_VERSION_MINOR 9
#define APP_VERSION_BUILD 1

Build and run the OTA client

Press the “Local Windows Debugger” button to build and run the demo. Allow the client to continue to run as it waits to receive an OTA Job from the AWS IoT OTA Manager service.

Creating the OTA update job using the AWS IoT console

At this point, you should have:

Create the OTA update job

With the OTA Client running and the cloud services set up, the next step is to send the device a new firmware image by creating an OTA job. Start by going to the AWS IoT console.

1. In the navigation pane of the AWS IoT console, choose Manage, and then choose Jobs. Then press “Create a Job”.

   
   

   
   

2. Under Create a FreeRTOS OTA update job, choose Create OTA update job.
   
   

   
   

3. You can deploy an OTA update to a single device or a group of devices. Under Select devices to update, choose Select. Choose the Things tab to update a single device. Select the check box next to the IoT Thing associated with your device and press Next to continue.
   
   

   
   

4. Under “Select the protocol for firmware image transfer” , choose MQTT

   
   

   
   

5. Under the “Select and sign your firmware image” section, leave the default option of “Sign a new firmware image for me” selected. Under the “Code signing profile” section, press the “Create button”. 

   
   

   
   

6. In the “Profile name” section, enter “winsim_codesigning”. In the “Device hardware platform” section, select “Windows Simulator”. Under the “Code signing certificate” section select import and select the certificate and certificate private keys that you generated earlier. If you were using the suggested command, they will be called “ecdsasigner.crt” and “ecdsasigner.key”. After choosing these, select import. Write the path to the “ecdsasigner.crt” certificate that was just imported into the section called “Pathname of code signing certificate on device”. Then press “Create” to make the code signing profile. After doing these steps, it should look like the following image:
   
   

   
   

7. Press select in the “Select your firmware image in S3 or upload it” section and navigate to the executable uploaded during the previous steps. Type “./NewRTOSDemo.exe” in the “Pathname of firmware image on device” section. This path is where the file downloaded during the OTA update will be saved. Select the IAM role created for the OTA process and then press “Next” to continue.
   • Note: The support for File Type feature works with OTA library version v2.0.0 or higher.
   
   
   

   
   

8. Enter a unique job ID.
   
   

   
   

9. Leave the Job Type as the default option (snapshot) and click Create to finish creating the OTA Update Job.
   
   

   
   

10. You can monitor that status of the job by pressing the “View Job” pop-up or by navigating to Manage > Jobs in the AWS IoT console. The job will be shown as “IN PROGRESS” until the device has successfully rebooted. 
    
    

Receive and activate the update

After the job has been created, the device should begin downloading the update. The progress of the download can be monitored by viewing the Visual Studio console. Below is an example of a progress update:

Current State=[WaitingForFileBlock], Event=[RequestFileBlock], New state=[WaitingForFileBlock]
Received valid file block: Block index=96, Size=2048
Number of blocks remaining: 3

The following message will print to the monitor after receiving the final block of the download:

Received final block of the update.

At this point, the demo will verify the code signing signature of the download. If it’s successful, the following message will be printed to the console:

sig-sha256-ecdsa signature verification passed.

The demo will attempt to activate the new image after successfully downloading the update. For this demo, the update needs to be activated by manually running the downloaded executable. This is indicated by the following message:

Manual reset required: OtaPalStatus_t=OtaPalSuccess

The demo will exit with the following message after successfully validating the update.

OTA agent task stopped. Exiting OTA demo.

If the image was successfully downloaded then it is ready to be activated. Stop the debugging session and close the window. Check the directory that you specified earlier for the new executable that was downloaded over-the-air. If you typed in “./NewRTOSDemo.exe” when you created the job, then the new executable will be located in the same directory as the Visual Studio solution. Run this executable. The device will begin to validate the image after the new executable has started. If this process is successful, then the following message will be printed to the console:

New image validation succeeded in self test mode.

When the job process is complete the state of the job will change from IN PROGRESS to COMPLETED in the IoT console. If the device has successfully passed the self-test process, the status of the job will change to Succeeded.

Troubleshooting

The following sections contain information to help you troubleshoot issues with OTA updates.  

Topics

• Set Up Cloudwatch Logs for OTA Updates
• Log AWS IoT OTA API Calls with AWS CloudTrail
• Get OTA Failure Codes with the AWS CLI

Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.