Wi-Fi 程式庫

重要

此程式庫託管在已棄用的 Amazon-FreeRTOS 儲存庫上。我們建議您在建立新專案時從這裡開始。如果您已經有基於現已棄用之 Amazon-FreeRTOS 儲存庫的現有免費RTOS專案，請參閱 Amazon-FreeRTOS Github 儲存庫遷移指南。

概觀

免費RTOS Wi-Fi 程式庫會將連接埠特定的 Wi-Fi 實作抽象化為通用API，可簡化具有 Wi-Fi RTOS功能的所有免費合格主機板的應用程式開發和移植。使用此通用 API，應用程式可以透過通用界面與其較低層級的無線堆疊進行通訊。

相依性和要求

免費RTOS Wi-Fi 程式庫需要 FreeRTOS＋TCP 核心。

功能

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

支援 WEP、WPA2、 WPA和 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、WPA2、 WPA和 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 檔案做為初始化範本時，請執行下列動作：

如果您的應用程式會處理 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();
    ...
        }

呼叫 WIFI_On() 來初始化您的 Wi-Fi 晶片，並開啟其電源。

注意
有些主機板可能需要額外的硬體初始化。
將設定的 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 程式庫。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

Transport Layer Security

FreeRTOS 示