OTA Updates with AWS and the CY8CKIT-064S0S2-4343W Kit – KBA231112

[GaryS_06]

Version : *A

This tutorial provides instructions on using OTA with the CY8CKIT-064S0S2-4343W kit.  If you do not have a kit, you can purchase one from the website at this link: CY8CKIT-064S0S2-4343W.

First Steps

Before you begin, follow the Getting Started Guide for the Cypress CY8CKIT-064S0S2-4343W Kit and ensure you are able to perform a build and run the Amazon FreeRTOS MQTT demo project. As a result, you are already familiar with the development environment and how to work with the hardware.

Note: In this tutorial, the path to the FreeRTOS download directory is referred to as <freertos>.

 

Note on Amazon FreeRTOS Qualification Status

PSoC® 64 devices have passed all of the required FreeRTOS qualification tests. However, the optional OTA feature implemented in the PSoC 64 Standard Secure AWS firmware library is still pending evaluation. The OTA feature as-implemented currently passes all of the OTA qualification tests except “OTA_incorrect_wifi_password” (https://github.com/aws/amazon-freertos/blob/master/tools/ota_e2e_tests/aws_ota_test/aws_ota_test_cas...).

When a successfully validated OTA image is applied to a device using the PSoC64 Standard Secure AWS MCU and the device is unable to communicate with AWS IoT Core, the device will not be able to automatically rollback to the original known good image. This may result in the device being unreachable from AWS IoT Core for any further updates. This functionality is still under development by the Cypress team.

Resources

FreeRTOS Over-the-Air description can be found here.

https://docs.aws.amazon.com/freertos/latest/userguide/freertos-ota-dev.html

See also README.md at https://github.com/aws/amazon-freertos

OTA Update Prerequisites

In preparation for OTA, following the prerequisites as described here.

https://docs.aws.amazon.com/freertos/latest/userguide/ota-prereqs.html

Specifically, please follow instructions to accomplish the following.

1. Create an Amazon S3 bucket to store your update
2. Create an OTA Update service role
3. Create an OTA user policy
4. Create a code-signing certificate – Refer to instructions in the next section
5. Grant access to code signing for AWS IoT
6. Prerequisites for OTA updates using MQTT
7. Prerequisites for OTA updates using HTTP

Create a Code-Signing Certificate

To digitally sign firmware images, you need a code-signing certificate and private key. For testing purposes, you can create a self‐signed certificate and private key. For production environments, purchase a certificate through a well‐known certificate authority (CA).

Use the AWS Command Line Interface to import your code-signing certificate, private key, and certificate chain into AWS Certificate Manager. For more information see Installing the AWS CLI in the AWS Command Line Interface User Guide.

1. Open a command prompt or terminal with administrator permissions.
2. Generate the private key using the following command:

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -pkeyopt ec_param_enc:named_curve -outform PEM -out <filename>.pem 

3. Create a new file cert_config.txt in the same directory with the following contents. Modify <user_name> and <domain> to match your credentials.

[req]
prompt             = no
distinguished_name = my_dn   

[my_dn]
commonName = <user_name>@<domain>.com   

[my_exts]
keyUsage         = digitalSignature
extendedKeyUsage = codeSigning 

4. Generate a code-signing certificate using the following command:

openssl req -new -x509 -config cert_config.txt -extensions my_exts -nodes -days 365 -key <filename>.pem -out <filename>.crt

5. Paste the contents of <filename>.crt in aws_ota_codesigner_certificate.h at <amazon-freertos>/demos/include. Follow the format explained in the file. This is used to verify the signature generated by AWS and streamed with the image to the kit.
6. Register the certificate and private key with AWS Certificate Manager (ACM). An ARN is created in this stage and stored in certarn.json. This ARN is needed when you create an OTA job.

aws acm import-certificate –certificate file://<filename>.crt –private-key file://<filename>.pem > certarn.json

 

Build and Run the Amazon FreeRTOS OTA Demo Project

Build the FreeRTOS Demo

1. Open Eclipse and choose or create a workspace.
2. From the File menu, choose Import. Expand General, choose Existing Project Into Workspace and then choose Next.
3. In Root Directory, enter <freertos>/projects/cypress/<kit-name>/mtb/aws_demos. The project name aws_demos should be selected by default. Choose Finish to import the project into your workspace.
4. Configure for the OTA demo. From the left panel, select aws_demos->vendors->cypress->boards->CY8CKIT_064S0S2_4343W->aws_demos->config_files->aws_demo_config.h.  Change the following line.

#define CONFIG_MQTT_DEMO_ENABLED  

to

#define CONFIG_OTA_UPDATE_DEMO_ENABLED 

5. Enable OTA Support. From the left panel, select aws_demos->Makefile. Change the following line.

OTA_SUPPORT=0 

to

OTA_SUPPORT=1 

6. From the Quick Panel, click Build aws_demos Application (Or, use Project > Build All). Confirm the project compiles without any errors.

Run the FreeRTOS Demo Project

1. Click the project aws_demos in the workspace
2. From the Quick Panel, click aws_demos Program (KitProg3). This step will program the board and the demo application starts running after the programming is finished.
3. You can view the status of the running application in the serial terminal. Following figure shows a part of the terminal output.

 

The OTA demo will now wait for an OTA job.

Build Update Image and Create OTA Job

Next, advance the version number and create an update image. The FreeRTOS guide can be found in the following link.

https://docs.aws.amazon.com/freertos/latest/userguide/dev-guide-ota-workflow.html

The instructions are simplified here for CY8CKIT_064S0S2_4343W.

1. In Eclipse, select aws_demos->include->aws_application_version.h from the left pane. Increase one of APP_VERSION_MAJOR, APP_VERSION_MINOR, or APP_VERSION_BUILD.
2. Build application again.
3. Add cm4.bin to the s3 bucket and create an OTA job. Follow the instructions in the following links for creating an OTA Job.
   1. Creating an OTA update (AWS IoT console)
   2. Creating an OTA update with the AWS CLI

Using CMake with FreeRTOS

You can alternatively use CMake to build and run the demo application. See CMake Prerequisites to setup CMake and a native build system.

1. Use the following command to generate build files. Specify the target board through -DBOARD option. Ensure -DOTA_SUPPORT=1 is specified to enable OTA.

cmake -DVENDOR=cypress -DBOARD=CY8CKIT_064S0S2_4343W -DCOMPILER=arm-gcc -S <freertos> -B <build_dir> -DOTA_SUPPORT=1 

If you are using Windows, you must specify the native build system using -G option because CMake uses Visual Studio by default. For example:

cmake -DVENDOR=cypress -DBOARD=CY8CPROTO_064S0S2_4343W -DCOMPILER=arm-gcc -S <freertos> -B <build_dir> -DOTA_SUPPORT=1 -G Ninja 

If arm-none-eabi-gcc is not in your shell path, you also need to set the AFR_TOOLCHAIN_PATH CMake variable. For example:

-DAFR_TOOLCHAIN_PATH=/home/user/opt/gcc-arm-none-eabi/bin 

2. Use the following command to build the project using CMake.

CMake --build <build_dir> 

3. Finally, program the cm4.elf file generated under <build_dir> using Cypress Programmer and/or use cm4.bin as the update image.

Monitoring OTA Job on the Cloud

You can use the AWS IoT console to monitor the active OTA job.

1. Sign in to the AWS IoT console.
2. In the navigation pane, choose Manage and select Jobs.
3. The job you create should appear in the list

Debugging

Debugging is done via ModusToolbox Eclipse and the steps are as documented in the Getting Started Guide.

Additional Help

If you have further questions or need technical support, please contact the Cypress Developer Community.