Wi-Fi 程式庫

重要

該庫託管在亞馬遜免費RTOS存儲庫上，該存儲庫已被棄用。我們建議您在建立新專案時從這裡開始。如果您已經有一個基於現在不推薦使用的 Amazon-Free RTOS 存儲庫的現有免費RTOS項目，請參閱. 亞馬遜自由 Github 存儲庫遷移指南

概觀

免費 RTOS Wi-Fi 庫將特定於端口的 Wi-Fi 實現摘要為一種通用實現，簡化API了應用程序開發和移植所有具有 Wi-Fi 功能的免費RTOS認證主機板。使用這種常見API的應用程序可以通過通用接口與其較低級別的無線堆棧進行通信。

相依性和要求

免費RTOS無線網絡庫需要免費 RTOS + TCP 核心。

功能

Wi-Fi 程式庫包含下列功能：

• Sup WEP port、WPAWPA2、和WPA3驗證

• 存取點掃描

• 電源管理

• 網路分析

如需 Wi-Fi 程式庫功能的詳細資訊，請參閱下面資訊。

Wi-Fi 模式

Wi-Fi 裝置可以處於三種模式之一：站台、存取點或 P2P。您可以透過呼叫 WIFI_GetMode 來取得 Wi-Fi 裝置的目前模式。您可以透過呼叫 WIFI_SetMode 來設定裝置的 Wi-Fi 模式。呼叫 WIFI_SetMode 切換模式會中斷連線裝置 (若該裝置已連線到網路)。

站台模式

將您的裝置設定為站台模式，以將主機板連接到現有的存取點。

存取點 (AP) 模式

將您的裝置設定為 AP 模式，讓裝置成為其他裝置連接到其中的存取點。當您的設備處於 AP 模式時，您可以將其他設備連接到免費設RTOS備並配置新的 Wi-Fi 憑據。若要設定 AP 模式，請呼叫 WIFI_ConfigureAP。若要將您的裝置置入 AP 模式中，請呼叫 WIFI_StartAP。若要關閉 AP 模式，請呼叫 WIFI_StopAP。

注意

免費RTOS程式庫在 AP 模式下不提供 Wi-Fi 佈建。您必須提供其他功能，包括DHCP和HTTP伺服器功能，才能完全支援 AP 模式。

P2P 模式

將您的裝置設定為 P2P 模式，以允許多個裝置無需存取點即可彼此直接連接。

安全

Wi-Fi API 支援WEP、WPAWPA2、和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 資料庫之前，除了免費RTOS元件之外，還需要初始化一些主機板特定元件。使用 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
}

掃描附近 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);
}

移植

iot_wifi.c 實作需要實作 iot_wifi.h 中定義的函數。至少，實作需要針對任何非必要或不支援的函數傳回 eWiFiNotSupported。

如需有關移植 Wi-Fi 資料庫的詳細資訊，請參閱《免費移植指南》中的RTOS移植 Wi-Fi 資料庫。