Porting FreeRTOS+TCP - FreeRTOS

Porting FreeRTOS+TCP

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


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


Before you start porting the FreeRTOS-TCP library, check the freertos/libraries/freertos_plus/standard/freertos_plus_tcp/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 or Wi-Fi drivers in a file called NetworkInterface.c, and save the file to freertos/libraries/freertos_plus/standard/freertos_plus_tcp/portable/NetworkInterface/board_family.


    The files in the freertos/libraries/freertos_plus/standard/freertos_plus_tcp/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 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.


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.


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 freertos/libraries/freertos_plus/standard/freertos_plus_tcp and its subdirectories to the aws_tests IDE project.


    FreeRTOS includes five example heap management implementations under 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 FreeRTOS demo applications run properly. Do not use a custom heap implementation.

  2. Add 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 FreeRTOS portable layers.

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

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. If you have not ported the Secure Sockets library, open freertos/libraries/freertos_plus/standard/utils/src/iot_system_init.c, and in the function SYSTEM_Init(), 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 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.


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

    To disable DHCP, open freertos/vendors/vendor/boards/board/aws_tests/config_files/FreeRTOSIPConfig.h, and set ipconfigUSE_DHCP to 0. For demos, ipconfigUSE_DHCP is defined in freertos/vendors/vendor/boards/board/aws_demos/config_files/FreeRTOSIPConfig.h.

    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 freertos/vendors/vendor/boards/board/aws_tests/config_files/FreeRTOSIPConfig.h, and set the ipconfigUSE_NETWORK_EVENT_HOOK macro to 1.

  5. Open 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 or Wi-Fi driver successfully connected to the network, and the test is complete.


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.