Wi-Fi 库 - FreeRTOS
概述依赖项和要求功能配置初始化API 参考示例用法移植
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Wi-Fi 库

重要

该库托管在已弃用的 Amazon-FreeRTOS 存储库中。当您创建新项目时，我们建议从此处开始。如果您已经有一个基于现已弃用的 Amazon-FreeRTOS 存储库的 FreeRTOS 项目，请参阅 Amazon-FreeRTOS Github 存储库迁移指南。

概述

FreeRTOS Wi-Fi 库将端口特定的 Wi-Fi 实现抽象为一个常用 API，后者使用 Wi-Fi 功能简化了针对所有符合 FreeRTOS 要求的主板的应用程序开发和移植。通过使用此常用 API，应用程序可通过常用接口与其低级别无线堆栈进行通信。

依赖项和要求

FreeRTOS Wi-Fi 库需要 FreeRTOS+TCP 内核。

功能

Wi-Fi 库包括以下功能：

  • 对 WEP、WPA、WPA2 和 WPA3 身份验证的支持

  • 接入点扫描

  • 电源管理

  • 网络分析

有关 Wi-Fi 库的功能的更多信息，请见下文。

Wi-Fi 模式

Wi-Fi 设备可以处于以下三种模式之一：工作站、接入点或 P2P。可以调用 WIFI_GetMode 获取 Wi-Fi 设备的当前模式。可通过调用 WIFI_SetMode 设置设备的 Wi-Fi 模式。如果设备已经与网络连接，则通过调用 WIFI_SetMode 切换模式会断开设备的连接。

工作站模式

将您的设备设置为工作站模式以将主板连接到现有接入点。

接入点 (AP) 模式

将您的设备设置为 AP 模式可使设备成为一个可供其他设备连接到的接入点。当设备处于 AP 模式下时，可以将另一个设备连接到 FreeRTOS 设备，并配置新的 Wi-Fi 凭证。要配置 AP 模式，可调用 WIFI_ConfigureAP。要将设备置于 AP 模式下，请调用 WIFI_StartAP。要关闭 AP 模式，请调用 WIFI_StopAP。

注意

FreeRTOS 库在 AP 模式下不提供 Wi-Fi 配置。您必须提供其他功能，包括 DHCP 和 HTTP 服务器功能，才能完全支持 AP 模式。

P2P 模式

将您的设备设置为 P2P 模式可允许多个设备直接互连，而无需接入点。

安全性

Wi-Fi API 支持 WEP、WPA、WPA2 和 WPA3 安全类型。如果设备处于工作站模式下，则在调用 WIFI_ConnectAP 函数时，您必须指定网络安全类型。如果设备处于 AP 模式下，则可以配置设备以使用任何支持的安全类型：

  • eWiFiSecurityOpen

  • eWiFiSecurityWEP

  • eWiFiSecurityWPA

  • eWiFiSecurityWPA2

  • eWiFiSecurityWPA3

扫描和连接

要扫描附近的接入点，请将设备设置为工作站模式，并调用 WIFI_Scan 函数。如果在扫描中找到了所需的网络，则可以通过调用 WIFI_ConnectAP 并提供网络凭证来连接到该网络。通过调用 WIFI_Disconnect，可以断开 Wi-Fi 设备与网络的连接。有关扫描和连接的更多信息，请参阅示例用法和API 参考。

电源管理

不同 Wi-Fi 设备具有不同的电源要求，具体取决于应用程序和可用电源。设备可能始终通着电以缩短延迟，也可能间歇性连接并在不需要 Wi-Fi 时切换到低功耗模式。接口 API 支持各种电源管理模式，如常开、低功耗和正常模式。可以使用 WIFI_SetPMMode 函数，为设备设置电源模式。可以调用 WIFI_GetPMMode 函数，获取设备当前的电源模式。

网络配置文件

可使用 Wi-Fi 库将网络配置文件保存在设备的非易失性存储中。这样一来，您可以保存网络设置，以便当设备重新连接到 Wi-Fi 网络时可以进行检索，从而无需在设备连接到网络后再次预配置设备。WIFI_NetworkAdd 用于添加网络配置文件。WIFI_NetworkGet 用于检索网络配置文件。WIFI_NetworkDel 用于删除网络配置文件。可以保存的配置文件数量取决于平台。

配置

要使用 Wi-Fi 库，您需要在配置文件中定义几个标识符。有关这些标识符的信息，请参阅API 参考。

注意

该库不包含所需的配置文件。您必须创建一个配置文件。在创建配置文件时，请务必包含主板所需的任何特定于主板的配置标识符。

初始化

在使用 Wi-Fi 库之前，您需要初始化一些特定于主板的组件以及 FreeRTOS 组件。使用 vendors/vendor/boards/board/aws_demos/application_code/main.c 文件作为初始化模板时，请执行以下操作：

  1. 如果应用程序处理 Wi-Fi 连接，请删除 main.c 中的示例 Wi-Fi 连接逻辑。替换以下 DEMO_RUNNER_RunDemos() 函数调用：

    if( SYSTEM_Init() == pdPASS )
    {
    ...
        DEMO_RUNNER_RunDemos();
    ...
        }

    对于针对您自己的应用程序的调用：

    if( SYSTEM_Init() == pdPASS )
    {
    ...
        // This function should create any tasks
        // that your application requires to run.
        YOUR_APP_FUNCTION();
    ...
        }

  2. 调用 WIFI_On() 以初始化和启动您的 Wi-Fi 芯片。

    注意

    一些主板可能需要额外的硬件初始化。

  3. 将已配置的 WIFINetworkParams_t 结构传递到 WIFI_ConnectAP() 以将主板连接到可用的 Wi-Fi 网络。有关 WIFINetworkParams_t 结构的更多信息，请参阅示例用法和API 参考。

API 参考

有关完整 API 参考，请参阅 Wi-Fi API 参考。

示例用法

连接到已知 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
}

扫描附近 AP

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);
}

移植

iot_wifi.c 实现需要实施 iot_wifi.h 中定义的函数。对于任何不必要的或不受支持的函数，此实现至少需要返回 eWiFiNotSupported。

有关移植 Wi-Fi 库的更多信息，请参阅《FreeRTOS 移植指南》中的移植 Wi-Fi 库。