Amazon FreeRTOS
Porting Guide

Porting FreeRTOS+TCP

FreeRTOS+TCP is a native TCP/IP stack for the FreeRTOS kernel. For more information, see FreeRTOS.org.

Prerequisites

To port the FreeRTOS+TCP library, you need the following:

Porting

Before you start porting the FreeRTOS-TCP library, check the <amazon-freertos>/libraries/freertos_plus/standard/freertos_plus_tcp/source/portable/NetworkInterface directory to see if a port to your device already exists.

If a port does not exist, do the following:

  1. Follow the Porting FreeRTOS+TCP to a Different Microcontroller instructions on FreeRTOS.org to port FreeRTOS+TCP to your device.

  2. If necessary, follow the Porting FreeRTOS+TCP to a New Embedded C Compiler instructions on FreeRTOS.org to port FreeRTOS+TCP to a new compiler.

  3. Implement a new port that uses the vendor-supplied Ethernet drivers in a file called NetworkInterface.c, and save the file to <amazon-freertos>/libraries/freertos_plus/standard/freertos_plus_tcp/source/portable/NetworkInterface/<board_family>.

    Note

    The files in the <amazon-freertos>/libraries/freertos_plus/standard/freertos_plus_tcp/source/portable/BufferManagement directory are used by multiple ports. Do not edit the files in this directory.

After you create a port, or if a port already exists, open <amazon-freertos>/vendors/<vendor>/boards/<board>/aws_tests/config_files/FreeRTOSIPConfig.h, and edit the configuration options so they are correct for your platform. For more information about the configuration options, see FreeRTOS+TCP Configuration on FreeRTOS.org.

Testing

If you are 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 are using an IDE for porting and testing, you need to add some source files to the IDE test project before you can test your ported code.

Important

In the following steps, make sure that you add the source files to your IDE project from their on-disk location. Do not create duplicate copies of source files.

To set up the FreeRTOS+TCP library in the IDE project

  1. Add all of the source and header files in <amazon-freertos>/libraries/freertos_plus/standard/freertos_plus_tcp and its subdirectories to the aws_tests IDE project.

    Note

    FreeRTOS includes five example heap management implementations under <amazon-freertos>/freertos_kernel/portable/MemMang. FreeRTOS+TCP and BufferAllocation_2.c require the heap_4.c or heap_5.c implementations. You must use heap_4.c or heap_5.c to ensure that the Amazon FreeRTOS demo applications run properly. Do not use a custom heap implementation.

  2. Add <amazon-freertos>/libraries/freertos_plus/standard/freertos_plus_tcp/include to your compiler's include path.

Configuring the CMakeLists.txt File

If you are using CMake to build your test project, you need to define a portable layer target for the library in your CMake list file.

To define a library's portable layer target in CMakeLists.txt, follow the instructions in Amazon FreeRTOS Portable Layers.

The CMakeLists.txt template list file under <amazon-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.

Setting Up Your Local Testing Environment

After you set up the library in the IDE project, you need to configure some other files for testing.

To configure the source and header files for the TCP tests

  1. Open <amazon-freertos>/libraries/freertos_plus/standard/utils/src/aws_system_init.c, and in the function SYSTEM_Init(), comment out the lines that call BUFFERPOOL_Init() and MQTT_AGENT_Init(), if you have not done so already. Bufferpool and the MQTT agent are not used in this library's porting tests. When you reach the Setting Up the MQTT Library for Testing section, you will be instructed to uncomment these initialization function calls for testing the MQTT library.

    If you have not ported the Secure Sockets library, also comment out the line that calls SOCKETS_Init(). When you reach the Porting the Secure Sockets Library section, you will be instructed to uncomment this initialization function call.

  2. Open <amazon-freertos>/vendors/<vendor>/boards/<board>/aws_tests/application_code/main.c, and uncomment the call to FreeRTOS_IPInit().

  3. Fill the following arrays with valid values for your network:

    Variable Description
    uint8_t ucMACAddress[ 6 ] Default MAC address configuration.
    uint8_t ucIPAddress[ 4 ]

    Default IP address configuration.

    Note

    By default, the IP address is acquired by DHCP. If DCHP fails or if you do not want to use DHCP, the static IP address that is defined here is used.

    To disable DCHP, open <amazon-freertos>/vendors/<vendor>/boards/<board>/aws_tests/config_files/FreeRTOSIPConfig.h, and set ipconfigUSE_DHCP to 0.

    uint8_t ucNetMask[ 4 ] Default net mask configuration.
    uint8_t ucGatewayAddress[ 4 ] Default gateway address configuration.
    uint8_t ucDNSServerAddress[ 4 ] Default DNS server address configuration.
  4. Open <amazon-freertos>/vendors/<vendor>/boards/<board>/aws_tests/config_files/FreeRTOSIPConfig.h, and set the ipconfigUSE_NETWORK_EVENT_HOOK macro to 1.

  5. Open <amazon-freertos>/vendors/<vendor>/boards/<board>/aws_tests/application_code/main.c, and add the following code to the beginning of the function definition for vApplicationIPNetworkEventHook():

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

Running the Tests

To execute the FreeRTOS+TCP tests

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

  2. Check the test results in the UART console. If Network connection successful appears, the Ethernet driver successfully connected to the network, and the test is complete.

Validation

To officially qualify a device for Amazon 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 Amazon FreeRTOS in the Amazon 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.