NOTE: The coreMQTT agent used by the OTA library is functional but not yet part of the coreMQTT library or in the main FreeRTOS.org download because it does not yet meet our code quality criteria and hasn’t yet been fully tested. The OTA code is currently a release candidate.
Running OTA Integrated with the MQTT Agent
Including Code Signing
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.
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.
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:
- Set up the cloud services to be able to store the firmware image and send it to the device.
- Configure the device and run the OTA client to receive the update.
- Prepare and create the OTA Update Job to send the firmware to the device.
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.
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 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 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):
- Set the application version number and build the project executable.
- Verify that the executable can build and run correctly.
- Upload the executable /build/VisualStudio/Demo/RTOSDemo.exe to S3.
- Set the application version number to something lower than that used in step 1.
- Build the demo with the lowered version number.
- Run the updated demo and let it continue to run while waiting for an OTA Job.
Note: An example of a production workflow would be:
Set the application version
- Write the MCU firmware, integrating the OTA Client library source code.
- Program the device hardware (the MCU) with the initial firmware.
- Make changes to and test the firmware locally.
- Generate the binary for the new version of the firmware.
- Upload the new version to S3 and send it to the MCU with the an OTA Job.
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:
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
- Sign in to the Amazon S3 console at https://console.aws.amazon.com/s3/.
- Click on the bucket created in the previous steps.
- Click on the “Upload” button that is under the “Overview” tab.
- Drag and drop “RTOSDemo.exe” to the bucket.
- Click “Upload” to add the executable to the 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:
- Created an AWS IoT Thing with the AWS IoT Service.
- Setup the S3 bucket and managed permissions for the various services.
- Uploaded a “newer” firmware image to the S3 bucket.
- Completed the setup required for code signing.
- Configured the OTA client running on your device.
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.
In the navigation pane of the AWS IoT console, choose
Manage, and then choose Jobs.
Then press “Create a Job”.
Under Create a FreeRTOS OTA update job,
choose Create OTA update job.
- 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.
Under “Select the protocol for firmware image transfer”
, choose MQTT
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”.
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
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.
Enter a unique job ID.
Leave the Job Type as the default option (snapshot) and click Create to
finish creating the OTA Update Job.
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.
The following sections contain information to help you troubleshoot issues with OTA updates.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.