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

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

FreeRTO [Wi-Fi](https://docs.aws.amazon.com/freertos/latest/lib-ref/html2/wifi/index.html)S 库将 Wi-Fi 特定于端口的实现抽象成一个通用 API，可简化所有具有功能的主板的应用程序开发和移植。 FreeRTOS-qualified Wi-Fi 通过使用此常用 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 库包括以下功能：
+ 对 WEP、WPA、WPA2 和 WPA3 身份验证的支持
+ 接入点扫描
+ 电源管理
+ 网络分析

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

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

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

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

**接入点 (AP) 模式**  
将您的设备设置为 AP 模式可使设备成为一个可供其他设备连接到的接入点。当您的设备处于 AP 模式时，您可以将另一台设备连接到 FreeRTOS 设备并配置新的凭据。 Wi-Fi 要配置 AP 模式，可调用 `WIFI_ConfigureAP`。要将设备置于 AP 模式下，请调用 `WIFI_StartAP`。要关闭 AP 模式，请调用 `WIFI_StopAP`。  
FreeRTOS 库不 Wi-Fi 提供接入点模式下的资源调配。您必须提供其他功能，包括 DHCP 和 HTTP 服务器功能，才能完全支持 AP 模式。

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

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

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

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

要扫描附近的接入点，请将设备设置为工作站模式，并调用 `WIFI_Scan` 函数。如果在扫描中找到了所需的网络，则可以通过调用 `WIFI_ConnectAP` 并提供网络凭证来连接到该网络。您可以通过拨打来断开 Wi-Fi 设备与网络的连接`WIFI_Disconnect`。有关扫描和连接的更多信息，请参阅[示例用法](#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. `main.c`如果您的应用程序处理 Wi-Fi 连接，请删除中的示例 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.aws.amazon.com/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
}
```

### 扫描附近 AP
<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.aws.amazon.com/freertos/latest/portingguide/afr-porting-wifi.html)。