Amazon Free RTOS Qualification Program Developer Guide

Amazon FreeRTOS Qualification

Developer Guide

Document Version V1.1.3

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Amazon FreeRTOS Qualification: Developer Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is

not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that

disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their

respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Revision History

Date

Versi

on

Change History

Compatible

Amazon

FreeRTOS

Version

July 31, 2018

1.0.0

Initial Version.

1.3.0

August 09, 2018

1.0.1

Updates in appendices:

 Updates in Porting Order chart.

 Updates in PKCS#11 “Porting” section.

 File path changes in TLS “Test Setup” section and

TLS Server Setup step 9.

 Fix hyperlinks in MQTT prerequisite section.

 Add AWS CLI config instruction in BYOC

certificate creation example.

1.3.1

1.3.2

August 27, 2018

1.1.0

Added tests for Over-the-air (OTA) updates and

guidelines for bootloader

1.4.0

1.4.1

October 08, 2018

1.1.1

Added clarifications in (B3.1) tests enable constants

table.

Updated path changes of Unity module in “Create

Test Project (B2.2)” section.

Updates in appendices:

 Updated Porting Order Flowchart.

 Updated client credential certificate/key variable

names in TLS “Test Setup” section.

 Corrections of a file path in Secure Socket “Test

Setup” section and TLS Server Setup.

 Updated the path for echo servers in TLS “Test

Setup” section and TLS Server Setup.

1.4.2

November 07, 2018

1.1.2

Updates in appendices:

 Modifications of PKCS #11 PAL layer interface

changes in PKCS #11 porting section.

 Updated GSG template, “Download and

Configure Amazon FreeRTOS” section.

 Updated the path of

CertificateConfigurator.html.

1.4.3

1.4.4

November 26, 2018

1.1.3

Added BLE section.

Updated with IoT Device Tester information.

Added cmake preparation section.

To be

assigned

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3           
 
Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.  4 
 
Contents 
Revision History ............................................................................................................................................ 3 
Introduction .......................................................................................................................................... 6 
1  What is the Amazon FreeRTOS Qualification? .............................................................................. 6 
2  Target System Requirements ........................................................................................................ 6 
3  Document Outline ......................................................................................................................... 6 
Amazon FreeRTOS Qualification Test Project ....................................................................................... 7 
1  Download Amazon FreeRTOS Source Code .................................................................................. 7 
2  Set Up Your Amazon FreeRTOS Project ........................................................................................ 7 
2.1  Preparing Amazon FreeRTOS Folders ................................................................................... 7 
2.2  Create the Test Project ......................................................................................................... 9 
3  Port, Build and Test Libraries and Demos ................................................................................... 15 
3.1  Port Libraries, Build and Test Libraries ............................................................................... 15 
3.2  “Hello World” Demo and Getting Started Guide ................................................................ 16 
3.3  Configure your board name ................................................................................................ 17 
FAQs .................................................................................................................................................... 18 
Contact Us ........................................................................................................................................... 19 
Appendix ............................................................................................................................................. 20 
1  Appendix A: configPRINT_STRING() ............................................................................................ 21 
2  Appendix B: FreeRTOS kernel ..................................................................................................... 23 
3  Appendix C: Wi-Fi Management ................................................................................................. 25 
4  Appendix D: FreeRTOS TCP/IP Stack ........................................................................................... 28 
5  Appendix E: Secure Sockets ........................................................................................................ 31 
6  Appendix F: PKCS #11 ................................................................................................................. 35 
7  Appendix G: TLS .......................................................................................................................... 39 
8  Appendix H: MQTT ...................................................................................................................... 45 
9  Appendix I: OTA Updates ............................................................................................................ 47 
10  Appendix J: Bootloader ............................................................................................................... 51 
11  Appendix K: Bluetooth Low Energy (Beta) .................................................................................. 52 
12  Appendix L: Test List ................................................................................................................... 57 
13  Appendix M: TLS Server Setup .................................................................................................... 63 
14  Appendix N: “Hello World” Demo Project Set Up ...................................................................... 64 

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3           
 
Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.  5 
 
15  Appendix O: Checklist for Qualification ...................................................................................... 67 
16  Appendix P: Troubleshooting Porting Setup ............................................................................... 68 
17  Appendix Q: Instructions to Create a BYOC (ECDSA) .................................................................. 69 
18  Appendix R: Source for ca.config ................................................................................................ 71 
19  Appendix S: Modify issuer in a certificate................................................................................... 77 
20  Appendix T: Getting Started Guide Template ............................................................................. 81 
21  Appendix U: Hardware Information............................................................................................ 83 
22  Appendix V: Information for listing on the Amazon FreeRTOS Console ..................................... 85 
23  Appendix W: Glossary ................................................................................................................. 86 
 
  

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

1 Introduction

1.1 What is the Amazon FreeRTOS Qualification?

The Amazon FreeRTOS Qualification (AFQ) defines a process that the author of an Amazon FreeRTOS

port

1

must follow, and a set of tests that the port must pass, in order for the port to be described as

'qualified by Amazon'. Amazon only distributes and supports Amazon FreeRTOS ports that have passed

the qualification program. The purpose of the AFQ is to give developers confidence that qualified

Amazon FreeRTOS ports behave correctly and consistently with each other.

AWS provides a free test automation framework called AWS IoT Device Tester for Amazon FreeRTOS,

which developers can use to automate running of the qualification tests. See

https://aws.amazon.com/freertos/device-tester for more information on how to set it up.

1.2 Target System Requirements

It is recommended that Amazon FreeRTOS is only qualified on microcontrollers (MCUs) that have a

minimum processing speed of 25MHz, a minimum of 64K bytes of RAM, and a minimum of 128K bytes of

program memory per executable image stored on the MCU. For future qualification requirement with

Over-the-air update (OTA) functionality, two executable images must be stored in program memory at

the same time.

1.3 Document Outline

This document guides you through setting up your Amazon FreeRTOS project, porting Amazon FreeRTOS

libraries, building and testing your ports using the Amazon FreeRTOS Qualification tests. Appendixes

provide more detail information on each Amazon FreeRTOS library.

We also prepared a checklist for the process: Appendix O: Checklist for Qualification

1

An Amazon FreeRTOS port is a board-specific implementation of APIs for certain Amazon FreeRTOS libraries. The port enables these APIs to

work on the specific board, and implements the required integration with device drivers and BSPs provided by the platform vendor. It should

also include any configuration adjustments (e.g. clock rate, stack size, heap size etc.) required by the board.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

2 Amazon FreeRTOS Qualification Test Project

Follow the steps below.

2.1 Download Amazon FreeRTOS Source Code

You can download the Amazon FreeRTOS source code and test code from GitHub:

https://github.com/aws/amazon-freertos

Please download the latest release code from the “release” branch. You should import the repository to

your own private GitHub repository and configure to watch Amazon FreeRTOS public repository. You

will get notifications if there are new releases on our release branch.

If you are using Windows, you must keep the file path short (for example clone to C:\AFreeRTOS rather

than C:\Users\username\programs\projects\AmazonFreeRTOS\) to avoid a Windows limitation with

long file paths. The chosen folder will be referred as $AFR_HOME from here on in the document.

2.2 Set Up Your Amazon FreeRTOS Project

At the end of this step, you will have a working project that can write to a serial console.

2.2.1 Preparing Amazon FreeRTOS Folders

All qualified Amazon FreeRTOS ports use the same directory structure. New files, including IDE project

files, must be created in the correct folder locations.

The directory structure is explained below. Detailed instructions on how to create the same directory

structure are listed in the grey box.

Directory Structure:

The three root level folders under $AFR_HOME are:

$AFR_HOME

├───demos Contains projects that build demo applications

├───lib Contains Amazon FreeRTOS and third-party libraries

└───tests Contains projects that build qualification tests

Create your project in the tests folder, which is structured as follows:

$AFR_HOME

└───tests

├───common Contains files built by all test projects

├───pc Contains a reference test project for the FreeRTOS Windows port

└───vendor Template, to be renamed to the name of the MCU vendor

└───board Template, to be renamed to the name of the development board

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Instructions:

1. Rename the $AFR_HOME/tests/vendor folder to the name of the company that manufactures the

MCU – from here on the folder is referred to as [vendor].

2. Rename the $AFR_HOME/tests/board folder to the name of the development board being qualified

– from here on the folder is referred to as [board].

The $AFR_HOME/tests/[vendor]/[board] folder is a template provided to simplify the creation of a new

test project and ensures all test projects have a consistent organization. It has the following structure:

$AFR_HOME

└───tests

└───[vendor]

└───[board]

├───common

│ ├───application_code Contains main.c, which itself contains main()

│ │ └───vendor_code Contains vendor supplied board specific files

│ └───config_files Contains Amazon FreeRTOS config files

└───ide Contains an IDE specific project

Test projects always require vendor-supplied driver libraries. Some vendor-supplied libraries, such as a

header file that maps a GPIO output to an LED output, are specific to the target development board.

Other vendor-supplied libraries, such as the GPIO library itself, are specific to the target MCU family.

For Vendor-supplied driver libraries that are specific to the target development board:

Instructions (continued):

3. Save any required vendor-supplied libraries that are specific to the board in the

$AFR_HOME/tests/[vendor]/[board]/common/application_code/vendor_code folder.

4. Rename the $AFR_HOME/tests/[vendor]/[board]/ide folder to the name of the IDE that will be used

to build the test project – from here on the folder is referenced as [IDE].

Vendor-supplied driver libraries that are specific to the target MCU family belong in the

$AFR_HOME/lib/third_party/mcu_vendor folder, which has the following structure:

$AFR_HOME

└─lib

├──AmazonLib1 Contains an Amazon FreeRTOS library (example name only)

├──AmazonLib2 Contains an Amazon FreeRTOS library (example name only)

└──third_party Contains all non-board specific third-party libraries

├───Lib1 Contains a third-party library (example name only)

├───Lib2 Contains a third-party library (example name only)

└───mcu_vendor Contains vendor-supplied MCU specific libraries

└──vendor Template, to be renamed to the name of the MCU vendor

└─driver_library Template, to be renamed to the library name

└─driver_library_version Template, to be renamed to the library version

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Instructions (continued):

5. Rename the $AFR_HOME/lib/third_party/mcu_vendor/vendor folder to [vendor] (the name of the

company that manufactures the MCU).

6. Likewise, rename the contained driver_library folder to the name of the vendor’s MCU specific driver

library, and the contained driver_library_version folder to the version number of the vendor’s MCU

specific driver library.

7. Copy the vendor-supplied driver library into the newly renamed driver_library_version folder.

NOTE: DO NOT save vendor-supplied libraries that are specific to the MCU family anywhere within

either the $AFR_HOME/tests or $AFR_HOME/demos folders!

2.2.2 Create the Test Project

All qualified Amazon FreeRTOS test projects look the same when viewed from within an IDE. This section

describes and demonstrates the required project structure. By the end of this section you will have a

project with FreeRTOS Kernel libraries ready to run. The next section (2.32.3) will cover porting of other

Amazon FreeRTOS libraries into the project.

Instructions:

1. Read this section of the document, and then replicate the project it describes, but using the selected

IDE, and targeting the hardware being qualified. Take care to ensure the structure of the created

project matches that described below.

NOTE 1: All files in the project must be built in the file’s original position within the folder structure.

They are imported into the project by linking the files. Never directly copy files into the project’s folder

or use absolute file paths.

NOTE 2: If you are using an Eclipse based IDE, do not configure the project to build all the files in any

given folder. Instead, add source files into the project by linking to each source file individually.

The project is called aws_tests. Under aws_tests, there are three virtual folders. In this context, a virtual

folder is created in an IDE to better organize the source code. It may not correspond to a physical directory

on disk. The three virtual folders are application_code, config_files and lib, as described below:

aws_tests The project name

├───application_code Contains application logic, in this case it is AFQ test code

├───config_files Contains header files that configure Amazon FreeRTOS libraries

└───lib Contains Amazon and third-party libraries

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Error! Reference source not found. shows how the top three virtual folders appear in an IDE. The

depicted IDE is Eclipse, but the structure is the same in all IDEs.

Figure 1 The top three virtual folders viewed in an IDE’s project explorer view

Figure 2 shows the contents of the application_code virtual folder.

Figure 2 An IDE project with the application_code virtual folder expanded

NOTE:

 The main.c file, and the vendor_code folder, are

(physically on the disk) located in the

$AFR_HOME/tests/[vendor]/[board]/common/

application_code folder.

 common_test is a virtual folder – it does not

actually exist within the $AFR_HOME directory

structure. The folders under common_test are

located in the $AFR_HOME/tests/common

folder. The project builds the source files located

in those folders.

NOTE:

 The “Includes” folder is generated

automatically by Eclipse. It is not part

of the required structure

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Figure 3 shows the contents of the config_files virtual folder.

Figure 3 An IDE project with the config_files folder expanded

Figure 4 shows the contents of the lib virtual folder.

Figure 4 IDE project with the lib group expanded

NOTE:

 The files shown under config_files are located

in the

$AFR_HOME/tests/[vendor]/[board]/common

/config_files folder.

NOTE:

 aws and third_party are virtual folders.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Figure 5 shows the contents of the lib/aws folder, which contains AWS (as opposed to third party)

provided libraries. It only contains FreeRTOS kernel library at this stage. You will import more libraries

in this folder during later porting effort.

Figure 5 IDE project with the lib/AWS

group expanded

NOTE:

 The files and folders shown under lib/aws/FreeRTOS are

located in the $AFR_HOME/lib/FreeRTOS folder. The figure

shows lib/aws/FreeRTOS/portable/MSVC-MingW being

included in the project. That folder contains the FreeRTOS

kernel Windows port and should be substituted with

whichever folder contains the correct FreeRTOS port for

your target IDE and MCU, see below instruction.

 The file shown under

lib/aws/FreeRTOS/portable/MemMang is located in the

$AFR_HOME/lib/FreeRTOS/MemMang folder. It is

FreeRTOS memory management implementation.

 The files shown under lib/aws/include are located in the

$AFR_HOME/lib/include folder. Although not shown in

Figure , it includes all the header files and folders under

$AFR_HOME/lib/include.

 aws_system_init.c is located in the $AFR_HOME/lib/utils

folder.

Instructions (continued):

1. Replicate the folder structure (continued)

a. Import the FreeRTOS Kernel port for your compiler and architecture in place of

lib/aws/FreeRTOS/portable/MSVC_MingW in Figure 5.

$AFR_HOME/lib/FreeRTOS/portable contains the FreeRTOS kernel port files organized

first by compiler, and then by architecture.

b. Import one of the FreeRTOS Kernel memory management implementation to

lib/aws/FreeRTOS/portable/MemMang. For Amazon FreeRTOS, we use heap_4.c. For

more information, please visit FreeRTOS Memory Management

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Figure 6 shows the contents of the lib/third_party directory.

Figure 6 IDE project with the lib/third_party

group expanded

Instructions (continued, to be followed after creating the project):

2. Make sure the following compiler include paths are set in the project property.

a. $AFR_HOME/tests/common/include, which is

aws_tests/application_code/common_tests/include when viewed in the IDE project.

b. $AFR_HOME/lib/include, which is aws_tests/lib/aws/include when viewed in the IDE.

c. $AFR_HOME/lib/include/private, which is aws_tests/lib/aws/include/private when viewed in

the IDE.

d. $AFR_HOME/lib/FreeRTOS/portable/[compiler]/[architecture], which is

aws_tests/lib/aws/FreeRTOS/portable/[compiler]/[architecture] when viewed in the IDE.

e. $AFR_HOME/lib/third_party/unity/src, which is aws_tests/lib/third_party/unity when viewed

in the IDE.

f. $AFR_HOME/lib/third_party/unity/extras/fixture/src, which is

aws_tests/lib/third_party/unity_fixture when viewed in the IDE.

g. $AFR_HOME/demos/vendor/board/common/config_files, which is aws_tests/config_files

when viewed in the IDE.

h. Any paths necessitated by vendor-supplied driver libraries.

3. Define the following two project level macros in your IDE:

 UNITY_INCLUDE_CONFIG_H

 AMAZON_FREERTOS_ENABLE_UNIT_TESTS

NOTE:

 unity and unity_fixture are virtual folders.

 The files shown under unity are located in the

$AFR_HOME/lib/third_party/unity/src folder.

 The files shown under unity_fixture are located in the

$AFR_HOME/lib/third_party/unity/extras/fixture

folder.

 Although not shown in Figure , also add the MCU

specific vendor-supplied driver libraries that were

saved in the

$AFR_HOME/lib/third_party/[mcu_vendor]/[vendor]/

[driver_library]/[driver_library_version] folder (see

section Preparing Amazon FreeRTOS Folders).

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Figure 7 Preprocessor Macro Definitions Example (Visual Studio)

Visual Studio 2017 Example: Project Properties => Preprocessor => Preprocessor Definitions

4. Implement configPRINT_STRING() as described in Appendix A.

5. Make sure the new project builds successfully, that the resultant executable binary can be loaded to

the target hardware. If you run the project in debug mode, the pc should stop at the first line of

main().

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

2.3 Port, Build and Test Libraries and Demos

2.3.1 Port Libraries, Build and Test Libraries

With the folder structure and test projects prepared you are ready to start porting and testing the

Amazon FreeRTOS libraries. You must enable AFQ test group first.

$AFR_HOME/tests/[vendor]/[board]/common/config_files/aws_test_runner_config.h contains a

macro defined shown below. Uncomment the following line:

/*#define testrunnerAFQP_ENABLED */

Then bring an Amazon FreeRTOS library into your test project and port the library to your hardware.

The libraries are listed in below table. The detailed instruction on porting and testing procedures are

listed in the appendices – one appendix per library. The order of the appendices accounts for

interdependencies between libraries so should be followed in turn.

Library

Details in

Location

Notes

configPRINT_STRING Macro

Appendix A

Required for console output.

FreeRTOS Kernel

Appendix B

Required for the FreeRTOS kernel.

Wi-Fi Management

Appendix C

Required only if hardware supports network

connectivity over Wi-Fi.

FreeRTOS TCP/IP Stack

Appendix D

Required only if a board does not have its own

TCPIP stack support.

Secure Sockets

Appendix E

Required for AWS cloud connectivity.

PKCS#11

Appendix F

Required for over-the-air (OTA) and TLS

support.

TLS

Appendix G

Required for TLS support.

MQTT

Appendix H

Required for AWS cloud connectivity.

OTA Updates

Appendix I

Required for OTA updates.

Bootloader (demo)

Appendix J

Required for OTA updates.

Bluetooth Low Energy (Beta)

Appendix K

Required for Bluetooth Low Energy (BLE)

support

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

There are constants defined in

$AFR_HOME/tests/[vendor]/[board]/common/config_files/aws_test_runner_config.h file which can

be used as a switch to trigger a test set for a library. To enable a set of tests, set the constant to 1.

These constants listed in table below:

Defined constant to trigger a set of tests on a

library

Default value. (set to ‘1’

for enabling the test)

Required for AFQ

testrunnerFULL_CBOR_ENABLED

0

testrunnerFULL_OTA_AGENT_ENABLED

0

Y (if supports OTA)

testrunnerFULL_OTA_PAL_ENABLED

0

Y (if supports OTA)

testrunnerFULL_MQTT_ALPN_ENABLED

0

testrunnerFULL_MQTT_STRESS_TEST_ENABLED

0

testrunnerFULL_MQTT_AGENT_ENABLED

0

testrunnerFULL_TCP_ENABLED

0

Y

testrunnerFULL_GGD_ENABLED

0

testrunnerFULL_GGD_HELPER_ENABLED

0

testrunnerFULL_SHADOW_ENABLED

0

testrunnerFULL_MQTT_ENABLED

0

Y

testrunnerFULL_PKCS11_ENABLED

0

Y

testrunnerFULL_CRYPTO_ENABLED

0

testrunnerFULL_TLS_ENABLED

0

Y

testrunnerFULL_WIFI_ENABLED

0

Y

testrunnerFULL_BLE_ENABLED

0

Y (if supports BLE)

This is a vendor configurable file. If your board does not support a certain feature (i.e. OTA), you can

define the corresponding test sets to not supported, like the following:

#define testrunnerFULL_OTA_AGENT_ENABLED testrunnerUNSUPPORTED

NOTE: If you have setup AWS IoT Device Tester for Amazon FreeRTOS, to run the test project you do not

need to modify this file.

2.3.2 “Hello World” Demo and Getting Started Guide

Prepare the “Hello World” demo project in the code packaged delivered to Amazon. The project

creation process is similar to the test project creation. Please see Appendix N: “Hello World” Demo

Project Set Up for detailed instructions.

Prepare a “Getting Started Guide” for your board to help users run the Hello World Demo project (and

any other demos you may include). You can use the Getting Started Guide template to start and look at

the guide for the Window Simulator for reference.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

2.3.3 Configure your board name

Please put your board name in:

$AFR_HOME/demos/[vendor]/[board]/common/config_files/FreeRTOSConfig.h

#define mqttconfigMETRIC_PLATFORM "Platform=Unknown"

Replace “Unknown” with your own board name.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

3 FAQs

1. What is an Amazon FreeRTOS port?

An Amazon FreeRTOS port is a board-specific implementation of APIs for certain Amazon FreeRTOS

libraries. The port enables these APIs to work on the specific board, and implements the required

integration with device drivers and BSPs provided by the platform vendor. It should also include any

configuration adjustments (e.g. clock rate, stack size, heap size) required by the board.

2. Do I need to retest for minor version releases of Amazon FreeRTOS?

There is no need to retest for qualification with minor version releases of Amazon FreeRTOS.

3. What network ports will need to be opened to run AFQ tests?

The network connections needed in the AFQ tests include

Port

Protocol

443, 8883

MQTT

8443

Greengrass Discovery

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

4 Contact Us

If you have any questions, please post questions to AWS Amazon FreeRTOS forum (you must have an

AWS account): http://forums.aws.amazon.com.

You can also post questions in GitHub/issues board (you must have a GitHub account):

https://github.com/aws/amazon-freertos/issues.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5 Appendix

The Appendix contains detailed descriptions of Amazon FreeRTOS libraries and macros to be ported, as

well as steps to verify them.

Here is the recommended porting order:

Port configPRINT_STRING()

Port FreeRTOS Kernel

START

Is Wi-Fi support needed? Port Wi-Fi library

Is the TCP/IP stack

offloaded from the main

MCU?

Port Secure Sockets library

Port FreeRTOS+TCP

TCP/IP stack

Port PKCS#11 library

Port TLS library

END

YES

NO

NO YES

Amazon FreeRTOS

Qualification

Recommended Porting Order

Port OTA library and use

bootloader

Yes

Support OTA?

(Wi-Fi Support is

required)

No

Appendix A

Appendix B

Appendix C

Appendix D

Appendix E

Appendix F

Appendix G

Appendix I and J

Appendix I:

OTA Update

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.1 Appendix A: configPRINT_STRING()

Description

configPRINT_STRING() is a macro used by the AFQ test framework to output test results as human

readable ASCII strings. It must be implemented before AFQ porting and testing can begin.

These instructions assume test results are output over a UART serial port.

Pre-requisites

1. A development board that supports UART or virtual COM port output.

2. A test project that was created in accordance with the instructions provided in the body of this

document, and that is building vendor-supplied UART initialization and output functions.

3. The UART initialization and output must not have any dependency on FreeRTOS.

Setup

1. Connect a terminal emulator, such as TeraTerm, to the port on the target hardware that is to be

used to output test results.

Porting

1. Locate the call to configPRINT_STRING( “Test Message” ) within the function prvMiscInitialization(),

which is itself in the file

$AFR_HOME/tests/[vendor]/[board]/common/application_code/main.c.

2. Immediately before the call to configPRINT_STRING( “Test Message” ), add code that uses the

vendor-supplied UART driver to initialize the UART to 115200 baud

3. $AFR_HOME/tests/[vendor]/[board]/common/config_files/FreeRTOSConfig.h contains an

empty definition of configPRINT_STRING(). The macro takes a NULL terminated ASCII C string

as its only parameter. Update the empty definition of configPRINT_STRING() so that it calls the

vendor-supplied UART output function. For example, if the UART output function has the following

prototype:

then you would implement configPRINT_STRING() as:

Manual Testing

Build and execute the application. If “Test Message” appears in the UART console then the console is

connected and configured correctly, and configPRINT_STRING() is behaving as expected. If this is the

void MyUARTOutput( char *DataToOutput, size_t LengthToOutput );

#define configPRINT_STRING( X ) MyUARTOutput( (X), strlen( (X) ) )

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

case then configPRINT_STRING() testing is complete and the call to configPRINT_STRING( “Test

Message” ) can be removed from prvMiscInitialization().

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.2 Appendix B: FreeRTOS kernel

Description

Amazon FreeRTOS uses the FreeRTOS kernel for multitasking and inter-task communications. This

appendix describes how to integrate a port of the FreeRTOS kernel into the AFQ test project.

The FreeRTOS.org website contains a list of all the available kernel ports.

Porting the FreeRTOS kernel to a new architecture is out of scope of this document. Contact the

Amazon FreeRTOS Qualification team if a port does not exist for your architecture.

Pre-requisites

1. An official FreeRTOS kernel port for the target MCU architecture.

2. A test project that was created in accordance with the instructions provided in the body of this

document (Create the Test Project), and that includes the correct FreeRTOS kernel port files for the

MCU and compiler in use.

3. An implementation of configPRINT_STRING() that was created and tested as described in Appendix

A.

Porting

The header file $AFR_HOME/tests/[vendor]/[board]/common/config_files/FreeRTOSConfig.h

contains application specific FreeRTOS kernel configuration settings. The FreeRTOS.org website

provides a description of each configuration option. In particular, ensure the following constants are set

correctly for your hardware:

Configuration definitions

Comment

configCPU_CLOCK_HZ

The frequency of the clock used to generate the tick interrupt.

configMINIMAL_STACK_SIZE

As a starting point, this can be set to whichever value is used in the

official FreeRTOS demo for the FreeRTOS kernel port in use. Official

FreeRTOS demos are those distributed from the FreeRTOS.org web

site. Ensure stacks overflow checking is set to 2, and increase

configMINIMAL_STACK_SIZE if overflows occur. To save RAM, set

stack sizes to the minimum value that does not result in a stack

overflow.

configTOTAL_HEAP_SIZE

Sets the size of the FreeRTOS heap. Like task stack sizes, the heap

size can be tuned to ensure unused heap space does not consume

RAM.

ARM Cortex-M3, M4 and M7 devices must also have configPRIO_BITS and

configMAX_SYSCALL_INTERRUPT_PRIORITY set correctly.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

The MQTT (Appendix H) and Secure Sockets (Appendix E) libraries have not been ported yet, so

it is necessary to comment out the lines that call BUFFERPOOL_Init(), MQTT_AGENT_Init()

and SOCKETS_Init() from within function SYSTEM_Init(), which is implemented in

$AFR_HOME/lib/utils/aws_system_init.c.

Test Setup

No further setup is required for this section.

Test Execution

1. Build and execute the project.

2. If a “.” appears in the UART console every 5 seconds then the FreeRTOS kernel is operating as

expected and this test is complete. Set configUSE_IDLE_HOOK to 0 in

$AFR_HOME/tests/[vendor]/[board]/common/config_files/FreeRTOSConfig.h before moving

to the next section. Setting configUSE_IDLE_HOOK to 0 stops the FreeRTOS kernel from executing

vApplicationIdleHook(), and so stop the “.” Being output during future test executions.

3. If a “.” appears at any other frequency then check the setting of configCPU_CLOCK_HZ in

$AFR_HOME/tests/[vendor]/[board]/common/config_files/FreeRTOSConfig.h.

configCPU_CLOCK_HZ must be set to the correct value for your board.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.3 Appendix C: Wi-Fi Management

Description

The Wi-Fi Management library is the Amazon FreeRTOS interface to vendor-supplied Wi-Fi drivers. Skip

this section if your hardware does not support Wi-Fi.

Pre-requisites

1. A test project that was created in accordance with the instructions provided in the body of this

document, and that is building vendor-supplied Wi-Fi drivers.

2. An implementation of configPRINT_STRING() that was created and tested as described in Appendix A.

3. A validated FreeRTOS kernel configuration, as described in Appendix B: FreeRTOS kernel

4. Two wireless Access Points.

Preparing the IDE Project

1. Add the source file $AFR_HOME/lib/wifi/portable/[vendor]/[board]/aws_wifi.c into the

[project_top_level]/lib/aws/wifi virtual folder of the IDE project.

2. Add the source file $AFR_HOME/tests/common/wifi/aws_test_wifi.c into the

[project_top_level]/application_code/common_tests/wifi virtual folder of the IDE project.

3. Enable the Wi-Fi connection code in

$AFR_HOME/tests/[vendor]/[board]/common/application_code/main.c by deleting the #if 0

and #endif compiler directives in the functions vApplicationDaemonTaskStartupHook(void)

and prvWifiConnect(void).

Porting

1. $AFR_HOME/lib/wifi/portable/[vendor]/[board]/aws_wifi.c contains empty definitions of a

set of Wi-Fi management functions. Use the vendor-supplied Wi-Fi driver library to implement at

least the subset of functions listed in the table below. $AFR_HOME/lib/include/aws_wifi.h

provides the information necessary to complete the implementations.

Function

Description

WIFI_On

Turns on Wi-Fi module. Initializes the drivers

WIFI_ConnectAP

Connects to a Wi-Fi Access Point (AP)

WIFI_Disconnect

Disconnects from the currently connected AP

WIFI_Scan

Performs a Wi-Fi network scan

WIFI_GetIP

Retrieves the Wi-Fi interface’s IP address

WIFI_GetMAC

Retrieves the Wi-Fi interface’s MAC address

WIFI_GetHostIP

Retrieves the host IP address from a hostname using DNS

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Since the MQTT library is not used for running Wi-Fi tests, comment out the lines that call

BUFFERPOOL_Init(), MQTT_AGENT_Init()in function SYSTEM_Init()in file

$AFR_HOME/lib/utils/aws_system_init.c. Bufferpool and mqtt_agent are used in MQTT

library. If you have not ported the SOCKETS library (Appendix E), comment out the line that calls

SOCKETS_Init()in function SYSTEM_Init(), in file $AFR_HOME/lib/utils/aws_system_init.c.

Test Setup

If you use AWS IoT Device Tester for Amazon FreeRTOS to run tests you don’t need to perform the

following setup steps. See https://aws.amazon.com/freertos/device-tester for more information.

1. In $AFR_HOME/tests/common/include/aws_clientcredential.h, set the macros shown in table

below to be correct for the first Wi-Fi access point.

Macro name

Value

clientcredentialWIFI_SSID

The Wi-Fi SSID as a C string (in quotes)

clientcredentialWIFI_PASSWORD

The Wi-Fi password as a C string

clientcredentialWIFI_SECURITY

Either eWiFiSecurityOpen,

eWiFiSecurityWEP, eWiFiSecurityWPA, or

eWiFiSecurityWPA2. eWiFiSecurityWPA2 is

recommended.

2. In $AFR_HOME/tests/common/wifi/aws_test_wifi.c, set the macros shown in table below to be

correct for the second Wi-Fi access point.

Macro name

Value

testwifiWIFI_SSID

The Wi-Fi SSID as a C string (in quotes)

testwifiWIFI_PASSWORD

The Wi-Fi password as a C string

testwifiWIFI_SECURITY

Either eWiFiSecurityOpen,

eWiFiSecurityWEP, eWiFiSecurityWPA, or

eWiFiSecurityWPA2. eWiFiSecurityWPA2 is

recommended.

The Wi-Fi management tests listed in the bullet points below have a dependency on the

Secure Sockets library, which may not have been ported yet. If the Secure Sockets library

has not been ported then all the Wi-Fi management tests other than those listed in the bullets

below must pass. After the Secure Sockets library has been ported it is necessary to re-run the Wi-Fi

management tests to ensure all the tests (including those in the bullet points below) pass.

Additionally, the tests listed in the bullet points attempt to communicate with an echo server. See

the Appendix E: Secure Sockets section “Test Setup” for information on starting the echo server.

 WiFiConnectionLoop

 WiFiIsConnected

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

 WiFiConnectMultipleAP

 WiFiSeperateTasksConnectingAndDisconnectingAtOnce

3. Enable the Wi-Fi tests, by setting the testrunnerFULL_WIFI_ENABLED macro in

$AFR_HOME/tests/[vendor]/[board]/common/config_files/aws_test_runner_config.h to 1.

Test Execution

1. Build and execute the test project.

2. View the test results in the UART console. As noted in the ‘Test Setup’ section of this appendix, not

all the tests will pass until porting of the Secure Sockets library is complete. If all the tests that are

expected to pass are passing, then save the test results by cutting and pasting them from the UART

console into a text file, and move to the next section.

Example output:

…

Alternatively, you can use AWS IoT Device Tester for Amazon FreeRTOS to test your implementation of

WiFi.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.4 Appendix D: FreeRTOS TCP/IP Stack

Description

FreeRTOS+TCP is the TCP/IP stack used by Amazon FreeRTOS. See https://www.freertos.org/FreeRTOS-

Plus/FreeRTOS_Plus_TCP for more information. Skip this section if your target hardware offloads TCP/IP

functionality to a separate network processor or module.

This appendix only describes how to create a port to the target hardware’s Ethernet driver, and test as

far as ensuring the Ethernet driver can connect to the network. Actually sending and receiving data is

not tested until the Secure Sockets library port is complete.

Pre-requisites

1. A test project that was created in accordance with the instructions provided in the body of this

document, and that is building vendor-supplied Ethernet drivers.

2. An implementation of configPRINT_STRING() that was created and tested as described in Appendix

A.

3. A validated FreeRTOS kernel configuration, as described in Appendix B: FreeRTOS kernel.

Preparing the IDE Project

In all steps below, add source files to the IDE project from their existing location on the disk (by

reference) – do not create duplicate copies of source files on the disk:

1. Add the source files from the $AFR_HOME/lib/FreeRTOS-Plus-TCP/source directory to the

[project_top_level]/lib/FreeRTOS-Plus-TCP/source folder of the IDE project.

2. Add the header files from the $AFR_HOME/lib/FreeRTOS-Plus-TCP/include directory to the

[project_top_level]/lib/FreeRTOS-Plus-TCP/include folder of the IDE project.

3. Add the port source files from the $AFR_HOME/lib/FreeRTOS-Plus-

TCP/source/portable/NetworkInterface/[board_family]/ directory to the

[project_top_level]/lib/FreeRTOS-Plus-TCP/portable/NetworkInterface folder of the IDE

project.

4. Add the $AFR_HOME/lib/FreeRTOS-Plus-

TCP/source/portable/BufferManagement/BufferAllocation_2.c source file to the

[project_top_level]/lib/FreeRTOS-Plus-TCP/portable/BufferManagement folder of the IDE

project.

FreeRTOS has five example heap implementations under $AFR_HOME

/lib/FreeRTOS/portable/MemMang. Using FreeRTOS+TCP and BufferAllocation_2.c

requires the heap_4.c implementation.

5. Add the directory $AFR_HOME/lib/FreeRTOS-Plus-TCP/include to your compiler’s include path.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Porting

1. Check the $AFR_HOME/lib/FreeRTOS-Plus-TCP/source/portable/NetworkInterface/

directory to see if a port to your target hardware already exists.

2. If a port does not exist, then:

a. Rename the $AFR_HOME/lib/FreeRTOS-Plus-

TCP/source/portable/NetworkInterface/[board_family] directory to be

appropriate for the target hardware.

b. Follow the instruction on the FreeRTOS.org website for porting the TCP/IP stack to a

different microcontroller, and if necessary, a different compiler, to create a new port

that uses the vendor supplied Ethernet drivers. Implement the new port in a file called

NetworkInterface.c, and save the file in the newly renamed directory.

Note: The files in $AFR_HOME/lib/FreeRTOS-Plus-TCP/source/portable/BufferManagement

are used by multiple ports so must not be edited.

3. Update the FreeRTOS+TCP configuration file

$AFR_HOME/tests/[vendor/[board]/common/config_files/FreeRTOSIPConfig.h so it is correct

for your target hardware. The FreeRTOS.org website describes each configuration option.

Since the MQTT library is not used for running Wi-Fi tests, comment out the lines that call

BUFFERPOOL_Init(), MQTT_AGENT_Init()in function SYSTEM_Init()in file

$AFR_HOME/lib/utils/aws_system_init.c. Bufferpool and mqtt_agent are used in MQTT library. If

you have not ported the SOCKETS library (Appendix E), comment out the line that calls

SOCKETS_Init()in function SYSTEM_Init(), in file $AFR_HOME/lib/utils/aws_system_init.c.

Test Setup

1. In $AFR_HOME/tests/[vendor]/[board]/common/application_code/main.c, uncomment the

call to FreeRTOS_IPInit() in main(). By default, the IP address is acquired by DHCP. If DCHP fails

or you do not want to use DHCP, you must set a static IP address in

$AFR_HOME/tests/[vendors]/[board]/common/application_code/main.c. The following

variables must be set to valid values of your actual network:

Network configuration variables

Description

uint8_t ucMACAddress[6]

uint8_t ucIPAddress[4]

uint8_t ucNetMask[4]

uint8_t ucGatewayAddress[ 4 ]

uint8_t ucDNSServerAddress[ 4 ]

uint8_t ucMACAddress[6]

2. In $AFR_HOME/tests/[vendor]/[board]/common/config_files/FreeRTOSIPConfig.h set the

ipconfigUSE_NETWORK_EVENT_HOOK macro to 1.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

3. In $AFR_HOME/tests/[vendor]/[board]/common/application_code/main.c add the code below

at the start of vApplicationIPNetworkEventHook():

Test Execution

1. Build and execute the test project.

2. If “Network connection successful” appears in the UART console, then the Ethernet driver has

successfully connected to the network and this test is complete.

if (eNetworkEvent == eNetworkUp)

{

configPRINT("Network connection successful.\n\r");

}

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.5 Appendix E: Secure Sockets

Description

The Secure Sockets library API is based on the Berkeley sockets API. It provides the API functions

necessary to create and configure a TCP socket, connect to an MQTT broker, and send and receive TCP

data.

The library is called Secure Sockets as it also encapsulates TLS functionality. To create a TLS protected

socket the application writer need only creates a standard TCP socket, then uses a setsockopt call make

the socket use TLS.

If your target hardware does not offload TCP/IP functionality to a separate network chip then use the

FreeRTOS+TCP TCP/IP stack. A Secure Sockets implementation already exists for the FreeRTOS+TCP

TCP/IP stack used in conjunction with mbedTLS – so if you are using those libraries no porting is

necessary, but the Secure Sockets tests must still be executed and pass.

Pre-requisites

1. If you are using Wi-Fi for network connectivity: A port of the Wi-Fi management library as described

in Appendix C: Wi-Fi Management.

2. If you are using the FreeRTOS+TCP TCP/IP stack: A port of the FreeRTOS+TCP library as described in

Appendix D: FreeRTOS TCP/IP Stack.

Preparing the IDE Project

In all steps below, add source files to the IDE project from their existing location on the disk (by

reference) – do not create duplicate copies of source files on the disk:

1. If you use the FreeRTOS+TCP TCP/IP stack, add

$AFR_HOME/lib/secure_sockets/portable/freertos_plus_tcp/aws_secure_sockets.c to the

[project_top_level]/lib/aws/secure_sockets folder of the IDE project.

2. If you use your own port, add

$AFR_HOME/lib/secure_sockets/portable/[vendor]/[board]/aws_secure_sockets.c to the

[project_top_leve]/lib/aws/secure_sockets folder of the IDE project.

3. Add

$AFR_HOME/tests/common/secure_sockets/portable/[vendor]/[board]/aws_test_tcp_port

able.h and

$AFR_HOME/tests/common/secure_sockets/portable/[vendor]/[board]/aws_test_tcp.c to

the [project_top_level]/application_code/common_tests/secure_sockets folder of the IDE

project.

Porting

If you use the FreeRTOS+TCP TCP/IP stack then no porting is necessary.

If your target hardware offloads TCP/IP functionality to a separate network chip then it is necessary to

implement all the functions for which stubs already exist in

$AFR_HOME/lib/secure_sockets/portable/[vendor]/[board]/aws_secure_sockets.c.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

$AFR_HOME/lib/include/aws_secure_sockets.h contains the information necessary to create the

implementations.

Since the MQTT library is not used for running Wi-Fi tests, comment out the calls to

BUFFERPOOL_Init() and MQTT_AGENT_Init() from SYSTEM_Init(), which is located

in $AFR_HOME/lib/utils/aws_system_init.c. Make sure the call to SOCKETS_init() is

uncommented.

Test Setup

If you use AWS IoT Device Tester for Amazon FreeRTOS to run tests you don’t need to perform the

following setup steps. See https://aws.amazon.com/freertos/device-tester for more information.

1. The Secure Sockets tests require an echo server to be present on the network. For your

convenience, the AFQ tests distribution contains a suitable echo server, written in Go, in the

$AFR_HOME/tools/echo_server directory.

To start the echo server:

a) Ensure the latest version of Go is installed on the computer that will run the echo server (the

server host). Go can be installed from https://golang.org/dl/

b) Copy $AFR_HOME/tools/echo_server/echo_server.go onto the server host.

c) Start the server by typing: “go run echo_server.go”

d) In $AFR_HOME/tests/common/include/aws_test_tcp.h, set the parameters shown in the

table below to the IP address of the server host. The value 192.168.0.200 is an example only.

Echo Server IP address

Example value if address is 192.168.0.200

tcptestECHO_SERVER_ADDR0

192

tcptestECHO_SERVER_ADDR1

168

tcptestECHO_SERVER_ADDR2

0

tcptestECHO_SERVER_ADDR3

200

To test that the echo server is working, open a command prompt on a computer on the same

network and type “telnet 192.168.0.200 9001” from a Windows host, or “nc 192.168.0.200 9001”

from a Linux host. Again, use the correct IP address for the server host – 192.168.0.200 is used as an

example only.

It may be necessary to adjust the firewall settings on the server host to enable the MCU to connect.

2. Set the tcptestTCP_ECHO_CLIENT_PORT macro in

$AFR_HOME/tests/common/include/aws_test_tcp.h to the port on which the echo server is

listening. The provided echo server listens on port 9001. If you have problems connecting to port

9001 due to corporate network security policies, you can change the listening port in the echo

server code to a port that is not restricted by your company’s security policy.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

3. Set the tcptestSECURE_SERVER macro to 0 in

$AFR_HOME/tests/common/include/aws_test_tcp.h to run the socket tests without TLS.

4. Set the testrunnerFULL_TCP_ENABLED macro to 1 in

$AFR_HOME/tests/[vendor]/[board]/common/config_files/aws_test_runner.config.h to

enable the sockets tests.

5. Enable the testing task in

$AFR_HOME/tests/[vendor]/[board]/common/application_code/main.c by deleting the #if 0

and #endif compiler directives, in vApplicationIPNetworkEventHook ( void ). This change is

required for all the remaining libraries to be ported in this document.

Dependency on TLS

The test set for this library (Secure Sockets) includes some tests that require TLS which is

described later in this document. The functionality verified by these tests is exercised when

tcptestSECURE_SERVER macro is set to 1. You MUST come back to run this subset of the Secure Socket

tests after TLS library porting is completed. A TLS capable echo server should be setup before running

these tests ( Appendix M: TLS Server Setup).

Test Execution

1. Build and execute the test project.

2. View the test results in the UART console. If all the tests pass, then testing is complete. Save the

test results by cutting and pasting them from the UART console into a text file, and move to the next

section.

Example test results output:

…

Alternatively, you can use AWS IoT Device Tester for Amazon FreeRTOS to test your implementation of

Secure Sockets.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.6 Appendix F: PKCS #11

Description

Amazon FreeRTOS uses the open standard PKCS #11 “CryptoKi” API as the abstraction layer for

cryptographic operations, including:

 Encryption and decryption.

 Storage and enumeration of X.509 certificates.

 Storage and management of cryptographic keys.

See the open standard PKCS #11 Cryptographic Token Interface Base Specification:

http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html

Storing private keys in general purpose flash memory can be convenient in evaluation and rapid

prototyping scenarios. However, when it comes to production scenarios, we recommend the use of

dedicated cryptographic hardware in order to reduce the threats of data theft and device duplication.

Cryptographic hardware includes components with features that prevent cryptographic secret keys from

being exported. In order to use such hardware with Amazon FreeRTOS, the PKCS #11 API must be ported

to it.

Pre-requisites

1. A test project that was created in accordance with the instructions provided in the body of this

document, and that is building vendor-supplied storage drivers that are suitable for sensitive data.

2. An implementation of configPRINT_STRING() that was created and tested as described in Appendix A.

3. A validated FreeRTOS kernel configuration, as described in Appendix B: FreeRTOS kernel.

Preparing the IDE Project

In all steps below, add source files to the IDE project from their existing location on the disk (by

reference) – do not create duplicate copies of source files on the disk:

1. Add $AFR_HOME/lib/pkcs11/portable/[vendor]/[board]/aws_pkcs11_pal.c to the

[project_top_level]/lib/aws/pkcs11 folder of the test project.

2. Add the PKCS #11 library header files from $AFR_HOME/lib/third_party/pkcs11 to the

[project_top_level]/lib/third_party/pkcs11 folder of the test project.

3. Add the PKCS #11 tests from $AFR_HOME/tests/common/pkcs11/aws_test_pkcs11.c to the

[project_top_level]/application_code/common_tests/pkcs11 folder folder of the test

project.

4. Add the implementation of PKCS #11 for mbedTLS

$AFR_HOME/lib/pkcs11/mbedtls/aws_pkcs11_mbedtls.c to the

[project_top_level]/lib/pkcs11 folder of the test project

5. Import the CRYPTO abstraction wrapper file for mbedTLS $AFR_HOME/lib/crypto/aws_crypto.c

to the [project_top_level]/lib/crypto folder of the test project.

6. Add the mbedTLS library itself from $AFR_HOME/lib/third_party/mbedtls/library into the

[project_top_level]/lib/third_party/mbedtls/source folder of the test project.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

7. Add the mbedTLS library header file from $AFR_HOME/lib/third_party/mbedtls/include into

the [project_top_level]/lib/third_party/mbedtls/include folder of the test project.

8. Add both $AFR_HOME/lib/third_party/mbedtls/include and

$AFR_HOME/lib/third_party/pkcs11 to the compiler’s include path.

Porting

1. Porting the PKCS #11 API functions

The PKCS #11 API is dependent on the implementation of cryptographic primitives such as SHA256

hashing and ECDSA signing. The Amazon FreeRTOS implementation of PKCS #11 uses the

cryptographic primitives implemented in the mbedTLS library, for which a port is already provided.

Modifying the existing PKCS #11 port is required if you wish to use a different software

implementation of the cryptographic primitives (i.e., other than mbedTLS), or if your target

hardware offloads crypto to a separate module.

2. Porting the PKCS #11 Platform Abstraction Layer (PAL) for device specific certificate and key storage

If you decide to use the Amazon FreeRTOS implementation of PKCS #11, there is a relatively small

amount of customization required in order to read and write cryptographic objects to non-volatile

memory (NVM) (for example, onboard flash memory).

Cryptographic objects should be stored in a section of NVM that is not initialized/erased on device

reprogramming. Users of the PKCS #11 library should be able to provision devices with credentials,

and then reprogram the device with a new application which accesses these credentials via the PKCS

#11 interface.

PKCS #11 PAL ports must provide a location to store device client certificate, device client private

key, device client public key, trusted root CA, and a code verification public key (or certificate

containing the code verification public key) for secure bootloader and over-the-air updates.

$AFR_HOME/lib/pkcs11/portable/[vendor][board]/aws_pkcs11_pal.c contains stubs for the

PAL functions, of which you must provide ports for at least the functions listed in the table below:

Function

Description

PKCS11_PAL_SaveObject

Writes data to non-volatile storage

PKCS11_PAL_FindObject

Uses a PKCS #11 CKA_LABEL to search for a

corresponding PKCS #11 object in non-volatile storage,

and returns that object’s handle if it exists.

PKCS11_PAL_GetObjectValue

Retrieves the value of an object, given the handle.

PKCS11_PAL_GetObjectValueCleanup

Cleanup for the PKCS11_PAL_GetObjectValue call. May

be used to free memory allocated in

PKCS11_PAL_GetObjectValue call.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

3. Implement mbedtls_hardware_poll()

You only need to port this function if you plan to use Amazon FreeRTOS’ PKCS#11

implementation and the mbedTLS library for underlying cryptographic and TLS support.

TCP/IP and TLS require cryptographic pseudo-random number generation (PRNG) for sequence

number and key generation, respectively. A hardware entropy source is important for seeding the

PRNG. For the mbedTLS library to work, you MUST implement mbedtls_hardware_poll() which

allows the mbedTLS library to seed its PRNG using your board’s entropy source. This function is

located in $AFR_HOME/lib/pkcs11/portable/[vendor][board]/aws_pkcs11_pal.c

Note that if the port board does not contain a cryptographically accepted random number source, it

may be necessary to follow the entropy seeding approach described in the mbedTLS porting guide

below.

For more information see, https://docs.mbed.com/docs/mbed-os-

handbook/en/5.2/advanced/tls_porting.

Since the MQTT library is not used for running PKCS11 tests, comment out the lines that call

BUFFERPOOL_Init(), MQTT_AGENT_Init()in function SYSTEM_Init()in file

$AFR_HOME/lib/utils/aws_system_init.c. Bufferpool and mqtt_agent are used in MQTT library. If

you have not ported the SOCKETS library (Appendix E), comment out the line that calls

SOCKETS_Init()in function SYSTEM_Init(), in file $AFR_HOME/lib/utils/aws_system_init.c.

Test Setup

If you use AWS IoT Device Tester for Amazon FreeRTOS to run tests you don’t need to perform the

following setup steps. See https://aws.amazon.com/freertos/device-tester for more information.

1. Enable the PKCS 11 test by setting the testrunnerFULL_PKCS11_ENABLED macro to 1 in

$AFR_HOME/tests/[vendor]/[board]/common/config_files/aws_test_runner_config.h.

Test Execution

Build and execute the project. The UART output indicates how many tests have run and completed

successfully. Copy the results from the terminal and save it to a text file.

Example of the test results output:

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

…

Alternatively, you can use AWS IoT Device Tester for Amazon FreeRTOS to test your implementation of

PKCS#11.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.7 Appendix G: TLS

Description

The AWS IoT Core MQTT broker only accepts mutually authenticated TLS connections. Amazon

FreeRTOS can use either mbedTLS, in which case no porting is necessary, or an off-chip TLS

implementation, such as those found on some network co-processors. To allow both options the TLS

library is not accessed directly, but through a TLS abstraction layer.

In all cases, the TLS tests must be executed and pass. Preparing the tests requires IoT device

configuration in the AWS cloud and certificate and key provisioning on the target hardware.

Pre-requisites

1. A port of the Secure Sockets library, as described in Appendix E: Secure Sockets.

2. A port of the PKCS #11 library, as described in Appendix F: PKCS #11.

3. An AWS account.

Preparing the IDE Project

1. Add the TLS abstraction implementation $AFR_HOME/lib/tls/aws_tls.c or

$AFR_HOME/lib/tls/portable/[vendor]/[board]/aws_tls.c (if your target hardware offloads

TLS to a separate processor) to the [project_top_leve]/lib/aws/tls folder of the test project.

2. Add the TLS tests file $AFR_HOME/tests/common/tls/aws_test_tls.c to the

[project_top_level]/application_code/common_tests/tls folder of the test project.

3. Enable the tests by setting the testrunnerFULL_TLS_ENABLED macro to 1 in

$AFR_HOME/tests/[vendor]/[board]/common/config_files/aws_test_runner_config.h.

Porting

If your target hardware offloads TLS functionality to a separate network chip then it is necessary to

implement all the TLS abstraction layer functions in the table below.

$AFR_HOME/lib/include/aws_tls.h contains the information necessary to create the

implementations. Save the created file as

$AFR_HOME/lib/tls/portable/[vendor]/[board]/aws_tls.c

Function

Description

TLS_Init

Initialize the TLS context

TLS_Connect

Negotiate TLS and connect to the server

TLS_Recv

Read the requested number of bytes from the TLS connection

TLS_Send

Write the requested number of bytes to the TLS connection

TLS_Cleanup

Free resources consumed by the TLS context

Since the MQTT library is not used for running Wi-Fi tests, comment out the calls to

BUFFERPOOL_Init() and MQTT_AGENT_Init() from SYSTEM_Init(), which is located

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

in $AFR_HOME/lib/utils/aws_system_init.c. Make sure the call to SOCKETS_init() is

uncommented.

Test Setup

If you use AWS IoT Device Tester for Amazon FreeRTOS to run tests you don’t need to perform the

following setup steps. See https://aws.amazon.com/freertos/device-tester for more information.

The tests in this section require use of the online AWS console, where your target hardware will be

represented as a ‘thing’, and communicate with AWS via a custom MQTT endpoint that is tied to your

AWS account.

The steps below create the certificates and keys necessary to complete qualification tests.

The tests require the created certificates and keys to be built into the target hardware’s

executable image. That is convenient in this test scenario, but is not recommended for

production scenarios, where the keys should be kept in hardened storage.

Certificate Formatting Tool: It is necessary to convert the certificates and keys to C strings before

building them into the executable image. The AFQ tests include a tool for that purpose. To convert

certificate and key pairs into C strings:

a. Open $AFR_HOME/tools/certificate_configuration/PEMfileToCString.html in a web

browser.

b. Follow the instructions on the opened web page to load the certificate and private key.

c. Once loaded, follow the instruction in the opened web page to convert the opened certificate

and private key to a formatted C string.

1. Set the clientcredentialMQTT_BROKER_ENDPOINT[] variable in

$AFR_HOME/tests/common/include/aws_clientcredential.h to the custom end point of your

AWS account – this is the URL the TLS tests connect to.

To find your custom end point, use the URL https://aws.amazon.com/iot/ to log into your AWS

account, then click the “Settings” link in the bottom left corner of the screen to open the settings

window – the customer end point is displayed at the top of the settings window.

2. Noting the information below about the information you need to record during the process, follow

the steps in the AWS IoT Getting Started tutorial to create the resources in AWS IoT that will

represent your target hardware (Thing, Certificate and Policies).

a. Start here: https://docs.aws.amazon.com/iot/latest/developerguide/iot-console-

signin.html, and continue through each of the steps of the tutorial until you complete

“Attach your Certificate to a Thing”. See notes below for additional guidance about these

steps.

b. During this process,

 Set the clientcredentialIOT_THING_NAME variable in

$AFR_HOME/tests/common/include/aws_clientcredential.h to the name you

assigned your ‘thing’ (the thing name).

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

 The steps on the link above include the creation of a certificate. Download and save all

three files that are generated during that process.

 The steps on the link above include creating a policy. Use the following policy to attach

to the certificate:

This policy will allow all IoT actions on all resources. That is convenient in a test

and evaluation scenario but is not recommended for production scenarios.

3. Prepare certificate/key pairs for various tests for the TLS library.

AWS IoT can use AWS IoT-generated certificates or certificates signed by a CA certificate for device

authentication. In order to run the various tests, you will need to create multiple credentials as

listed below:

a. Generate a certificate by AWS IoT. (RSA Certificate)

b. Generate a certificate from a CSR (Certificate Signing Request). (ECDSA cert, Malformed

cert)

c. Generate a certificate from a registered CA. (Untrusted, BYOC certificate)

The credentials for the types listed above are described in detail in following table. All of the testing

client certificates and private keys listed above must be stored in:

$AFR_HOME/tests/common/aws_clientcredential_keys.h

$AFR_HOME/tests/common/aws_test_tls.h

Cert/Key Variables

Description

keyCLIENT_CERTIFICATE_PEM

Device certificate used for AWS cloud communication. It

is also used in TLS_ConnectRSA() test. You can set this up

using AWS Console.

keyCLIENT_PRIVATE_KEY_PEM

Device private key used for AWS cloud communication. It

is also used in TLS_ConnectRSA() test. You can set this up

using AWS Console.

tlstestCLIENT_CERTIFICATE_PEM_EC

Certificate for P-256 elliptic curve key. It is used in

TLS_ConnectEC() test.

{

"Effect": "Allow",

"Action": "iot:*",

"Resource": "*"

}

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

tlstestCLIENT_PRIVATE_KEY_PEM_EC

A p-256 elliptic curve key. It is used in TLS_ConnectEC()

test.

tlstestCLIENT_CERTIFICATE_PEM_MALFORMED

A RSA or ECDSA certificate that has a field modified.

Used in TLS_ConnectMalformedCert() test.

tlstestCLIENT_UNTRUSTED_CERTIFICATE_PEM

A certificate is not trusted (not registered) by AWS IoT.

Used in TLS_ConnectUntrustedCert().

tlstestCLIENT_UNTRUSTED_PRIVATE_KEY_PEM

The private key correspond to the untrusted certificate.

tlstestCLIENT_BYOC_CERTIFICATE_PEM

A certificate created by a CA (registered to AWS IoT).

Used in TLS_ConnectBYOCCredentials().

tlstestCLIENT_BYOC_PRIVATE_KEY_PEM

The private key corresponding to the BYOC certificate.

Setup for RSA certificate/private key used in TLS_ConnectRSA() :

This pair of certificate/key is generated in Test Setup Step 2. The three files you downloaded

during that “Thing” creation process will be used here.

Format the certificate and the private key with the formatting tool and copy them to macros

keyCLIENT_CERTIFICATE_PEM

keyCLIENT_PRIVATE_KEY_PEM

in file $AFR_HOME/tests/common/aws_clientcredential_keys.h.

Setup for ECDSA certificate/private key used in TLS_ConnectEC():

OpenSSL is an open source toolkit for TLS protocol. (https://www.openssl.org/). We

will use openssl in examples of generating certificates below. Please use TLS V1.2.

You can download it here: https://www.openssl.org/source/

1) Create a CSR with openssl:

a) openssl ecparam -name prime256v1 -genkey -noout -out p256_privatekey.pem

b) openssl req –new –key p256_privatekey.pem –out csr.csr

2) Create a certificate with the AWS IoT console:

a) On the AWS IoT / Security / Certificate page, click “Create” in upper right-hand corner

b) Click “Create with CSR” and upload the .csr file created in step 1.

c) Download the cert .pem file, activate it and attach the same policy you used when

setting up the RSA certificate.

d) Attach the certificate to the IoT thing created when you set up the “Thing”.

3) Format the certificate and the private key using the formatting tool.

4) Copy the created cert and private key to the following variables in

$AFR_HOME/tests/common/aws_test_tls.h:

a) tlstestCLIENT_CERTIFICATE_PEM_EC

b) tlstestCLIENT_PRIVATE_KEY_PEM_EC

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5) In $AFR_HOME/tests/common/tls/aws_test_tls.c, set the

tlstestMQTT_BROKER_ENDPOINT_EC variable to the same AWS IoT message broker

endpoint address in TLS Test Setup Step 1.

Setup for Malformed certificate used in TLS_ConnectMalformedCert():

The purpose of the test is to be able to use a malformed certificate to authenticate with the

server. Random modification of a certificate will most likely be rejected by x509 certificate

verification before the connection request is sent out. We have a suggestion to setup this

malformed certificate: modifying the issuer of the certificate.

See Appendix S: Modify issuer in a certificate for process details.

Setup for BYOC (Bring You Own Certificate) certificate used in TLS_ConnectBYOCCredentials():

1) Create your own certificate with a valid rootCA/CA chain. See example in Appendix Q:

Instructions to Create a BYOC (ECDSA).

2) Register CAs and your own certificate in the AWS IoT console: IoT Core / Secure /

Certificates / Create / Get started.

3) Format the certificate and the private key using the formatting tool.

4) Copy the certificate and private key strings to the following variables in

$AFR_HOME/tests/common/aws_test_tls.h:

a) tlstestCLIENT_BYOC_CERTIFICATE_PEM

b) tlstestCLIENT_BYOC_PRIVATE_KEY_PEM

Setup for Untrusted certificate used in TLS_ConnectUntrustedCert():

1) Create your own certificate with valid rootCA/CA chain. See example in Appendix Q:

Instructions to Create a BYOC (ECDSA).

2) Do not register them in AWS IoT console.

3) Format the certificate and the private key using the formatting tool.

4) Copy the cert and private key strings to the following variables in

$AFR_HOME/tests/common/aws_test_tls.h:

a) tlstestCLIENT_UNTRUSTED_CERTIFICATE_PEM

b) tlstestCLIENT_UNTRUSTED_PRIVATE_KEY_PEM

Test Execution

1. Build and execute the test project.

2. View the test results in the UART console. If all the tests pass, then testing is complete. Save the

test results by cutting and pasting them from the UART console into a text file, and move to the next

section.

Example of the test results output:

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Once TLS porting and verification is completed, note that you must go back to run a subset of

the Secure Socket tests which depend on this functionality i.e. when tcptestSECURE_SERVER

macro is set to 1. See Dependency on TLS in the Secure Sockets porting section.

Alternatively, you can use AWS IoT Device Tester for Amazon FreeRTOS to test your implementation of

TLS.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.8 Appendix H: MQTT

Description

Communication between IoT devices and AWS IoT Core (the MQTT broker) uses the MQTT protocol.

The MQTT library that implements the protocol does not need to be ported, but does need to pass all

the MQTT tests.

The MQTT library has a dependency on the Buffer Pool library, which is used to allocate the memory

necessary to hold MQTT packets.

Pre-requisites

1. A port of the Secure Sockets library, as described in Appendix E: Secure Sockets.

2. A port of the PKCS #11 library, as described in Appendix F: PKCS #11.

3. A port of the TLS library, as described in Appendix G: TLS.

4. An AWS account.

5. An IoT thing created in AWS cloud and its associated credential information. (Refer to

TLS_Test_Setup_Step_1, TLS_Test_Setup_Step_2 and RSA_Certificate_Setup)

Preparing the IDE Project

In all steps below, add source files to the IDE project from their existing location on the disk (by

reference) – do not create duplicate copies of source files on the disk:

1. Add the MQTT library source files from $AFR_HOME/lib/mqtt into the

[project_top_level]/lib/aws/mqtt folder of the test project.

2. Add the Bufferpool source files from $AFR_HOME/lib/bufferpool into the

[project_top_level]/lib/bufferpool folder of the test project.

3. Add the MQTT test source files from $AFR_HOME/tests/common/mqtt/ to

[project_top_level]/application_code/common_tests/mqtt folder of the test project.

4. Uncomment all the initialization functions called from SYSTEM_Init() within

$AFR_HOME/lib/utils/aws_system_init.c.

Porting

In order to enable MQTT functionality, uncomment the calls to BUFFERPOOL_Init() and

MQTT_AGENT_Init() from SYSTEM_Init(), which is located in

$AFR_HOME/lib/utils/aws_system_init.c. Make sure the call to SOCKETS_init() is also still

uncommented.

There is no additional porting required for this library.

Test Setup

If you use AWS IoT Device Tester for Amazon FreeRTOS to run tests you don’t need to perform the

following setup steps. See https://aws.amazon.com/freertos/device-tester for more information.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

These tests require the certificates and keys that were created prior to testing the TLS library.

1. Enable the MQTT tests by setting testrunnerFULL_MQTT_ENABLED to 1 in

$AFR_HOME/tests/[vendor]/[board]/common/config_files/aws_test_runner_config.h

Test Execution

1. Build and execute the test project.

2. View the test results in the UART console. If all the tests pass, then testing is complete. Save the

test results by cutting and pasting them from the UART console into a text file.

Example of the test results output:

Alternatively, you can use AWS IoT Device Tester for Amazon FreeRTOS to test MQTT.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.9 Appendix I: OTA Updates

Description

The Amazon FreeRTOS over-the-air (OTA) update feature enables you to:

 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 re-provisioned.

 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 the AWS Signer service.

Amazon FreeRTOS devices must enforce cryptographic code-sign verification of the OTA firmware

images they receive. Regarding algorithm selection, we recommend the use of the Elliptic-Curve Digital

Signature Algorithm (ECDSA), the NIST P256 curve, and a SHA-256 hash

Pre-requisites

1. A Bootloader that can support OTA update as described in Appendix J: Bootloader.

2. A port of the PKCS #11 library, as described in Appendix F: PKCS #11.

3. A port of the TLS library, as described in Appendix G: TLS.

Preparing the IDE Project

1. Add the OTA library files from $AFR_HOME/lib/ota into the IDE project under the

[project_top_level]/lib/aws/ota virtual folder.

2. Import the OTA library PAL files,

$AFR_HOME/lib/ota/portable/[vendor]/[board]/aws_ota_pal.c into the IDE project under the

[project_top_level]/lib/aws/ota virtual folder.

3. Import the OTA tests,

o $AFR_HOME/tests/common/ota/aws_test_cbor.c

o $AFR_HOME/tests/common/ota/aws_test_ota_agent.c

o $AFR_HOME/tests/common/aws_test_pal.c

into the IDE project under the [project_top_level]/application_code/common_tests/ota

virtual folder.

4. Add the OTA Update demo from $AFR_HOME/demos/common/ota/aws_ota_update_demo.c into

the IDE project under the [project_top_level]/application_code/common_tests/ota virtual

folder.

Porting

Amazon FreeRTOS defines an OTA platform abstraction layer (PAL) in order to ensure that the OTA

library can be used on a wide variety of hardware. The OTA PAL interface is listed below.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Function

Description

prvAbort

Aborts an OTA update.

prvCreateFileForRx

Creates a new file to store the data chunks as they are received.

prvCloseFile

Closes the specified file. This may authenticate the file if storage that

implements cryptographic protection is being used.

prvWriteBlock

Writes a block of data to the specified file at the given offset. Returns

the number of bytes written on success or negative error code.

prvActivateNewImage

Activates or launches the new firmware image. For some ports, if the

device is programmatically reset synchronously, this function may not

return.

prvSetImageState

Does what is required by the platform to accept or reject the most

recent OTA firmware image (or bundle). Refer to your respective

board (platform) details and architecture to determine how to

implement this function.

prvGetImageState

Gets the state of the OTA update image.

The following two functions are optional if a device has built-in support for them. If not then they need

to be implemented in the PAL.

Function

Description

prvCheckFileSignature

Verifies the signature of the specified file.

prvReadAndAssumeCertificate

Reads the specified signer certificate from the file system and

returns it to the caller.

Test Setup

If you use AWS IoT Device Tester for Amazon FreeRTOS to run tests you don’t need to perform the

following setup steps. See https://aws.amazon.com/freertos/device-tester for more information.

The OTA AFQ tests are split into the following two categories: Agent and PAL module tests, and end-to-

end functional tests.

1. Agent/PAL tests

a. Enable the OTA Agent/PAL tests by setting the following macros to 1 in

$AFR_HOME/tests/[vendor]/[board]/common/config_files/aws_test_runner_config.h:

 testrunnerFULL_OTA_AGENT_ENABLED

 testrunnerFULL_OTA_PAL_ENABLED

b. Select a signing certificate that is appropriate for your device from

$AFR_HOME/tests/common/ota/test_files.

Each board has its specific way to provision a device. The certificate will be used for verification

in OTA tests.

Three types of signing certificates are available in the test code. These include RSA/SHA1,

RSA/SHA256 and ECDSA/SHA256. Out of the three, the use of ECDSA/SHA256 is recommended

for OTA updates. The other two are available for existing platforms only. If you have a different

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

scheme that is not included in the aforementioned three schemes, then please contact your

Qual-Rep.

2. End-to-end OTA tests

These tests will be conducted by manually running python scripts located in

$AFR_HOME/tools/ota_e2e_test/

a. Enable the OTA end-to-end tests by setting the following macros to 1 in

$AFR_HOME/tests/[vendor]/[board]/common/config_files/aws_test_runner_config.h:

 testrunner_OTA_END_TO_END_ENABLED

b. Follow the instructions in $AFR_HOME/tools/ota_e2e_test/README.md

Test Execution

1. Agent/PAL tests

a. Build and execute the test project.

b. View the test results in the UART console. If all the tests pass, then testing is complete. Save

the test results by cutting and pasting them from the UART console into a text file.

Example of the test results output:

…

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

2. End-to-end OTA Tests

a. Make sure there are no changes to aws_demo_runner.c, aws_clientcredential.h,

aws_clientcredential_keys.h, aws_application_version.h, and

aws_ota_codesigner_certificate.h from what was used to run the agent/PAL tests.

b. Follow the example listed in $AFR_HOME/tools/ota_e2e_test/README.md to run the ota end-

to-end test script.

Alternatively, you can use AWS IoT Device Tester for Amazon FreeRTOS to test OTA.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.10 Appendix J: Bootloader

Amazon FreeRTOS provides a demo bootloader as an example for the Microchip Curiosity PIC32MZEF

platform. It may be ported to other platforms where applicable. However there is the option for users to

provide their own bootloader. In order for such a bootloader to work with the OTA functionality, the

following requirements must be adhered to:

1. The bootloader shall be stored in non-volatile memory so it cannot be overwritten.

2. The bootloader shall verify the cryptographic signature of the downloaded application image.

Signature verification must be consistent with the OTA image signer. See Appendix I: OTA

Updates for supported signatures.

3. The bootloader shall not allow rolling back to a previously installed application image.

4. The bootloader shall maintain at least one image that can be booted.

5. If the MCU contains more than one image then the image that is executed shall be the latest

(newest). The newest version can be determined based on implementation, for example a user

defined sequence number, application version etc. As per other requirements, this can only be

the case until a newer version has been verified and proven functional.

6. If the MCU cannot verify any images then it shall place itself into a controlled benign state. In

this state it prevents itself from being taken over by ensuring no actions are performed.

7. These requirements shall not be breached even in the presence of an accidental or malicious

write to any MCU memory location (key store, program memory, RAM, etc.)

8. The bootloader shall support self-test of a new OTA image. If test execution fails, the bootloader

shall roll back to the previous valid image. If test execution succeeds, the image shall be marked

valid and the previous version erased.

The state of the application must be set by the OTA PAL as described in the user documentation at

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

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.11 Appendix K: Bluetooth Low Energy (Beta)

Description

The Amazon FreeRTOS Bluetooth Low Energy (BLE) feature allows you to do WIFI provisioning and

MQTT over BLE. It also provides users with higher level API that streamline the use of the BLE stack.

The AFR Bluetooth Library is layered as show below:

The AFQ tests target the wrapper layer, just above the Bluetooth Low Energy stack provided by the

OEMs. Passing the AFQ tests should ensure the connectivity over BLE is working properly. As for how to

use the Amazon FreeRTOS BLE library in your application, see more information here:

https://docs.aws.amazon.com/freertos/latest/userguide/freertos-ble-library.html

This library is in beta. Please download the code from GitHub branch https://github.com/aws/amazon-

freertos/tree/feature/ble-beta.

Pre-requisites

1. A test project that was created in accordance with the instructions provided in the body of this

document, and that is building vendor-supplied BLE drivers.

2. An implementation of configPRINT_STRING() that was created and tested as described in Appendix A.

3. A validated FreeRTOS kernel configuration, as described in Appendix B: FreeRTOS kernel.

4. A Raspberry PI 3b+ device.

OEM BLE stack

Low level wrappers for HAL

BLE APIs

Middle ware

Services

User APP

AFQ tests

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Preparing the IDE Project

1. Add all files in $AFR_HOME/lib/bluetooth_low_energy/portable/[vendor]/[board]/

directory to the [project_top_level]/lib/aws/bluetooth_low_energy virtual folder of the

test IDE project.

2. Add the $AFR_HOME/lib/include/bluetooth_low_energy directory to the

[project_top_level]/lib/aws/include folder of the test IDE project.

3. Add the file $AFR_HOME/tests/common/ble/aws_test_ble.c to the

[project_top_level]/application_code/common_tests/ble virtual folder of the IDE

project.

4. Enable the necessary BLE drivers in the

$AFR_HOME/tests/[vendor]/[board]/common/application_code/main.c driver

initializations of the relevant projects in the test project

Porting

The API for BLE feature are defined in three files at $AFR_HOME/lib/include/bluetooth_low_energy

directory.

 bt_hal_manager.h

 bt_hal_manager_adapter_ble.h

 bt_hal_gatt_server.h

See the comments in the files for description of APIs. The API that MUST be implemented are listed

below.

GAP Common (bt_hal_manager.h)

pxBtManagerInit

pxEnable

pxDisable

pxGetDeviceProperty

pxSetDeviceProperty (All options

mandatory except

eBTpropertyRemoteRssi,

eBTpropertyRemoteVersionInfo)

pxPair

Y(All options mandatory expect

eBTpropertyRemoteRssi,

eBTpropertyRemoteVersionInfo)

pxRemoveBond

pxGetConnectionState

pxPinReply

pxSspReply

pxGetTxpower

pxGetLeAdapter

pxDeviceStateChangedCb

pxAdapterPropertiesCb

pxSspRequestCb

pxPairingStateChangedCb

pxTxPowerCb

GAP BLE (bt_hal_manager_adapter_ble.h)

pxRegisterBleApp

pxUnregisterBleApp

pxBleAdapterInit

pxStartAdv

pxStopAdv

pxSetAdvData

pxConnParameterUpdateRequest

pxRegisterBleAdapterCb

pxAdvStartCb

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

pxSetAdvDataCb

pxConnParameterUpdateRequestCb

pxCongestionCb

GATT Server (bt_hal_gatt_server.h)

pxRegisterServer

pxUnregisterServer

pxGattServerInit

pxAddService

pxAddIncludedService

pxAddCharacteristic

pxSetVal

pxAddDescriptor

pxStartService

pxStopService

pxDeleteService

pxSendIndication

pxSendResponse

pxMtuChangedCb

pxCongestionCb

pxIndicationSentCb

pxRequestExecWriteCb

pxRequestWriteCb

pxRequestReadCb

pxServiceDeletedCb

pxServiceStoppedCb

pxServiceStartedCb

pxDescriptorAddedCb

pxSetValCallbackCb

pxCharacteristicAddedCb

pxIncludedServiceAddedCb

pxServiceAddedCb

pxConnectionCb

pxUnregisterServerCb

pxRegisterServerCb

Test Setup

The setup for BLE AFQ tests requires a Raspberry PI 3b+ as an external device to run the BLE tests.

The test computer sends test python file to the Raspberry and execute them remotely through ssh. Test

results are returned through the ssh client.

At the same time, the test computer runs the tests on the DUT. Tests results are returned thought UART.

On the Raspberry PI:

Computer

SSH

Raspberry PI DUT

UART

BLE

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

1. Make sure to order a Raspberry PI 3b+. Previous versions of devices don’t have Bluetooth

support. You also need to order a memory card with it as Raspberry PI are not provided with a

hard drive.

2. Raspberry PI 3b+: https://www.raspberrypi.org/products/raspberry-pi-3-model-b-plus/

3. Follow the step here to setup the Raspberry PI with Raspbian OS:

https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up

4. Download bluez 5.50: https://git.kernel.org/pub/scm/bluetooth/bluez.git

5. Follow the README at the root to install on the Raspberry PI.

6. Enable SSH on the PI: https://www.raspberrypi.org/documentation/remote-access/ssh/

On the test computer:

1. Temporarily (do not push the change) modify the script in

$AFR_HOME/tests/common/framework/bleTestsScripts/runPI.sh with the IP address of

your Raspberry PI:

Test Execution

Launch the script runPI.sh and launch the test project. The tests must pass in the PI and on the DUT:

Example of tests results:

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.12 Appendix L: Test List

The tests listed here are the current tests we provide. It is subject to change.

Library

Tests

Notes

Wi-Fi

WiFiOnOff

WiFiMode

WiFiConnectionLoop

WiFiIsConnected

WiFiNetworkAddGetDelete

WiFiPowerManagementMode

WiFiGetIP

WiFiGetMAC

WiFiGetHostIP

WiFiScan

WiFiReset

WiFiPing

WiFiConnectMultipleAP

WiFiSeperateTasksConnectingAndDisconnectingAtOnce

WiFiOnOffLoop

WIFI_GetMode_NullParameters

WIFI_GetIP_NullParameters

WIFI_GetMAC_NullParameters

WIFI_GetHostIP_NullParameters

WIFI_Scan_NullParameters

WIFI_NetworkAdd_NullParameters

WIFI_NetworkGet_NullParameters

WIFI_SetPMMode_NullParameters

WIFI_GetPMMode_NullParameters

WIFI_Ping_NullParameters

WIFI_ConnectAP_NullParameters

WIFI_SetMode_InvalidMode

WIFI_GetHostIP_InvalidDomainName

WIFI_GetHostIP_DomainNameLengthExceeded

WIFI_NetworkDelete_DeleteNonExistingNetwork

WIFI_NetworkGetNonExistingNetwork

WIFI_SetPMMode_InvalidPMMode

WIFI_Ping_ZeroParameters

WIFI_ConnectAP_InvalidSSID

WIFI_ConnectAP_InvalidPassword

WIFI_ConnectAP_InvalidSecurityTypes

WIFI_ConnectAP_MaxSSIDLengthExceeded

WIFI_ConnectAP_MaxPasswordLengthExceeded

WIFI_ConnectAP_ZeroLengthSSID

WIFI_ConnectAP_ZeroLengthPassword

WIFI_ConnectAP_PasswordLengthLess

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Library

Tests

Notes

WIFI_Scan_ZeroScanNumber

WIFI_NetworkGet_GetManyNetworks

WIFI_NetworkAdd_AddManyNetworks

WIFI_NetworkDelete_DeleteManyNetworks

WIFI_ConnectAP_ConnectAllChannels

Secure

Sockets

SOCKETS_Threadsafe_SameSocketDifferentTasks

SOCKETS_Threadsafe_DifferentSocketsDifferentTasks

SOCKETS_Connect_InvalidAddressLength

SOCKETS_Connect_InvalidParams

SOCKETS_Socket_TCP

SOCKETS_SetSockOpt_RCVTIMEO

SOCKETS_SetSockOpt_InvalidParams

SOCKETS_Shutdown

SOCKETS_ShutdownInvalidParams

SOCKETS_ShutdownWithoutReceiving

SOCKETS_Close

SOCKETS_CloseInvalidParams

SOCKETS_CloseWithoutReceiving

SOCKETS_Recv_ByteByByte

SOCKETS_Recv_On_Unconnected_socket

SOCKETS_SendRecv_VaryLength

SOCKETS_Socket_InvalidTooManySockets

SOCKETS_Socket_InvalidInputParams

SOCKETS_Send_Invalid

SOCKETS_Recv_Invalid

SOCKETS_htos_HappyCase

SOCKETS_inet_addr_quick_HappyCase

SOCKETS_NonBlocking_Test

SECURE_SOCKETS_Threadsafe_DifferentSocketsDifferentTasks

SECURE_SOCKETS_Threadsafe_SameSocketDifferentTasks

SECURE_SOCKETS_Connect_InvalidAddressLength

SECURE_SOCKETS_Connect_InvalidParams

SECURE_SOCKETS_NonBlockingConnect

SECURE_SOCKETS_NonBlocking_Test

SECURE_SOCKETS_SetSockOpt_SERVER_NAME_INDICATION

SECURE_SOCKETS_SetSockOpt_TRUSTED_SERVER_CERTIFICATE

SECURE_SOCKETS_SetSockOpt_RCVTIMEO

SECURE_SOCKETS_SetSockOpt_InvalidParams

SECURE_SOCKETS_Shutdown

SECURE_SOCKETS_ShutdownInvalidParams

SECURE_SOCKETS_ShutdownWithoutReceiving

SECURE_SOCKETS_Close

SECURE_SOCKETS_CloseInvalidParams

SECURE_SOCKETS_CloseWithoutReceiving

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Library

Tests

Notes

SECURE_SOCKETS_Recv_ByteByByte

SECURE_SOCKETS_Recv_On_Unconnected_socket

SECURE_SOCKETS_SendRecv_VaryLength

SECURE_SOCKETS_SockEventHandler

SECURE_SOCKETS_Send_Invalid

SECURE_SOCKETS_SetSecureOptionsAfterConnect

SECURE_SOCKETS_TwoSecureConnections

SECURE_SOCKETS_Recv_Invalid

TLS

TLS_ConnectEC

TLS_ConnectRSA

TLS_ConnectMalformedCert

TLS_ConnectUntrustedCert

TLS_ConnectBYOCCredentials

PKCS #11

CreateObject_InvalidParams

Digest

Digest_ErrorConditions

FindObjectsFinal_InvalidParams

FindObjectsInit_InvalidParams

FindObjects_InvalidParams

GenerateRandom_HappyPath

GenerateRandom_InvalidParams

GetAttributeValue_InvalidParams

GetFunctionListInvalidParams

GetSlotListInvalidParams

InitializeFinalizeInvalidParams

KeyGenerationEcdsaHappyPath

Objects_HappyPath

OpenCloseSessionInvalidParams

SignInit_InvalidParams

SignVerifyCryptoApiInteropRSA

SignVerifyRoundTripWithCorrectECPublicKey

SignVerifyRoundTripWithCorrectRSAPublicKey

SignVerifyRoundTripWithWrongECPublicKey

SignVerifyRoundTripWithWrongRSAPublicKey

Sign_HappyPath

Sign_InvalidParams

TestECDSAExport

TestECDSAParse

TestRSAExport

TestRSAParse

VerifyInit_InvalidParams

Verify_HappyPath

Verify_InvalidParams

MQTT

MQTT_Init_HappyCase

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Library

Tests

Notes

MQTT_Init_NULLParams

MQTT_Connect_HappyCase

MQTT_Connect_BrokerRejectsConnection

MQTT_Connect_ConnACKWithoutConnect

MQTT_Connect_ReservedReturnCodeFromBroker

MQTT_Connect_ShorterConnACK

MQTT_Connect_LongerConnACK

MQTT_Connect_NULLParams

MQTT_Connect_SecondConnectWhileAlreadyConnected

MQTT_Connect_SecondConnectWhileWaitingForConnACK

MQTT_Connect_NetworkSendFailed

prvGetTopicFilterType_HappyCases

prvGetTopicFilterType_ErrorCases

prvDoesTopicMatchTopicFilter_MatchCases

prvDoesTopicMatchTopicFilter_NotMatchCases

OTA

OTA_SetImageState_InvalidParams

prvParseJobDocFromJSONandPrvOTA_Close

prvParseJSONbyModel_Errors

prvPAL_CloseFile_ValidSignature

prvPAL_CloseFile_InvalidSignatureBlockWritten

prvPAL_CloseFile_InvalidSignatureNoBlockWritten

prvPAL_CloseFile_NonexistingCodeSignerCertificate

prvPAL_CreateFileForRx_CreateAnyFile

prvPAL_Abort_OpenFile

prvPAL_Abort_FileWithBlockWritten

prvPAL_Abort_NullFileHandle

prvPAL_Abort_NonExistentFile

prvPAL_WriteBlock_WriteSingleByte

prvPAL_WriteBlock_WriteManyBlocks

prvPAL_SetPlatformImageState_SelfTestImageState

prvPAL_SetPlatformImageState_InvalidImageState

prvPAL_SetPlatformImageState_UnknownImageState

prvPAL_SetPlatformImageState_RejectImageState

prvPAL_GetPlatformImageState_InvalidImageStateFromFileCloseFai

lure

prvPAL_ReadAndAssumeCertificate_ExistingFile

prvPAL_CheckFileSignature_ValidSignature

prvPAL_CheckFileSignature_InvalidSignatureBlockWritten

prvPAL_CheckFileSignature_InvalidSignatureNoBlockWritten

prvPAL_CheckFileSignature_NonexistingCodeSignerCertificate

OtaTestGreaterVersion

OtaTestUnsignedImage

OtaTestSameVersion

OtaTestUntrustedCertificate

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Library

Tests

Notes

OtaTestCorruptImageBeforeSigning

OtaTestPreviousVersion

OtaTestCorruptImageAfterSigning

OtaTestCorruptSignature

OtaTestSingleByteImage

OtaTestMissingFilename

OtaTestIncorrectPlatform

OtaTestBackToBackDownloads

OtaTestIncorrectWifiPassword

BLE

(test on DUT)

BLE_Initialize_common_GAP

BLE_Initialize_BLE_GAP

BLE_Initialize_BLE_GATT

BLE_CreateAttTable_CreateServices

BLE_CreateAttTable_CreateCharacteristics

BLE_CreateAttTable_Descriptors

BLE_CreateAttTable_IncludedService

Disabled

BLE_CreateAttTable_StartService

BLE_Advertising_SetProperties

BLE_Advertising_SetAvertisementData

BLE_Advertising_StartAdvertisement

BLE_Connection_SimpleConnection

BLE_Connection_UpdateConnectionParamReq

BLE_Property_WriteCharacteristic

BLE_Property_WriteDescriptor

BLE_Property_ReadCharacteristic

BLE_Property_ReadDescriptor

BLE_Property_WriteNoResponse

BLE_Property_Notification

BLE_Property_Indication

BLE_Connection_Mode1Level4

BLE_Connection_Mode1Level4_Property_WriteDescr

BLE_Connection_Mode1Level4_Property_WriteChar

BLE_Connection_Disconnect

BLE_Connection_BondedReconnectAndPair

BLE_Connection_Disconnect

BLE_Connection_CheckBonding

BLE_Connection_RemoveBonding

BLE_Connection_Mode1Level2

BLE_DeInitialize

BLE

(test on PI)

discoverPrimaryServices

simpleConnection

checkProperties

checkUUIDs

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Library

Tests

Notes

readWriteSimpleConnection

writeWithoutResponse

notification

indication

readWriteProtectedAttributesWhileNotPaired

readWriteProtectedAttributesWhilePaired

pairing

disconnect

reconnectWhileBonded

reconnectWhileNotBonded

Total

215

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.13 Appendix M: TLS Server Setup

A simple TLS echo server is provided with Amazon FreeRTOS code. It is located in

$AFR_HOME/tools/echo_server/tls_echo_server.go.

Instructions:

1. Install the latest version of GO on your server host: https://golang.org/dl/

2. Install openssl on your server host:

a. Linux --- https://www.openssl.org/source/

b. Windows --- https://slproweb.com/products/Win32OpenSSL.html

3. Copy tls_echo_server.go to a directory you choose.

4. Generate a TLS server self-signed certificate and private key. See

$AFR_HOME/tools/echo_server/readme-gencert.txt for the openssl commands to generate a

self-signed server certificate and private key.

5. Copy the certificate and private key .pem files into a subdirectory called “certs”. The “certs”

directory should be a subdirectory of the directory where the server code will run.

6. Start the TLS server by running: go run tls_echo_server.go

7. The server will listen on port 9000. The IP address and the port must be set in

$AFR_HOME/tests/common/include/aws_test_tcp.h. For example if your server’s IP address is

192.168.2.6, set the following macros:

Macro definition for TLS server

Example value if address is 192.168.0.200

tcptestECHO_SERVER_TLS_ADDR0

192

tcptestECHO_SERVER_TLS_ADDR1

168

tcptestECHO_SERVER_TLS_ADDR2

2

tcptestECHO_SERVER_TLS_ADDR3

6

tcptestECHO_PORT_TLS

( 9000 )

8. The tests will check the server certificate. In

$AFR_HOME/tests/common/include/aws_test_tcp.h, set tcptestECHO_HOST_ROOT_CA to your

formatted server certificate.

You can use the formatting tool to format your server certificate.

9. The AFQ secure sockets tests require TLS mutual authentication to be configured. The readme-

gencert.txt file also describes how to generate a client certificate and private key that is signed by

the server key. This will allow the custom echo server to trust the client certificate presented by

your device during TLS authentication. The client certificate and private key must be PEM formatted

and copied into aws_clientcredential_keys.h before building and running the test project on the

device.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.14 Appendix N: “Hello World” Demo Project Set Up

Amazon FreeRTOS Directory Structure

All qualified Amazon FreeRTOS ports use the same directory structure, so all new files, including IDE

project files, must be created in the correct folder locations. The directory structure is explained below.

The three root level folders under $AFR_HOME are:

$AFR_HOME

├───demos Contains projects that build demo applications

├───lib Contains Amazon FreeRTOS and third-party libraries

└───tests Contains projects that build qualification tests

Your project is to be created within the demos folder, which is structured as follows:

$AFR_HOME

└───demos

├───common Contains files built by all demo projects

├───pc Contains a demo project for the FreeRTOS Windows port

└───vendor Contains your vendor specific code

└───board Contains your board specific code

The $AFR_HOME/demos/[vendor]/[board] folder is a template provided to simplify the creation of a

new test project and ensures all test projects have a consistent organization. It has the following

structure:

$AFR_HOME

└───demos

└───[vendor]

└───[board]

├───common

│ ├───application_code Contains main.c

│ │ └───vendor_code Contains vendor supplied board specific files

│ └───config_files Contains Amazon FreeRTOS config files

└───ide Contains an IDE specific project

Your demo projects always require vendor-supplied driver libraries. Some vendor-supplied libraries,

such as a header file that maps a GPIO output to an LED, are specific to the target development board.

Other vendor-supplied libraries, such as the GPIO library itself, are specific to the target MCU family. Do

not save vendor-supplied libraries that are specific to the MCU anywhere within either the

$AFR_HOME/tests or $AFR_HOME/demos folders.

Preparing Your Project Directories:

1. Rename the $AFR_HOME/demos/vendor folder to the name of the company that manufactures the

MCU – from here on the folder is referred to as [vendor].

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

2. Rename the $AFR_HOME/demos/[vendor]/board folder to the name of the development board

being qualified – from here on the folder is referred to as [board].

3. Copy your main.c and main.h in

$AFR_HOME/demos/[vendor]/[board]/common/application_code folder. You can re-use the

main.c in your aws_tests project.

4. Save any required vendor-supplied libraries that are specific to the board in the

$AFR_HOME/demos/[vendor]/[board]/common/application_code/vendor_code folder.

5. Rename the $AFR_HOME/demos/[vendor]/[board]/ide folder to the name of the IDE that will be

used to build the test project – from here on the folder is referenced as [ide].

Create the “Hello World” Demo Project

If your IDE does not use relative paths, define a variable in the project for relative folder locations

before importing Amazon FreeRTOS source files.

1. Create an IDE project aws_demos in the $AFR_HOME/demos/[vendor]/[board]/[ide] directory.

2. Create the project structure in the IDE

3. Create three top level virtual folders:

a. application_code

b. config_files

c. lib

4. Import the $AFR_HOME/demos/[vendor]/[board]/common/application_code directory and its

contents into the application_code virtual folder.

5. Import the files in $AFR_HOME/demos/[vendor]/[board]/common/config_files into the

config_files virtual folder.

6. Create a virtual folder under application_code and call it common_demos.

7. Create a source folder under common_demos.

8. Import the files in each of the following directories into the source folder:

a. $AFR_HOME/demos/common/demo_runner

b. $AFR_HOME/demos/common/devmode_key_provisioning (only the .c file)

c. $AFR_HOME/demos/common/mqtt

d. $AFR_HOME/demos/common/logging

9. Import the following directories and its contents into common_demos folder.

a. $AFR_HOME/demos/common/include

10. Create two virtual folders aws and third_party under virtual folder lib

11. Import each of the following directories and their contents into the aws folder:

a. $AFR_HOME/lib/bufferpool

b. $AFR_HOME/lib/FreeRTOS

c. $AFR_HOME/lib/FreeRTOS/portable/MemMang/heap_4.c

d. $AFR_HOME/lib/FreeRTOS/portable/[compiler your IDE uses]

e. $AFR_HOME/lib/FreeRTOS-Plus-TCP (if you have ported this library, please refer to

Appendix D on what files should be included in this project)

f. $AFR_HOME/lib/include

g. $AFR_HOME/lib/include/private (only .h files)

h. $AFR_HOME/lib/mqtt

i. $AFR_HOME/lib/pkcs11/portable/[vendor]/[board]/pkcs11.c (under pkcs11 folder)

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

$AFR_HOME/lib/secure_sockets/portable/[vendor]/[board]/aws_secure_sockets.c

(under secure_sockets folder)

j. $AFR_HOME/lib/tls (if you have ported TLS library)

k. $AFR_HOME/lib/wifi/portable/[vendor]/[board]/aws_wifi.c (under wifi folder,

if you have ported WI-FI library)

12. Import each of the following directories and their contents into third_party:

a. $AFR_HOME/lib/third_party/mcu_vendor/[vendor]/[board]/[driver_library]/[dri

ver_library_version] (under mcu_vendor folder)

b. $AFR_HOME/lib/third_party/mbedtls (rename ../mbedtls/library to

../mbedtls/source)

c. $AFR_HOME/lib/third_party/pkcs11

13. Make sure the following compiler include paths are set in the project property:

a. $AFR_HOME/demos/common/include

b. $AFR_HOME/lib/include

c. $AFR_HOME/lib/include/private

d. $AFR_HOME/lib/FreeRTOS/portable/[compiler]/[architecture]

e. $AFR_HOME/demos/vendor/board/common/config_files

f. $AFR_HOME/lib/third_party/mbedtls/include

g. Any paths required by vendor-supplied driver libraries

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.15 Appendix O: Checklist for Qualification

 “Test” project passed all tests in AFQ tests version ______________.

 Ported configPRINT_STRING() macro.

 Configured FreeRTOS kernel according to your target MCU.

 Ported Wi-Fi Management library (Optional if your board does not support Wi-Fi) and

passed Wi-Fi Management library tests.

 Ported OTA library (Optional if your board does not support Wi-Fi) and passed OTA library

tests.

 Bootloader following the Amazon FreeRTOS guidelines in Appendix J: Bootloader

 Ported FreeRTOS TCP/IP stack (Optional if you use off-chip TCP/IP stack).

 Ported CYPTO library and passed CYPTO library tests.

 Ported PKCS #11 library and passed tests for this library.

 Ported TLS library (Optional if you use Amazon FreeRTOS TLS support) and passed tests for

this library.

 Ported Secure Sockets library and passed the associated tests.

 Passed tests for MQTT library.

 Prepare a “Demo” project for an IDE you choose that can send “Hello World” to AWS IoT Console

and receive reply through MQTT protocol.

 Put the appropriate open source license text in your code. Please refer to

https://opensource.org/licenses for license text information.

 Configure your board name in

$AFR_HOME/demos/[vendor]/[board]/common/config_files/FreeRTOSConfig.h

#define mqttconfigMETRIC_PLATFORM "Platform=Your board name"

 Information required for Appendix U: Hardware Information filled

 Prepare a “Getting Started Guide” for your board to help users run your “Demo” project. You can

use the Getting Started Guide template to start and look at the guide for the Window Simulator for

reference.

 (Optionally) Provide Appendix V: Information for listing on the Amazon FreeRTOS Console

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.16 Appendix P: Troubleshooting Porting Setup

1. Can I reach the “echo server” from two different networks (for example, from two subnets across

2 different access points)?

An echo server is required for successful completion of the TCP/IP and TLS tests. The echo server

must be reachable from the network that the boards are connected to. Please consult your IT

support to enable routing across subnets if you need devices on different subnets to communicate

to a single echo server.

2. Can I use openssl in a Windows environment?

Yes. Even though only a Linux distribution of openssl is provided on https://www.openssl.org/, you

can find openssl distributions for Windows on the internet.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.17 Appendix Q: Instructions to Create a BYOC (ECDSA)

Prerequisite:

To follow the instructions below, you need to have openssl and the AWS CLI installed.

 OpenSSL is an open source toolkit for the TLS protocol. (https://www.openssl.org/). We

will use openssl in examples for generating certificates below. Please use TLS V1.2. You

can download it here:

Linux --- https://www.openssl.org/source/

 AWS CLI installation guide:

https://docs.aws.amazon.com/cli/latest/userguide/installing.html

o MUST DO: Configure AWS CLI before use.

Please follow the instruction here to configure AWS CLI:

https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html

Note: during the CA certificate creation process, please consider fill in valid information. You may see

errors if the organization or other fields don’t align in later signing steps.

Generate a Root CA

1. Generate a root CA private key

a. openssl ecparam -name prime256v1 -genkey -noout -out rootCA.key

2. Generate a root CA certificate

a. openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out

rootCA.crt

Generate Intermediate CA

1. Create necessary files

a. touch index.txt

b. echo 1000 > serial

2. Paste the ca.config file in Appendix R: Source for ca.config in the directory

3. Generate intermediate CA’s private key:

a. openssl ecparam -name prime256v1 -genkey -noout -out intermediateCA.key

4. Generate intermediate CA’s CSR [Make sure to fill Common Name to some value]

a. openssl req -new -sha256 -key intermediateCA.key -out intermediateCA.csr

5. Sign the intermediate CA’s CSR with root CA

b. openssl ca -config ca.config -notext -cert rootCA.crt -keyfile rootCA.key -

days 500 -in intermediateCA.csr -out intermediateCA.crt

Generate Device Certificate (ECDSA certificate as an example)

1. Generate private key

a. openssl ecparam -name prime256v1 -genkey -noout -out deviceCert.key

2. Generate CSR for device certificate

a. openssl req -new -key deviceCert.key -out deviceCert.csr

3. Sign the device certificate with the intermediate CA

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

a. openssl x509 -req -in deviceCert.csr -CA intermediateCA.crt -CAkey

intermediateCA.key -CAcreateserial -out deviceCert.crt -days 500 -sha256

Register both CA certificates

1. Get registration code

a. aws iot get-registration-code

2. Generate private key for verification certificates

a. openssl ecparam -name prime256v1 -genkey -noout -out verificationCert.key

3. Create CSR for verification certificates. Set the Common Name field to your registration code

obtained in the first step.

a. openssl req -new -key verificationCert.key -out verificationCert.csr

4. Sign a verification certificate using root CA and another one using intermediate CA

a. openssl x509 -req -in verificationCert.csr -CA rootCA.crt -CAkey rootCA.key

-CAcreateserial -out rootCAverificationCert.crt -days 500 -sha256

b. openssl x509 -req -in verificationCert.csr -CA intermediateCA.crt -CAkey

intermediateCA.key -CAcreateserial -out intermediateCAverificationCert.crt

-days 500 -sha256

5. Register both CA certificates with AWS IoT

a. aws iot register-ca-certificate --ca-certificate file://rootCA.crt --

verification-cert file://rootCAverificationCert.crt

b. aws iot register-ca-certificate --ca-certificate file://intermediateCA.crt

--verification-cert file://intermediateCAverificationCert.crt

6. Activate both CA certificates

a. aws iot update-ca-certificate --certificate-id xxxxxxxxxxxxxxxx --new-

status ACTIVE

Register Device Certificate

1. Register the device certificate with AWS IoT

a. aws iot register-certificate --certificate-pem file://deviceCert.crt --ca-

certificate-pem file://intermediateCA.crt

2. Activate the device certificate

a. aws iot update-certificate --certificate-id xxxxxxxxxxxxxx --new-status

ACTIVE

deviceCert.crt is device certificate and deviceCert.key is device private key.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.18 Appendix R: Source for ca.config

#

# OpenSSL example configuration file.

# This is mostly being used for generation of certificate requests.

#

# This definition stops the following lines choking if HOME isn't

# defined.

HOME = .

RANDFILE = $ENV::HOME/.rnd

# Extra OBJECT IDENTIFIER info:

#oid_file = $ENV::HOME/.oid

oid_section = new_oids

# To use this configuration file with the "-extfile" option of the

# "openssl x509" utility, name here the section containing the

# X.509v3 extensions to use:

# extensions =

# (Alternatively, use a configuration file that has only

# X.509v3 extensions in its main [= default] section.)

[ new_oids ]

# We can add new OIDs in here for use by 'ca', 'req' and 'ts'.

# Add a simple OID like this:

# testoid1=1.2.3.4

# Or use config file substitution like this:

# testoid2=${testoid1}.5.6

# Policies used by the TSA examples.

tsa_policy1 = 1.2.3.4.1

tsa_policy2 = 1.2.3.4.5.6

tsa_policy3 = 1.2.3.4.5.7

####################################################################

[ ca ]

default_ca = CA_default # The default ca section

####################################################################

[ CA_default ]

dir = . # Where everything is kept

certs = $dir # Where the issued certs are kept

crl_dir = $dir # Where the issued crl are kept

database = $dir/index.txt # database index file.

#unique_subject = no # Set to 'no' to allow creation of

# several ctificates with same subject.

new_certs_dir = $dir # default place for new certs.

certificate = $dir/cacert.pem # The CA certificate

serial = $dir/serial # The current serial number

crlnumber = $dir/crlnumber # the current crl number

# must be commented out to leave a V1 CRL

crl = $dir/crl.pem # The current CRL

private_key = $dir/private/cakey.pem# The private key

RANDFILE = $dir/private/.rand # private random number file

x509_extensions = usr_cert # The extentions to add to the cert

# Comment out the following two lines for the "traditional"

# (and highly broken) format.

name_opt = ca_default # Subject Name options

cert_opt = ca_default # Certificate field options

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

# Extension copying option: use with caution.

# copy_extensions = copy

# Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs

# so this is commented out by default to leave a V1 CRL.

# crlnumber must also be commented out to leave a V1 CRL.

# crl_extensions = crl_ext

default_days = 365 # how long to certify for

default_crl_days = 30 # how long before next CRL

default_md = default # use public key default MD

preserve = no # keep passed DN ordering

# A few difference way of specifying how similar the request should look

# For type CA, the listed attributes must be the same, and the optional

# and supplied fields are just that :-)

policy = policy_match

# For the CA policy

[ policy_match ]

countryName = match

stateOrProvinceName = match

organizationName = match

organizationalUnitName = optional

commonName = supplied

emailAddress = optional

# For the 'anything' policy

# At this point in time, you must list all acceptable 'object'

# types.

[ policy_anything ]

countryName = optional

stateOrProvinceName = optional

localityName = optional

organizationName = optional

organizationalUnitName = optional

commonName = supplied

emailAddress = optional

####################################################################

[ req ]

default_bits = 2048

default_keyfile = privkey.pem

distinguished_name = req_distinguished_name

attributes = req_attributes

x509_extensions = v3_ca # The extentions to add to the self signed cert

# Passwords for private keys if not present they will be prompted for

# input_password = secret

# output_password = secret

# This sets a mask for permitted string types. There are several options.

# default: PrintableString, T61String, BMPString.

# pkix : PrintableString, BMPString (PKIX recommendation before 2004)

# utf8only: only UTF8Strings (PKIX recommendation after 2004).

# nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).

# MASK:XXXX a literal mask value.

# WARNING: ancient versions of Netscape crash on BMPStrings or UTF8Strings.

string_mask = utf8only

# req_extensions = v3_req # The extensions to add to a certificate request

[ req_distinguished_name ]

countryName = Country Name (2 letter code)

countryName_default = AU

countryName_min = 2

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

countryName_max = 2

stateOrProvinceName = State or Province Name (full name)

stateOrProvinceName_default = Some-State

localityName = Locality Name (eg, city)

0.organizationName = Organization Name (eg, company)

0.organizationName_default = Internet Widgits Pty Ltd

# we can do this but it is not needed normally :-)

#1.organizationName = Second Organization Name (eg, company)

#1.organizationName_default = World Wide Web Pty Ltd

organizationalUnitName = Organizational Unit Name (eg, section)

#organizationalUnitName_default =

commonName = Common Name (e.g. server FQDN or YOUR name)

commonName_max = 64

emailAddress = Email Address

emailAddress_max = 64

# SET-ex3 = SET extension number 3

[ req_attributes ]

challengePassword = A challenge password

challengePassword_min = 4

challengePassword_max = 20

unstructuredName = An optional company name

[ usr_cert ]

# These extensions are added when 'ca' signs a request.

# This goes against PKIX guidelines but some CAs do it and some software

# requires this to avoid interpreting an end user certificate as a CA.

basicConstraints=CA:TRUE

# Here are some examples of the usage of nsCertType. If it is omitted

# the certificate can be used for anything *except* object signing.

# This is OK for an SSL server.

# nsCertType = server

# For an object signing certificate this would be used.

# nsCertType = objsign

# For normal client use this is typical

# nsCertType = client, email

# and for everything including object signing:

# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate.

# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape's comment listbox.

nsComment = "OpenSSL Generated Certificate"

# PKIX recommendations harmless if included in all certificates.

subjectKeyIdentifier=hash

authorityKeyIdentifier=keyid,issuer

# This stuff is for subjectAltName and issuerAltname.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

# Import the email address.

# subjectAltName=email:copy

# An alternative to produce certificates that aren't

# deprecated according to PKIX.

# subjectAltName=email:move

# Copy subject details

# issuerAltName=issuer:copy

#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem

#nsBaseUrl

#nsRevocationUrl

#nsRenewalUrl

#nsCaPolicyUrl

#nsSslServerName

# This is required for TSA certificates.

# extendedKeyUsage = critical,timeStamping

[ v3_req ]

# Extensions to add to a certificate request

basicConstraints = CA:FALSE

keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ v3_ca ]

# Extensions for a typical CA

# PKIX recommendation.

subjectKeyIdentifier=hash

authorityKeyIdentifier=keyid:always,issuer

# This is what PKIX recommends but some broken software chokes on critical

# extensions.

#basicConstraints = critical,CA:true

# So we do this instead.

basicConstraints = CA:true

# Key usage: this is typical for a CA certificate. However since it will

# prevent it being used as an test self-signed certificate it is best

# left out by default.

# keyUsage = cRLSign, keyCertSign

# Some might want this also

# nsCertType = sslCA, emailCA

# Include email address in subject alt name: another PKIX recommendation

# subjectAltName=email:copy

# Copy issuer details

# issuerAltName=issuer:copy

# DER hex encoding of an extension: beware experts only!

# obj=DER:02:03

# Where 'obj' is a standard or added object

# You can even override a supported extension:

# basicConstraints= critical, DER:30:03:01:01:FF

[ crl_ext ]

# CRL extensions.

# Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

# issuerAltName=issuer:copy

authorityKeyIdentifier=keyid:always

[ proxy_cert_ext ]

# These extensions should be added when creating a proxy certificate

# This goes against PKIX guidelines but some CAs do it and some software

# requires this to avoid interpreting an end user certificate as a CA.

basicConstraints=CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted

# the certificate can be used for anything *except* object signing.

# This is OK for an SSL server.

# nsCertType = server

# For an object signing certificate this would be used.

# nsCertType = objsign

# For normal client use this is typical

# nsCertType = client, email

# and for everything including object signing:

# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate.

# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape's comment listbox.

nsComment = "OpenSSL Generated Certificate"

# PKIX recommendations harmless if included in all certificates.

subjectKeyIdentifier=hash

authorityKeyIdentifier=keyid,issuer

# This stuff is for subjectAltName and issuerAltname.

# Import the email address.

# subjectAltName=email:copy

# An alternative to produce certificates that aren't

# deprecated according to PKIX.

# subjectAltName=email:move

# Copy subject details

# issuerAltName=issuer:copy

#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem

#nsBaseUrl

#nsRevocationUrl

#nsRenewalUrl

#nsCaPolicyUrl

#nsSslServerName

# This really needs to be in place for it to be a proxy certificate.

proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:3,policy:foo

####################################################################

[ tsa ]

default_tsa = tsa_config1 # the default TSA section

[ tsa_config1 ]

# These are used by the TSA reply generation only.

dir = ./demoCA # TSA root directory

serial = $dir/tsaserial # The current serial number (mandatory)

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

crypto_device = builtin # OpenSSL engine to use for signing

signer_cert = $dir/tsacert.pem # The TSA signing certificate

# (optional)

certs = $dir/cacert.pem # Certificate chain to include in reply

# (optional)

signer_key = $dir/private/tsakey.pem # The TSA private key (optional)

default_policy = tsa_policy1 # Policy if request did not specify it

# (optional)

other_policies = tsa_policy2, tsa_policy3 # acceptable policies (optional)

digests = md5, sha1 # Acceptable message digests (mandatory)

accuracy = secs:1, millisecs:500, microsecs:100 # (optional)

clock_precision_digits = 0 # number of digits after dot. (optional)

ordering = yes # Is ordering defined for timestamps?

# (optional, default: no)

tsa_name = yes # Must the TSA name be included in the reply?

# (optional, default: no)

ess_cert_id_chain = no # Must the ESS cert id chain be included?

# (optional, default: no)

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.19 Appendix S: Modify issuer in a certificate

1. Take the valid client certificate that you have been using as a base. In this example is it

81909ac548-certificate.pem.crt

2. Convert the certificate from PEM to DER (openssl x509 -outform der -in 81909ac548-

certificate.pem.crt -out 81909ac548-certificate.der.crt)

3. Open the .der certificate. “Amazon Web Services” in hex is 41 6d 61 7a 6f 6e 20 57 65

62 20 53 65 72 76 69 63 65 73. Search for this sequence in your DER output:

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

4. Modify the sequence to say ‘Amazon Web Cervices’, switching out the 53 to be a

43. Save the file. To verify your change, you can check out the modified cert in the

windows certificate manager. See that it now says Issued by: Amazon Web Cervices

5. Convert your newly modified certificate back to PEM. openssl x509 -inform der -in

81909ac548-certificate.der.crt -out 81909ac548-cert-modified.pem.crt

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Again, viewing this in the certificate viewer should show the modified certificate.

6. Put this certificate into the Certificate Configuration Tool

($AFR_HOME\tools\certificate_configuration\CertificateConfigurator.html) and copy the

formatted output.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.20 Appendix T: Getting Started Guide Template

Getting Started with the [board-name]

Provide a brief description of the board(s) that are qualified to run Amazon FreeRTOS with links to more

in-depth information on your company’s website

 What hardware is required?

 What host operating systems are supported?

 What IDEs are supported? (Include links to download IDEs)

 What toolchains will the developer use? (Include links to download toolchains)

 Prerequisite

Prerequisites

List any prerequisites for your board

Setting up the [board-name] Hardware

Provide instructions for setting up the hardware including:

 Jumper settings

 Driver installation (include links to supported driver versions)

 Connecting the board to a computer

Setting Up Your Environment

 Provide instructions to establish a serial connection to your board for each host operating

system.

 Provide instructions and link(s) to set up the toolchain for each host operating system.

 Provide instructions for installing/configuring any board-specific software for each host

operating system (anything listed here should be called out in the prerequisites section).

Download and Configure Amazon FreeRTOS

 Provide instructions to download Amazon FreeRTOS from the Amazon FreeRTOS Online

Connection Wizard or GitHub repository.

Build and Run the FreeRTOS Samples

 Provide instructions for loading/importing the Amazon FreeRTOS sample code into your IDE.

 Provide instructions on how to flash the sample application to your board including:

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

o How to connect your board to the host computer

o How to use an IDE or other tools to flash the sample application to your board

o How to verify the sample application is running correctly

o Troubleshooting steps for resolving problems

Debugging the samples

 Provide instructions on how to use any on-board debugging interface or external debuggers for

each supported host OS.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.21 Appendix U: Hardware Information

General Information:

Company Name

Company Name (short, if any) for

Amazon FreeRTOS Console

High Resolution Logo

Link to Landing Page

Company Description (15 words)

Development Board Information:

Board Name

Board Name (20 chars) for Amazon

FreeRTOS Console

High Resolution Board Image

Board Description

Board Description (50 chars) for

Amazon FreeRTOS Console

Microcontroller Family Name

Board Datasheet

Compiler Options (optimization)

IDE with Version Number

CLI command to build target

executables

CLI command to flash target

Link to Board Landing Page

Getting Started Guide

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Link to Purchase Board

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.22 Appendix V: Information for listing on the Amazon FreeRTOS

Console

To list the qualified board(s) on the Amazon FreeRTOS console, we require you to provide additional

information based on CMakefile Template. Please follow the guide listed at

https://github.com/aws/amazon-freertos/tree/feature/cmake/cmake/doc/porting_guide.md

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.23 Appendix W: Glossary

$AFR_HOME

The path where Amazon FreeRTOS is installed/extracted.

Amazon Free RTOS Qualification Program Developer Guide

Navigation menu

Versions of this User Manual:

Views

Navigation