Wi-Fi API 提供对 802.11b/g/n 协议驱动程序的支持。此 API 包括：

• Station 模式（STA 模式或 Wi-Fi 客户端模式）。ESP32 连接到接入点
• AP 模式（又名 Soft-AP 模式或接入点模式）。设备连接到 ESP32
• 安全模式（WPA2、WPA3 等）
• 扫描接入点

在此模式下，ESP32 配置为接入点 （AP），并且能够通过提供 Wi-Fi 网络来接收来自其他设备（站点）的传入连接。

例如，此模式可用于为 ESP32 内的 HTTP 或 HTTPS 服务器提供服务。

STA 模式用于将 ESP32 连接到接入点提供的 Wi-Fi 网络。

如果要将项目连接到 Internet，则可以使用此模式。

以下是 Wi-Fi API 的说明。

以下是用于 AP 和 STA 两种模式的常用 API。

注册调用方提供的函数，以便在 Wi-Fi 事件发生时调用。有几种形式可供选择。

获取事件 ID 的函数指针回调：

typedef void (*WiFiEventCb)(arduino_event_id_t);
wifi_event_id_t onEvent(WiFiEventCb, arduino_event_id_t = ARDUINO_EVENT_MAX);

采用 event-id-and-info 结构体的函数指针回调：

typedef struct{
    arduino_event_id_t event_id;
    arduino_event_info_t event_info;
} arduino_event_t;

typedef void (*WiFiEventSysCb)(arduino_event_t *);
wifi_event_id_t onEvent(WiFiEventSysCb, arduino_event_id_t = ARDUINO_EVENT_MAX);

使用 std::function 分别获取事件 ID 和信息进行回调：

typedef std::function<void(arduino_event_id_t, arduino_event_info_t)> WiFiEventFuncCb;
wifi_event_id_t onEvent(WiFiEventFuncCb, arduino_event_id_t = ARDUINO_EVENT_MAX);

一组类似的函数可用于删除回调：

void removeEvent(WiFiEventCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
void removeEvent(WiFiEventSysCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
void removeEvent(wifi_event_id_t = ARDUINO_EVENT_MAX);

在所有情况下，订阅函数都接受可选的事件类型，以 仅针对该特定事件调用回调;替换为默认的 ARDUINO_EVENT_MAX，所有 Wi-Fi 事件都会调用该回调。

任何回调函数都在参数中被赋予事件类型。 一些可能的回调函数格式也采用 arduino_event_info_t（或使用包含 ID 和 info 的 arduino_event_t），它是结构体的联合，其中包含有关不同事件类型的其他信息。

看 WiFiGeneric.h 有关事件类型和 “info” 子结构的列表，另请参阅完整的 事件处理示例： 事件示例 。

S设置 DHCP 客户端用于标识自身的名称。在典型的网络设置中，这将是 Wi-Fi 路由器设备列表中显示的名称。主机名不得超过 32 个字符。

setHostname(const char *hostname);

如果从未指定主机名，则将根据芯片类型和 MAC 地址分配默认主机名。可以检索当前主机名（默认或自定义）：

const char *getHostname();

该函数用于设置 Wi-Fi 缓冲区的内存分配模式。

static void useStaticBuffers(bool bufferMode);

• 设置为 true 以将 Wi-Fi 缓冲区内存分配用作静态 。
• 设置 false 可将缓冲区内存分配设置为 dynamic。

建议使用动态分配，以节省内存并减少资源使用。但是，动态的执行速度比静态分配稍慢。如果您想获得更高的性能，并且您的应用程序是多任务的，请使用静态分配。

默认情况下，如果未使用此函数，则内存分配将设置为 dynamic。

配置 Dual antenna（双天线）功能。此功能只能用于 ESP32-WROOM-DA 模块或任何其他带有射频开关的 ESP32。

bool setDualAntennaConfig(uint8_t gpio_ant1, uint8_t gpio_ant2, wifi_rx_ant_t rx_mode, wifi_tx_ant_t tx_mode);

• gpio_ant1 配置连接到 RF 开关的天线 1 的 GPIO 编号（ESP32-WROOM-DA 上默认为 GPIO2）
• gpio_ant2 配置连接到 RF 开关的天线 2 的 GPIO 编号（ESP32-WROOM-DA 上默认为 GPIO25）
• rx_mode 设置 RX 天线模式。有关选项，请参阅 wifi_rx_ant_t。
• tx_mode 设置 TX 天线模式。有关选项，请参阅 wifi_tx_ant_t。

如果配置成功，则返回 true。

对于 rx_mode，您可以使用以下配置：

• WIFI_RX_ANT0 为所有 RX 活动选择天线 1。
• WIFI_RX_ANT1 为所有 RX 活动选择天线 2。
• WIFI_RX_ANT_AUTO 自动选择 RX 的天线。

对于 tx_mode，您可以使用以下配置：

• WIFI_TX_ANT0 为所有 TX 活动选择天线 1。
• WIFI_TX_ANT1 为所有 TX 活动选择天线 2。
• WIFI_TX_ANT_AUTO 自动选择 TX 的天线。

WiFiAP 用于配置和管理作为接入点的 Wi-Fi。您可以在此处找到 AP 的相关功能。

将 Wi-Fi 作为接入点启动。

WiFi.softAP(ssid, password);

请参阅完整的 WiFiAP 示例：ap 示例 。

使用函数 softAP 配置 Wi-Fi AP 特性：

bool softAP(const char* ssid, const char* passphrase = NULL, int channel = 1, int ssid_hidden = 0, int max_connection = 4, bool ftm_responder = false);

Where:  哪里：

• ssid 设置 Wi-Fi 网络 SSID。
• passphrase 设置 Wi-Fi 网络密码。如果网络已打开，则设置为 NULL。
• channel 配置 Wi-Fi 频道。
• ssid_hidden 将网络设置为隐藏。
• max_connection 设置最大同时连接数。默认值为 4。
• ftm_responder 设置 Wi-Fi FTM 响应程序功能。 仅适用于 ESP32-S2 和 ESP32-C3 SoC！

如果配置成功，则返回 true。

用于将 IP 配置为静态（固定）以及网关和子网的函数。

bool softAPConfig(IPAddress local_ip, IPAddress gateway, IPAddress subnet);

Where:  哪里：

• local_ip 设置本地 IP 地址。
• gateway 设置网关 IP。
• subnet 设置子网掩码。

如果配置成功，该函数将返回 true。

用于强制 AP 断开连接的功能。

bool softAPdisconnect(bool wifioff = false);

Where: 

• wifioff 如果为 true，则设置 Wi-Fi 关闭。

如果配置成功，该函数将返回 true。

此函数返回连接到 AP 的客户端数。

uint8_t softAPgetStationNum();

获取 AP IPv4 地址的函数。

IPAddress softAPIP();

该函数将以 IPAddress 格式返回 AP IP 地址。

获取 AP IPv4 广播地址的函数。

IPAddress softAPBroadcastIP();

该函数将以 IPAddress 格式返回 AP 广播地址。

获取 softAP 网络 ID。

IPAddress softAPNetworkID();

该函数将以 IPAddress 格式返回 AP 网络地址。

获取 softAP 子网 CIDR。

uint8_t softAPSubnetCIDR();

获取 softAP 子网掩码。

IPAddress softAPSubnetMask();

用于启用 IPv6 支持的函数。

bool softAPenableIPv6(bool enable=true);

如果配置成功，该函数将返回 true。

获取 IPv6 地址的函数。

IPAddress softAPlinkLocalIPv6();

该函数将以 IPAddress 格式返回 AP IPv6 地址。

用于获取 AP 主机名的函数。

const char * softAPgetHostname();

设置 AP 主机名的函数。

bool softAPsetHostname(const char * hostname);

Where:  

• hostname 设置设备主机名。

如果配置成功，该函数将返回 true。

定义 AP MAC 地址的函数。

uint8_t* softAPmacAddress(uint8_t* mac);

Where:  

• mac 设置新的 MAC 地址。

获取 AP MAC 地址的函数。

String softAPmacAddress(void);

用于获取 AP SSID 的功能。

String softAPSSID(void) const;

返回 AP SSID。

WiFiSTA 用于配置和管理 Wi-Fi 作为 Station。STA 的相关函数在这里。

以下代码显示了 WifiSTA 功能的基本用法。

WiFi.begin(ssid, password);

其中 ssid 和 password 来自要连接 ESP32 的网络。

要检查连接是否成功，您可以使用：

while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
}

连接成功后，您可以打印网络提供的 IP 地址。

Serial.println("IP address: ");
Serial.println(WiFi.localIP());

请在以下位置查看 WiFiSTA 的完整示例：sta 示例 。

• 函数 begin 用于配置和启动 Wi-Fi。

wl_status_t begin(const char* ssid, const char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);

Where:  

• ssid 设置 AP SSID。
• passphrase 设置 AP 密码。对于开放网络，设置为 NULL。
• channel 设置 Wi-Fi 频道。
• uint8_t* bssid 设置 AP BSSID。
• connect （连接） 设置为 true 以自动连接到配置的网络。

wl_status_t begin(char* ssid, char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = true);

Where: 

• ssid 设置 AP SSID。
• passphrase 设置 AP 密码。对于开放网络，设置为 NULL。
• channel 设置 Wi-Fi 频道。
• bssid 设置 AP BSSID。
• connect （连接） 设置为 true 以自动连接到配置的网络。

配置后启动连接的函数。

wl_status_t begin();

函数 config 用于配置 Wi-Fi。配置完成后，您可以调用 function begin 启动 Wi-Fi 进程。

bool config(IPAddress local_ip, IPAddress gateway, IPAddress subnet, IPAddress dns1 = (uint32_t)0x00000000, IPAddress dns2 = (uint32_t)0x00000000);

Where: 

• local_ip 设置本地 IP。
• gateway 设置网关 IP。
• subnet 设置子网掩码。
• dns1 设置 DNS。
• dns2 设置 DNS alternative 选项。

如果配置成功，该函数将返回 true。

IPAddress 格式由 4 个字节定义，如下所述：

IPAddress(uint8_t first_octet, uint8_t second_octet, uint8_t third_octet, uint8_t fourth_octet);

Example: 

IPAddress local_ip(192, 168, 10, 20);

有关如何使用此功能的更多详细信息，请参阅 WiFiClientStaticIP.ino。

用于重新连接 Wi-Fi 连接的功能。

bool reconnect();

强制断开连接的功能。

bool disconnect(bool wifioff = false, bool eraseap = false);

Where: 

• wifioff 使用 true 关闭 Wi-Fi 无线电。
• eraseap 使用 true 从 NVS 内存中擦除 AP 配置。

如果配置成功，该函数将返回 true。

用于获取连接状态的函数。

bool isConnected();

返回连接状态。

函数已弃用。

函数已弃用。

用于设置连接丢失时自动重新连接的功能。

bool setAutoReconnect(bool autoReconnect);

Where:  

• autoConnect 设置为 true 以启用此选项。

用于获取连接丢失时自动重连的函数。

bool getAutoReconnect();

如果启用此设置，该函数将返回 true。

用于设置 AP 被视为可连接的最低安全性的函数。

bool setMinSecurity(wifi_auth_mode_t minSecurity);

Where:  

• minSecurity 是 AP 被视为可连接的最低安全性。默认值为 WIFI_AUTH_WPA2_PSK。

WiFiMulti 允许您在作为工作站运行时为 AP 连接添加多个选项。

要添加 AP，请使用以下功能。您可以添加多个 AP，此库将处理连接。

bool addAP(const char* ssid, const char *passphrase = NULL);

添加 AP 后，由以下函数运行。

uint8_t run(uint32_t connectTimeout=5000);

要了解如何使用 WiFiMulti，请查看可用的 WiFiMulti.ino 示例。

要对网络执行 Wi-Fi 扫描，您可以使用以下功能：

开始扫描可用的 Wi-Fi 网络。

int16_t scanNetworks(bool async = false, bool show_hidden = false, bool passive = false, uint32_t max_ms_per_chan = 300, uint8_t channel = 0);

调用以获取异步模式下的扫描状态。

int16_t scanComplete();

从 RAM 中删除上次扫描结果。

void scanDelete();

将扫描的 Wi-Fi 中的所有信息加载到 ptr 参数中。

bool getNetworkInfo(uint8_t networkItem, String &ssid, uint8_t &encryptionType, int32_t &RSSI, uint8_t* &BSSID, int32_t &channel);

要了解如何使用 WiFiScan，请查看可用的 WiFiScan.ino 或 WiFiScanAsync.ino 示例。

libraries/WiFi/examples/WiFiAccessPoint/WiFiAccessPoint.ino

libraries/WiFi/examples/WiFiClient/WiFiClient.ino

libraries/WiFi/examples/WiFiClientEvents/WiFiClientEvents.ino