Wi-Fi 库 - FreeRTOS
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

Wi-Fi 库

概述

FreeRTOS Wi-Fi 库将端口特定的 Wi-Fi 实现抽象为一个常用 API,后者使用 Wi-Fi 功能简化了针对所有符合 FreeRTOS 要求的主板的应用程序开发和移植。通过使用此常用 API,应用程序可通过常用接口与其低级别无线堆栈进行通信。

依赖项和要求

FreeRTOS Wi-Fi 库需要 FreeRTOS+TCP 内核。

功能

Wi-Fi 库包括以下功能:

  • 对 WEP、WPA 和 WPA2 身份验证的支持

  • 接入点扫描

  • 电源管理

  • 网络分析

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

Wi-Fi 模式

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

工作站模式

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

接入点 (AP) 模式

将您的设备设置为 AP 模式可使设备成为一个可供其他设备连接到的接入点。当您的 FreeRTOS 设备处于 AP 模式下时,可以将另一个设备连接到您的设备,并配置新的 Wi-Fi 凭证。要配置 AP 模式,可调用 WIFI_ConfigureAP。要将设备置于 AP 模式下,请调用 WIFI_StartAP。要关闭 AP 模式,请调用 WIFI_StopAP

注意

FreeRTOS 库不提供 AP 模式下的 Wi-Fi 配置。您必须提供其他功能,包括 DHCP 和 HTTP 服务器功能,才能完全支持 AP 模式。

P2P 模式

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

安全性

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

  • eWiFiSecurityOpen

  • eWiFiSecurityWEP

  • eWiFiSecurityWPA

  • eWiFiSecurityWPA2

扫描和连接

要扫描附近的接入点,请将设备设置为工作站模式,并调用 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 库之前,您需要初始化一些特定于主板的组件以及 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(); ... }
  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 }

扫描附近 AP

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 库的更多信息,请参阅 FreeRTOS 移植指南中的移植 Wi-Fi 库