Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Wi-Fi library

Overview

The FreeRTOS Wi-Fi library abstracts port-specific Wi-Fi implementations into a common API that simplifies application development and porting for all FreeRTOS-qualified boards with Wi-Fi capabilities. Using this common API, applications can communicate with their lower-level wireless stack through a common interface.

Dependencies and requirements

The FreeRTOS Wi-Fi library requires the FreeRTOS+TCP core.

Features

The Wi-Fi library includes the following features:

For more information about the features of the Wi-Fi library, see below.

Wi-Fi modes

Wi-Fi devices can be in one of three modes: Station, Access Point, or P2P. You can get the current mode of a Wi-Fi device by calling WIFI_GetMode. You can set a device's wi-fi mode by calling WIFI_SetMode. Switching modes by calling WIFI_SetMode disconnects the device, if it is already connected to a network.

Security

The Wi-Fi API supports WEP, WPA, WPA2, and WPA3 security types. When a device is in Station mode, you must specify the network security type when calling the WIFI_ConnectAP function. When a device is in AP mode, the device can be configured to use any of the supported security types:

Scanning and connecting

To scan for nearby access points, set your device to Station mode, and call the WIFI_Scan function. If you find a desired network in the scan, you can connect to the network by calling WIFI_ConnectAP and providing the network credentials. You can disconnect a Wi-Fi device from the network by calling WIFI_Disconnect. For more information about scanning and connecting, see Example usage and API reference.

Power management

Different Wi-Fi devices have different power requirements, depending on the application and available power sources. A device might always be powered on to reduce latency or it might be intermittently connected and switch into a low power mode when Wi-Fi is not required. The interface API supports various power management modes like always on, low power, and normal mode. You set the power mode for a device using the WIFI_SetPMMode function. You can get the current power mode of a device by calling the WIFI_GetPMMode function.

Network profiles

The Wi-Fi library enables you to save network profiles in the non-volatile memory of your devices. This allows you to save network settings so they can be retrieved when a device reconnects to a Wi-Fi network, removing the need to provision devices again after they have been connected to a network. WIFI_NetworkAdd adds a network profile. WIFI_NetworkGet retrieves a network profile. WIFI_NetworkDel deletes a network profile. The number of profiles you can save depends on the platform.

Configuration

To use the Wi-Fi library, you need to define several identifiers in a configuration file. For information about these identifiers, see the API reference.

Initialization

Before you use the Wi-Fi library, you need to initialize some board-specific components, in addition to the FreeRTOS components. Using the vendors/vendor/boards/board/aws_demos/application_code/main.c file as a template for initialization, do the following:

API reference

For a full API reference, see Wi-Fi API Reference.

Example usage

Connecting to a known AP

#define clientcredentialWIFI_SSID    "MyNetwork"
#define clientcredentialWIFI_PASSWORD   "hunter2"

WIFINetworkParams_t xNetworkParams;
WIFIReturnCode_t xWifiStatus;

xWifiStatus = WIFI_On(); // Turn on Wi-Fi module

// Check that Wi-Fi initialization was successful
if( xWifiStatus == eWiFiSuccess )
{
    configPRINT( ( "WiFi library initialized.\n") );
}
else
{
    configPRINT( ( "WiFi library failed to initialize.\n" ) );
    // Handle module init failure
}

/* Setup parameters. */
xNetworkParams.pcSSID = clientcredentialWIFI_SSID;
xNetworkParams.ucSSIDLength = sizeof( clientcredentialWIFI_SSID );
xNetworkParams.pcPassword = clientcredentialWIFI_PASSWORD;
xNetworkParams.ucPasswordLength = sizeof( clientcredentialWIFI_PASSWORD );
xNetworkParams.xSecurity = eWiFiSecurityWPA2;

// Connect!
xWifiStatus = WIFI_ConnectAP( &( xNetworkParams ) );

if( xWifiStatus == eWiFiSuccess )
{
    configPRINT( ( "WiFi Connected to AP.\n" ) );
    // IP Stack will receive a network-up event on success
}
else
{
    configPRINT( ( "WiFi failed to connect to AP.\n" ) );
    // Handle connection failure
}

Scanning for nearby APs

WIFINetworkParams_t xNetworkParams;
WIFIReturnCode_t xWifiStatus;

configPRINT( ("Turning on wifi...\n") );
xWifiStatus = WIFI_On();

configPRINT( ("Checking status...\n") );
if( xWifiStatus == eWiFiSuccess )
{
    configPRINT( ("WiFi module initialized.\n") );
}
else
{
    configPRINTF( ("WiFi module failed to initialize.\n" ) );
    // Handle module init failure
}

WIFI_SetMode(eWiFiModeStation);

/* Some boards might require additional initialization steps to use the Wi-Fi library. */

while (1)
{
    configPRINT( ("Starting scan\n") );
    const uint8_t ucNumNetworks = 12; //Get 12 scan results
    WIFIScanResult_t xScanResults[ ucNumNetworks ];
    xWifiStatus = WIFI_Scan( xScanResults, ucNumNetworks ); // Initiate scan

    configPRINT( ("Scan started\n") );

    // For each scan result, print out the SSID and RSSI
    if ( xWifiStatus == eWiFiSuccess )
    {
        configPRINT( ("Scan success\n") );
        for ( uint8_t i=0; i<ucNumNetworks; i++ ) 
        {
            configPRINTF( ("%s : %d \n", xScanResults[i].cSSID, xScanResults[i].cRSSI) );
        }
    } else {
        configPRINTF( ("Scan failed, status code: %d\n", (int)xWifiStatus) );
    }
    
    vTaskDelay(200);
}

Porting

The iot_wifi.c implementation needs to implement the functions defined in iot_wifi.h. At the very least, the implementation needs to return eWiFiNotSupported for any non-essential or unsupported functions.

For more information about porting the Wi-Fi library, see Porting the Wi-Fi Library in the FreeRTOS Porting Guide.