概览

[English]

ESP32 Wi-Fi 功能列表

ESP32 支持以下 Wi-Fi 功能：

  • 支持 4 个虚拟 Wi-Fi 接口，即 STA、AP、Sniffer 和保留接口

  • 支持仅 station 模式、仅 AP 模式、station/AP 共存模式

  • 支持使用 IEEE 802.11b、IEEE 802.11g、IEEE 802.11n 和提供配置协议模式的 API

  • 支持 WPA/WPA2/WPA3/WPA2-企业版/WPA3-企业版/WAPI/WPS 和 DPP

  • 支持 AMSDU、AMPDU、HT40、QoS 以及其它关键功能

  • 支持 Modem-sleep

  • 支持乐鑫专属 ESP-NOW 协议和长距离模式，可实现最远 1 km 的数据传输

  • 空中数据传输最高可达 20 MBit/s TCP 吞吐量和 30 MBit/s UDP 吞吐量

  • 支持 Sniffer

  • 支持快速扫描和全信道扫描

  • 支持多天线

  • 支持获取信道状态信息

  • Wi-Fi Aware (NAN)

如何编写 Wi-Fi 应用程序

准备工作

一般来说，要编写自己的 Wi-Fi 应用程序，最高效的方式是先选择一个相似的应用程序示例，然后将其中可用的部分移植到自己的项目中。如果你希望编写一个强健的 Wi-Fi 应用程序，强烈建议在开始之前先阅读本文。非强制要求，请依个人情况而定。

本文将补充说明 Wi-Fi API 和 Wi-Fi 示例的相关信息，重点描述使用 Wi-Fi API 的原则、当前 Wi-Fi API 实现的限制以及使用 Wi-Fi 时的常见错误。同时，本文还介绍了 Wi-Fi 驱动程序的一些设计细节。建议选择一个示例 example 进行参考。

  • wifi/getting_started/station 演示如何使用 station 功能连接到 AP。

  • wifi/getting_started/softAP 演示如何使用 SoftAP 功能将 ESP32 配置为 AP。

  • wifi/scan 演示如何扫描可用的 AP，配置扫描设置，并显示扫描结果。

  • wifi/fast_scan 演示如何执行快速和全通道扫描，查找附近的 AP，设置信号强度的阈值和认证模式，并根据信号强度和认证模式连接到最合适的 AP。

  • wifi/wps 演示如何使用 WPS 入网功能，简化连接 Wi-Fi 路由器的过程，支持 PIN 或 PBC 模式。

  • wifi/wps_softap_registrar 演示如何在 SoftAP 模式下使用 WPS 注册器功能，从而简化从 station 连接到 Wi-Fi SoftAP 的过程。

  • wifi/smart_config 演示如何使用 smartconfig 功能通过 ESPTOUCH app 连接到目标 AP。

  • wifi/power_save 演示如何使用 station 模式的省电模式。

  • wifi/softap_sta 演示如何配置 ESP32 同时用作 AP 和 station，从而可将其用作 Wi-Fi NAT 路由器。

  • wifi/iperf 演示如何实现 iPerf 性能测量工具所使用的协议，允许在两个芯片之间或在单个芯片和运行 iPerf 工具的计算机之间进行性能测量，并提供测试 station/SoftAP TCP/UDP RX/TX 吞吐量的具体说明。

  • wifi/roaming/roaming_app 演示如何使用 Wi-Fi Roaming App 功能，在兼容的 AP 之间高效漫游。

  • wifi/roaming/roaming_11kvr 演示如何使用 11k 和 11v API 实现漫游功能。

设置 Wi-Fi 编译时选项

请参阅 Wi-Fi Menuconfig。

Wi-Fi 初始化

请参阅 ESP32 Wi-Fi station 通用场景、ESP32 Wi-Fi AP 通用场景。

启动/连接 Wi-Fi

请参阅 ESP32 Wi-Fi station 通用场景、ESP32 Wi-Fi AP 通用场景。

事件处理

通常，在理想环境下编写代码难度并不大，如 WIFI_EVENT_STA_START、WIFI_EVENT_STA_CONNECTED 中所述。难度在于如何在现实的困难环境下编写代码，如 WIFI_EVENT_STA_DISCONNECTED 中所述。能否在后者情况下完美地解决各类事件冲突，是编写一个强健的 Wi-Fi 应用程序的根本。请参阅 ESP32 Wi-Fi 事件描述, ESP32 Wi-Fi station 通用场景, ESP32 Wi-Fi AP 通用场景。另可参阅 ESP-IDF 中的 事件处理概述。

编写错误恢复程序

除了能在比较差的环境下工作，错误恢复能力也对一个强健的 Wi-Fi 应用程序至关重要。请参阅 ESP32 Wi-Fi API 错误代码。

ESP32 Wi-Fi API 错误代码

所有 ESP32 Wi-Fi API 都有定义好的返回值，即错误代码。这些错误代码可分类为：

  • 无错误，例如：返回值 ESP_OK 代表 API 成功返回

  • 可恢复错误，例如：ESP_ERR_NO_MEM

  • 不可恢复的非关键性错误

  • 不可恢复的关键性错误

一个错误是否为关键性取决于其 API 和应用场景，并且由 API 用户定义。

要使用 Wi-Fi API 编写一个强健的应用程序，根本原则便是要时刻检查错误代码并编写相应的错误处理代码。 一般来说，错误处理代码可用于解决：

  • 可恢复错误，你可以编写相应的错误恢复代码。例如，当 esp_wifi_start() 返回 ESP_ERR_NO_MEM 时，调用可恢复错误处理代码 vTaskDelay 以获取微秒级的延迟后重新尝试。

  • 不可恢复非关键性错误，打印错误代码可以帮助你更好地处理该类错误。

  • 不可恢复关键性错误，可使用 "assert" 语句处理该类错误。例如，如果 esp_wifi_set_mode() 返回 ESP_ERR_WIFI_NOT_INIT，这意味着 Wi-Fi 驱动程序未通过 esp_wifi_init() 成功初始化。这类错误可以在应用开发阶段被快速检测到。

在 esp_common/include/esp_err.h 中， ESP_ERROR_CHECK 负责检查返回值。这是一个较为常见的错误处理代码，可在应用程序开发阶段作为默认的错误处理代码。但是，我们强烈建议 API 的使用者编写自己的错误处理代码。

初始化 ESP32 Wi-Fi API 参数

在为 API 初始化结构体参数时，应遵循以下两种方式之一：

  • 显式设置参数的所有字段

  • 先使用 get API 获取当前配置，然后设置特定于应用程序的字段

初始化或获取整个结构体这一步至关重要，因为大多数情况下，值为 0 意味着程序使用了默认值。未来可能会向该结构体添加更多字段，而将这些字段初始化为 0 可以确保在 ESP-IDF 更新到新版本后，应用程序仍能正常运行。

ESP32 Wi-Fi 编程模型

ESP32 Wi-Fi 编程模型如下图所示：

Wi-Fi 编程模型

Wi-Fi 驱动程序可以看作是一个无法感知上层代码（如 TCP/IP 堆栈、应用程序任务、事件任务等）的黑匣子。通常，应用程序任务（代码）负责调用 Wi-Fi 驱动程序 API 来初始化 Wi-Fi，并在必要时处理 Wi-Fi 事件。然后，Wi-Fi 驱动程序接收 API 调用，处理后将事件发送给应用程序。

Wi-Fi 事件处理是在 esp_event 库 的基础上进行的。Wi-Fi 驱动程序将事件发送至 默认事件循环，应用程序便可以使用 esp_event_handler_register() 中的回调函数处理这些事件。除此之外，esp_netif 组件 也负责处理 Wi-Fi 事件，并产生一系列默认行为。例如，当 Wi-Fi station 连接至一个 AP 时，esp_netif 将自动开启 DHCP 客户端服务（系统默认）。

ESP32 Wi-Fi 事件描述

WIFI_EVENT_WIFI_READY

Wi-Fi 驱动程序永远不会生成此事件，因此，应用程序的事件回调函数可忽略此事件。在未来的版本中，此事件可能会被移除。

WIFI_EVENT_SCAN_DONE

扫描完成事件，由 esp_wifi_scan_start() 函数触发，将在以下情况下产生：

  • 扫描已完成，例如：Wi-Fi 已成功找到目标 AP 或已扫描所有信道。

  • 当前扫描因函数 esp_wifi_scan_stop() 而终止。

  • 在当前扫描完成之前调用了函数 esp_wifi_scan_start()。此时，新的扫描将覆盖当前扫描过程，并生成一个扫描完成事件。

以下情况下将不会产生扫描完成事件：

接收到此事件后，事件任务暂不做任何响应。首先，应用程序的事件回调函数需调用 esp_wifi_scan_get_ap_num() 和 esp_wifi_scan_get_ap_records() 获取已扫描的 AP 列表，然后触发 Wi-Fi 驱动程序释放在扫描过程中占用的内存空间（切记该步骤）。 更多详细信息，请参阅 ESP32 Wi-Fi 扫描。

WIFI_EVENT_STA_START

如果调用函数 esp_wifi_start() 后接收到返回值 ESP_OK，且当前 Wi-Fi 处于 station 或 station/AP 共存模式，则将产生此事件。接收到此事件后，事件任务将初始化 LwIP 网络接口 (netif)。通常，应用程序的事件回调函数需调用 esp_wifi_connect() 来连接已配置的 AP。

WIFI_EVENT_STA_STOP

如果调用函数 esp_wifi_stop() 后接收到返回值 ESP_OK，且当前 Wi-Fi 处于 station 或 station/AP 共存模式，则将产生此事件。接收到此事件后，事件任务将进行释放 station IP 地址、终止 DHCP 客户端服务、移除 TCP/UDP 相关连接并清除 LwIP station netif 等动作。此时，应用程序的事件回调函数通常不需做任何响应。

WIFI_EVENT_STA_CONNECTED

如果调用函数 esp_wifi_connect() 后接收到返回值 ESP_OK，且 station 已成功连接目标 AP，则将产生此连接事件。接收到此事件后，事件任务将启动 DHCP 客户端服务并开始获取 IP 地址。此时，Wi-Fi 驱动程序已准备就绪，可发送和接收数据。如果你的应用程序不依赖于 LwIP（即 IP 地址），则此刻便可以开始应用程序开发工作。但是，如果你的应用程序需基于 LwIP 进行，则还需等待 got ip 事件发生后才可开始。

WIFI_EVENT_STA_DISCONNECTED

此事件将在以下情况下产生：

  • 调用了函数 esp_wifi_disconnect() 或 esp_wifi_stop()，且 Wi-Fi station 已成功连接至 AP。

  • 调用了函数 esp_wifi_connect()，但 Wi-Fi 驱动程序因为某些原因未能成功连接至 AP，例如：未扫描到目标 AP、验证超时等。或存在多个 SSID 相同的 AP，station 无法连接所有已找到的 AP，也将产生该事件。

  • Wi-Fi 连接因为某些原因而中断，例如：station 连续多次丢失 N beacon、AP 踢掉 station、AP 认证模式改变等。

接收到此事件后，事件任务的默认动作为：

  • 关闭 station 的 LwIP netif。

  • 通知 LwIP 任务清除导致所有套接字状态错误的 UDP/TCP 连接。针对基于套接字编写的应用程序，其回调函数可以在接收到此事件时（如有必要）关闭并重新创建所有套接字。

应用程序处理此事件最常用的方法为：调用函数 esp_wifi_connect() 重新连接 Wi-Fi。但是，如果此事件是由函数 esp_wifi_disconnect() 引发的，则应用程序不应调用 esp_wifi_connect() 来重新连接。应用程序须明确区分此事件的引发原因，因为某些情况下应使用其它更好的方式进行重新连接。请参阅 Wi-Fi 重新连接 和 连接 Wi-Fi 时扫描。

需要注意的另一点是：接收到此事件后，LwIP 的默认动作是终止所有 TCP 套接字连接。大多数情况下，该动作不会造成影响。但对某些特殊应用程序可能除外。例如：

  • 应用程序创建一个了 TCP 连接，以维护每 60 秒发送一次的应用程序级、保持活动状态的数据。

  • 由于某些原因，Wi-Fi 连接被切断并引发了 WIFI_EVENT_STA_DISCONNECTED 事件。根据当前实现，此时所有 TCP 连接都将被移除，且保持活动的套接字将处于错误的状态中。但是，由于应用程序设计者认为网络层 不应 考虑这个 Wi-Fi 层的错误，因此应用程序不会关闭套接字。

  • 5 秒后，因为在应用程序的事件回调函数中调用了 esp_wifi_connect()，Wi-Fi 连接恢复。同时，station 连接至同一个 AP 并获得与之前相同的 IPV4 地址。

  • 60 秒后，当应用程序发送具有保持活动状态的套接字的数据时，套接字将返回错误，应用程序将关闭套接字并在必要时重新创建。

在上述场景中，理想状态下应用程序套接字和网络层将不会受到影响，因为在此过程中 Wi-Fi 连接只是短暂地断开然后快速恢复。

IP_EVENT_STA_GOT_IP

当 DHCP 客户端成功从 DHCP 服务器获取 IPV4 地址或 IPV4 地址发生改变时，将引发此事件。此事件意味着应用程序一切就绪，可以开始任务（如：创建套接字）。

IPV4 地址可能由于以下原因而发生改变：

  • DHCP 客户端无法重新获取/绑定 IPV4 地址，且 station 的 IPV4 重置为 0。

  • DHCP 客户端重新绑定了其它地址。

  • 静态配置的 IPV4 地址已发生改变。

函数 ip_event_got_ip_t 中的字段 ip_change 说明了 IPV4 地址是否发生改变。

套接字的状态是基于 IPV4 地址的，这意味着，如果 IPV4 地址发生改变，则所有与此 IPV4 相关的套接字都将变为异常。接收到此事件后，应用程序需关闭所有套接字，并在 IPV4 变为有效地址时重新创建应用程序。

IP_EVENT_GOT_IP6

当 IPV6 SLAAC 支持自动为 ESP32 配置一个地址，或 ESP32 地址发生改变时，将引发此事件。此事件意味着应用程序一切就绪，可以开始任务（如：创建套接字）。

IP_EVENT_STA_LOST_IP

当 IPV4 地址失效时，将引发此事件。

此事件不会在 Wi-Fi 断连后立刻出现。Wi-Fi 连接断开后，首先将启动一个 IPV4 地址丢失计时器（可通过 CONFIG_ESP_NETIF_LOST_IP_TIMER_ENABLE 与 CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL 配置）。如果 station 在该计时器超时之前成功获取了 IPV4 地址，则不会发生此事件。否则，此事件将在计时器超时时发生。

一般来说，应用程序可忽略此事件。这只是一个调试事件，主要使应用程序获知 IPV4 地址已丢失。

WIFI_EVENT_AP_START

与 WIFI_EVENT_STA_START 事件相似。

WIFI_EVENT_AP_STOP

与 WIFI_EVENT_STA_STOP 事件相似。

WIFI_EVENT_AP_STACONNECTED

每当有一个 station 成功连接 ESP32 AP 时，将引发此事件。接收到此事件后，事件任务将不做任何响应，应用程序的回调函数也可忽略这一事件。但是，你可以在此时进行一些操作，例如：获取已连接 station 的信息等。

WIFI_EVENT_AP_STADISCONNECTED

此事件将在以下情况下发生：

发生此事件时，事件任务将不做任何响应，但应用程序的事件回调函数需执行一些操作，例如：关闭与此 station 相关的套接字等。

WIFI_EVENT_AP_PROBEREQRECVED

默认情况下，此事件处于禁用状态，应用程序可以通过调用 API esp_wifi_set_event_mask() 启用。 启用后，每当 AP 接收到 probe request 时都将引发此事件。

WIFI_EVENT_STA_BEACON_TIMEOUT

如果 station 在 inactive 时间内未收到所连接 AP 的 beacon，将发生 beacon 超时，将引发此事件。inactive 时间通过调用函数 esp_wifi_set_inactive_time() 设置。

WIFI_EVENT_CONNECTIONLESS_MODULE_WAKE_INTERVAL_START

非连接模块在 Interval 开始时触发此事件。 请参考 非连接模块功耗管理 。

ESP32 Wi-Fi 配置

使能 Wi-Fi NVS 时，所有配置都将存储到 flash 中；反之，请参阅 Wi-Fi NVS Flash。

Wi-Fi 模式

调用函数 esp_wifi_set_mode() 设置 Wi-Fi 模式。

模式

描述

WIFI_MODE_NULL

NULL 模式：此模式下，内部数据结构不分配给 station 和 AP，同时，station 和 AP 接口不会为发送/接收 Wi-Fi 数据进行初始化。通常，此模式用于 Sniffer，或者你不想通过调用函数 esp_wifi_deinit() 卸载整个 Wi-Fi 驱动程序来同时停止 station 和 AP。

WIFI_MODE_STA

station 模式：此模式下，esp_wifi_start() 将初始化内部 station 数据，同时 station 接口准备发送/接收 Wi-Fi 数据。调用函数 esp_wifi_connect() 后，station 将连接到目标 AP。

WIFI_MODE_AP

AP 模式：在此模式下，esp_wifi_start() 将初始化内部 AP 数据，同时 AP 接口准备发送/接收 Wi-Fi 数据。随后，Wi-Fi 驱动程序开始广播 beacon，AP 即可与其它 station 连接。

WIFI_MODE_APSTA

station/AP 共存模式：在此模式下，函数 esp_wifi_start() 将同时初始化 station 和 AP。该步骤在 station 模式和 AP 模式下完成。请注意 ESP station 所连外部 AP 的信道优先于 ESP AP 信道。

Station 基本配置

API esp_wifi_set_config() 可用于配置 station。配置的参数信息会保存到 NVS 中。下表详细介绍了各个字段。

字段

描述

ssid

station 想要连接的目标 AP 的 SSID。

password

目标 AP 的密码。

scan_method

WIFI_FAST_SCAN 模式下，扫描到一个匹配的 AP 时即结束。 WIFI_ALL_CHANNEL_SCAN 模式下，在所有信道扫描所有匹配的 AP。默认扫描模式是 WIFI_FAST_SCAN。

bssid_set

如果 bssid_set 为 0，station 连接 SSID 与 “ssid” 字段相同的 AP，同时忽略字段 “bssid”。其他情况下，station 连接 SSID 与 “ssid” 字段相同、BSSID 与 “bssid” 字段也相同的 AP。

bssid

只有当 bssid_set 为 1 时有效。见字段 “bssid_set”。

channel

该字段为 0 时，station 扫描信道 1 ~ N 寻找目标 AP；否则，station 首先扫描值与 “channel” 字段相同的信道，再扫描其他信道。比如，当该字段设置为 3 时，扫描顺序为 3，1，2，...，N 。如果你不知道目标 AP 在哪个信道，请将该字段设置为 0。

sort_method

该字段仅用于 WIFI_ALL_CHANNEL_SCAN 模式。

如果设置为 WIFI_CONNECT_AP_BY_SIGNAL，所有匹配的 AP 将会按照信号强度排序，信号最好的 AP 会被首先连接。比如，如果 station 想要连接 ssid 为 “apxx” 的 AP，且扫描到两个这样的 AP。第一个 AP 的信号为 -90 dBm，第二个 AP 的信号为 -30 dBm，station 首先连接第二个 AP。除非失败，才会连接第一个。

如果设置为 WIFI_CONNECT_AP_BY_SECURITY，所有匹配的 AP 将会按照安全性排序。比如，如果 station 想要连接 ssid 为 “apxx” 的 AP，并且扫描到两个这样的 AP。第一个 AP 为开放式，第二个 AP 为 WPA2 加密，station 首先连接第二个 AP。除非失败，才会连接第一个。

threshold

该字段用来筛选找到的 AP，如果 AP 的 RSSI 或安全模式小于配置的阈值，则不会被连接。

如果 RSSI 设置为 0，则表示默认阈值、默认 RSSI 阈值为 -127 dBm。如果 authmode 阈值设置为 0，则表示默认阈值，默认 authmode 阈值为开放模式。

注意

WEP/WPA 安全模式在 IEEE802.11-2016 协议中已弃用，建议不要使用。可使用 authmode 阈值代替，通过将 threshold.authmode 设置为 WIFI_AUTH_WPA2_PSK 使用 WPA2 模式。

AP 基本配置

API esp_wifi_set_config() 可用于配置 AP。配置的参数信息会保存到 NVS 中。下表详细介绍了各个字段。

字段

描述

ssid

指 AP 的 SSID。如果 ssid[0] 和 ssid[1] 均为 0xFF，AP 默认 SSID 为 ESP_aabbcc，”aabbcc” 是 AP MAC 的最后三个字节。

password

AP 的密码。如果身份验证模式为 WIFI_AUTH_OPEN，此字段将被忽略。

ssid_len

SSID 的长度。如果 ssid_len 为 0，则检查 SSID 直至出现终止字符。如果 ssid_len 大于 32，请更改为 32，或者根据 ssid_len 设置 SSID 长度。

channel

AP 的信道。如果信道超出范围，Wi-Fi 驱动程序将返回 error。所以，请确保信道在要求的范围内。有关详细信息，请参阅 Wi-Fi 国家/地区代码。

authmode

ESP AP 的身份验证模式。目前，ESP AP 不支持 AUTH_WEP。如果 authmode 是一个无效值，AP 默认该值为 WIFI_AUTH_OPEN。

ssid_hidden

如果 ssid_hidden 为 1，AP 不广播 SSID。若为其他值，则广播。

max_connection

允许连接 station 的最大数目，默认值是 10。ESP Wi-Fi 支持 15 (ESP_WIFI_MAX_CONN_NUM) 个 Wi-Fi 连接。请注意， ESP AP 和 ESP-NOW 共享同一块加密硬件 keys，因此 max_connection 参数将受到 CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM 的影响。加密硬件 keys 的总数是 17，如果 CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM 小于等于 2，那么 max_connection 最大可以设置为 15，否则 max_connection 最大可以设置为 (17 - CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM)。

beacon_interval

beacon 间隔。值为 100 ~ 60000 ms，默认值为 100 ms。如果该值不在上述范围，AP 默认取 100 ms。

Wi-Fi 协议模式

目前，IDF 支持以下协议模式：

协议模式

描述

802.11b

调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B)，将 station/AP 设置为仅 802.11b 模式。

802.11bg

调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G)，将 station/AP 设置为 802.11bg 模式。

802.11g

调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11g 模式。

802.11bgn

调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)，将 station/AP 设置为 802.11bgn 模式。

802.11gn

调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11gn 模式。

802.11 BGNLR

调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR)，将 station/AP 设置为 802.11bgn 和 LR 模式。

802.11 LR

调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR)，将 station/AP 设置为 LR 模式。

此模式是乐鑫的专利模式，可以达到 1 公里视线范围。请确保 station 和 AP 同时连接至 ESP 设备。

Wi-Fi 带宽模式

ESP32 目前支持 20 MHz 和 40 MHz 两种带宽模式，并与协议模式组合使用，常见的组合包括：

  • HT20：802.11n，20 MHz 带宽

  • HT40：802.11n，40 MHz 带宽

备注

  • 40 MHz 带宽模式仅在 802.11n 模式下支持。

应用程序可以使用 esp_wifi_set_bandwidth() API 来设置当前接口的带宽模式。

示例：

// 设置 STA 的协议为 802.11bgn
uint8_t protocol = WIFI_PROTOCOL_11B | WIFI_PROTOCOL_11G | WIFI_PROTOCOL_11N;
esp_wifi_set_protocol(WIFI_IF_STA, protocol);

// 设置 STA 的带宽为 40 MHz
esp_wifi_set_bandwidth(WIFI_IF_STA, WIFI_BW_HT40);

长距离 (LR)

长距离 (LR) 模式是乐鑫的一项专利 Wi-Fi 模式，可达到 1 公里视线范围。与传统 802.11b 模式相比，接收灵敏度更高，抗干扰能力更强，传输距离更长。

LR 兼容性

由于 LR 是乐鑫的独有 2.4 GHz 频段 Wi-Fi 模式，只有 ESP32 芯片系列设备（ESP32-C2 除外）才能传输和接收 LR 数据。也就是说，如果连接的设备不支持 LR，ESP32 芯片系列设备（ESP32-C2 除外）则不会以 LR 数据速率传输数据。可通过配置适当的 Wi-Fi 模式使你的应用程序实现这一功能。

  • 如果协商的模式支持 LR，ESP32 芯片系列设备（ESP32-C2 除外）可能会以 LR 速率传输数据。

  • 否则，ESP32 芯片系列设备（ESP32-C2 除外）将以传统 Wi-Fi 数据速率传输所有数据。

下表是 2.4 GHz 频段 Wi-Fi 模式协商：

APSTA

BGN

BG

B

BGNLR

BGLR

BLR

LR

BGN

BGN

BG

B

BGN

BG

B

BG

BG

BG

B

BG

BG

B

B

B

B

B

B

B

B

BGNLR

BGNLR

BGLR

BLR

LR

BGLR

BGLR

BGLR

BLR

LR

BLR

BLR

BLR

BLR

LR

LR

LR

LR

LR

LR

上表中，行是 AP 的 Wi-Fi 模式，列是 station 的 Wi-Fi 模式。"-" 表示 AP 和 station 的 Wi-Fi 模式不兼容。

根据上表，得出以下结论：

  • 对于已使能 LR 的 ESP32 AP，由于以 LR 模式发送 beacon，因此与传统的 802.11 模式不兼容。

  • 对于已使能 LR 且并非仅 LR 模式的 ESP32 station，与传统 802.11 模式兼容。

  • 如果 station 和 AP 都是 ESP32 芯片系列设备（ESP32-C2 除外），并且两者都使能 LR 模式，则协商的模式支持 LR。

如果协商的 Wi-Fi 模式同时支持传统的 802.11 模式和 LR 模式，则 Wi-Fi 驱动程序会在不同的 Wi-Fi 模式下自动选择最佳数据速率，应用程序无需任何操作。

LR 对传统 Wi-Fi 设备的影响

以 LR 速率进行的数据传输不会影响传统 Wi-Fi 设备，因为：

  • LR 模式下的 CCA 和回退过程符合 802.11 协议。

  • 传统的 Wi-Fi 设备可以通过 CCA 检测 LR 信号并进行回退。

也就是说，LR 模式下传输效果与 802.11b 模式相似。

LR 传输距离

LR 的接收灵敏度比传统的 802.11b 模式高 4 dB，理论上，传输距离约为 11B 的 2 至 2.5 倍。

LR 吞吐量

因为原始 PHY 数据传输速率为 1/2 Mbps 和 1/4 Mbps，LR 的吞吐量有限。

何时使用 LR

使用 LR 的一般条件如下：

  • AP 和 station 都是乐鑫设备。

  • 需要长距离 Wi-Fi 连接和数据传输。

  • 数据吞吐量要求非常小，例如远程设备控制等。

Wi-Fi 国家/地区代码

调用 esp_wifi_set_country()，设置国家/地区信息。下表详细介绍了各个字段，请在配置这些字段之前参考当地的 2.4 GHz RF 操作规定。

字段

描述

cc[3]

国家/地区代码字符串，此属性标识 station/AP 位于的国家/地区或非国家/地区实体。如果是一个国家/地区，该字符串的前两个八位字节是 ISO/IEC3166-1 中规定的国家/地区两位字母代码。第三个八位字节应是下述之一：

  • ASCII 码空格字符，代表 station/AP 所处国家/地区的规定允许当前频段所需的所有环境。

  • ASCII 码 ‘O’ 字符，代表 station/AP 所处国家/地区的规定仅允许室外环境。

  • ASCII 码 ‘I’ 字符，代表 station/AP 所处国家/地区的规定仅允许室内环境。

  • ASCII 码 ‘X’ 字符，代表 station/AP 位于非国家/地区实体。非国家实体的前两个八位字节是两个 ASCII 码 ‘XX’ 字符。

  • 当前使用的操作类表编号的二进制形式。见 IEEE Std 802.11-2020 附件 E。

schan

起始信道，station/AP 所处国家/地区规定的最小信道值。

nchan

规定的总信道数，比如，如果 schan=1，nchan=13，那么 station/AP 可以从信道 1 至 13 发送数据。

policy

国家/地区策略，当配置的国家/地区信息与所连 AP 的国家/地区信息冲突时，该字段决定使用哪一信息。更多策略相关信息，可参见下文。

默认国家/地区信息为:

wifi_country_t config = {
    .cc = "01",
    .schan = 1,
    .nchan = 11,
    .policy = WIFI_COUNTRY_POLICY_AUTO,
};

如果 Wi-Fi 模式为 station/AP 共存模式，则它们配置的国家/地区信息相同。有时，station 所连 AP 的国家/地区信息与配置的不同。例如，配置的 station 国家/地区信息为:

wifi_country_t config = {
    .cc = "JP",
    .schan = 1,
    .nchan = 14,
    .policy = WIFI_COUNTRY_POLICY_AUTO,
};

但所连 AP 的国家/地区信息为:

wifi_country_t config = {
    .cc = "CN",
    .schan = 1,
    .nchan = 13,
};

此时，使用所连 AP 的国家/地区信息。

下表描述了在不同 Wi-Fi 模式和不同国家/地区策略下使用的国家/地区信息，并描述了对主动扫描的影响。

Wi-Fi 模式

策略

描述

station 模式

WIFI_COUNTRY_POLICY_AUTO

如果所连 AP 的 beacon 中有国家/地区的 IE，使用的国家/地区信息为 beacon 中的信息，否则，使用默认信息。

扫描时：

主动扫描信道 1 至信道 11，被动扫描信道 12 至 信道 14。

请记住，如果带有隐藏 SSID 的 AP 和 station 被设置在被动扫描信道上，被动扫描将无法找到该 AP。也就是说，如果应用程序希望在每个信道中找到带有隐藏 SSID 的 AP，国家/地区信息应该配置为 WIFI_COUNTRY_POLICY_MANUAL。

station 模式

WIFI_COUNTRY_POLICY_MANUAL

总是使用配置的国家/地区信息。

扫描时：

主动扫描信道 schan 至信道 schan+nchan-1。

AP 模式

WIFI_COUNTRY_POLICY_AUTO

总是使用配置的国家/地区信息。

AP 模式

WIFI_COUNTRY_POLICY_MANUAL

总是使用配置的国家/地区信息。

station/AP 共存模式

WIFI_COUNTRY_POLICY_AUTO

该 station 与 station 模式、WIFI_COUNTRY_POLICY_AUTO 策略下使用的国家/地区信息相同。 如果 station 不连接任何外部 AP，AP 使用配置的国家/地区信息。如果 station 连接一个外部 AP，该 AP 的国家/地区信息与该 station 相同。

station/AP 共存模式

WIFI_COUNTRY_POLICY_MANUAL

该 station 与 station 模式、WIFI_COUNTRY_POLICY_MANUAL 策略下使用的国家/地区信息相同。 该 AP 与 AP 模式、WIFI_COUNTRY_POLICY_MANUAL 策略下使用的国家/地区信息相同。

主信道

AP 模式下，AP 的信道定义为主信道。station 模式下，station 所连 AP 的信道定义为主信道。station/AP 共存模式下，AP 和 station 的主信道必须相同。如果不同，station 的主信道始终优先。比如，初始时，AP 位于信道 6，但 station 连接信道 9 的 AP。因为 station 的主信道具有优先性，该 AP 需要将信道从 6 切换至 9，确保与 station 主信道相同。切换信道时，AP 模式下的 ESP32 将使用信道切换公告 (CSA) 通知连接的 station。支持信道切换的 station 将直接通过，无需与 AP 断连再重新连接。

Wi-Fi Menuconfig

Wi-Fi 缓冲区配置

如果要修改默认的缓冲区数量或类型，最好也了解缓冲区在数据路径中如何分配或释放。下图显示了发送数据方向的过程。

TX Buffer Allocation

描述：

  • 应用程序分配需要发送的数据。

  • 应用程序调用 TCPIP 或套接字相关的 API 发送用户数据。这些 API 会分配一个在 LwIP 中使用的 PBUF，并复制用户数据。

  • 当 LwIP 调用 Wi-Fi API 发送 PBUF 时，Wi-Fi API 会分配一个“动态发送数据缓冲区”或“静态发送数据缓冲区”，并复制 LwIP PBUF，最后发送数据。

下图展示了如何在接收数据方向分配或释放缓冲区：

接收数据缓冲区分配

描述：

  • Wi-Fi 硬件在空中接收到数据包后，将数据包内容放到“静态接收数据缓冲区”，也就是“接收数据 DMA 缓冲区”。

  • Wi-Fi 驱动程序分配一个“动态接收数据缓冲区”、复制“静态接收数据缓冲区”，并将“静态接收数据缓冲区”返回给硬件。

  • Wi-Fi 驱动程序将数据包传送到上层 (LwIP)，并分配一个 PBUF 用于存放“动态接收数据缓冲区”。

  • 应用程序从 LwIP 接收数据。

下表是 Wi-Fi 内部缓冲区的配置情况。

缓冲区类型

分配类型

默认

是否可配置

描述

静态接收数据缓冲区（硬件接收数据缓冲区）

静态

10 * 1600 Bytes

是

这是一种 DMA 内存，在函数 esp_wifi_init() 中初始化，在函数 esp_wifi_deinit() 中释放。 该缓冲区形成硬件接收列表。当通过空中接收到一个帧时，硬件将该帧写入缓冲区，并向 CPU 发起一个中断。然后，Wi-Fi 驱动程序从缓冲区中读取内容，并将缓冲区返回到列表中。

如果应用程序希望减少 Wi-Fi 静态分配的内存，可以将该值从 10 减少到 6， 从而节省 6400 Bytes 的内存。除非禁用 AMPDU 功能，否则不建议将该值降低到 6 以下。

动态接收数据缓冲区

动态

32

是

缓冲区的长度可变，取决于所接收帧的长度。当 Wi-Fi 驱动程序 从“硬件接收数据缓冲区”接收到一帧时，需要从堆中分配“动态接收数据缓冲区”。在 Menuconfig 中配置的“动态接收数据缓冲区” 数量用来限制未释放的“动态接收数据缓冲区”总数量。

动态发送数据缓冲区

动态

32

是

这是一种 DMA 内存，位于堆内存中。当上层 (LwIP) 向 Wi-Fi 驱动程序发送数据包时，该缓冲区首先分配一个“动态发送数据缓 冲区”，并复制上层缓冲区。

动态发送数据缓冲区和静态发送数据缓冲区相互排斥。

静态发送数据缓冲区

静态

16 * 1600 Bytes

是

这是一种 DMA 内存，在函数 esp_wifi_init() 中初始化，在函数 esp_wifi_deinit() 中释放。 当上层 (LwIP) 向 Wi-Fi 驱动程序发送数据包时，该缓冲区首先 分配一个“静态发送数据缓冲区”，并复制上层缓冲区。

动态发送数据缓冲区和静态发送数据缓冲区相互排斥。

由于发送数据缓冲区必须是 DMA 缓冲区，所以当使能 PSRAM 时，发送数据缓冲区必须是静态的。

管理短缓冲区

动态

8

否

Wi-Fi 驱动程序的内部缓冲区。

管理长缓冲区

动态

32

否

Wi-Fi 驱动程序的内部缓冲区。

管理超长缓冲区

动态

32

否

Wi-Fi 驱动程序的内部缓冲区。

Wi-Fi NVS Flash

如果使能 Wi-Fi NVS flash，所有通过 Wi-Fi API 设置的 Wi-Fi 配置都会被存储到 flash 中，Wi-Fi 驱动程序在下次开机或重启时将自动加载这些配置。但是，应用程序可视情况禁用 Wi-Fi NVS flash，例如：其配置信息不需要存储在非易失性内存中、其配置信息已安全备份，或仅出于某些调试原因等。

故障排除

请见 乐鑫 Wireshark 使用指南。

此文档对您有帮助吗？