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

# Wi-Fi 库
<a name="freertos-wifi"></a>

**重要**  <a name="deprecation-message-library"></a>
该库托管在已弃用的 Amazon-FreeRTOS 存储库中。当您创建新项目时，我们建议[从此处开始](freertos-getting-started-modular.md)。如果您已经有一个基于现已弃用的 Amazon-FreeRTOS 存储库的 FreeRTOS 项目，请参阅 [Amazon-FreeRTOS Github 存储库迁移指南](github-repo-migration.md)。

## 概述
<a name="freertos-wifi-overview"></a>

FreeRTOS [Wi-Fi](https://docs.amazonaws.cn/freertos/latest/lib-ref/html2/wifi/index.html) 库将端口特定的 Wi-Fi 实现抽象为一个常用 API，后者使用 Wi-Fi 功能简化了针对所有符合 FreeRTOS 要求的主板的应用程序开发和移植。通过使用此常用 API，应用程序可通过常用接口与其低级别无线堆栈进行通信。

## 依赖项和要求
<a name="freertos-wifi-dependencies"></a>

FreeRTOS Wi-Fi 库需要 [FreeRTOS\+TCP](https://freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/index.html) 内核。

## 功能
<a name="freertos-wifi-features"></a>

Wi-Fi 库包括以下功能：
+ Support 支持 WEP、WPA 和身份 WPA2验证 WPA3 
+ 接入点扫描
+ 电源管理
+ 网络分析

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

### Wi-Fi 模式
<a name="freertos-wifi-setup"></a>

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 模式可允许多个设备直接互连，而无需接入点。

### 安全性
<a name="freertos-wifi-security"></a>

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

### 扫描和连接
<a name="freertos-wifi-connection"></a>

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

### 电源管理
<a name="freertos-wifi-power-management"></a>

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

### 网络配置文件
<a name="freertos-wifi-profiles"></a>

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

## 配置
<a name="freertos-wifi-config"></a>

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

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

## 初始化
<a name="freertos-wifi-init"></a>

在使用 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();
       ...
           }
   ```

1. 调用 `WIFI_On()` 以初始化和启动您的 Wi-Fi 芯片。
**注意**  
一些主板可能需要额外的硬件初始化。

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

## API 参考
<a name="freertos-wifi-api"></a>

有关完整 API 参考，请参阅 [Wi-Fi API 参考](https://docs.amazonaws.cn/freertos/latest/lib-ref/html2/wifi/index.html)。

## 示例用法
<a name="freertos-wifi-example"></a>

### 连接到已知 AP
<a name="w2aac31b9c13c53c21b3"></a>

```
#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
}
```

### 正在扫描附近 APs
<a name="w2aac31b9c13c53c21b5"></a>

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

## 移植
<a name="freertos-wifi-porting"></a>

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

有关移植 Wi-Fi 库的更多信息，请参阅《FreeRTOS 移植指南》中的[移植 Wi-Fi 库](https://docs.amazonaws.cn/freertos/latest/portingguide/afr-porting-wifi.html)。