Amazon Free RTOS Qualification Program Developer Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 86

DownloadAmazon Free RTOS Qualification Program Developer Guide
Open PDF In BrowserView PDF
Amazon FreeRTOS Qualification
Developer Guide
Document Version V1.1.3

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Amazon FreeRTOS Qualification: Developer Guide
Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

2

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Revision History
Date

Versi
on

Change History

Compatible
Amazon
FreeRTOS
Version

July 31, 2018
August 09, 2018

1.0.0
1.0.1

1.3.0
1.3.1
1.3.2

August 27, 2018

1.1.0

October 08, 2018

1.1.1

November 07, 2018

1.1.2

Initial Version.
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.
Added tests for Over-the-air (OTA) updates and
guidelines for bootloader
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.
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.

November 26, 2018

1.1.3

Added BLE section.
Updated with IoT Device Tester information.
Added cmake preparation section.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

1.4.0
1.4.1
1.4.2

1.4.3
1.4.4

To be
assigned

3

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Contents
Revision History ............................................................................................................................................ 3
1

2

Introduction .......................................................................................................................................... 6
1.1

What is the Amazon FreeRTOS Qualification? .............................................................................. 6

1.2

Target System Requirements ........................................................................................................ 6

1.3

Document Outline......................................................................................................................... 6

Amazon FreeRTOS Qualification Test Project ....................................................................................... 7
2.1

Download Amazon FreeRTOS Source Code .................................................................................. 7

2.2

Set Up Your Amazon FreeRTOS Project ........................................................................................ 7

2.2.1

Preparing Amazon FreeRTOS Folders ................................................................................... 7

2.2.2

Create the Test Project ......................................................................................................... 9

2.3

Port, Build and Test Libraries and Demos ................................................................................... 15

2.3.1

Port Libraries, Build and Test Libraries ............................................................................... 15

2.3.2

“Hello World” Demo and Getting Started Guide ................................................................ 16

2.3.3

Configure your board name ................................................................................................ 17

3

FAQs .................................................................................................................................................... 18

4

Contact Us ........................................................................................................................................... 19

5

Appendix ............................................................................................................................................. 20
5.1

Appendix A: configPRINT_STRING() ............................................................................................ 21

5.2

Appendix B: FreeRTOS kernel ..................................................................................................... 23

5.3

Appendix C: Wi-Fi Management ................................................................................................. 25

5.4

Appendix D: FreeRTOS TCP/IP Stack ........................................................................................... 28

5.5

Appendix E: Secure Sockets ........................................................................................................ 31

5.6

Appendix F: PKCS #11 ................................................................................................................. 35

5.7

Appendix G: TLS .......................................................................................................................... 39

5.8

Appendix H: MQTT ...................................................................................................................... 45

5.9

Appendix I: OTA Updates ............................................................................................................ 47

5.10

Appendix J: Bootloader ............................................................................................................... 51

5.11

Appendix K: Bluetooth Low Energy (Beta) .................................................................................. 52

5.12

Appendix L: Test List ................................................................................................................... 57

5.13

Appendix M: TLS Server Setup .................................................................................................... 63

5.14

Appendix N: “Hello World” Demo Project Set Up ...................................................................... 64

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

4

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
5.15

Appendix O: Checklist for Qualification ...................................................................................... 67

5.16

Appendix P: Troubleshooting Porting Setup ............................................................................... 68

5.17

Appendix Q: Instructions to Create a BYOC (ECDSA) .................................................................. 69

5.18

Appendix R: Source for ca.config ................................................................................................ 71

5.19

Appendix S: Modify issuer in a certificate................................................................................... 77

5.20

Appendix T: Getting Started Guide Template ............................................................................. 81

5.21

Appendix U: Hardware Information............................................................................................ 83

5.22

Appendix V: Information for listing on the Amazon FreeRTOS Console ..................................... 85

5.23

Appendix W: Glossary ................................................................................................................. 86

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

5

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
port1 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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

6

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
├───lib
└───tests

Contains projects that build demo applications
Contains Amazon FreeRTOS and third-party libraries
Contains projects that build qualification tests

Create your project in the tests folder, which is structured as follows:
$AFR_HOME
└───tests
├───common
├───pc
└───vendor
└───board

Contains files built by all test projects
Contains a reference test project for the FreeRTOS Windows port
Template, to be renamed to the name of the MCU vendor
Template, to be renamed to the name of the development board

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

7

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
│
│
└───vendor_code
│
└───config_files
└───ide

Contains
Contains
Contains
Contains

main.c, which itself contains main()
vendor supplied board specific files
Amazon FreeRTOS config files
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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

8

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
├───application_code
├───config_files
└───lib

The project name
Contains application logic, in this case it is AFQ test code
Contains header files that configure Amazon FreeRTOS libraries
Contains Amazon and third-party libraries

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

9

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.
NOTE:



The “Includes” folder is generated
automatically by Eclipse. It is not part
of the required structure

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.

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.

Figure 2 An IDE project with the application_code virtual folder expanded

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

10

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
Figure 3 shows the contents of the config_files virtual folder.

NOTE:


The files shown under config_files are located
in the
$AFR_HOME/tests/[vendor]/[board]/common
/config_files folder.

Figure 3 An IDE project with the config_files folder expanded

Figure 4 shows the contents of the lib virtual folder.

NOTE:


aws and third_party are virtual folders.

Figure 4 IDE project with the lib group expanded

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

11

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.
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.

Figure 5 IDE project with the lib/AWS
group expanded

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

12

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
Figure 6 shows the contents of the lib/third_party directory.
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).

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

13

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().

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

14

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

Notes

configPRINT_STRING Macro

Details in
Location
Appendix A

FreeRTOS Kernel

Appendix B

Required for the FreeRTOS kernel.

Wi-Fi Management

Appendix C

FreeRTOS TCP/IP Stack

Appendix D

Secure Sockets

Appendix E

Required only if hardware supports network
connectivity over Wi-Fi.
Required only if a board does not have its own
TCPIP stack support.
Required for AWS cloud connectivity.

PKCS#11

Appendix F

TLS

Appendix G

Required for over-the-air (OTA) and TLS
support.
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

Required for console output.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

15

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
testrunnerFULL_CBOR_ENABLED
testrunnerFULL_OTA_AGENT_ENABLED
testrunnerFULL_OTA_PAL_ENABLED
testrunnerFULL_MQTT_ALPN_ENABLED
testrunnerFULL_MQTT_STRESS_TEST_ENABLED
testrunnerFULL_MQTT_AGENT_ENABLED
testrunnerFULL_TCP_ENABLED
testrunnerFULL_GGD_ENABLED
testrunnerFULL_GGD_HELPER_ENABLED
testrunnerFULL_SHADOW_ENABLED
testrunnerFULL_MQTT_ENABLED
testrunnerFULL_PKCS11_ENABLED
testrunnerFULL_CRYPTO_ENABLED
testrunnerFULL_TLS_ENABLED
testrunnerFULL_WIFI_ENABLED
testrunnerFULL_BLE_ENABLED

Default value. (set to ‘1’
for enabling the test)
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

Required for AFQ

Y (if supports OTA)
Y (if supports OTA)

Y

Y
Y
Y
Y
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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

16

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

17

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

18

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

19

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:

START

Appendix A
Port configPRINT_STRING()

Appendix B
Port FreeRTOS Kernel

Appendix C
Is Wi-Fi support needed?

Port Wi-Fi library

YES

NO

Appendix D
Port FreeRTOS+TCP
TCP/IP stack

NO

Appendix E
Is the TCP/IP stack
offloaded from the main
MCU?

YES

Port Secure Sockets library

Appendix F
Port PKCS#11 library

Appendix G
Port TLS library

Support OTA?
(Wi-Fi Support is
required)

No

Yes

Port OTA library and use
bootloader

Appendix I and J

Appendix I:
OTA Update
Amazon FreeRTOS
Qualification

END

Recommended Porting Order

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

20

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:
void MyUARTOutput( char *DataToOutput, size_t LengthToOutput );

then you would implement configPRINT_STRING() as:
#define configPRINT_STRING( X ) MyUARTOutput( (X), strlen( (X) ) )

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

21

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().

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

22

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
configCPU_CLOCK_HZ
configMINIMAL_STACK_SIZE

configTOTAL_HEAP_SIZE

Comment
The frequency of the clock used to generate the tick interrupt.
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.
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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

23

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

24

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
WIFI_On
WIFI_ConnectAP
WIFI_Disconnect
WIFI_Scan
WIFI_GetIP
WIFI_GetMAC
WIFI_GetHostIP

Description
Turns on Wi-Fi module. Initializes the drivers
Connects to a Wi-Fi Access Point (AP)
Disconnects from the currently connected AP
Performs a Wi-Fi network scan
Retrieves the Wi-Fi interface’s IP address
Retrieves the Wi-Fi interface’s MAC address
Retrieves the host IP address from a hostname using DNS

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

25

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
clientcredentialWIFI_SSID
clientcredentialWIFI_PASSWORD
clientcredentialWIFI_SECURITY

Value
The Wi-Fi SSID as a C string (in quotes)
The Wi-Fi password as a C string
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
testwifiWIFI_SSID
testwifiWIFI_PASSWORD
testwifiWIFI_SECURITY

Value
The Wi-Fi SSID as a C string (in quotes)
The Wi-Fi password as a C string
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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

26

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

27

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/FreeRTOSPlus/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-PlusTCP/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-PlusTCP/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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

28

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-PlusTCP/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
uint8_t ucMACAddress[6]
uint8_t ucIPAddress[4]
uint8_t ucNetMask[4]
uint8_t ucGatewayAddress[ 4 ]
uint8_t ucDNSServerAddress[ 4 ]
uint8_t ucMACAddress[6]

Description

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

29

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():

if (eNetworkEvent == eNetworkUp)
{
configPRINT("Network connection successful.\n\r");
}

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

30

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.
Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

31

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
tcptestECHO_SERVER_ADDR1
tcptestECHO_SERVER_ADDR2
tcptestECHO_SERVER_ADDR3

192
168
0
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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

32

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

33

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

34

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

35

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
PKCS11_PAL_SaveObject
PKCS11_PAL_FindObject

PKCS11_PAL_GetObjectValue
PKCS11_PAL_GetObjectValueCleanup

Description
Writes data to non-volatile storage
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.
Retrieves the value of an object, given the handle.
Cleanup for the PKCS11_PAL_GetObjectValue call. May
be used to free memory allocated in
PKCS11_PAL_GetObjectValue call.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

36

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-oshandbook/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:

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

37

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

38

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
TLS_Init
TLS_Connect
TLS_Recv
TLS_Send
TLS_Cleanup

Description
Initialize the TLS context
Negotiate TLS and connect to the server
Read the requested number of bytes from the TLS connection
Write the requested number of bytes to the TLS connection
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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

39

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-consolesignin.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).
Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

40

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:
{
"Effect": "Allow",
"Action": "iot:*",
"Resource": "*"
}

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

41

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

42

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:

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

43

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

44

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.
Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

45

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

46

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
o
o

$AFR_HOME/tests/common/ota/aws_test_cbor.c
$AFR_HOME/tests/common/ota/aws_test_ota_agent.c
$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.
Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

47

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
Function
prvAbort
prvCreateFileForRx
prvCloseFile
prvWriteBlock
prvActivateNewImage

prvSetImageState

prvGetImageState

Description
Aborts an OTA update.
Creates a new file to store the data chunks as they are received.
Closes the specified file. This may authenticate the file if storage that
implements cryptographic protection is being used.
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.
Activates or launches the new firmware image. For some ports, if the
device is programmatically reset synchronously, this function may not
return.
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.
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-toend 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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

48

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:

…

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

49

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 endto-end test script.
Alternatively, you can use AWS IoT Device Tester for Amazon FreeRTOS to test OTA.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

50

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

51

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:

User APP
Services
Middle ware
Low level wrappers for HAL
BLE APIs

AFQ tests

OEM BLE stack

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/amazonfreertos/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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

52

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
pxGetDeviceProperty
pxSetDeviceProperty (All options
mandatory except
eBTpropertyRemoteRssi,
eBTpropertyRemoteVersionInfo)
Y(All options mandatory expect
eBTpropertyRemoteRssi,
eBTpropertyRemoteVersionInfo)
pxRemoveBond
pxGetConnectionState
pxSspReply
pxGetTxpower
pxDeviceStateChangedCb
pxAdapterPropertiesCb
pxPairingStateChangedCb
pxTxPowerCb

GAP BLE (bt_hal_manager_adapter_ble.h)
pxRegisterBleApp
pxUnregisterBleApp
pxStartAdv
pxStopAdv
pxConnParameterUpdateRequest pxRegisterBleAdapterCb

pxDisable
pxPair

pxPinReply
pxGetLeAdapter
pxSspRequestCb

pxBleAdapterInit
pxSetAdvData
pxAdvStartCb

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

53

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.

Computer

UART

SSH
Raspberry PI

BLE

DUT

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:

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

54

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:

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

55

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

56

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
Wi-Fi

Tests
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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Notes

57

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
Library

Secure
Sockets

Tests
WIFI_Scan_ZeroScanNumber
WIFI_NetworkGet_GetManyNetworks
WIFI_NetworkAdd_AddManyNetworks
WIFI_NetworkDelete_DeleteManyNetworks
WIFI_ConnectAP_ConnectAllChannels
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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Notes

58

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
Library

TLS

PKCS #11

MQTT

Tests
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_ConnectEC
TLS_ConnectRSA
TLS_ConnectMalformedCert
TLS_ConnectUntrustedCert
TLS_ConnectBYOCCredentials
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_Init_HappyCase

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Notes

59

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
Library

OTA

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_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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

60

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
Library

BLE
(test on DUT)

BLE
(test on PI)

Tests
OtaTestCorruptImageBeforeSigning
OtaTestPreviousVersion
OtaTestCorruptImageAfterSigning
OtaTestCorruptSignature
OtaTestSingleByteImage
OtaTestMissingFilename
OtaTestIncorrectPlatform
OtaTestBackToBackDownloads
OtaTestIncorrectWifiPassword
BLE_Initialize_common_GAP
BLE_Initialize_BLE_GAP
BLE_Initialize_BLE_GATT
BLE_CreateAttTable_CreateServices
BLE_CreateAttTable_CreateCharacteristics
BLE_CreateAttTable_Descriptors
BLE_CreateAttTable_IncludedService
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
advertisement
discoverPrimaryServices
simpleConnection
checkProperties
checkUUIDs

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Notes

Disabled

61

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
Library

Total

Tests
readWriteSimpleConnection
writeWithoutResponse
notification
indication
readWriteProtectedAttributesWhileNotPaired
readWriteProtectedAttributesWhilePaired
pairing
disconnect
reconnectWhileBonded
reconnectWhileNotBonded
215

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Notes

62

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
tcptestECHO_SERVER_TLS_ADDR1
tcptestECHO_SERVER_TLS_ADDR2
tcptestECHO_SERVER_TLS_ADDR3
tcptestECHO_PORT_TLS

192
168
2
6
( 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 readmegencert.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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

63

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
├───lib
└───tests

Contains projects that build demo applications
Contains Amazon FreeRTOS and third-party libraries
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
├───pc
└───vendor
└───board

Contains
Contains
Contains
Contains

files built by all demo projects
a demo project for the FreeRTOS Windows port
your vendor specific code
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
│
│
└───vendor_code
│
└───config_files
└───ide

Contains
Contains
Contains
Contains

main.c
vendor supplied board specific files
Amazon FreeRTOS config files
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].

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

64

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
5.

$AFR_HOME/demos/[vendor]/[board]/common/application_code/vendor_code folder.
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.
b.
c.
d.

$AFR_HOME/demos/common/demo_runner
$AFR_HOME/demos/common/devmode_key_provisioning (only the .c file)
$AFR_HOME/demos/common/mqtt
$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)

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

65

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.
b.
c.
d.
e.
f.

$AFR_HOME/demos/common/include
$AFR_HOME/lib/include
$AFR_HOME/lib/include/private
$AFR_HOME/lib/FreeRTOS/portable/[compiler]/[architecture]
$AFR_HOME/demos/vendor/board/common/config_files
$AFR_HOME/lib/third_party/mbedtls/include

g. Any paths required by vendor-supplied driver libraries

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

66

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

67

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

68

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

69

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 --newstatus ACTIVE

Register Device Certificate
1. Register the device certificate with AWS IoT
a. aws iot register-certificate --certificate-pem file://deviceCert.crt --cacertificate-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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

70

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
serial
crlnumber

= $dir/cacert.pem
# The CA certificate
= $dir/serial
# The current serial number
= $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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

71

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
default_crl_days
= 30
default_md
= default
preserve = no

# how long to certify for
# how long before next CRL
# use public key default MD
# 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
stateOrProvinceName
organizationName = match
organizationalUnitName
commonName
emailAddress

= match
= match
= optional
= supplied
= 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
countryName_default
countryName_min

= Country Name (2 letter code)
= AU
= 2

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

72

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
countryName_max

= 2

stateOrProvinceName
stateOrProvinceName_default

= State or Province Name (full name)
= Some-State

localityName

= Locality Name (eg, city)

0.organizationName
0.organizationName_default

= Organization Name (eg, company)
= 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
commonName_max
emailAddress
emailAddress_max

= Common Name (e.g. server FQDN or YOUR name)
= 64
= Email Address
= 64

# SET-ex3

= SET extension number 3

[ req_attributes ]
challengePassword
challengePassword_min
challengePassword_max

= A challenge password
= 4
= 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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

73

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
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName

= http://www.domain.dom/ca-crl.pem

# 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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

74

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
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName

= http://www.domain.dom/ca-crl.pem

# 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)

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

75

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
crypto_device
signer_cert

signer_key

# OpenSSL engine to use for signing
# The TSA signing certificate
# (optional)
= $dir/cacert.pem
# Certificate chain to include in reply
# (optional)
= $dir/private/tsakey.pem # The TSA private key (optional)

default_policy

= tsa_policy1

certs

= builtin
= $dir/tsacert.pem

# 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)

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

76

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 81909ac548certificate.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:

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

77

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

78

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

79

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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

80

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:

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

81

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

o
o
o
o

How to connect your board to the host computer
How to use an IDE or other tools to flash the sample application to your board
How to verify the sample application is running correctly
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.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

82

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

83

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3
Link to Purchase Board

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

84

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

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

85

Amazon FreeRTOS Qualification Developer Guide – V 1.1.3

5.23 Appendix W: Glossary
$AFR_HOME

The path where Amazon FreeRTOS is installed/extracted.

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

86



Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 86
Language                        : en-US
Tagged PDF                      : Yes
Author                          : Amazon FreeRTOS Qualification Program
Creator                         : Microsoft® Word 2016
Create Date                     : 2018:11:26 16:28:36-08:00
Modify Date                     : 2018:11:26 16:28:36-08:00
Producer                        : Microsoft® Word 2016
EXIF Metadata provided by EXIF.tools

Navigation menu