Amazon FreeRTOS
Porting Guide

Porting the Wi-Fi Library

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

If your device does not support Wi-Fi networking, you can skip porting the Amazon FreeRTOS Wi-Fi library and start Porting a TCP/IP Stack.

Note

For qualification, 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 Amazon FreeRTOS Wi-Fi library is not necessarily required.

Prerequisites

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

Porting

<amazon-freertos>/vendors/<vendor>/boards/<board>/ports/wifi/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 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.

<amazon-freertos>/libraries/abstractions/wifi/include/aws_wifi.h provides the information required to implement these functions.

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 Wi-Fi library in the IDE project

  1. Add the source file <amazon-freertos>/vendors/<vendor>/boards/<board>/ports/wifi/aws_wifi.c to your aws_tests IDE project.

  2. Add the source file aws_test_wifi.c to the aws_tests IDE project.

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.

See below for an example portable layer target definition for the Wi-Fi library.

# WiFi afr_mcu_port(wifi) target_sources( AFR::wifi::mcu_port INTERFACE "<amazon-freertos>/vendors/<vendor>/boards/<board>/ports/wifi/aws_wifi.c" )

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

  1. Open <amazon-freertos>/vendors/<vendor>/boards/<board>/aws_tests/application_code/main.c, and delete the #if 0 and #endif compiler directives in the function definitions of vApplicationDaemonTaskStartupHook(void) and prvWifiConnect(void).

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

  3. Open <amazon-freertos>/tests/include/aws_clientcredential.h, and set the macros in the following table for the first 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 <amazon-freertos>/libraries/abstractions/wifi/test/aws_test_wifi.h, and set the macros in the following table for the second AP.

    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 <amazon-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. For information about setting up an echo server, see Setting Up an Echo Server.

Running the Tests

To execute the Wi-Fi tests

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

  2. Check the test results in the UART console.

    ...

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.

After you finish porting the Amazon FreeRTOS Wi-Fi library to your device, you can start porting a TCP/IP stack. See Porting a TCP/IP Stack for instructions.