- 支持 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
- 支持快速扫描和全信道扫描
- 支持多天线
- 支持获取信道状态信息

- 支持 3 个虚拟接口，即 STA、AP 和 Sniffer
- 支持仅 station 模式、仅 AP 模式、station/AP 共存模式
- 支持使用 IEEE 802.11b、IEEE 802.11g、IEEE 802.11n 和 API 配置协议模式
- 支持 WPA/WPA2/WPA3/WPA2-企业版/WPA3-企业版/WPS 和 DPP
- 支持 AMPDU、QoS 以及其它主要功能
- 支持 Modem-sleep
- 空中数据传输最高可达 20 MBit/s TCP 吞吐量和 30 MBit/s UDP 吞吐量
- 支持 Sniffer
- 支持快速扫描和全信道扫描
- 支持多个天线

- 支持 4 个虚拟接口，即 STA、AP、Sniffer 和 reserved
- 支持仅 station 模式、仅 AP 模式、station/AP 共存模式
- 支持使用 IEEE 802.11b、IEEE 802.11g、IEEE 802.11n、IEEE 802.11ax 和 API 配置协议模式
- 支持 WPA/WPA2/WPA3/WPA2-企业版/WPA3-企业版/WAPI/WPS 和 DPP
- 支持 AMSDU、AMPDU、HT40、QoS 以及其它主要功能
- 支持 Modem-sleep
- 支持乐鑫专属协议，可实现 **1 km** 数据通信量
- 空中数据传输最高可达 20 MBit/s TCP 吞吐量和 30 MBit/s UDP 吞吐量
- 支持 Sniffer
- 支持快速扫描和全信道扫描
- 支持多个天线
- 支持获取信道状态信息
- 支持 Individual TWT 和 Broadcast TWT
- 支持下行 MU-MIMO
- 支持 OFDMA
- 支持 BSS Color

- 支持 4 个虚拟接口，即 STA、AP、Sniffer 和 reserved
- 支持仅 station 模式、仅 AP 模式、station/AP 共存模式
- 支持使用 IEEE 802.11b、IEEE 802.11g、IEEE 802.11n、IEEE 802.11a、IEEE 802.11ac、IEEE 802.11ax 和 API 配置协议模式
- 支持 WPA/WPA2/WPA3/WPA2-企业版/WPA3-企业版/WAPI/WPS 和 DPP
- 支持 AMSDU、AMPDU、HT40、QoS 以及其它主要功能
- 支持 Modem-sleep
- 2.4 GHz 支持乐鑫专属协议，可实现 **1 km** 数据通信量
- 空中数据传输最高可达 20 MBit/s TCP 吞吐量和 30 MBit/s UDP 吞吐量
- 支持 Sniffer
- 支持快速扫描和全信道扫描
- 支持多个天线
- 支持获取信道状态信息
- 支持 Individual TWT 和 Broadcast TWT
- 支持下行 MU-MIMO
- 支持 OFDMA
- 支持 BSS Color

- Wi-Fi Aware (NAN)

- :example:`wifi/itwt` 演示如何使用 iTWT 功能，该功能仅在 station 模式下工作，并在不同的省电模式下提供设置、拆卸和挂起的命令，还展示了启用和禁用 iTWT 时的电流消耗差异。

blockdiag wifi-programming-model {

    # global attributes
    node_height = 60;
    node_width = 100;
    span_width = 100;
    span_height = 60;
    default_shape = roundedbox;
    default_group_color = none;

    # node labels
    TCP_STACK [label="TCP\n stack", fontsize=12];
    EVNT_TASK [label="Event\n task", fontsize=12];
    APPL_TASK [label="Application\n task", width = 120, fontsize=12];
    WIFI_DRV  [label="Wi-Fi\n Driver", width = 120, fontsize=12];
    KNOT [shape=none];

    # node connections + labels
    TCP_STACK -> EVNT_TASK [label=event];
    EVNT_TASK -> APPL_TASK [label="callback\n or event"];

    # arrange nodes vertically
    group {
       label = "default handler";
       orientation = portrait;
       EVNT_TASK <- WIFI_DRV [label=event];
    }

    # intermediate node
    group {
        label = "user handler";
        orientation = portrait;
        APPL_TASK -- KNOT;
    }
    WIFI_DRV <- KNOT [label="API\n call"];
}

Wi-Fi 频段配置
+++++++++++++++++++++++++

可通过函数 :cpp:func:`esp_wifi_set_band_mode()` 设置 {IDF_TARGET_NAME} 所使用的 Wi-Fi 频段模式。

.. list-table::
    :header-rows: 1
    :widths: 15 50

    * - 模式
      - 描述
    * - ``WIFI_BAND_MODE_2G_ONLY``
      - **2.4 GHz 频段模式**：设备仅可在 2.4 GHz 频段信道上工作。
    * - ``WIFI_BAND_MODE_5G_ONLY``
      - **5 GHz 频段模式**：设备仅可在 5 GHz 频段信道上工作。
    * - ``WIFI_BAND_MODE_AUTO``
      - **2.4 GHz + 5 GHz 自动模式**：设备可根据所连接的 AP 或 SoftAP 配置，自动选择 2.4 GHz 或 5 GHz 频段。

.. note::
    - ``WIFI_BAND_MODE_AUTO`` 并不表示同时支持双频段，而是允许自动选择频段。

    当工作在 ``WIFI_BAND_MODE_AUTO`` 模式下时，可以分别为 2.4 GHz 和 5 GHz 频段配置协议和带宽：

    - 使用函数 :cpp:func:`esp_wifi_set_protocols()` 设置每个频段支持的协议类型（例如 802.11b/g/n/ac/ax）；

    - 使用函数 :cpp:func:`esp_wifi_set_bandwidths()` 设置每个频段的带宽（如 20MHz、40MHz等）。

AP 选择
+++++++++++++++++++++++++

当设备扫描到多个 SSID 相同的 AP（接入点）时，{IDF_TARGET_NAME} 会根据信号强度（RSSI）以及频段等信息，选择最合适的 AP 进行连接。默认策略通常优先选择 RSSI 更高的 AP，但在 2.4 GHz 与 5 GHz 并存的环境下，这可能导致设备偏向连接 2.4 GHz 频段，忽略 5 GHz 频段的高性能优势。

为此，ESP-IDF 提供了 :cpp:type:`wifi_scan_threshold_t` 结构体中的 :cpp:member:`rssi_5g_adjustment` 字段，用于优化 5G AP 的选择优先级。

.. list-table::
  :header-rows: 1
  :widths: 30 70

  * - 字段
    - 描述
  * - ``rssi_5g_adjustment``
    - 用于在 SSID 相同的 2.4 GHz 和 5 GHz AP 之间进行优先级调整。默认值为 ``10``，表示当 5 GHz AP 的 RSSI 至少比 2.4 GHz AP 低 ``10 dB`` 以内时，优先连接 5 GHz AP。通过合理设置该参数，可以在信号强度接近时优先连接具有更好带宽与干扰抵抗能力的 5 GHz 网络。

示例：

若设备扫描到以下两个 AP，SSID 均为 "MyWiFi"：

- 2.4 GHz AP：RSSI = -60 dBm
- 5 GHz AP：RSSI = -68 dBm

则由于 ``rssi_5g_adjustment = 10``（默认值）， 且满足 ``-68 > -60 - 10`` ，设备会优先连接 5 GHz AP。

.. note::

    该参数仅在扫描结果中存在相同 SSID 且分别处于 2.4 GHz 与 5 GHz 频段的 AP 时生效。其目的是避免设备总是连接信号强度略高但性能较差的 2.4 GHz 网络。

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

.. list-table::
  :header-rows: 1
  :widths: 15 55

  * - 字段
    - 描述
  * - 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 支持 {IDF_TARGET_MAX_CONN_STA_NUM} (``ESP_WIFI_MAX_CONN_NUM``) 个 Wi-Fi 连接。请注意， ESP AP 和 ESP-NOW 共享同一块加密硬件 keys，因此 max_connection 参数将受到 :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` 的影响。加密硬件 keys 的总数是 17，如果 :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` 小于等于 {IDF_TARGET_SUB_MAX_NUM_FROM_KEYS}，那么 max_connection 最大可以设置为 {IDF_TARGET_MAX_CONN_STA_NUM}，否则 max_connection 最大可以设置为 (17 - :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`)。
  * - beacon_interval
    - beacon 间隔。值为 100 ~ 60000 ms，默认值为 100 ms。如果该值不在上述范围，AP 默认取 100 ms。

.. list-table::
  :header-rows: 1
  :widths: 15 55

  * - 字段
    - 描述
  * - 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 驱动程序将默认为信道 1。所以，请确保信道在要求的范围内。有关详细信息，请参阅 `Wi-Fi 国家/地区代码`_。
  * - authmode
    - ESP AP 的身份验证模式。目前，ESP AP 不支持 AUTH_WEP。如果 authmode 是一个无效值，AP 默认该值为 ``WIFI_AUTH_OPEN``。
  * - ssid_hidden
    - 如果 ssid_hidden 为 1，AP 不广播 SSID。若为其他值，则广播。
  * - max_connection
    - 允许连接 station 的最大数目，默认值是 2。ESP Wi-Fi 支持 {IDF_TARGET_MAX_CONN_STA_NUM} (``ESP_WIFI_MAX_CONN_NUM``) 个 Wi-Fi 连接。请注意， ESP AP 和 ESP-NOW 共享同一块加密硬件 keys，因此 max_connection 参数将受到 :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` 的影响。加密硬件 keys 的总数是 {IDF_TARGET_MAX_CONN_STA_NUM}， max_connection 最大可以设置为 ({IDF_TARGET_MAX_CONN_STA_NUM} - :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`)。
  * - beacon_interval
    - beacon 间隔。值为 100 ~ 60000 ms，默认值为 100 ms。如果该值不在上述范围，AP 默认取 100 ms。

.. list-table::
  :header-rows: 1
  :widths: 15 55

  * - 协议模式
    - 描述
  * - 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 设备。**

.. list-table::
  :header-rows: 1
  :widths: 15 55

  * - 协议模式
    - 描述
  * - 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.11bgnax
    - 调用函数 ``esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_11AX)``，将 station/AP 设置为 802.11bgnax 模式。
  * - 802.11 BGNAXLR
    - 调用函数 ``esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_11AX|WIFI_PROTOCOL_LR)``，将 station/AP 设置为 802.11bgnax 和 LR 模式。
  * - 802.11 LR
    - 调用函数 ``esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR)``，将 station/AP 设置为 LR 模式。

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

- **2.4 GHz 频段**：支持 802.11b、802.11bg、802.11bgn、802.11bgnax 以及乐鑫专有的 LR 模式。
- **5 GHz 频段**：支持 802.11a、802.11an、802.11anac 和 802.11anacax。

{IDF_TARGET_NAME} 支持为 2.4 GHz 和 5 GHz 频段分别配置 Wi-Fi 协议模式。推荐使用 :cpp:func:`esp_wifi_set_protocols()` 进行配置，也兼容旧接口 :cpp:func:`esp_wifi_set_protocol()`。

**推荐用法**

使用新 API :cpp:func:`esp_wifi_set_protocols()`，分别设置两个频段的协议：

.. code-block:: c

    // 设置 2.4 GHz 使用 802.11bgnax，5 GHz 使用 802.11anacax 协议
    wifi_protocols_t protocols = {
        .ghz_2g = WIFI_PROTOCOL_11B | WIFI_PROTOCOL_11G | WIFI_PROTOCOL_11N | WIFI_PROTOCOL_11AX,
        .ghz_5g = WIFI_PROTOCOL_11A | WIFI_PROTOCOL_11N | WIFI_PROTOCOL_11AC | WIFI_PROTOCOL_11AX,
    };
    esp_wifi_set_protocols(WIFI_IF_STA, &protocols);

**兼容用法**

使用旧 API :cpp:func:`esp_wifi_set_protocol()`，配置 2.4 GHz 或者 5 GHz 频段的协议：

.. code-block:: c

    // 设置频段为 2.4 GHz 频段
    esp_wifi_set_band_mode(WIFI_BAND_MODE_2G_ONLY);

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

.. note::

    - 新接口 `esp_wifi_set_protocols()` 可同时配置两个频段，建议在{IDF_TARGET_NAME}上优先使用。
    - ``esp_wifi_set_protocol()`` 适用于仅使用单一频段的场景，如 ``WIFI_BAND_MODE_2G_ONLY`` 或 ``WIFI_BAND_MODE_5G_ONLY`` 模式。仅对当前连接的频段生效，例如，当接口处于 5 GHz 频段时，该函数将忽略对 2.4 GHz 频段的配置。
    - 若配置包含不受支持的协议组合，函数调用将返回错误。
    - 如需启用乐鑫专有 LR 模式，请确保 2.4 GHz 配置中包含 `WIFI_PROTOCOL_LR`。

.. list-table::
  :header-rows: 1
  :widths: 15 55

  * - 协议模式
    - 描述
  * - 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 模式。

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

- **HT20**：802.11n，20 MHz 带宽
- **HT40**：802.11n，40 MHz 带宽

.. note::

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

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

示例：

.. code-block:: c

    // 设置 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_BW40);

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

- **HT20**：802.11n，20 MHz 带宽
- **HT40**：802.11n，40 MHz 带宽
- **HE20**：802.11ax，20 MHz 带宽

.. note::

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

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

示例：

.. code-block:: c

    // 设置 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_BW40);

{IDF_TARGET_NAME} 当前支持 20 MHz 和 40 MHz 两种带宽模式，可与不同协议模式组合使用，常见配置包括：

- **HT20**：802.11n/11an，20 MHz 带宽
- **HT40**：802.11n/11an，40 MHz 带宽
- **HE20**：802.11ax，20 MHz 带宽

.. note::

    - 40 MHz 模式仅适用于 802.11n（2.4 GHz）或 802.11an（5 GHz）协议。

应用程序可使用 :cpp:func:`esp_wifi_set_bandwidths()` API，分别为 2.4 GHz 和 5 GHz 配置独立带宽。

示例：

.. code-block:: c

    // 设置 2.4 GHz 使用 802.11bgnax，5 GHz 使用 802.11an 协议
    wifi_protocols_t protocols = {
        .ghz_2g = WIFI_PROTOCOL_11B | WIFI_PROTOCOL_11G | WIFI_PROTOCOL_11N | WIFI_PROTOCOL_11AX,
        .ghz_5g = WIFI_PROTOCOL_11A | WIFI_PROTOCOL_11N,
    };
    esp_wifi_set_protocols(WIFI_IF_STA, &protocols);

    // 设置 2.4 GHz 带宽为 20 MHz，5 GHz 带宽为 40 MHz
    wifi_bandwidths_t bw = {
        .ghz_2g = WIFI_BW20,
        .ghz_5g = WIFI_BW40
    };
    esp_wifi_set_bandwidths(WIFI_IF_STA, &bw);

.. note::

    - 若 `.ghz_2g` 设置为 0，仅配置 5 GHz 带宽，2.4 GHz 保持不变。
    - 若 `.ghz_5g` 设置为 0，仅配置 2.4 GHz 带宽，5 GHz 保持不变。

**兼容用法**

可使用旧版 API :cpp:func:`esp_wifi_set_bandwidth()` 配置 2.4 GHz 频段或者 5 GHz 频段的带宽：

.. code-block:: c

      // 设置频段为 5 GHz 频段
      esp_wifi_set_band_mode(WIFI_BAND_MODE_5G_ONLY);

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

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

.. note::

    - 新版 API :cpp:func:`esp_wifi_set_bandwidths()` 支持同时配置 2.4 GHz 与 5 GHz 带宽，推荐在 {IDF_TARGET_NAME} 上优先使用。
    - ``esp_wifi_set_bandwidth()`` 适用于单频段场景，如 ``WIFI_BAND_MODE_2G_ONLY`` 或 ``WIFI_BAND_MODE_5G_ONLY``，仅作用于当前连接频段。例如，若接口工作在 5 GHz，则 2.4 GHz 的配置将被忽略。
    - 若设置了当前频段不支持的带宽值，函数将返回错误。

{IDF_TARGET_NAME} 目前仅支持 20 MHz 带宽模式。

长距离 (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 模式协商：

.. only:: esp32 or esp32s2 or esp32c3 or esp32s3

    +-------+-----+----+---+-------+------+-----+----+
    |AP\STA | 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 |
    +-------+-----+----+---+-------+------+-----+----+

.. only:: esp32c5 or esp32c6

    +---------+-------+-----+----+---+---------+-------+------+-----+----+
    | AP\STA  | BGNAX | BGN | BG | B | BGNAXLR | BGNLR | BGLR | BLR | LR |
    +=========+=======+=====+====+===+=========+=======+======+=====+====+
    | BGNAX   | BGAX  | BGN | BG | B | BGAX    | BGN   | BG   | B   | -  |
    +---------+-------+-----+----+---+---------+-------+------+-----+----+
    | BGN     | BGN   | BGN | BG | B | BGN     | BGN   | BG   | B   | -  |
    +---------+-------+-----+----+---+---------+-------+------+-----+----+
    | BG      | BG    | BG  | BG | B | BG      | BG    | BG   | B   | -  |
    +---------+-------+-----+----+---+---------+-------+------+-----+----+
    | B       | B     | B   | B  | B | B       | B     | B    | B   | -  |
    +---------+-------+-----+----+---+---------+-------+------+-----+----+
    | BGNAXLR | -     | -   | -  | - | BGAXLR  | BGNLR | BGLR | BLR | LR |
    +---------+-------+-----+----+---+---------+-------+------+-----+----+
    | BGNLR   | -     | -   | -  | - | BGNLR   | BGNLR | BGLR | BLR | LR |
    +---------+-------+-----+----+---+---------+-------+------+-----+----+
    | BGLR    | -     | -   | -  | - | BGLR    | BGLR  | BGLR | BLR | LR |
    +---------+-------+-----+----+---+---------+-------+------+-----+----+
    | BLR     | -     | -   | -  | - | BLR     | BLR   | BLR  | BLR | LR |
    +---------+-------+-----+----+---+---------+-------+------+-----+----+
    | LR      | -     | -   | -  | - | LR      | LR    | LR   | LR  | LR |
    +---------+-------+-----+----+---+---------+-------+------+-----+----+

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

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

- 对于已使能 LR 的 {IDF_TARGET_NAME} AP，由于以 LR 模式发送 beacon，因此与传统的 802.11 模式不兼容。
- 对于已使能 LR 且并非仅 LR 模式的 {IDF_TARGET_NAME} 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 连接和数据传输。
- 数据吞吐量要求非常小，例如远程设备控制等。

动态频率选择（DFS）
+++++++++++++++++++++++++++++++++++++++++++++++++++++++

在 5 GHz Wi-Fi 频段中，一些信道（如信道 52 ~ 144）与天气雷达等关键通信系统共享频谱。为避免 Wi-Fi 信号对这些系统产生干扰，Wi-Fi 设备在使用这些信道前，必须执行特定的侦测与切换机制，即 **动态频率选择（DFS）**。

启用 DFS 的设备可以访问更多 5 GHz 信道，从而提高网络容量并减少干扰，尤其适用于高密度部署或需要大带宽的应用场景。不同国家和地区 DFS 信道范围可以参考 :component_file:`esp_wifi/regulatory/esp_wifi_regulatory.txt`

{IDF_TARGET_NAME} 支持在 5 GHz 频段使用 DFS 信道，但仅支持 **被动雷达检测** 功能。

.. list-table::
  :header-rows: 1
  :widths: 20 60

  * - 类型
    - 描述
  * - 被动雷达检测 支持
    - 设备在扫描过程中能够监听 DFS 信道，识别并连接工作在 DFS 信道上的接入点（AP）。当目标 AP 在 DFS 信道上检测到雷达并通过信道切换（CSA）切换信道时，{IDF_TARGET_NAME} 会跟随 AP 切换信道。
  * - 主动雷达检测 不支持
    - {IDF_TARGET_NAME} **不支持** 主动雷达检测功能，因此无法在 SoftAP 模式下作为 DFS AP 启动。

.. note::

    - 在 STA 模式下，{IDF_TARGET_NAME}  可连接至位于 DFS 信道上的 AP，前提是该信道已在扫描中被识别。
    - 在 SoftAP 模式下，{IDF_TARGET_NAME} 不允许使用 DFS 信道作为工作信道，以避免违反无线电监管规定。
    - 在 STA+SoftAP 共存模式下：

      1. 当 STA 连接到位于 DFS 信道的 AP 时，SoftAP 允许通过 CSA (Channel Switch Announcement) 切换至相同的 DFS 信道。
      2. 当 STA 断开连接后，SoftAP 将通过 CSA 切换回非 DFS 信道，确保符合监管要求。

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

.. list-table::
  :header-rows: 1
  :widths: 15 55

  * - 字段
    - 描述
  * - 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 模式和不同国家/地区策略下使用的国家/地区信息，并描述了对主动扫描的影响。

.. list-table::
  :header-rows: 1
  :widths: 15 15 35

  * - 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 策略下使用的国家/地区信息相同。

调用 :cpp:func:`esp_wifi_set_country()` 可设置国家/地区信息。下表详细介绍了各字段含义，请在配置这些字段前，参考本地 2.4 GHz 与 5 GHz 射频使用规定。

.. list-table::
  :header-rows: 1
  :widths: 15 55

  * - 字段
    - 描述
  * - cc[3]
    - 国家/地区代码字符串。用于标识 station/AP 所在的国家/地区，或非国家实体。如果为国家/地区，该字段的前两个字节为符合 ISO/IEC 3166-1 标准的两位国家代码，第三个字节含义如下：

      - 空格字符（ASCII），表示当前国家/地区在所有环境中允许使用相应频段。
      - 字符 `'O'`，表示仅允许在户外环境中使用。
      - 字符 `'I'`，表示仅允许在室内环境中使用。
      - 字符 `'X'`，表示非国家实体，此时前两个字符应为 `'X'`（即 `'XX'`）。
      - 二进制形式的操作类编号，参考 IEEE Std 802.11-2020 附录 E。

  * - schan
    - 起始信道值，即当前国家/地区在 2.4 GHz 频段中允许使用的最小信道。
  * - nchan
    - 信道数量。定义在 2.4 GHz 频段中允许使用的总信道数。例如，若 schan = 1，nchan = 13，则 station/AP 可使用信道 1 至 13。
  * - policy
    - 国家/地区策略。当配置的国家/地区与连接 AP 的信息冲突时，此字段决定应使用哪一方的信息。详情见下文说明。
  * - wifi_5g_channel_mask
    - 表示 station/AP 在 5 GHz 频段中可使用的信道掩码。信道值与位的对应关系详见 :cpp:enum:`wifi_5g_channel_bit_t`。

默认配置示例如下::

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

若 Wi-Fi 处于 station/AP 共存模式，则两者使用相同的国家/地区信息。有时，连接的 AP 的国家/地区信息可能与 station 预设的不同。例如：

配置的 station 信息为::

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

而连接的 AP 信息为::

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

此时将使用连接的 AP 的国家/地区信息。

下表说明了在不同 Wi-Fi 模式及策略下使用的国家/地区信息，并说明了扫描行为的差异：

.. list-table::
  :header-rows: 1
  :widths: 15 15 35

  * - Wi-Fi 模式
    - 策略
    - 描述
  * - station 模式
    - WIFI_COUNTRY_POLICY_AUTO
    - 若连接的 AP 的 beacon 中包含国家/地区信息 IE，则使用该信息；否则使用默认配置。

      扫描行为：

        - 2.4 GHz 频段：主动扫描信道 1–11，被动扫描信道 12–14；
        - 5 GHz 频段：主动扫描非 DFS 信道，被动扫描 DFS 信道。

      注意：若隐藏 SSID 的 AP 设在被动扫描信道上，扫描可能无法发现该 AP。若需在所有信道上发现隐藏 SSID，请使用 `WIFI_COUNTRY_POLICY_MANUAL`。

  * - station 模式
    - WIFI_COUNTRY_POLICY_MANUAL
    - 始终使用配置的国家/地区信息。

      扫描行为：

        - 2.4 GHz 频段：扫描从 `schan` 到 `schan + nchan - 1` 的信道；
        - 5 GHz 频段：扫描 `wifi_5g_channel_mask` 中标记支持的信道。

  * - AP 模式
    - WIFI_COUNTRY_POLICY_AUTO
    - 始终使用配置的国家/地区信息。
  * - AP 模式
    - WIFI_COUNTRY_POLICY_MANUAL
    - 始终使用配置的国家/地区信息。
  * - station/AP 共存模式
    - WIFI_COUNTRY_POLICY_AUTO
    - 与 station 模式中的 `WIFI_COUNTRY_POLICY_AUTO` 相同。

      若 station 未连接任何 AP，则 AP 使用配置的国家/地区信息；
      若 station 连接了外部 AP，则 AP 使用该 station 获取的国家/地区信息。

  * - station/AP 共存模式
    - WIFI_COUNTRY_POLICY_MANUAL
    - 与 station 模式中 `WIFI_COUNTRY_POLICY_MANUAL` 相同，AP 也始终使用配置的国家/地区信息。

blockdiag buffer_allocation_tx {

    # global attributes
    node_height = 60;
    node_width = 100;
    span_width = 50;
    span_height = 20;
    default_shape = roundedbox;

    # labels of diagram nodes
    APPL_TASK [label="Application\n task", fontsize=12];
    LwIP_TASK [label="LwIP\n task", fontsize=12];
    WIFI_TASK [label="Wi-Fi\n task", fontsize=12];

    # labels of description nodes
    APPL_DESC [label="1> User data", width=120, height=25, shape=note, color=yellow];
    LwIP_DESC [label="2> Pbuf", width=120, height=25, shape=note, color=yellow];
    WIFI_DESC [label="3> Dynamic (Static)\n TX Buffer", width=150, height=40, shape=note, color=yellow];

    # node connections
    APPL_TASK -> LwIP_TASK -> WIFI_TASK
    APPL_DESC -> LwIP_DESC -> WIFI_DESC [style=none]
}

blockdiag buffer_allocation_rx {

    # global attributes
    node_height = 60;
    node_width = 100;
    span_width = 40;
    span_height = 20;
    default_shape = roundedbox;

    # labels of diagram nodes
    APPL_TASK [label="Application\n task", fontsize=12];
    LwIP_TASK [label="LwIP\n task", fontsize=12];
    WIFI_TASK [label="Wi-Fi\n task", fontsize=12];
    WIFI_INTR [label="Wi-Fi\n interrupt", fontsize=12];

    # labels of description nodes
    APPL_DESC [label="4> User\n Data Buffer", height=40, shape=note, color=yellow];
    LwIP_DESC [label="3> Pbuf", height=40, shape=note, color=yellow];
    WIFI_DESC [label="2> Dynamic\n RX Buffer", height=40, shape=note, color=yellow];
    INTR_DESC [label="1> Static\n RX Buffer", height=40, shape=note, color=yellow];

    # node connections
    APPL_TASK <- LwIP_TASK <- WIFI_TASK <- WIFI_INTR
    APPL_DESC <- LwIP_DESC <- WIFI_DESC <- INTR_DESC [style=none]
}

../wireshark-user-guide