本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 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)。 FreeRTOS 

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

FreeRTOS [Wi-Fi](https://docs.aws.amazon.com/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\$1TCP](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。您可以透過呼叫 `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、WPA2 和 WPA3 安全類型。當裝置處於站台模式時，您必須在呼叫 `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` 則會刪除網路描述檔。您可以儲存的描述檔數量需視平台而定。

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

若要使用 Wi-Fi 程式庫，您需要在組態檔案中定義數個識別碼。如需這些識別碼的相關資訊，請參閱 [API 參考](#freertos-wifi-api)。

**注意**  
此程式庫不包含所需的組態檔案。您必須建立一個。在建立您的組態檔案時，請務必包含您主機板需要的任何主機板特定的組態識別碼。

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

除了 FreeRTOS 元件外，您還需要將一些主機板特定的元件初始化，才能使用 Wi-Fi 程式庫。使用 `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.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)。