Porting Guide FreeRTOS

(1)

FreeRTOS

Porting Guide

(2)

FreeRTOS: Porting Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

FreeRTOS Porting

What is FreeRTOS?

Developed in partnership with the world's leading chip companies over a 15-year period, and now downloaded every 175 seconds, FreeRTOS is a market-leading real-time operating system (RTOS) for microcontrollers and small microprocessors. Distributed freely under the MIT open source license, FreeRTOS includes a kernel and a growing set of libraries suitable for use across all industry sectors.

FreeRTOS is built with an emphasis on reliability and ease of use.

FreeRTOS includes libraries for connectivity, security, and over-the-air (OTA) updates. FreeRTOS also includes demo applications that show FreeRTOS features on qualiﬁed boards.

FreeRTOS is an open-source project. You can download the source code, contribute changes or enhancements, or report issues on the GitHub site at https://github.com/aws/amazon-freertos. We release FreeRTOS code under the MIT open source license, so you can use it in commercial and personal projects.

We also welcome contributions to the FreeRTOS documentation (FreeRTOS User Guide, FreeRTOS Porting Guide, and FreeRTOS Qualiﬁcation Guide). The markdown source for the documentation is available at https://github.com/awsdocs/aws-freertos-docs. It is released under the Creative Commons (CC BY-ND) license.

The FreeRTOS kernel and components are released individually and use semantic versioning. Integrated FreeRTOS releases are made periodically. All releases use date-based versioning with the format YYYYMM.NN, where:

• Y represents the year.

• M represents the month.

• N represents the release order within the designated month (00 being the ﬁrst release).

For example, a second release in July 2021 would be 202107.01.

Previously, FreeRTOS releases used semantic versioning for major releases. Although it has moved to date-based versioning (FreeRTOS 1.4.8 updated to FreeRTOS AWS Reference Integrations 201906.00), the FreeRTOS kernel and each individual FreeRTOS library still retain semantic versioning. In semantic versioning, the version number itself (X.Y.Z) indicates whether the release is a major, minor, or point release. You can use the semantic version of a library to assess the scope and impact of a new release on your application.

LTS releases are maintained diﬀerently than other release types. Major and minor releases are frequently updated with new features in addition to defect resolutions. LTS releases are only updated with changes to address critical defects and security vulnerabilities. No new features are introduced in a given LTS release after launch. They are maintained for at least three calendar years after release, and provide device manufacturers the option to use a stable baseline as opposed to a more dynamic baseline represented by major and minor releases.

Porting FreeRTOS to your IoT device

Before a microcontroller board can run FreeRTOS, some FreeRTOS code must be ported to the device's hardware. Basic kernel ports should refer to the FreeRTOS porting guide on www.freertos.org. For ports intending to include the FreeRTOS libraries for security, connectivity, etc., the following instructions build on the kernel port.

(7)

System requirements

To port FreeRTOS to your device

1. Follow the instructions in Downloading FreeRTOS for Porting (p. 8) to download the latest version of FreeRTOS for porting.

2. Follow the instructions in Setting Up Your FreeRTOS Source Code for Porting (p. 9) to conﬁgure the ﬁles and folders in your FreeRTOS download for porting and testing.

3. Follow the instructions in Porting the FreeRTOS Libraries (p. 25) to port the FreeRTOS libraries to your device. Each porting topic includes instructions on testing the ports.

System requirements

The device that you port to FreeRTOS must be a microcontroller board that meets the following minimum requirements:

• 25MHz processing speed

• 64KB RAM

• 128KB program memory per executable image stored on the MCU

• (If Porting the AWS IoT over-the-air update library (p. 72)) Two executable images stored on the MCU

Porting older versions of FreeRTOS

If you are porting an older version of FreeRTOS, go to the FreeRTOS AWS Reference Integrations repository, and checkout the version of FreeRTOS that you are porting by its version tag. The

qualiﬁcation and testing documentation will be in PDF format, in the tests folder. See the table below for the qualiﬁcation and testing documentation history.

Revision history of FreeRTOS porting and qualiﬁcation documentation

Date Documentation version

for the Porting and Qualiﬁcation guides

Change history FreeRTOS version

July, 2021 202107.00 (Porting Guide)

202107.00

(Qualiﬁcation Guide)

• Release 202107.00

• Changed Porting the AWS IoT over- the-air update library (p. 72)

• Added Migrating from version 1 to version 3 for OTA applications (p. 105)

• Added Migrating from version 1 to version 3 for OTA Pal port (p. 117)

202107.00

December, 2020 202012.00 (Porting Guide)

202012.00

• Release 202012.00

• Added Conﬁguring the coreHTTP library for testing (p. 71)

202012.00

(8)

Porting older versions of FreeRTOS

• Added Porting the Cellular Interface library (p. 102) November, 2020 202011.00 (Porting

Guide) 202011.00

• Release 202011.00

• Added Conﬁguring the coreMQTT library for testing (p. 70)

202011.00

July, 2020 202007.00 (Porting Guide)

202007.00

• Release 202007.00 202007.00

February 18, 2020 202002.00 (Porting Guide)

202002.00

• Release 202002.00

• Amazon FreeRTOS is now FreeRTOS

202002.00

December 17, 2019 201912.00 (Porting Guide)

201912.00

• Release 201912.00

• Added Porting the common I/O libraries (p. 93).

201912.00

October 29, 2019 201910.00 (Porting Guide)

201910.00

• Release 201910.00

• Updated random number generator porting information.

201910.00

August 26, 2019 201908.00 (Porting Guide)

201908.00

• Release 201908.00

• Added Conﬁguring the HTTPS client library for testing Updated Porting the corePKCS11 library (p. 47)

201908.00

June 17, 2019 201906.00 (Porting Guide)

201906.00

• Release 201906.00

• Directory structured updated

201906.00 Major

(9)

May 21, 2019 1.4.8 (Porting Guide) 1.4.8 (Qualiﬁcation Guide)

• Porting documentation moved to the FreeRTOS Porting Guide

• Qualiﬁcation documentation moved to the FreeRTOS

Qualiﬁcation Guide

1.4.8

February 25, 2019 1.1.6 • Removed download

and conﬁguration instructions from Getting Started Guide Template Appendix (page 84)

1.4.5 1.4.6 1.4.7

December 27, 2018 1.1.5 • Updated Checklist

for Qualiﬁcation appendix with CMake requirement (page 70)

1.4.5 1.4.6

December 12, 2018 1.1.4 • Added lwIP porting

instructions to TCP/

IP porting appendix (page 31)

1.4.5

November 26, 2018 1.1.3 • Added Bluetooth

Low Energy porting appendix (page 52)

• Added AWS IoT Device Tester for FreeRTOS testing information throughout document

• Added CMake link to Information for listing on the FreeRTOS Console appendix (page 85)

1.4.4

(10)

November 7, 2018 1.1.2 • Updated PKCS #11

PAL interface porting instructions in PKCS

#11 porting appendix (page 38)

• Updated path to

CertificateConfigurator.html (page 76)

• Updated Getting Started Guide Template appendix (page 80)

1.4.3

October 8, 2018 1.1.1 • Added new "Required

for AFQP" column to

aws_test_runner_config.h test conﬁguration

table (page 16)

• Updated Unity module directory path in Create the Test Project section (page 14)

• Updated

"Recommended Porting Order" chart (page 22)

• Updated client certiﬁcate and key variable names in TLS appendix, Test Setup (page 40)

• File paths changed in Secure Sockets porting appendix, Test Setup (page 34);

TLS porting appendix, Test Setup (page 40);

and TLS Server Setup appendix (page 57)

1.4.2

August 27, 2018 1.1.0 • Added OTA Updates

porting appendix (page 47)

• Added Bootloader porting appendix (page 51)

1.4.0 1.4.1

(11)

Porting FAQs

August 9, 2018 1.0.1 • Updated

"Recommended Porting Order" chart (page 22)

• Updated PKCS #11 porting appendix (page 36)

• File paths changed in TLS porting appendix, Test Setup (page 40), and TLS Server Setup appendix, step 9 (page 51)

• Fixed hyperlinks in MQTT porting appendix,

Prerequisites (page 45)

• Added AWS CLI conﬁg instructions to examples in Instructions to Create a BYOC appendix (page 57)

1.3.1 1.3.2

July 31, 2018 1.0.0 Initial version of the

FreeRTOS Qualiﬁcation Program Guide

1.3.0

Porting FAQs

What is a FreeRTOS port?

A FreeRTOS port is a board-speciﬁc implementation of APIs for the required FreeRTOS libraries and the FreeRTOS that your platform supports. The port enables the APIs to work on the board, and implements the required integration with the device drivers and BSPs that are provided by the platform vendor. Your port should also include any conﬁguration adjustments (e.g. clock rate, stack size, heap size) that are required by the board.

My device does not support Wi-Fi, Bluetooth Low Energy, or over-the-air (OTA) updates. Are all libraries required to port FreeRTOS?

The primary requirement for porting FreeRTOS connectivity libraries is that your device can connect to the cloud. If, for example, you can connect to the cloud across a secure Ethernet connection, the Wi-Fi, Bluetooth Low Energy, and over-the-air (OTA) libraries are not required. Keep in mind that some test and demo applications will not work without porting all of the libraries.

Can I reach an "echo server" from two diﬀerent networks (for example, from two subnets across 2 diﬀerent access points)?

An echo server is required to pass the TCP/IP and TLS port tests. The echo server must be reachable from the network that a board is connected to. Please consult your IT support to enable routing across subnets if you need devices on diﬀerent subnets to communicate with a single echo server.

(12)

Porting FAQs

What network ports need to be open to run the FreeRTOS port tests?

The following network connections are required to run the FreeRTOS port tests:

Port Protocol

443, 8883 MQTT

8443 Greengrass Discovery

If you have questions about porting that are not answered on this page or in the rest of the FreeRTOS Porting Guide, please contact the FreeRTOS engineering team.

(13)

Downloading FreeRTOS for Porting

Before you begin porting FreeRTOS to your platform, you need to download FreeRTOS or clone the FreeRTOS repository from GitHub. See the README.md ﬁle for instructions.

Note

We recommend that you clone the repository. Cloning makes it easier for you to pick up updates to the main branch as they are pushed to the repository.

After you download or clone FreeRTOS, you can start porting FreeRTOS code to your platform. For instructions, see Setting Up Your FreeRTOS Source Code for Porting (p. 9), and then see Porting the FreeRTOS Libraries (p. 25).

Note

Throughout FreeRTOS documentation, the FreeRTOS download is referred to as freertos.

(14)

Conﬁguring the FreeRTOS download

Setting Up Your FreeRTOS Source Code for Porting

After you download FreeRTOS, you need to conﬁgure some of the ﬁles and folders in the FreeRTOS download before you can begin porting.

To prepare your FreeRTOS download for porting, you need to follow the instructions in Configuring the FreeRTOS download (p. 9) to configure the directory structure of your FreeRTOS download to fit your device.

If you plan to test the ported libraries as you implement them for debugging purposes, you also need to conﬁgure some ﬁles for testing before you begin porting. For instructions on test set up, see Setting up your FreeRTOS source code for testing (p. 11).

Note

You must use the AWS IoT Device Tester for FreeRTOS to oﬃcially validate your ports for qualiﬁcation. For more information about AWS IoT Device Tester for FreeRTOS, see Using AWS IoT Device Tester for FreeRTOS in the FreeRTOS User Guide.

For information about qualifying your device for FreeRTOS, see the FreeRTOS Qualiﬁcation Guide.

After you conﬁgure your FreeRTOS download and set up your testing environment, you can beginning porting FreeRTOS. For porting and testing instructions, see Porting the FreeRTOS Libraries (p. 25).

Conﬁguring the FreeRTOS download

Follow the instructions below to conﬁgure the FreeRTOS download for porting FreeRTOS code to your device.

Conﬁguring directories for vendor-supplied, board- speciﬁc libraries

Under the download's root directory (freertos), the vendors folder is structured as follows:

vendors

+ - vendor (Template, to be renamed to the name of the MCU vendor) + - boards

| + - board (Template, to be renamed to the name of the development board) | + - aws_demos

| + - aws_tests | + - CMakeLists.txt | + - ports

+ - driver_library (Template, to be renamed to the library name)

+ - driver_library_version (Template, to be renamed to the library version)

The vendor and board folders are template folders that we provide to make it easier to create demo and test projects. Their directory structure ensures that all demo and test projects have a consistent organization.

(15)

Conﬁguring directories for project ﬁles

The aws_tests folder has the following structure:

vendors/vendor/boards/board/aws_tests

+ - application_code (Contains main.c, which contains main())

| + - vendor_code (Contains vendor-supplied, board-specific files)

| + - main.c (Contains main())

+ - config_files (Contains FreeRTOS config files)

All test projects require vendor-supplied driver libraries. Some vendor-supplied files, such as a header file that maps GPIO output to an LED light, are specific to a target development board. These files belong in the vendor_code folder.

Other vendor-supplied ﬁles, such as a GPIO library, are common across a board's MCU family. These ﬁles belong in the driver_library folder.

To set up the directories for vendor-supplied libraries that are common across an MCU family

1. Save all required vendor-supplied libraries that are common across a target board's MCU family in

the driver_library_version folder.

2. Rename the vendor folder to the name of the vendor, and rename the driver_library and driver_library_version folders to the name of the driver library and its version.

Important

Do not save vendor-supplied libraries that are common across a target board's MCU family to any subdirectories of freertos/test or freertos/demos.

Conﬁguring directories for project ﬁles

Under freertos, the projects folder is structured as follows:

projects

+ - vendor (Template, to be renamed to the name of the MCU vendor)

+ - board (Template, to be renamed to the name of the development board) + - ide (Contains an IDE-specific project)

+ - visual_studio (contains project files for Visual Studio)

To set up the project directories

1. Rename the ide folder to the name of the IDE that you are using to build the test project.

2. Rename the vendor folder to the name of the vendor, and rename the board folder to the name of the development board.

Conﬁguring FreeRTOSConfig.h

After you have configured the directory structure of your FreeRTOS download, configure your board name in the FreeRTOSConfig.h configuration header file.

To conﬁgure your board name in FreeRTOSConfig.h

1. Open freertos/vendors/vendor/boards/board/aws_tests/config_files/

FreeRTOSConfig.h.

2. In the line #define configPLATFORM_NAME "Unknown", change Unknown to match the name of your board.

(16)

Setting up your FreeRTOS source code for testing

FreeRTOS includes tests for each ported library. The aws_test_runner.c file defines a RunTests function that runs each test that you have specified in the aws_test_runner_config.h header file.

As you port each FreeRTOS library, you can test the ports by building the ported FreeRTOS source code, ﬂashing the compiled code to your board, and running it on the board.

To build the FreeRTOS source code for testing, you can use either of the following:

• A supported IDE.

If you're using an IDE to build FreeRTOS source code, you need to set up an IDE test project. Follow the instructions in Creating an IDE project (p. 11) to create a test project in your IDE. Each library- speciﬁc porting section under Porting the FreeRTOS Libraries (p. 25) includes additional instructions for setting up a library's ported source ﬁles in the IDE test project.

• The CMake build system.

If you are using CMake, you need to create a CMakeLists.txt CMake list file. Follow the instructions in Creating a CMake list file (p. 12) to create a CMakeLists.txt CMake list file.

Important

A CMakeLists.txt ﬁle is required for listing a qualiﬁed device on the FreeRTOS console, regardless of the testing method that you use.

After you build the code, use your platform's ﬂash utility to ﬂash the compiled code to your device.

Note

You specify your build and flash tools in the userdata.json file for Device Tester, so if you are validating your ports with Device Tester, you do not need to flash your code manually.

Creating an IDE project

After you conﬁgure your FreeRTOS download, you can create an IDE project and import the code into the project.

Follow the instructions below to create an IDE project with the required IDE project structure for testing.

Important

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 to a project by linking to each source file individually.

1. Open your IDE, and create a project named aws_tests in the freertos/

projects/vendor/board/ide directory.

2. In the IDE, create two virtual folders under the aws_tests project:

• application_code

• config_files

Under aws_tests, there should now be two virtual folders in the IDE project: application_code and config_files.

Note

Eclipse generates an additional includes folder. This folder is not a part of the required structure.

3. Import all of the ﬁles under freertos/vendors/vendor/boards/board/aws_tests/

application_code and its subdirectories into the aws_tests/application_code virtual folder in your IDE.

(17)

Creating a CMake list ﬁle

4. Import all of the ﬁles under freertos/tests and its subdirectories into the aws_tests/

application_code virtual directory in your IDE.

5. Import all of the header ﬁles in the freertos/vendors/vendor/boards/board/aws_tests/

config_files directory into the aws_tests/config_files virtual folder in your IDE.

Note

If you are not porting a specific library, you do not need to import the files for that library into your project. For example, if you are not porting the OTA library, you can leave out the aws_ota_agent_config.h and aws_test_ota_config.h files. If you are not porting the Wi-Fi library, you can leave out the aws_test_wifi_config.h and aws_wifi_config.h files.

6. Import the required libraries in freertos/libraries and its subdirectories into the aws_tests IDE project, including any required third-party libraries. For information on the required libraries please follow the FreeRTOS porting ﬂowchart. Information about which FreeRTOS libraries depend on third-party libraries that need to be included in addition to the test project is provided in the speciﬁc library's porting section.

Finally, import the unity ﬁles from the following directories into your project.

• freertos/libraries/3rdparty/unity/src/

• freertos/libraries/3rdparty/unity/extras/fixture/src/

Note

If you are not porting a speciﬁc library, you do not need to import the ﬁles for that library into your project.

7. Import all of the source ﬁles in the freertos/freertos_kernel and freertos/

freertos_kernel/include directories into the aws_tests IDE project.

8. Import the subdirectory of freertos/freertos_kernel/portable that corresponds to your compiler and platform architecture into the aws_tests IDE project.

9. Import the FreeRTOS memory management implementation that you are using for your device into the aws_tests IDE project.

The freertos/freertos_kernel/portable/MemMang directory contains FreeRTOS memory management implementations. We highly recommend that you use heap_4.c or heap_5.c.

For more information about FreeRTOS memory management, see Memory Management.

10. Open your project's IDE properties, and add the following paths to your compiler's include path:

• freertos/vendors/vendor/boards/board/aws_tests/config_files

• freertos/freertos_kernel/include

• freertos/freertos_kernel/portable/compiler/architecture

• Any paths required for vendor-supplied driver libraries

11. Deﬁne UNITY_INCLUDE_CONFIG_H and AMAZON_FREERTOS_ENABLE_UNIT_TESTS as project-level macros in the project properties.

After you ﬁnish setting up your IDE project, you are ready to port the FreeRTOS libraries to your device.

For instructions, see Porting the FreeRTOS Libraries (p. 25).

Creating a CMake list ﬁle

After you conﬁgure your FreeRTOS download for porting, you can set up a CMake list ﬁle for your project and platform.

Topics

(18)

• Prerequisites (p. 13)

• Creating a list ﬁle for your platform from the CMakeLists.txt template (p. 13)

• Building FreeRTOS with CMake (p. 20)

Prerequisites

Make sure that your host machine meets the following prerequisites before you continue:

• Your device's compilation toolchain must support the machine's operating system. CMake supports all versions of Windows, macOS, and Linux.

Windows subsystem for Linux (WSL) is not supported. Use native CMake on Windows machines.

• You must have CMake version 3.13 or later installed.

You can download the binary distribution of CMake from CMake.org.

Note

If you download the binary distribution of CMake, make sure that you add the CMake executable to the PATH environment variable before you use CMake from command line.

You can also download and install CMake using a package manager, like homebrew on macOS, and scoop or chocolatey on Windows.

Note

The CMake package versions in the package managers for many Linux distributions are out-of- date. If your distribution's package manager does not include the latest version of CMake, you can try linuxbrew or nix.

• You must have a compatible native build system.

CMake can target many native build systems, including GNU Make or Ninja. Both Make and Ninja can be installed with package managers on Linux, macOS, and Windows. If you are using Make on Windows, you can install a standalone version from Equation, or you can install MinGW, which bundles Make.

Note

The Make executable in MinGW is called mingw32-make.exe, instead of make.exe.

We recommend that you use Ninja, because it is faster than Make and also provides native support to all desktop operating systems.

Creating a list ﬁle for your platform from the CMakeLists.txt template

A CMakeLists.txt template ﬁle is provided with FreeRTOS, under freertos/vendors/vendor/

boards/board/CMakeLists.txt.

The CMakeLists.txt template ﬁle consists of four sections:

• FreeRTOS console metadata (p. 14)

• Compiler settings (p. 15)

• FreeRTOS portable layers (p. 16)

• FreeRTOS demos and tests (p. 19)

Follow the instructions to edit these four sections of the list file to match your platform. You can refer to the CMakeLists.txt files for other qualified vendor boards under freertos/vendors as examples.

(19)

Two primary functions are called throughout the ﬁle:

afr_set_board_metadata(name value)

This function deﬁnes metadata for the FreeRTOS console. The function is deﬁned in freertos/

tools/cmake/afr_metadata.cmake.

afr_mcu_port(module_name [<DEPENDS> [targets...]])

This function deﬁnes the portable-layer target associated with a FreeRTOS module (that is, library). It creates a CMake GLOBAL INTERFACE IMPORTED target with a name of the form AFR:module_name::mcu_port. If DEPENDS is used, additional targets are linked with target_link_libraries. The function is deﬁned in freertos/tools/cmake/

afr_module.cmake.

FreeRTOS console metadata

The first section of the template file defines the metadata that is used to display a board's information in the FreeRTOS console. Use the function afr_set_board_metadata(name value) to define each field listed in the template. This table provides descriptions of each field.

Field Name Value Description

ID A unique ID for the board.

DISPLAY_NAME The name of the board as you want it displayed

on the FreeRTOS console.

DESCRIPTION A short description of the board for the FreeRTOS

console.

VENDOR_NAME The name of the vendor of the board.

FAMILY_NAME The name of the board's MCU family.

DATA_RAM_MEMORY The size of the board's RAM, followed by

abbreviated units. For example, use KB for kilobytes.

PROGRAM_MEMORY The size of the board's program memory, followed

by abbreviated units. For example, use "MB" for megabytes.

CODE_SIGNER The code-signing platform used for OTA updates.

Use AmazonFreeRTOS-Default for SHA256 hash algorithm and ECDSA encryption algorithm. If you want to use a diﬀerent code-signing platform, contact us.

SUPPORTED_IDE A semicolon-delimited list of IDs for the IDEs that the board supports.

IDE_ID_NAME The name of the supported IDE. Replace ID with

the ID listed for the IDE in the SUPPORTED_IDE ﬁeld.

IDE_ID_COMPILER A semicolon-delimited list of names of supported

compilers for the supported IDE. Replace ID with the ID listed for the IDE in the SUPPORTED_IDE ﬁeld.

(20)

Field Name Value Description

KEY_IMPORT_PROVISIONING Set to TRUE if the board demo project imports the credentials from the pre-provisioned aws_clientcredential_keys.h header ﬁle;

in this case, Quick Connect will be enabled in the FreeRTOS console.

Set to FALSE if the intended board provisioning mechanism is JITR/JITP or multi-account registration; in this case, Quick Connect will be disabled in the FreeRTOS console.

Compiler settings

The second section of the template ﬁle deﬁnes the compiler settings for your board. To create a target that holds the compiler settings, call the afr_mcu_port function with compiler in place of the module_name to create an INTERFACE target with the name AFR::compiler::mcu_port. The kernel publicly links to this INTERFACE target so that the compiler settings are transitively populated to all modules.

Use the standard, built-in CMake functions to deﬁne the compiler settings in this section of the list ﬁle.

As you deﬁne the compiler settings, follow these best practices:

• Use target_compile_definitions to provide compile deﬁnitions and macros.

• Use target_compile_options to provide compiler ﬂags.

• Use target_include_directories to provide include directories.

• Use target_link_options to provide linker ﬂags.

• Use target_link_directories to provide linker-search directories.

• Use target_link_libraries to provide libraries to link against.

Note

If you define the compiler settings somewhere else, you don't need to duplicate the information in this section of the file. Instead, call afr_mcu_port with DEPENDS to bring in the target definition from another location.

For example:

# your_target is defined somewhere else. It does not have to be in the same file.

afr_mcu_port(compiler DEPENDS your_target)

When you call afr_mcu_port with DEPENDS, it calls

target_link_libraries(AFR::module_name::mcu_port INTERFACE your_targets), which populates the compiler settings for the required AFR::compiler::mcu_port target.

Using multiple compilers

If your board supports multiple compilers, you can use the AFR_TOOLCHAIN variable to dynamically select the compiler settings. This variable is set to the name of the compiler you are using, which should be same as the name of the toolchain ﬁle found under freertos/tools/cmake/toolchains.

For example:

if("${AFR_TOOLCHAIN}" STREQUAL "arm-gcc")

afr_mcu_port(compiler DEPENDS my_gcc_settings).

(21)

elseif("${AFR_TOOLCHAIN}" STREQUAL "arm-iar") afr_mcu_port(compiler DEPENDS my_iar_settings).

else()

message(FATAL_ERROR "Compiler ${AFR_TOOLCHAIN} not supported.") endif()

Advanced compiler settings

If you want to set more advanced compiler settings, such as setting compiler ﬂags based on

programming language, or changing settings for diﬀerent release and debug conﬁgurations, you can use CMake generator expressions.

For example:

set(common_flags "-foo") set(c_flags "-foo-c") set(asm_flags "-foo-asm") target_compile_options(

my_compiler_settings INTERFACE

$<$<COMPILE_LANGUAGE:C>:${common_flags} ${c_flags}> # This only have effect on C files.

$<$<COMPILE_LANGUAGE:ASM>:${common_flags} ${asm_flags}> # This only have effect on ASM files.

)

CMake generator expressions are not evaluated at the conﬁguration stage, when CMake reads list ﬁles.

They are evaluated at the generation stage, when CMake finishes reading list files and generates build files for the target build system.

FreeRTOS portable layers

The third section of the template ﬁle deﬁnes all of the portable layer targets for FreeRTOS (that is, libraries).

You must use the afr_mcu_port(module_name) function to deﬁne a portable layer target for each FreeRTOS module that you plan to implement.

You can use any CMake functions you want, as long as the afr_mcu_port call creates a target with a name that provides the information required to build the corresponding FreeRTOS module.

The afr_mcu_port function creates a GLOBAL INTERFACE IMPORTED library target with a name of the form AFR::module_name::mcu_port. As a GLOBAL target, it can be referenced in CMake list ﬁles. As an INTERFACE target, it is not built as a standalone target or library, but compiled into the corresponding FreeRTOS module. As an IMPORTED target, its name includes a namespace (::) in the target name (for example, AFR::kernel::mcu_port).

Modules without corresponding portable layer targets are disabled by default. If you run CMake to conﬁgure FreeRTOS, without deﬁning any portable layer targets, you should see the following output:

FreeRTOS modules:

Modules to build:

Disabled by user:

Disabled by dependency: kernel, posix, pkcs11, secure_sockets, mqtt, ...

Available demos:

Available tests:

As you update the CMakeLists.txt ﬁle with porting layer targets, the corresponding FreeRTOS modules are enabled. You should also be able to build any FreeRTOS module whose dependency

(22)

requirements are subsequently satisﬁed. For example, if the coreMQTT library is enabled, the Device Shadow library is also enabled, because its only dependency is the coreMQTT library.

Note

The FreeRTOS kernel dependency is a minimum requirement. The CMake conﬁguration fails if the FreeRTOS kernel dependency is not satisﬁed.

Setting up the kernel porting target

To create the kernel porting target (AFR::kernel::mcu_port), call afr_mcu_port with the module name kernel. When you call afr_mcu_port, specify the targets for the FreeRTOS portable layer and driver code. After you create the target, you can provide the dependency information and the FreeRTOS portable layer and driver code information for the target to use.

Follow these instructions to set up the kernel porting target.

To set up the kernel porting target

1. Create a target for the driver code.

For example, you can create a STATIC library target for the driver code:

add_library(my_board_driver STATIC ${driver_sources})

# Use your compiler settings target_link_libraries(

my_board_driver

PRIVATE AFR::compiler::mcu_port

# Or use your own target if you already have it.

# PRIVATE ${compiler_settings_target}

)

target_include_directories(

my_board_driver

PRIVATE "include_dirs_for_private_usage"

PUBLIC "include_dirs_for_public_interface"

)

Or you can create an INTERFACE library target for the driver code:

# No need to specify compiler settings since kernel target has them.

add_library(my_board_driver INTERFACE ${driver_sources})

Note

An INTERFACE library target does not have build output. If you use an INTERFACE library target, the driver code is compiled into the kernel library.

2. Conﬁgure the FreeRTOS portable layer:

add_library(freertos_port INTERFACE) target_sources(

freertos_port INTERFACE

"${AFR_MODULES_DIR}/freertos_kernel/portable/GCC/ARM_CM4F/port.c"

"${AFR_MODULES_DIR}/freertos_kernel/portable/GCC/ARM_CM4F/portmacro.h"

"${AFR_MODULES_DIR}/freertos_kernel/portable/MemMang/heap_4.c"

)target_include_directories(

freertos_port INTERFACE

"${AFR_MODULES_DIR}/freertos_kernel/portable/GCC/ARM_CM4F"

"${include_path_to_FreeRTOSConfig_h}

(23)

)

Note

You can also conﬁgure the FreeRTOS portable layer by specifying these source ﬁles and their include directories directly in the AFR::kernel::mcu_port target.

3. Create the kernel portable layer target:

# Bring in driver code and freertos portable layer dependency.

afr_mcu_port(kernel DEPENDS my_board_driver freertos_port)

# If you need to specify additional configurations, use standard CMake functions with

# AFR::kernel::mcu_port as the target name.

target_include_directories(

AFR::kernel::mcu_port INTERFACE

"${additional_includes}" # e.g. board configuration files )target_link_libraries(

AFR::kernel::mcu_port INTERFACE

"${additional_dependencies}"

)

4. To test your list ﬁle and conﬁguration, you can write a simple application that uses the FreeRTOS kernel port. For more information about developing and building FreeRTOS applications with CMake, see Building FreeRTOS with CMake (p. 20).

5. After you create the demo, add add_executable and target_link_libraries calls to the list ﬁle, and compile the kernel as a static library to verify that the kernel portable layer is correctly conﬁgured.

add_executable(

my_demo main.c

)target_link_libraries(

my_demo

PRIVATE AFR::kernel )

Setting up the porting targets for FreeRTOS modules

After you add the portable layer target for the kernel, you can add portable layer targets for other FreeRTOS modules.

For example, to add the portable layer for the Wi-Fi module:

afr_mcu_port(wifi) target_sources(

AFR::wifi::mcu_port

INTERFACE "${AFR_MODULES_DIR}/vendors/vendor/boards/board/ports/wifi/iot_wifi.c"

)

This example Wi-Fi module portable layer has only one implementation ﬁle, which is based on the driver code.

If you want to add the portable layer for the FreeRTOS Secure Sockets module, the module depends on TLS. This makes its portable layer target slightly more complicated than that of the Wi-Fi module.

FreeRTOS provides a default TLS implementation based on mbedTLS that you can link to:

(24)

afr_mcu_port(secure_sockets) target_sources(

AFR::secure_sockets::mcu_port INTERFACE ${portable_layer_sources}

)target_link_libraries(

AFR::secure_sockets::mcu_port AFR::tls

)

In this example code, the standard CMake function target_link_libraries states that the Secure Sockets portable layer depends on AFR::tls.

You can reference all FreeRTOS modules by using their target name AFR::module_name. For example, you can use the same syntax to also state a dependency on FreeRTOS-Plus-TCP:

target_link_libraries(

AFR::secure_sockets::mcu_port AFR::freertos_plus_tcp AFR::tls

)

Note

If your platform handles TLS by itself, you can use your driver code directly. If you use your driver code directly for TLS, you don't need to call target_link_libraries, because all FreeRTOS modules implicitly depend on the kernel that includes your driver code.

Because all non-kernel FreeRTOS modules implicitly depend on the kernel, their porting layers don't require you to specify the kernel as a dependency. The POSIX module, however, is deﬁned as an optional kernel module. If you want to use POSIX, you must explicitly include it in your kernel portable layer. For example:

# By default, AFR::posix target does not expose standard POSIX headers in its public

# interface, i.e., You need to use "freertos_plus_posix/source/

FreeRTOS_POSIX_pthread.c" instead of "pthread.h".

# Link to AFR::use_posix instead if you need to use those headers directly.

target_link_libraries(

AFR::kernel::mcu_port INTERFACE AFR::use_posix )

FreeRTOS demos and tests

The final section of the template file defines the demo and test targets for FreeRTOS. CMake targets are created automatically for each demo and test that satisfies the dependency requirements.

In this section, deﬁne an executable target with the add_executable function. Use aws_tests as the target name if you're compiling tests, or aws_demos if you're compiling demos. You might need to provide other project settings, such as linker scripts and post-build commands. For example:

if(AFR_IS_TESTING)

set(exe_target aws_tests) else()

set(exe_target aws_demos) endif()

set(CMAKE_EXECUTABLE_SUFFIX ".elf")

add_executable(${exe_target} "${board_dir}/application_code/main.c")

(25)

target_link_libraries is then called to link available CMake demo or test targets to your executable target.

Note

You still need to modify aws_demos/config_files/aws_demo_config.h and aws_tests/

config_files/aws_test_runner_config.h to enable demos and tests.

Running post-build commands

For information about running post-build commands, see add_custom_command. Use the second signature. For example:

# This should run an external command "command --arg1 --arg2".

add_custom_command(

TARGET ${exe_target} POST_BUILD COMMAND "command" "--arg1" "--arg2"

)

Note

CMake supports many common, platform-independent operations for creating directories, copying ﬁles, and so on. For more information about CMake command-line operations, see the CMake command-line tool reference. You can reference the CMake command-line tool from a CMake list ﬁle with the built-in variable ${CMAKE_COMMAND}.

Building FreeRTOS with CMake

CMake targets your host operating system as the target system by default. To use CMake for cross compiling, you must provide a toolchain file that specifies the compiler that you want to use. FreeRTOS provides some default toolchain files in freertos/tools/cmake/toolchains. The instructions for using the toolchain file differ depending on whether you are using the CMake command-line interface or the GUI. Generating build files (CMake command-line tool) (p. 20) has more details. To learn more about cross-compiling in CMake, visit the Cross Compiling on the official CMake Wiki.

To build a CMake-based project

1. Run CMake to generate the build ﬁles for a native build system, like Make or Ninja.

You can use either the CMake command-line tool or the CMake GUI to generate the build ﬁles for your native build system.

For information about generating FreeRTOS build files, see Generating build files (CMake command- line tool) (p. 20) and Generating build files (CMake GUI) (p. 21).

2. Invoke the native build system to make the project into an executable.

For information about making FreeRTOS build ﬁles, see Building FreeRTOS from generated build ﬁles (p. 24).

Generating build ﬁles (CMake command-line tool)

You can use the CMake command-line tool (cmake) to generate build ﬁles for FreeRTOS from the command line.

To generate the build ﬁles, you must specify the target board, compiler and the locations of your source code and build directory. Specify the target board with the -DVENDOR option. Specify the compiler with the -DCOMPILER option. Specify the location of your source code with the -S switch and the location of the generated build ﬁles with the -B switch.

Note

The compiler must be in the system's PATH variable, otherwise you must specify the location of the compiler.

(26)

For example, if the vendor is Texas Instruments, and the board is the CC3220 Launchpad, and the compiler is GCC for ARM, you can issue the following command to build from the source ﬁles located in the current directory to a directory named build-directory:

cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory

Note

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

cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build- directory -G Ninja

Or:

cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build- directory -G "MinGW Makefiles"

The regular expressions ${VENDOR}.* and ${BOARD}.* are used to search for a matching board, so you don't have to use the full names of the vendor and board for the VENDOR and BOARD options. Partial names work, provided there is a single match. For example, the following commands generate the same build ﬁles from the same source:

cmake -DVENDOR=ti -DCOMPILER=arm-ti -S . -B build-directory

cmake -DBOARD=cc3220 -DCOMPILER=arm-ti -S . -B build-directory

cmake -DVENDOR=t -DBOARD=cc -DCOMPILER=arm-ti -S . -B build-directory

You can use the CMAKE_TOOLCHAIN_FILE option if you want to use a toolchain ﬁle that is not located in the default directory cmake/toolchains. For example:

cmake -DBOARD=cc3220 -DCMAKE_TOOLCHAIN_FILE='/path/to/toolchain_file.cmake' -S . -B build- directory

If the toolchain file does not use absolute paths for your compiler, and you didn't add your compiler to the PATH environment variable, CMake might not be able to find it. To make sure that CMake finds your toolchain file, you can use the AFR_TOOLCHAIN_PATH option. This option searches the specified toolchain directory path and the toolchain's subfolder under bin. For example:

cmake -DBOARD=cc3220 -DCMAKE_TOOLCHAIN_FILE='/path/to/toolchain_file.cmake' - DAFR_TOOLCHAIN_PATH='/path/to/toolchain/' -S . -B build-directory

To enable debugging, set the CMAKE_BUILD_TYPE to debug. With this option enabled, CMake adds debug ﬂags to the compile options, and builds FreeRTOS with debug symbols.

# Build with debug symbols

cmake -DBOARD=cc3220 -DCOMPILER=arm-ti -DCMAKE_BUILD_TYPE=debug -S . -B build-directory

You can also set the CMAKE_BUILD_TYPE to release to add optimization ﬂags to the compile options.

Generating build ﬁles (CMake GUI)

You can use the CMake GUI to generate FreeRTOS build ﬁles.

(27)

To generate build ﬁles with the CMake GUI

1. From the command line, issue cmake-gui to start the GUI.

2. Choose Browse Source and specify the source input, and then choose Browse Build and specify the build output.

3. Choose Configure, and under Specify the build generator for this project, find and choose the build system that you want to use to build the generated build files.

Note

If you do not see the pop up window, you might be reusing an existing build directory. In this case, delete the CMake cache ﬁrst by clicking File->Delete Cache in the menu.

4. Choose Specify toolchain ﬁle for cross-compiling, and then choose Next.

5. Choose the toolchain ﬁle (for example, freertos/tools/cmake/toolchains/arm-ti.cmake), and then choose Finish.

The default conﬁguration for FreeRTOS is the template board, which does not provide any portable layer targets. As a result, a window appears with the message Error in conﬁguration process.

Note

If you see the following error message:

(28)

CMake Error at tools/cmake/toolchains/find_compiler.cmake:23 (message):

Compiler not found, you can specify search path with "AFR_TOOLCHAIN_PATH".

It means the compiler is not in your environment variable PATH. You can set the

AFR_TOOLCHAIN_PATH variable in the GUI to tell CMake where you installed your compiler.

If you do not see the AFR_TOOLCHAIN_PATH variable, click the Add Entry button in the pop up window, enter AFR_TOOLCHAIN_PATH as the name, select PATH as the type, and enter the compiler path in the value, for example, "C:/toolchains/arm-none-eabi-gcc".

6. The GUI should now look like this:

Choose AFR_BOARD, choose your board, and then choose Conﬁgure again.

7. Choose Generate. CMake generates the build system files (for example, makefiles or ninja files), and these files appear in the build directory you specified in the first step. Follow the instructions in the next section to generate the binary image.

(29)

Building FreeRTOS from generated build ﬁles

You can build FreeRTOS with a native build system by calling the build system command from the output binaries directory. For example, if your build ﬁle output directory is build-directory, and you are using Make as your native build system, run the following commands:

cd build-directory make -j4

You can also use the CMake command-line tool to build FreeRTOS. CMake provides an abstraction layer for calling native build systems. For example:

cmake --build build-directory

Here are some other common uses of the CMake command-line tool's build mode:

# Take advantage of CPU cores.

cmake --build build-directory --parallel 8

# Build specific targets.

cmake --build build-directory --target afr_kernel

# Clean first, then build.

cmake --build build-directory --clean-first

For more information about the CMake build mode, see the CMake documentation.

(30)

Porting the FreeRTOS Libraries

Before you start porting, follow the instructions in Setting Up Your FreeRTOS Source Code for Porting (p. 9).

To port FreeRTOS to your device, follow the instructions in the topics below.

1.Implementing the configPRINT_STRING() macro (p. 28) 2.Conﬁguring a FreeRTOS kernel port (p. 29)

3.Porting the Wi-Fi library (p. 30)

Note

If your device does not support Wi-Fi, you can use an ethernet connection to connect to the AWS Cloud instead. A port of the FreeRTOS Wi-Fi library is not necessarily required.

4.Porting a TCP/IP stack (p. 36)

5.Porting the Secure Sockets library (p. 40) 6.Porting the corePKCS11 library (p. 47) 7.Porting the TLS library (p. 52)

8.Conﬁguring the coreMQTT library for testing (p. 70) 9.Conﬁguring the coreHTTP library for testing (p. 71) 10.Porting the AWS IoT over-the-air update library (p. 72)

Note

Currently, a port of the FreeRTOS OTA update library is not required for qualiﬁcation.

11.Porting the Bluetooth Low Energy library (p. 81)

Note

Currently, a port of the FreeRTOS Bluetooth Low Energy library is not required for qualiﬁcation.

12.Perform Over the Air Updates using Bluetooth Low Energy (p. 85)

Note

Currently AWS IoT Device Tester does not support qualiﬁcation of Over the Air updates using Bluetooth Low Energy library. A partner interested in this qualiﬁcation should contact AWS through the APN (AWS Partner Network) team.

13.Porting the common I/O libraries (p. 93)

Note

Currently, a port of the FreeRTOS common I/O library is not required for qualiﬁcation.

14.Porting the Cellular Interface library (p. 102)

Note

Currently, a port of the FreeRTOS Cellular Interface library is not required for qualiﬁcation.

After you port FreeRTOS to your board, you can oﬃcially validate the ports for FreeRTOS qualiﬁcation with AWS IoT Device Tester for FreeRTOS. For more information about AWS IoT Device Tester for FreeRTOS, see Using AWS IoT Device Tester for FreeRTOS in the FreeRTOS User Guide.

Note

Before you validate your port of FreeRTOS using the AWS IoT Device Tester for FreeRTOS you must remove any logging messages that you might have inserted in your code for testing purposes, otherwise the validation may fail.

(31)

Porting ﬂowchart

For information about qualifying your device for FreeRTOS, see the FreeRTOS Qualiﬁcation Guide.

FreeRTOS porting ﬂowchart

Use the ﬂowchart below as a visual aid as you port FreeRTOS to your device.

(32)

Porting ﬂowchart

(33)

configPRINT_STRING()

Implementing the configPRINT_STRING() macro

You must implement the configPRINT_STRING() macro before you port the FreeRTOS libraries.

FreeRTOS uses configPRINT_STRING() to output test results as human-readable ASCII strings.

Prerequisites

To implement the configPRINT_STRING() macro, you need the following:

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

• A FreeRTOS project conﬁgured for your platform, and a porting-test IDE project.

For information, see Setting Up Your FreeRTOS Source Code for Porting (p. 9).

Implementation

To implement configPRINT_STRING()

1. Connect your device to a terminal emulator to output test results.

2. Open the ﬁle freertos/vendors/vendor/boards/board/aws_tests/application_code/

main.c, and locate the call to configPRINT_STRING("Test Message") in the prvMiscInitialization() function.

3. Immediately before the call to configPRINT_STRING("Test Message"), add code that uses the vendor-supplied UART driver to initialize the UART baud rate level to 115200.

4. Open freertos/vendors/vendor/boards/board/aws_tests/config_files/

FreeRTOSConfig.h, and locate the empty deﬁnition of configPRINT_STRING(). The macro takes a NULL-terminated ASCII C string as its only parameter.

5. Update the empty deﬁnition of configPRINT_STRING() so that it calls the vendor-supplied UART output function.

For example, suppose the UART output function has the following prototype:

void MyUARTOutput( char *DataToOutput, size_t LengthToOutput );

You would implement configPRINT_STRING() as:

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

Testing

Build and execute the test demo project. If Test Message appears in the UART console, then the console is connected and conﬁgured correctly, configPRINT_STRING() is behaving properly, and testing is complete. You can remove the call to configPRINT_STRING("Test Message") from prvMiscInitialization().

After you implement the configPRINT_STRING() macro, you can start conﬁguring a FreeRTOS kernel port for your device. See Conﬁguring a FreeRTOS kernel port (p. 29) for instructions.

(34)

FreeRTOS kernel

Conﬁguring a FreeRTOS kernel port

This section provides instructions for integrating a port of the FreeRTOS kernel into a FreeRTOS port- testing project. For a list of available kernel ports, see FreeRTOS Kernel Ports.

FreeRTOS uses the FreeRTOS kernel for multitasking and inter-task communications. For more information, see the FreeRTOS Kernel Fundamentals in the FreeRTOS User Guide and FreeRTOS.org.

Note

Porting the FreeRTOS kernel to a new architecture is out of the scope of this documentation. If you are interested in porting the FreeRTOS kernel to a new architecture, contact the FreeRTOS engineering team.

For the FreeRTOS Qualification program, only existing ports are supported. Modifications to these ports are not accepted within the Qualification program. Only the official ports that can be downloaded from Github are accepted.

Prerequisites

To set up the FreeRTOS kernel for porting, you need the following:

• An oﬃcial FreeRTOS kernel port for the target platform.

• An IDE project or CMakeLists.txt list ﬁle that includes the correct FreeRTOS kernel port ﬁles for the target platform and compiler.

For information about setting up a test project, see Setting Up Your FreeRTOS Source Code for Porting (p. 9).

• An implementation of the configPRINT_STRING() macro for your device.

For information about implementing configPRINT_STRING(), see Implementing the configPRINT_STRING() macro (p. 28).

Conﬁguring the FreeRTOS kernel

The header ﬁle freertos/vendors/vendor/boards/board/aws_tests/config_files/

FreeRTOSConfig.h specifies application-specific configuration settings for the FreeRTOS kernel. For a description of each configuration option, see Customisation on FreeRTOS.org.

To configure the FreeRTOS kernel to work with your device, open FreeRTOSConfig.h, and verify that the configuration options in the following table are correctly specified for your platform.

Conﬁguration option Description

configCPU_CLOCK_HZ Speciﬁes the frequency of the clock used to generate the tick interrupt.

configMINIMAL_STACK_SIZE Specifies the minimum stack size. As a starting point, this can be set to the value used in the official FreeRTOS demo for the FreeRTOS kernel port in use. Official FreeRTOS demos are those distributed from the FreeRTOS.org website. Make sure that stack 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.

(35)

Testing

Conﬁguration option Description

configTOTAL_HEAP_SIZE Sets the size of the FreeRTOS heap. Like task stack sizes, the heap size can be tuned to ensure unused heap space does not consume RAM.

Note

If you are porting ARM Cortex-M3, M4, or M7 devices, you must also specify configPRIO_BITS and configMAX_SYSCALL_INTERRUPT_PRIORITY correctly.

Testing

1. Open /libraries/freertos_plus/standard/utils/src/iot_system_init.c, and comment out the line that calls SOCKETS_Init() from within function SYSTEM_Init(). This initialization function belongs to a library that you haven't ported yet. The porting section for this library includes instructions to uncomment this function.

2. Build the test project, and then ﬂash it to your device for execution.

3. If "." appears in the UART console every 5 seconds, then the FreeRTOS kernel is conﬁgured correctly, and testing is complete.

Open freertos/vendors/vendor/boards/board/aws_tests/config_files/

FreeRTOSConfig.h, and set configUSE_IDLE_HOOK to 0 to stop the kernel from executing vApplicationIdleHook() and outputting ".".

4. If "." appears at any frequency other than 5 seconds, open FreeRTOSConfig.h and verify that configCPU_CLOCK_HZ is set to the correct value for your board.

After you have conﬁgured the FreeRTOS kernel port for your device, you can start porting the Wi-Fi library. See Porting the Wi-Fi library (p. 30) for instructions.

Porting the Wi-Fi library

The FreeRTOS Wi-Fi library interfaces with vendor-supplied Wi-Fi drivers. For more information about the FreeRTOS Wi-Fi library, see FreeRTOS Wi-Fi Library in the FreeRTOS User Guide.

If your device does not support Wi-Fi networking, you can skip porting the FreeRTOS Wi-Fi library and start Porting a TCP/IP stack (p. 36).

Note

For qualiﬁcation, your device must connect to the AWS Cloud. If your device does not support Wi-Fi, you can use an Ethernet connection instead. A port of the FreeRTOS Wi-Fi library is not necessarily required.

Prerequisites

To port the Wi-Fi library, you need the following:

• An IDE project or CMakeLists.txt list ﬁle that includes the vendor-supplied Wi-Fi drivers.

For information about setting up a test project, see Setting Up Your FreeRTOS Source Code for Porting (p. 9).

• A validated conﬁguration of the FreeRTOS kernel.

(36)

Porting

For information about conﬁguring the FreeRTOS kernel for your platform, see Conﬁguring a FreeRTOS kernel port (p. 29).

• Two wireless access points.

Porting

freertos/vendors/vendor/boards/board/ports/wifi/iot_wifi.c contains empty deﬁnitions of a set of Wi-Fi management functions. Use the vendor-supplied Wi-Fi driver library to implement at least the set of functions listed in the following table.

Function Description

WIFI_On Turns on Wi-Fi module and initializes the drivers.

WIFI_ConnectAP Connects to a Wi-Fi access point (AP).

WIFI_Disconnect Disconnects from an AP.

WIFI_Scan Performs a Wi-Fi network scan.

WIFI_GetIP Retrieves the Wi-Fi interface’s IP address.

WIFI_GetMAC Retrieves the Wi-Fi interface’s MAC address.

WIFI_GetHostIP Retrieves the host IP address from a hostname

using DNS.

freertos/libraries/abstractions/wifi/include/iot_wifi.h provides the information required to implement these functions.

Testing

If you're using an IDE to build test projects, you need to set up your library port in the IDE project.

Setting up the IDE test project

If you're using an IDE for porting and testing, you need to add some source ﬁles to the IDE test project before you can test your ported code.

Important

In the following steps, make sure that you add the source ﬁles to your IDE project from their on- disk location. Don't create duplicate copies of source ﬁles.

To set up the Wi-Fi library in the IDE project

1. Add the source ﬁle freertos/vendors/vendor/boards/board/ports/wifi/iot_wifi.c to your aws_tests IDE project.

2. Add the source ﬁle aws_test_wifi.c to the aws_tests IDE project.

Conﬁguring the CMakeLists.txt ﬁle

If you are using CMake to build your test project, you need to deﬁne a portable layer target for the library in your CMake list ﬁle.

(37)

Testing

To deﬁne a library's portable layer target in CMakeLists.txt, follow the instructions in FreeRTOS portable layers (p. 16).

The CMakeLists.txt template list ﬁle under freertos/vendors/vendor/boards/board/

CMakeLists.txt includes example portable layer target definitions. You can uncomment the definition for the library that you are porting, and modify it to fit your platform.

See below for an example portable layer target deﬁnition for the Wi-Fi library.

# WiFi

afr_mcu_port(wifi) target_sources(

AFR::wifi::mcu_port

INTERFACE "freertos/vendors/vendor/boards/board/ports/wifi/iot_wifi.c"

)

Setting up your local testing environment

After you set up the library in the IDE project, you need to conﬁgure some other ﬁles for testing.

To conﬁgure the source and header ﬁles for the Wi-Fi tests

1. Open freertos/vendors/vendor/boards/board/aws_tests/application_code/

main.c, and delete the #if 0 and #endif compiler directives in the function deﬁnitions of vApplicationDaemonTaskStartupHook(void) and prvWifiConnect(void).

2. If you have not ported the Secure Sockets library, open freertos/libraries/freertos_plus/

standard/utils/src/iot_system_init.c, and comment out the line that calls

SOCKETS_Init(). When you reach the Porting the Secure Sockets library (p. 40) section, you will be instructed to uncomment this initialization function call.

3. Open freertos/tests/include/aws_clientcredential.h, and set the macros in the following table for the ﬁrst AP.

Macro Value

clientcredentialWIFI_SSID The Wi-Fi SSID as a C string (in quotation marks).

clientcredentialWIFI_PASSWORD The Wi-Fi password as a C string (in quotation marks).

clientcredentialWIFI_SECURITY One of the following:

• eWiFiSecurityOpen

• eWiFiSecurityWEP

• eWiFiSecurityWPA

• eWiFiSecurityWPA2

eWiFiSecurityWPA2 is recommended.

4. Open freertos/libraries/abstractions/wifi/test/aws_test_wifi.h, and set the macros in the following table for the second AP.

(38)

Testing

Macro Value

testWIFI_SSID The Wi-Fi SSID as a C string (in quotation

marks).

testWIFI_PASSWORD The Wi-Fi password as a C string (in quotation marks).

testWIFI_SECURITY One of the following:

• eWiFiSecurityOpen

• eWiFiSecurityWEP

• eWiFiSecurityWPA

• eWiFiSecurityWPA2

eWiFiSecurityWPA2 is recommended.

5. To enable the Wi-Fi tests, open freertos/vendors/vendor/boards/board/aws_tests/

config_files/aws_test_runner_config.h, and set the testrunnerFULL_WIFI_ENABLED to 1.

Important

The following tests require a port of the Secure Sockets library and a running echo server:

• WiFiConnectionLoop

• WiFiIsConnected

• WiFiConnectMultipleAP

You won't be able to pass these tests until you port the Secure Sockets library and start an echo server. After you port the Secure Sockets library and start an echo server, rerun the Wi-Fi tests to be sure that all tests pass. For information about porting the Secure Sockets library, see Porting the Secure Sockets library (p. 40). For information about setting up an echo server, see Setting up an echo server (p. 45).

Running the tests

To execute the Wi-Fi tests

1. Build the test project, and then ﬂash it to your device for execution.

2. Check the test results in the UART console.

(39)

Testing

...

(40)

Validation

To officially qualify a device for FreeRTOS, you need to validate the device's ported source code with AWS IoT Device Tester. Follow the instructions in Using AWS IoT Device Tester for FreeRTOS in the FreeRTOS User Guide to set up Device Tester for port validation. To test a specific library's port, the correct test group must be enabled in the device.json file in the Device Tester configs folder.

Porting Guide FreeRTOS

FreeRTOS

Porting Guide

FreeRTOS: Porting Guide

Table of Contents

FreeRTOS Porting

What is FreeRTOS?

Porting FreeRTOS to your IoT device

To port FreeRTOS to your device

System requirements

Porting older versions of FreeRTOS

Revision history of FreeRTOS porting and qualiﬁcation documentation

Porting FAQs

Downloading FreeRTOS for Porting

Note

Note

Setting Up Your FreeRTOS Source Code for Porting

Note

Conﬁguring the FreeRTOS download

Conﬁguring directories for vendor-supplied, board- speciﬁc libraries

To set up the directories for vendor-supplied libraries that are common across an MCU family

Important

Conﬁguring directories for project ﬁles

To set up the project directories

Conﬁguring FreeRTOSConfig.h

To conﬁgure your board name in FreeRTOSConfig.h

Setting up your FreeRTOS source code for testing

Important

Note

Creating an IDE project

Important

Note

Note

Note

Creating a CMake list ﬁle

Prerequisites

Note

Note

Note

Creating a list ﬁle for your platform from the CMakeLists.txt template

FreeRTOS console metadata

Compiler settings

Note

FreeRTOS portable layers

Note

To set up the kernel porting target

Note

Note

Note

FreeRTOS demos and tests

Note

Note

Building FreeRTOS with CMake

To build a CMake-based project

Generating build ﬁles (CMake command-line tool)

Note

Note

Generating build ﬁles (CMake GUI)

To generate build ﬁles with the CMake GUI

Note

Note

Building FreeRTOS from generated build ﬁles

Porting the FreeRTOS Libraries

Note

Note

Note

Note

Note

Note

Note

FreeRTOS porting ﬂowchart

Implementing the configPRINT_STRING() macro

Prerequisites

Implementation

To implement configPRINT_STRING()

Testing

Conﬁguring a FreeRTOS kernel port

Note

Prerequisites

Conﬁguring the FreeRTOS kernel