espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-10-03 18:40:59 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'docs/esp32c5_programming_guide_v5.5' into 'release/v5.5'

Browse Source 
feat(docs): support esp32c5 wifi programming guide docs(backport v5.5)

See merge request espressif/esp-idf!41592
This commit is contained in:
Jiang Jiang Jian
2025-09-02 10:33:45 +08:00
parent e9790c04fa 1a2a5f4d5b
commit 79834396ae
5 changed files with 1186 additions and 276 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/docs_not_updated/esp32c5.txt
View File

@@ -1,11 +1,7 @@
api-guides/low-power-mode.rst
api-guides/RF_calibration.rst
api-guides/deep-sleep-stub.rst
api-guides/wifi.rst
api-guides/esp-wifi-mesh.rst
api-guides/inc/external-ram-esp32-notes.rst
api-guides/current-consumption-measurement-modules.rst
api-guides/wifi-security.rst
api-reference/storage/vfs.rst
api-reference/storage/spiffs.rst
api-reference/storage/nvs_encryption.rst
@@ -18,16 +14,6 @@ api-reference/storage/mass_mfg.rst
api-reference/storage/fatfsgen.rst
api-reference/storage/index.rst
api-reference/storage/nvs_partition_parse.rst
api-reference/peripherals/touch_pad.rst
api-reference/peripherals/index.rst
api-reference/peripherals/ecdsa.rst
api-reference/network/esp_dpp.rst
api-reference/network/esp_now.rst
api-reference/network/esp-wifi-mesh.rst
api-reference/network/esp_smartconfig.rst
api-reference/network/esp_nan.rst
api-reference/network/esp_wifi.rst
api-reference/network/index.rst
api-reference/system/sleep_modes.rst
api-reference/system/async_memcpy.rst
api-reference/system/power_management.rst

710
docs/en/api-guides/wifi.rst
View File

@@ -27,9 +27,18 @@ The following features are supported:
- Multiple antennas
- Channel state information
.. only:: SOC_WIFI_NAN_SUPPORT
.. only:: esp32c2
- Wi-Fi Aware (NAN)
- 3 virtual Wi-Fi interfaces, which are STA, AP and Sniffer.
- Station-only mode, AP-only mode, station/AP-coexistence mode
- IEEE 802.11b, IEEE 802.11g, IEEE 802.11n, and APIs to configure the protocol mode
- WPA/WPA2/WPA3/WPA2-Enterprise/WPA3-Enterprise/WPS and DPP
- AMPDU, QoS, and other key features
- Modem-sleep
- Up to 20 MBit/s TCP throughput and 30 MBit/s UDP throughput over the air
- Sniffer
- Both fast scan and all-channel scan
- Multiple antennas
.. only:: esp32c6
@@ -45,23 +54,32 @@ The following features are supported:
- Both fast scan and all-channel scan
- Multiple antennas
- Channel state information
- TWT
- Individual TWT and Broadcast TWT
- Downlink MU-MIMO
- OFDMA
- BSS Color
.. only:: esp32c2
.. only:: esp32c5
- 3 virtual Wi-Fi interfaces, which are STA, AP and Sniffer.
- 4 virtual Wi-Fi interfaces, which are STA, AP, Sniffer and reserved.
- Station-only mode, AP-only mode, station/AP-coexistence mode
- IEEE 802.11b, IEEE 802.11g, IEEE 802.11n, and APIs to configure the protocol mode
- WPA/WPA2/WPA3/WPA2-Enterprise/WPA3-Enterprise/WPS and DPP
- AMPDU, QoS, and other key features
- IEEE 802.11b, IEEE 802.11g, IEEE 802.11n, IEEE 802.11a, IEEE 802.11ac, IEEE 802.11ax, and APIs to configure the protocol mode
- WPA/WPA2/WPA3/WPA2-Enterprise/WPA3-Enterprise/WAPI/WPS and DPP
- AMSDU, AMPDU, HT40, QoS, and other key features
- Modem-sleep
- The Espressif-specific ESP-NOW protocol and Long Range mode (only supported on 2.4 GHz band), which supports up to **1 km** of data traffic
- Up to 20 MBit/s TCP throughput and 30 MBit/s UDP throughput over the air
- Sniffer
- Both fast scan and all-channel scan
- Multiple antennas
- Channel state information
- Individual TWT and Broadcast TWT
- Downlink MU-MIMO
- OFDMA
- BSS Color
.. only:: SOC_WIFI_NAN_SUPPORT
- Wi-Fi Aware (NAN)
How To Write a Wi-Fi Application
@@ -1302,6 +1320,65 @@ Call :cpp:func:`esp_wifi_set_mode()` to set the Wi-Fi mode.
* - ``WIFI_MODE_APSTA``
- Station/AP coexistence mode: in this mode, :cpp:func:`esp_wifi_start()` will simultaneously initialize both the station and the AP. This is done in station mode and AP mode. Please note that the channel of the external AP, which the ESP station is connected to, has higher priority over the ESP AP channel.
.. only:: esp32c5
Wi-Fi Band Mode Configuration
++++++++++++++++++++++++++++++
The Wi-Fi band mode used by {IDF_TARGET_NAME} can be set via the function :cpp:func:`esp_wifi_set_band_mode()`.
.. list-table::
:header-rows: 1
:widths: 15 50
* - Mode
- Description
* - ``WIFI_BAND_MODE_2G_ONLY``
- **2.4 GHz band mode**: The device operates only on 2.4 GHz band channels.
* - ``WIFI_BAND_MODE_5G_ONLY``
- **5 GHz band mode**: The device operates only on 5 GHz band channels.
* - ``WIFI_BAND_MODE_AUTO``
- **2.4 GHz + 5 GHz auto mode**: The device automatically selects either the 2.4 GHz or 5 GHz band based on the connected AP or SoftAP configuration.
.. note::
- ``WIFI_BAND_MODE_AUTO`` does not mean simultaneous dual-band support; it only allows automatic band selection.
When operating in ``WIFI_BAND_MODE_AUTO`` mode, protocols and bandwidth can be configured separately for the 2.4 GHz and 5 GHz bands:
- Use the function :cpp:func:`esp_wifi_set_protocols()` to set the supported protocol types for each band (e.g., 802.11b/g/n/ac/ax);
- Use the function :cpp:func:`esp_wifi_set_bandwidths()` to set the bandwidth for each band (e.g., 20 MHz, 40 MHz).
.. only:: esp32c5
AP Choose
+++++++++++++++++++++++++
When the device scans multiple APs with the same SSID, {IDF_TARGET_NAME} selects the most suitable AP to connect to based on signal strength (RSSI) and band information. The default policy usually prefers the AP with higher RSSI; however, in environments where 2.4 GHz and 5 GHz coexist, this can cause the device to favor the 2.4 GHz band, ignoring the performance benefits of the 5 GHz band.
To address this, ESP-IDF provides the field :cpp:member:`rssi_5g_adjustment` in the :cpp:type:`wifi_scan_threshold_t` structure to optimize the priority of selecting 5 GHz APs.
.. list-table::
:header-rows: 1
:widths: 30 70
* - Field
- Description
* - ``rssi_5g_adjustment``
- Used to adjust priority between 2.4 GHz and 5 GHz APs with the same SSID. The default value is ``10``, meaning when the 5 GHz AP's RSSI is within 10 dB lower than the 2.4 GHz AP, the 5 GHz AP will be preferred. Properly setting this parameter helps the device prioritize 5 GHz networks that offer better bandwidth and interference resistance when signal strengths are close.
Example:
Suppose the device scans the following two APs with the SSID "MyWiFi":
- 2.4 GHz AP: RSSI = -60 dBm
- 5 GHz AP: RSSI = -68 dBm
Since ``rssi_5g_adjustment = 10`` (default) and ``-68 > -60 - 10`` holds true, the device will prioritize connecting to the 5 GHz AP.
.. note::
This parameter only takes effect when scanning results contain APs with the same SSID on both 2.4 GHz and 5 GHz bands. Its purpose is to avoid always connecting to a 2.4 GHz network with slightly stronger signal but poorer performance.
Station Basic Configuration
+++++++++++++++++++++++++++++++++++++
@@ -1347,7 +1424,7 @@ AP Basic Configuration
API :cpp:func:`esp_wifi_set_config()` can be used to configure the AP. And the configuration will be stored in NVS. The table below describes the fields in detail.
.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c6
.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c5 or esp32c6
.. list-table::
:header-rows: 1
@@ -1362,7 +1439,7 @@ API :cpp:func:`esp_wifi_set_config()` can be used to configure the AP. And the c
* - ssid_len
- Length of SSID; if ssid_len is 0, check the SSID until there is a termination character. If ssid_len > 32, change it to 32; otherwise, set the SSID length according to ssid_len.
* - channel
- Channel of AP; if the channel is out of range, the Wi-Fi driver defaults to channel 1. So, please make sure the channel is within the required range. For more details, refer to `Wi-Fi Country Code`_.
- Channel of AP; if the channel is out of range, the Wi-Fi driver will return error. So, please make sure the channel is within the required range. For more details, refer to `Wi-Fi Country Code`_.
* - authmode
- Auth mode of ESP AP; currently, ESP AP does not support AUTH_WEP. If the authmode is an invalid value, AP defaults the value to ``WIFI_AUTH_OPEN``.
* - ssid_hidden
@@ -1458,6 +1535,46 @@ Currently, the ESP-IDF supports the following protocol modes:
**This mode is an Espressif-patented mode which can achieve a one-kilometer line of sight range. Please make sure both the station and the AP are connected to an ESP device.**
.. only:: esp32c5
- **2.4 GHz band**: Supports 802.11b, 802.11bg, 802.11bgn, 802.11bgnax, and Espressif's proprietary LR mode.
- **5 GHz band**: Supports 802.11a, 802.11an, 802.11anac, and 802.11anacax.
{IDF_TARGET_NAME} supports configuring Wi-Fi protocol modes for the 2.4 GHz and 5 GHz bands separately. It is recommended to use :cpp:func:`esp_wifi_set_protocols()` for this purpose. The legacy API :cpp:func:`esp_wifi_set_protocol()` is also supported.
**Recommended Usage**
Use the new API :cpp:func:`esp_wifi_set_protocols()` to configure each band independently:
.. code-block:: c
// Set 2.4 GHz to use 802.11bgnax, and 5 GHz to use 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);
**Legacy Usage**
Use the legacy API :cpp:func:`esp_wifi_set_protocol()` to configure the protocol mode for 2.4 GHz band or 5 GHz band:
.. code-block:: c
// Set band mode to 2.4 GHz band
esp_wifi_set_band_mode(WIFI_BAND_MODE_2G_ONLY);
// Set protocol of station to 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::
- The new API `esp_wifi_set_protocols()` allows configuring both bands simultaneously and is recommended for use on {IDF_TARGET_NAME}.
- The function ``esp_wifi_set_protocol()`` is suitable for single-band scenarios, such as when ``WIFI_BAND_MODE_2G_ONLY`` or ``WIFI_BAND_MODE_5G_ONLY`` is used. It only takes effect on the currently connected band. For example, if the interface is operating on the 5 GHz band, any configuration for the 2.4 GHz band will be ignored.
- If the configuration includes unsupported protocol combinations, the function will return an error.
- To enable Espressif's proprietary LR mode, make sure to include `WIFI_PROTOCOL_LR` in the 2.4 GHz protocol configuration.
.. only:: esp32c2
.. list-table::
@@ -1477,9 +1594,122 @@ Currently, the ESP-IDF supports the following protocol modes:
* - 802.11gn
- Call ``esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)`` and ``esp_wifi_config_11b_rate(ifx, true)`` to set the station/AP to 802.11gn mode.
Wi-Fi Bandwidth Mode
++++++++++++++++++++++
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3 or esp32c6
{IDF_TARGET_NAME} currently supports 20 MHz and 40 MHz bandwidth modes, which are used in combination with protocol modes. Common combinations include:
- **HT20**: 802.11n with 20 MHz bandwidth
- **HT40**: 802.11n with 40 MHz bandwidth
.. note::
- The 40 MHz bandwidth mode is only supported in 802.11n mode.
Applications can use the :cpp:func:`esp_wifi_set_bandwidth()` API to set the bandwidth mode of the current interface.
Example:
.. code-block:: c
// Set STA interface protocol to 802.11bgn
uint8_t protocol = WIFI_PROTOCOL_11B | WIFI_PROTOCOL_11G | WIFI_PROTOCOL_11N;
esp_wifi_set_protocol(WIFI_IF_STA, protocol);
// Set STA interface bandwidth to 40 MHz
esp_wifi_set_bandwidth(WIFI_IF_STA, WIFI_BW_HT40);
.. only:: esp32c6
{IDF_TARGET_NAME} currently supports 20 MHz and 40 MHz bandwidth modes, which are used in combination with protocol modes. Common combinations include:
- **HT20**: 802.11n with 20 MHz bandwidth
- **HT40**: 802.11n with 40 MHz bandwidth
- **HE20**: 802.11ax with 20 MHz bandwidth
.. note::
- The 40 MHz bandwidth mode is only supported in 802.11n mode.
Applications can use the :cpp:func:`esp_wifi_set_bandwidth()` API to set the bandwidth mode of the current interface.
Example:
.. code-block:: c
// Set protocol of station to 802.11bgn
uint8_t protocol = WIFI_PROTOCOL_11B | WIFI_PROTOCOL_11G | WIFI_PROTOCOL_11N;
esp_wifi_set_protocol(WIFI_IF_STA, protocol);
// Set bandwidth of station to 40 MHz
esp_wifi_set_bandwidth(WIFI_IF_STA, WIFI_BW_HT40);
.. only:: esp32c5
{IDF_TARGET_NAME} currently supports two bandwidth modes, 20 MHz and 40 MHz, which are used in combination with protocol modes. Common combinations include:
- **HT20**: 802.11n/11an, 20 MHz bandwidth
- **HT40**: 802.11n/11an, 40 MHz bandwidth
- **HE20**: 802.11ax, 20 MHz bandwidth
.. note::
- The 40 MHz bandwidth mode is only supported under 802.11n (2.4 GHz) or 802.11an (5 GHz) modes.
Applications can use the :cpp:func:`esp_wifi_set_bandwidths()` API to set independent bandwidths for 2.4 GHz and 5 GHz bands.
Example:
.. code-block:: c
// Set 2.4 GHz to use 802.11bgnax, and 5 GHz to use 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);
// Set bandwidth to 20 MHz for 2.4 GHz band and 40 MHz for 5 GHz band
wifi_bandwidths_t bw = {
.ghz_2g = WIFI_BW_HT20,
.ghz_5g = WIFI_BW_HT40
};
esp_wifi_set_bandwidths(WIFI_IF_STA, &bw);
.. note::
- When `.ghz_2g` is set to 0, only the 5 GHz bandwidth is updated, and the 2.4 GHz bandwidth remains unchanged.
- When `.ghz_5g` is set to 0, only the 2.4 GHz bandwidth is updated, and the 5 GHz bandwidth remains unchanged.
**Legacy Usage**
Use the legacy API :cpp:func:`esp_wifi_set_bandwidth()` to configure the bandwidth of the 2.4 GHz or 5 GHz band:
.. code-block:: c
// Set band mode to 5 GHz band
esp_wifi_set_band_mode(WIFI_BAND_MODE_5G_ONLY);
// Set protocol of the station interface to 802.11an
uint8_t protocol = WIFI_PROTOCOL_11A | WIFI_PROTOCOL_11N;
esp_wifi_set_protocol(WIFI_IF_STA, protocol);
// Set bandwidth of the station interface to 40 MHz
esp_wifi_set_bandwidth(WIFI_IF_STA, WIFI_BW_HT40);
.. note::
- The new API :cpp:func:`esp_wifi_set_bandwidths()` can configure both 2.4 GHz and 5 GHz bandwidths simultaneously, and is recommended for use on {IDF_TARGET_NAME}.
- ``esp_wifi_set_bandwidth()`` is suitable for single-band scenarios, such as ``WIFI_BAND_MODE_2G_ONLY`` or ``WIFI_BAND_MODE_5G_ONLY`` modes. It only affects the currently connected band. For example, if the interface is on the 5 GHz band, any 2.4 GHz bandwidth settings will be ignored.
- If the configured bandwidth is not supported on the current band, the function will return an error.
.. only:: esp32c2
{IDF_TARGET_NAME} currently supports only 20 MHz bandwidth mode.
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3 or esp32c5 or esp32c6
Long Range (LR)
+++++++++++++++++++++++++
@@ -1489,9 +1719,12 @@ Currently, the ESP-IDF supports the following protocol modes:
LR Compatibility
*************************
Since LR is Espressif-unique Wi-Fi mode, only ESP32 chip series devices (except ESP32-C2) can transmit and receive the LR data. In other words, the ESP32 chip series devices (except ESP32-C2) should NOT transmit the data in LR data rate if the connected device does not support LR. The application can achieve this by configuring a suitable Wi-Fi mode. If the negotiated mode supports LR, the ESP32 chip series devices (except ESP32-C2) may transmit data in LR rate. Otherwise, ESP32 chip series devices (except ESP32-C2) will transmit all data in the traditional Wi-Fi data rate.
Since LR is an Espressif-unique Wi-Fi mode operating on the 2.4 GHz band, only ESP32-series chips (excluding the ESP32-C2) support LR data transmission and reception. To ensure compatibility, the ESP32 devices should NOT use LR data rates when connected to non-LR-capable devices. This can be enforced by configuring the appropriate Wi-Fi mode:
The following table depicts the Wi-Fi mode negotiation:
- If the negotiated mode supports LR, ESP32 devices may transmit data at LR rates.
- Otherwise, they must default to traditional Wi-Fi data rates.
The following table depicts the Wi-Fi mode negotiation on 2.4 GHz band:
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
@@ -1513,7 +1746,7 @@ Currently, the ESP-IDF supports the following protocol modes:
| LR | - | - | - | LR | LR | LR | LR |
+-------+-----+----+---+-------+------+-----+----+
.. only:: esp32c6
.. only:: esp32c5 or esp32c6
+---------+-------+-----+----+---+---------+-------+------+-----+----+
| AP\STA | BGNAX | BGN | BG | B | BGNAXLR | BGNLR | BGLR | BLR | LR |
@@ -1576,107 +1809,243 @@ Currently, the ESP-IDF supports the following protocol modes:
- Long distance Wi-Fi connection and data transmission is required.
- Data throughput requirements are very small, such as remote device control.
.. only:: esp32c5
Dynamic Frequency Selection (DFS)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
In the 5 GHz Wi-Fi band, certain channels (e.g., channels 52–144) share spectrum with critical systems such as weather radars. To avoid interference with these systems, Wi-Fi devices must perform specific detection and channel switching mechanisms before operating on these channels—this is known as **Dynamic Frequency Selection (DFS)**.
Enabling DFS allows devices to access more 5 GHz channels, thereby increasing network capacity and reducing interference. This is especially beneficial in high-density deployments or applications that require high bandwidth. The range of DFS channels may vary by country or region; see :component_file:`esp_wifi/regulatory/esp_wifi_regulatory.txt` for details.
{IDF_TARGET_NAME} supports DFS channels in the 5 GHz band, but only supports **passive radar detection**.
.. list-table::
:header-rows: 1
:widths: 20 60
* - Type
- Description
* - Passive Radar Detection Supported
- During scanning, the device can listen to DFS channels, detect access points (APs) operating on DFS channels, and connect to them. If the AP detects radar signals and switches to another channel using Channel Switch Announcement (CSA), {IDF_TARGET_NAME} will follow the AP to the new channel.
* - Active Radar Detection Not Supported
- {IDF_TARGET_NAME} **does not support** active radar detection and therefore cannot operate as a DFS AP in SoftAP mode.
.. note::
- In STA mode, {IDF_TARGET_NAME} can connect to APs operating on DFS channels, provided those channels are detected during scanning.
- In SoftAP mode, {IDF_TARGET_NAME} is not allowed to operate on DFS channels to comply with regulatory requirements.
- In STA+SoftAP coexistence mode:
1. If the STA connects to an AP on a DFS channel, the SoftAP is allowed to switch to the same DFS channel using CSA (Channel Switch Announcement).
2. When the STA disconnects, the SoftAP will switch back to a non-DFS channel via CSA to remain compliant with regulations.
Wi-Fi Country Code
+++++++++++++++++++++++++
Call :cpp:func:`esp_wifi_set_country()` to set the country info. The table below describes the fields in detail. Please consult local 2.4 GHz RF operating regulations before configuring these fields.
.. only:: esp32 or esp32c2 or esp32s2 or esp32c3 or esp32s3 or esp32c6
.. list-table::
:header-rows: 1
:widths: 15 55
Call :cpp:func:`esp_wifi_set_country()` to set the country info. The table below describes the fields in detail. Please consult local 2.4 GHz RF operating regulations before configuring these fields.
* - Field
- Description
* - cc[3]
- Country code string. This attribute identifies the country or noncountry entity in which the station/AP is operating. If it is a country, the first two octets of this string is the two-character country info as described in the document ISO/IEC3166-1. The third octet is one of the following:
.. list-table::
:header-rows: 1
:widths: 15 55
- an ASCII space character, which means the regulations under which the station/AP is operating encompass all environments for the current frequency band in the country.
- an ASCII ‘O’ character, which means the regulations under which the station/AP is operating are for an outdoor environment only.
- an ASCII ‘I’ character, which means the regulations under which the station/AP is operating are for an indoor environment only.
- an ASCII ‘X’ character, which means the station/AP is operating under a noncountry entity. The first two octets of the noncountry entity is two ASCII ‘XX’ characters.
- the binary representation of the Operating Class table number currently in use. Refer to Annex E of IEEE Std 802.11-2020.
* - Field
- Description
* - cc[3]
- Country code string. This attribute identifies the country or noncountry entity in which the station/AP is operating. If it is a country, the first two octets of this string is the two-character country info as described in the document ISO/IEC3166-1. The third octet is one of the following:
* - schan
- Start channel. It is the minimum channel number of the regulations under which the station/AP can operate.
* - nchan
- Total number of channels as per the regulations. For example, if the schan=1, nchan=13, then the station/AP can send data from channel 1 to 13.
* - policy
- Country policy. This field controls which country info will be used if the configured country info is in conflict with the connected AP’s. For more details on related policies, see the following section.
- an ASCII space character, which means the regulations under which the station/AP is operating encompass all environments for the current frequency band in the country.
- an ASCII ‘O’ character, which means the regulations under which the station/AP is operating are for an outdoor environment only.
- an ASCII ‘I’ character, which means the regulations under which the station/AP is operating are for an indoor environment only.
- an ASCII ‘X’ character, which means the station/AP is operating under a noncountry entity. The first two octets of the noncountry entity is two ASCII ‘XX’ characters.
- the binary representation of the Operating Class table number currently in use. Refer to Annex E of IEEE Std 802.11-2020.
* - schan
- Start channel. It is the minimum channel number of the regulations under which the station/AP can operate.
* - nchan
- Total number of channels as per the regulations. For example, if the schan=1, nchan=13, then the station/AP can send data from channel 1 to 13.
* - policy
- Country policy. This field controls which country info will be used if the configured country info is in conflict with the connected AP’s. For more details on related policies, see the following section.
The default country info is::
The default country info is::
wifi_country_t config = {
.cc = "01",
.schan = 1,
.nchan = 11,
.policy = WIFI_COUNTRY_POLICY_AUTO,
};
wifi_country_t config = {
.cc = "01",
.schan = 1,
.nchan = 11,
.policy = WIFI_COUNTRY_POLICY_AUTO,
};
If the Wi-Fi Mode is station/AP coexist mode, they share the same configured country info. Sometimes, the country info of AP, to which the station is connected, is different from the country info of configured. For example, the configured station has country info::
If the Wi-Fi Mode is station/AP coexist mode, they share the same configured country info. Sometimes, the country info of AP, to which the station is connected, is different from the country info of configured. For example, the configured station has country info::
wifi_country_t config = {
.cc = "JP",
.schan = 1,
.nchan = 14,
.policy = WIFI_COUNTRY_POLICY_AUTO,
};
wifi_country_t config = {
.cc = "JP",
.schan = 1,
.nchan = 14,
.policy = WIFI_COUNTRY_POLICY_AUTO,
};
but the connected AP has country info::
but the connected AP has country info::
wifi_country_t config = {
.cc = "CN",
.schan = 1,
.nchan = 13,
};
wifi_country_t config = {
.cc = "CN",
.schan = 1,
.nchan = 13,
;
then country info of connected AP's is used.
then country info of connected AP's is used.
The following table depicts which country info is used in different Wi-Fi modes and different country policies, and it also describes the impact on active scan.
The following table depicts which country info is used in different Wi-Fi modes and different country policies, and it also describes the impact on active scan.
.. list-table::
:header-rows: 1
:widths: 15 15 35
.. list-table::
:header-rows: 1
:widths: 15 15 35
* - Wi-Fi Mode
- Policy
- Description
* - Station
- WIFI_COUNTRY_POLICY_AUTO
- If the connected AP has country IE in its beacon, the country info equals to the country info in beacon. Otherwise, use the default country info.
* - Wi-Fi Mode
- Policy
- Description
* - Station
- WIFI_COUNTRY_POLICY_AUTO
- If the connected AP has country IE in its beacon, the country info equals to the country info in beacon. Otherwise, use the default country info.
For scan:
For scan:
Use active scan from 1 to 11 and use passive scan from 12 to 14.
Use active scan from 1 to 11 and use passive scan from 12 to 14.
Always keep in mind that if an AP with hidden SSID and station is set to a passive scan channel, the passive scan will not find it. In other words, if the application hopes to find the AP with hidden SSID in every channel, the policy of country info should be configured to WIFI_COUNTRY_POLICY_MANUAL.
Always keep in mind that if an AP with hidden SSID and station is set to a passive scan channel, the passive scan will not find it. In other words, if the application hopes to find the AP with hidden SSID in every channel, the policy of country info should be configured to WIFI_COUNTRY_POLICY_MANUAL.
* - Station
- WIFI_COUNTRY_POLICY_MANUAL
- Always use the configured country info.
* - Station
- WIFI_COUNTRY_POLICY_MANUAL
- Always use the configured country info.
For scan:
For scan:
Use active scan from schan to schan+nchan-1.
Use active scan from schan to schan+nchan-1.
* - AP
- WIFI_COUNTRY_POLICY_AUTO
- Always use the configured country info.
* - AP
- WIFI_COUNTRY_POLICY_AUTO
- Always use the configured country info.
* - AP
- WIFI_COUNTRY_POLICY_MANUAL
- Always use the configured country info.
* - AP
- WIFI_COUNTRY_POLICY_MANUAL
- Always use the configured country info.
* - Station/AP-coexistence
- WIFI_COUNTRY_POLICY_AUTO
- Station: Same as station mode with policy WIFI_COUNTRY_POLICY_AUTO.
AP: If the station does not connect to any external AP, the AP uses the configured country info. If the station connects to an external AP, the AP has the same country info as the station.
* - Station/AP-coexistence
- WIFI_COUNTRY_POLICY_AUTO
- Station: Same as station mode with policy WIFI_COUNTRY_POLICY_AUTO.
AP: If the station does not connect to any external AP, the AP uses the configured country info. If the station connects to an external AP, the AP has the same country info as the station.
* - Station/AP-coexistence
- WIFI_COUNTRY_POLICY_MANUAL
- Station: Same as station mode with policy WIFI_COUNTRY_POLICY_MANUAL.
AP: Same as AP mode with policy WIFI_COUNTRY_POLICY_MANUAL.
* - Station/AP-coexistence
- WIFI_COUNTRY_POLICY_MANUAL
- Station: Same as station mode with policy WIFI_COUNTRY_POLICY_MANUAL.
AP: Same as AP mode with policy WIFI_COUNTRY_POLICY_MANUAL.
.. only:: esp32c5
The :cpp:func:`esp_wifi_set_country()` function is used to set the country/region information. The table below details the meaning of each field. Before configuring these fields, please refer to local 2.4 GHz and 5 GHz RF regulations.
.. list-table::
:header-rows: 1
:widths: 15 55
* - Field
- Description
* - cc[3]
- Country/region code string identifying the country or region of the station/AP, or a non-country entity. If it is a country/region, the first two bytes comply with the ISO/IEC 3166-1 two-letter country code standard. The third byte has the following meanings:
- Space character (ASCII): The country/region allows usage of the respective frequency band in all environments.
- Character `'O'`: Usage allowed only in outdoor environments.
- Character `'I'`: Usage allowed only in indoor environments.
- Character `'X'`: Non-country entity, in which case the first two characters should be `'XX'`.
- Binary operational class number, referring to IEEE Std 802.11-2020 Appendix E.
* - schan
- Start channel number, indicating the minimum channel allowed in the 2.4 GHz band for the configured country/region.
* - nchan
- Number of channels. Defines the total number of allowed channels in the 2.4 GHz band. For example, if `schan = 1` and `nchan = 13`, then channels 1 through 13 are allowed.
* - policy
- Country/region policy. When the configured country/region conflicts with that of the connected AP, this field determines which information to use. Details are explained below.
* - wifi_5g_channel_mask
- Bitmask indicating allowed 5 GHz channels for the station/AP. The mapping between channel numbers and bits can be found in :cpp:enum:`wifi_5g_channel_bit_t`.
A default configuration example::
wifi_country_t config = {
.cc = "01",
.schan = 1,
.nchan = 11,
.wifi_5g_channel_mask = 0xfe,
.policy = WIFI_COUNTRY_POLICY_AUTO,
};
When Wi-Fi is in station/AP coexistence mode, both use the same country/region information. Sometimes, the connected AP's country/region information may differ from the station's preset. For example:
Station configuration::
wifi_country_t config = {
.cc = "JP",
.schan = 1,
.nchan = 14,
.wifi_5g_channel_mask = 0xfe,
.policy = WIFI_COUNTRY_POLICY_AUTO,
};
Connected AP configuration::
wifi_country_t config = {
.cc = "CN",
.schan = 1,
.nchan = 13,
};
In this case, the connected AP's country/region information will be used.
The following table explains which country/region information is used under different Wi-Fi modes and policies, as well as differences in scanning behavior:
.. list-table::
:header-rows: 1
:widths: 15 15 35
* - Wi-Fi Mode
- Policy
- Description
* - Station mode
- WIFI_COUNTRY_POLICY_AUTO
- If the connected AP's beacon contains country/region information IE, that information is used; otherwise, the default configuration is used.
Scanning behavior:
- 2.4 GHz band: active scanning on channels 1–11, passive scanning on channels 12–14;
- 5 GHz band: active scanning on non-DFS channels, passive scanning on DFS channels.
Note: If an AP with a hidden SSID is on a passive scan channel, scanning may not discover that AP. To discover hidden SSIDs on all channels, use `WIFI_COUNTRY_POLICY_MANUAL`.
* - Station mode
- WIFI_COUNTRY_POLICY_MANUAL
- Always use the configured country/region information.
Scanning behavior:
- 2.4 GHz band: scan channels from `schan` to `schan + nchan - 1`;
- 5 GHz band: scan channels supported as indicated by `wifi_5g_channel_mask`.
* - AP mode
- WIFI_COUNTRY_POLICY_AUTO
- Always use the configured country/region information.
* - AP mode
- WIFI_COUNTRY_POLICY_MANUAL
- Always use the configured country/region information.
* - Station/AP coexistence mode
- WIFI_COUNTRY_POLICY_AUTO
- Same behavior as station mode with `WIFI_COUNTRY_POLICY_AUTO`.
If the station is not connected to any AP, the AP uses the configured country/region information;
if the station is connected to an external AP, the AP uses the country/region information obtained by the station.
* - Station/AP coexistence mode
- WIFI_COUNTRY_POLICY_MANUAL
- Same behavior as station mode with `WIFI_COUNTRY_POLICY_MANUAL`. The AP always uses the configured country/region information.
Home Channel
*************************
@@ -2343,54 +2712,133 @@ Please refer to the :doc:`PHY <../api-guides/phy>`
Wi-Fi Channel State Information
------------------------------------
Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In {IDF_TARGET_NAME}, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF), and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI are shown in the following table.
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
+-------------+--------------------+-----------------------------------------+--------------------------------------------------------+----------------------------------------------------------+
| channel | secondary channel | none | below | above |
+-------------+--------------------+-------------+---------------------------+----------+---------------------------------------------+----------+-----------------------------------------------+
| packet | signal mode | non HT | HT | non HT | HT | non HT | HT |
+ +--------------------+-------------+---------------------------+----------+-----------------+---------------------------+----------+-------------------+---------------------------+
| information | channel bandwidth | 20 MHz | 20 MHz | 20 MHz | 20 MHz | 40 MHz | 20 MHz | 20 MHz | 40 MHz |
+ +--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
| | STBC | non STBC | non STBC | STBC | non STBC | non STBC | STBC | non STBC | STBC | non STBC | non STBC | STBC | non STBC | STBC |
+-------------+--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
| sub-carrier | LLTF | 0~31, -32~-1| 0~31, -32~-1| 0~31, -32~-1| 0~63 | 0~63 | 0~63 | 0~63 | 0~63 | -64~-1 | -64~-1 | -64~-1 | -64~-1 | -64~-1 |
+ +--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
| index | HT-LTF | - | 0~31, -32~-1| 0~31, -32~-1| - | 0~63 | 0~62 | 0~63, -64~-1| 0~60, -60~-1| - | -64~-1 | -62~-1 | 0~63, -64~-1| 0~60, -60~-1|
+ +--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
| | STBC-HT-LTF | - | - | 0~31, -32~-1| - | - | 0~62 | - | 0~60, -60~-1| - | - | -62~-1 | - | 0~60, -60~-1|
+-------------+--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
| total bytes | 128 | 256 | 384 | 128 | 256 | 380 | 384 | 612 | 128 | 256 | 376 | 384 | 612 |
+----------------------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In {IDF_TARGET_NAME}, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF), and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI are shown in the following table.
All of the information in the table can be found in the structure wifi_csi_info_t.
+-------------+--------------------+-----------------------------------------+--------------------------------------------------------+----------------------------------------------------------+
| channel | secondary channel | none | below | above |
+-------------+--------------------+-------------+---------------------------+----------+---------------------------------------------+----------+-----------------------------------------------+
| packet | signal mode | non HT | HT | non HT | HT | non HT | HT |
+ +--------------------+-------------+---------------------------+----------+-----------------+---------------------------+----------+-------------------+---------------------------+
| information | channel bandwidth | 20 MHz | 20 MHz | 20 MHz | 20 MHz | 40 MHz | 20 MHz | 20 MHz | 40 MHz |
+ +--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
| | STBC | non STBC | non STBC | STBC | non STBC | non STBC | STBC | non STBC | STBC | non STBC | non STBC | STBC | non STBC | STBC |
+-------------+--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
| sub-carrier | LLTF | 0~31, -32~-1| 0~31, -32~-1| 0~31, -32~-1| 0~63 | 0~63 | 0~63 | 0~63 | 0~63 | -64~-1 | -64~-1 | -64~-1 | -64~-1 | -64~-1 |
+ +--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
| index | HT-LTF | - | 0~31, -32~-1| 0~31, -32~-1| - | 0~63 | 0~62 | 0~63, -64~-1| 0~60, -60~-1| - | -64~-1 | -62~-1 | 0~63, -64~-1| 0~60, -60~-1|
+ +--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
| | STBC-HT-LTF | - | - | 0~31, -32~-1| - | - | 0~62 | - | 0~60, -60~-1| - | - | -62~-1 | - | 0~60, -60~-1|
+-------------+--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
| total bytes | 128 | 256 | 384 | 128 | 256 | 380 | 384 | 612 | 128 | 256 | 376 | 384 | 612 |
+----------------------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+
- Secondary channel refers to secondary_channel field of rx_ctrl field.
- Signal mode of packet refers to sig_mode field of rx_ctrl field.
- Channel bandwidth refers to cwb field of rx_ctrl field.
- STBC refers to stbc field of rx_ctrl field.
- Total bytes refers to len field.
- The CSI data corresponding to each Long Training Field (LTF) type is stored in a buffer starting from the buf field. Each item is stored as two bytes: imaginary part followed by real part. The order of each item is the same as the sub-carrier in the table. The order of LTF is: LLTF, HT-LTF, STBC-HT-LTF. However, all 3 LTFs may not be present, depending on the channel and packet information (see above).
- If first_word_invalid field of :cpp:type:`wifi_csi_info_t` is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in {IDF_TARGET_NAME}.
- More information like RSSI, noise floor of RF, receiving time and antenna is in the rx_ctrl field.
All of the information in the table can be found in the structure wifi_csi_info_t.
When imaginary part and real part data of sub-carrier are used, please refer to the table below.
- Secondary channel refers to secondary_channel field of rx_ctrl field.
- Signal mode of packet refers to sig_mode field of rx_ctrl field.
- Channel bandwidth refers to cwb field of rx_ctrl field.
- STBC refers to stbc field of rx_ctrl field.
- Total bytes refers to len field.
- The CSI data corresponding to each Long Training Field (LTF) type is stored in a buffer starting from the buf field. Each item is stored as two bytes: imaginary part followed by real part. The order of each item is the same as the sub-carrier in the table. The order of LTF is: LLTF, HT-LTF, STBC-HT-LTF. However, all 3 LTFs may not be present, depending on the channel and packet information (see above).
- If first_word_invalid field of :cpp:type:`wifi_csi_info_t` is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in {IDF_TARGET_NAME}.
- More information like RSSI, noise floor of RF, receiving time and antenna is in the rx_ctrl field.
+-----------------+-------------------+------------------------------+--------------------------+
| PHY standard | Sub-carrier range | Pilot sub-carrier | Sub-carrier (total/data) |
+=================+===================+==============================+==========================+
| 802.11a/g | -26 to +26 | -21, -7, +7, +21 | 52 total, 48 usable |
+-----------------+-------------------+------------------------------+--------------------------+
| 802.11n, 20 MHz | -28 to +28 | -21, -7, +7, +21 | 56 total, 52 usable |
+-----------------+-------------------+------------------------------+--------------------------+
| 802.11n, 40 MHz | -57 to +57 | -53, -25, -11, +11, +25, +53 | 114 total, 108 usable |
+-----------------+-------------------+------------------------------+--------------------------+
When imaginary part and real part data of sub-carrier are used, please refer to the table below.
.. note::
+-----------------+-------------------+------------------------------+--------------------------+
| PHY standard | Sub-carrier range | Pilot sub-carrier | Sub-carrier (total/data) |
+=================+===================+==============================+==========================+
| 802.11a/g | -26 to +26 | -21, -7, +7, +21 | 52 total, 48 usable |
+-----------------+-------------------+------------------------------+--------------------------+
| 802.11n, 20 MHz | -28 to +28 | -21, -7, +7, +21 | 56 total, 52 usable |
+-----------------+-------------------+------------------------------+--------------------------+
| 802.11n, 40 MHz | -57 to +57 | -53, -25, -11, +11, +25, +53 | 114 total, 108 usable |
+-----------------+-------------------+------------------------------+--------------------------+
- For STBC packet, CSI is provided for every space-time stream without CSD (cyclic shift delay). As each cyclic shift on the additional chains shall be -200 ns, only the CSD angle of first space-time stream is recorded in sub-carrier 0 of HT-LTF and STBC-HT-LTF for there is no channel frequency response in sub-carrier 0. CSD[10:0] is 11 bits, ranging from -pi to pi.
.. note::
- If LLTF, HT-LTF, or STBC-HT-LTF is not enabled by calling API :cpp:func:`esp_wifi_set_csi_config()`, the total bytes of CSI data will be fewer than that in the table. For example, if LLTF and HT-LTF is not enabled and STBC-HT-LTF is enabled, when a packet is received with the condition above/HT/40MHz/STBC, the total bytes of CSI data is 244 ((61 + 60) * 2 + 2 = 244. The result is aligned to four bytes, and the last two bytes are invalid).
- For STBC packet, CSI is provided for every space-time stream without CSD (cyclic shift delay). As each cyclic shift on the additional chains shall be -200 ns, only the CSD angle of first space-time stream is recorded in sub-carrier 0 of HT-LTF and STBC-HT-LTF for there is no channel frequency response in sub-carrier 0. CSD[10:0] is 11 bits, ranging from -pi to pi.
- If LLTF, HT-LTF, or STBC-HT-LTF is not enabled by calling API :cpp:func:`esp_wifi_set_csi_config()`, the total bytes of CSI data will be fewer than that in the table. For example, if LLTF and HT-LTF is not enabled and STBC-HT-LTF is enabled, when a packet is received with the condition above/HT/40MHz/STBC, the total bytes of CSI data is 244 ((61 + 60) * 2 + 2 = 244. The result is aligned to four bytes, and the last two bytes are invalid).
.. only:: esp32c5
Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In {IDF_TARGET_NAME}, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. Except for the IEEE 802.11g mode, all other modes have two LTF sequences (LLTF + HT/VHT/HE-LTF). {IDF_TARGET_NAME} can determine whether to include LLTF or HT/VHT/HE-LTF through ``acquire_csi_force_lltf`` field of :cpp:struct:`wifi_csi_acquire_config_t`. For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI are shown in the following table.
+-------------+-------------------+--------------------------------------------+-----------------------------------+--------------------------------------------------------------------------+--------------------------------------------------------------------------+
| channel | secondary channel | none | below | above |
+-------------+-------------------+--------------+-----------------------------+-----------------------------------+--------------+-----------------------------------------------------------+--------------+-----------------------------------------------------------+
| packet | signal mode | non HT | HT | HE | non HT | HT | non HT | HT |
| +-------------------+--------------+-----------------------------+-----------------------------------+--------------+-----------------------------+-----------------------------+--------------+-----------------------------+-----------------------------+
| information | channel bandwidth | 20 MHz | 20 MHz | 20 MHz | 20 MHz | 20 MHz | 40 MHz | 20 MHz | 20 MHz | 40 MHz |
| +-------------------+--------------+--------------+--------------+---------------+-------------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+
| | STBC | non STBC | non STBC | STBC | non STBC | STBC | non STBC | non STBC | STBC | none STBC | STBC | non STBC | non STBC | STBC | non STBC | STBC |
+-------------+-------------------+--------------+--------------+--------------+---------------+-------------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+
| sub-carrier | LLTF | 0~26, -26~-1 | — | — | — | — | 0~52 | — | — | — | — | -53~-1 | — | — | — | — |
| +-------------------+--------------+--------------+--------------+---------------+-------------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+
| index | HT-LTF (HT-LTF1) | — | 0~28, -28~-1 | 0~28, -28~-1 | — | — | — | 0~56 | 0~56 | 0~58, -58~-1 | 0~58, -58~-1 | — | -57~-1 | -57~-1 | 0~58, -58~-1 | 0~58, -58~-1 |
| +-------------------+--------------+--------------+--------------+---------------+-------------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+
| | HT-LTF2 | — | — | 0~28, -28~-1 | — | — | — | — | 0~56 | — | 0~58, -58~-1 | — | — | -57~-1 | — | 0~58, -58~-1 |
| +-------------------+--------------+--------------+--------------+---------------+-------------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+
| | HE-LTF (HE-LTF1) | — | — | — | 0~122, -122~1 | Determined by | — | — | — | — | — | — | — | — | — | — |
| +-------------------+--------------+--------------+--------------+---------------+ +--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+
| | HE-LTF2 | — | — | — | — | wifi_csi_config_t | — | — | — | — | — | — | — | — | — | — |
+-------------+-------------------+--------------+--------------+--------------+---------------+-------------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+
| total bytes | 106 | 114 | 228 | 490 | 490 | 106 | 114 | 228 | 234 | 468 | 106 | 114 | 228 | 234 | 468 |
+---------------------------------+--------------+--------------+--------------+---------------+-------------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+
.. note ::
- In HT/VHT/HE modes, there are two LTF sequences: LLTF + HT/VHT/HE-LTF. If the ``acquire_csi_force_lltf`` field of :cpp:struct:`wifi_csi_acquire_config_t` is set to false, the CSI data will only contain HT/VHT/HE-LTF (as shown in the table above); otherwise, the CSI data will only contain LLTF. The sub-carrier index and total bytes for LLTF in HT/VHT/HE modes are the same as those for LLTF in non-HT modes.
- In VHT mode, the sub-carrier index and total bytes are the same as those in HT mode.
All of the information in the table can be found in the structure :cpp:type:`wifi_csi_info_t`.
- Secondary channel refers to ``second`` field of ``rx_ctrl`` field.
- signal mode of packet refers to ``cur_bb_format`` field of ``rx_ctrl`` field.
- total bytes refers to ``len`` field
- The CSI data corresponding to each Long Training Field (LTF) type is stored in a buffer starting from the buf field. Each item is stored as two bytes: imaginary part followed by real part. The order of each item is the same as the sub-carrier in the table.
- If ``first_word_invalid`` of :cpp:type:`wifi_csi_info_t` is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in {IDF_TARGET_NAME}.
- If ``rx_channel_estimate_info_vld`` of ``rx_ctrl`` field is 1, indicates that the CSI data is valid; otherwise, the CSI data is invalid.
- More information like RSSI, noise floor of RF, receiving time and antenna is in the ``rx_ctrl`` field.
For STBC packets, the subcarrier indices of HE-LTF1 and HE-LTF2 are determined by ``acquire_csi_he_stbc_mode`` field of :cpp:type:`wifi_csi_config_t`. Please refer to the table below for details.
+---------------------+----------------------+----------------------+
| acquire_csi_he_stbc | HE-LTF1 | HE-LTF2 |
+---------------------+----------------------+----------------------+
| 0 | -122~-1, 0~122 | — |
+---------------------+----------------------+----------------------+
| 1 | — | -122~-1, 0~122 |
+---------------------+----------------------+----------------------+
| 2 | Sample evenly among the HE-LTF1 and HE-LTF2 |
+---------------------+----------------------+----------------------+
When imaginary part and real part data of sub-carrier are used, please refer to the table below.
+-----------------------+-------------------+------------------------------------------+------------------------------+
| PHY standard | Sub-carrier range | Invalid sub-carrier | Sub-carrier (total/data) |
+=======================+===================+==========================================+==============================+
| 802.11a/g | -26 to +26 | 0 | 53 total, 52 usable |
+-----------------------+-------------------+------------------------------------------+------------------------------+
| 802.11n, 20 MHz | -28 to +28 | 0 | 57 total, 56 usable |
+-----------------------+-------------------+------------------------------------------+------------------------------+
| 802.11n, 40 MHz | -58 to +58 | -1, 0, 1 | 117 total, 114 usable |
+-----------------------+-------------------+------------------------------------------+------------------------------+
| 802.11ac, 20 MHz | -28 to +28 | 0 | 57 total, 56 usable |
+-----------------------+-------------------+------------------------------------------+------------------------------+
| 802.11ax, 20 MHz (SU) | -122 to + 122 | -1, 0, 1 | 245 total, 242 usable |
+-----------------------+-------------------+------------------------------------------+------------------------------+
.. note::
- When the PHY is 802.11ax, please refer to the protocol for sub-carrier range and invalid sub-carrier for MU packets.
.. note::
- For STBC packet, CSI is provided for every space-time stream without CSD (cyclic shift delay). As each cyclic shift on the additional chains shall be -200 ns, only the CSD angle of first space-time stream is recorded in sub-carrier 0 of HT-LTF1 (HE-LTF1) and HT-LTF2 (HE-LTF2) for there is no channel frequency response in sub-carrier 0. CSD[10:0] is 11 bits, ranging from -pi to pi.
Wi-Fi Channel State Information Configure
-------------------------------------------
@@ -2407,7 +2855,7 @@ Please refer to the :doc:`PHY <../api-guides/phy>`
Wi-Fi HT20/40
-------------------------
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3 or esp32c6
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3 or esp32c5 or esp32c6
{IDF_TARGET_NAME} supports Wi-Fi bandwidth HT20 or HT40 and does not support HT20/40 coexist. :cpp:func:`esp_wifi_set_bandwidth()` can be used to change the default bandwidth of station or AP. The default bandwidth for {IDF_TARGET_NAME} station and AP is HT40.
@@ -2419,6 +2867,12 @@ Wi-Fi HT20/40
Theoretically, the HT40 can gain better throughput because the maximum raw physical (PHY) data rate for HT40 is 150 Mbps while it is 72 Mbps for HT20. However, if the device is used in some special environment, e.g., there are too many other Wi-Fi devices around the {IDF_TARGET_NAME} device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, it is recommended that the bandwidth is always configured to HT20.
.. only:: esp32c5
..note ..
When operating in the 2.4 GHz + 5 GHz band mode (``WIFI_BAND_MODE_AUTO``), can use the function :cpp:func:`esp_wifi_set_bandwidths()` to configure the bandwidth for the 2.4 GHz and 5 GHz bands separately.
.. only:: esp32c2
{IDF_TARGET_NAME} supports Wi-Fi bandwidth HT20 and does not support Wi-Fi bandwidth HT40 or HT20/40 coexist.
@@ -2475,7 +2929,7 @@ Wi-Fi Fragment
supports Wi-Fi receiving fragment, but does not support Wi-Fi transmitting fragment.
.. only:: esp32c3 or esp32s3 or esp32c6
.. only:: esp32c3 or esp32s3 or esp32c5 or esp32c6
{IDF_TARGET_NAME} supports Wi-Fi receiving and transmitting fragment.

14
docs/en/api-reference/network/esp_now.rst
View File

@@ -92,7 +92,15 @@ Call :cpp:func:`esp_now_add_peer()` to add the device to the paired device list
You can send ESP-NOW data via both the Station and the SoftAP interface. Make sure that the interface is enabled before sending ESP-NOW data.
The range of the channel of paired devices is from 0 to 14. If the channel is set to 0, data will be sent on the current channel. Otherwise, the channel must be set as the channel that the local device is on.
.. only:: esp32 or esp32c2 or esp32s2 or esp32s3 or esp32c3 or esp32c6
The range of the channel of paired devices is from 0 to 14. If the channel is set to 0, data will be sent on the current channel. Otherwise, the channel must be set as the channel that the local device is on.
.. only:: esp32c5
The channel range for paired devices in the 2.4 GHz band is from 1 to 14. The channel range for paired devices in the 5 GHz band includes the following channels: [36, 40, 44, 48, 52, 56, 60, 64, 100, 112, 116, 120, 124, 128, 132, 136, 140, 144, 149, 153, 157, 161, 165, 169, 173, 177].
If the channel is set to 0, data will be transmitted on the current channel. Otherwise, the channel must correspond to the local device's current channel.
For the receiving device, calling :cpp:func:`esp_now_add_peer()` is not required. If no paired device is added, it can only receive broadcast packets and unencrypted unicast packets. To receive encrypted unicast packets, a paired device must be added, and the same LMK must be set.
@@ -100,7 +108,7 @@ For the receiving device, calling :cpp:func:`esp_now_add_peer()` is not required
The maximum number of paired devices is 20, and the paired encryption devices are no more than 4, the default is 2. If you want to change the number of paired encryption devices, set :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` in the Wi-Fi component configuration menu.
.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c6
.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c6 or esp32c5
The maximum number of paired devices is 20, and the paired encryption devices are no more than 17, the default is 7. If you want to change the number of paired encryption devices, set :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` in the Wi-Fi component configuration menu.
@@ -124,7 +132,7 @@ Config ESP-NOW Rate
Call :cpp:func:`esp_wifi_config_espnow_rate()` to config ESP-NOW rate of specified interface. Make sure that the interface is enabled before config rate. This API should be called after :cpp:func:`esp_wifi_start()`.
.. only:: esp32c6
.. only:: esp32c5 or esp32c6
Call :cpp:func:`esp_now_set_peer_rate_config()` to configure ESP-NOW rate of each peer. Make sure that the peer is added before configuring the rate. This API should be called after :cpp:func:`esp_wifi_start()` and :cpp:func:`esp_now_add_peer()`.

710
docs/zh_CN/api-guides/wifi.rst
View File

@@ -27,9 +27,18 @@ Wi-Fi 驱动程序
- 支持多个天线
- 支持获取信道状态信息
.. only:: SOC_WIFI_NAN_SUPPORT
.. only:: esp32c2
- Wi-Fi Aware (NAN)
- 支持 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
- 支持快速扫描和全信道扫描
- 支持多个天线
.. only:: esp32c6
@@ -45,24 +54,32 @@ Wi-Fi 驱动程序
- 支持快速扫描和全信道扫描
- 支持多个天线
- 支持获取信道状态信息
- 支持 TWT
- 支持 Individual TWT 和 Broadcast TWT
- 支持下行 MU-MIMO
- 支持 OFDMA
- 支持 BSS Color
.. only:: esp32c2
.. only:: esp32c5
- 支持 3 个虚拟接口，即 STA、AP 和 Sniffer。
- 支持 4 个虚拟接口，即 STA、AP、Sniffer 和 reserved。
- 支持仅 station 模式、仅 AP 模式、station/AP 共存模式
- 支持使用 IEEE 802.11b、IEEE 802.11g、IEEE 802.11n 和 API 配置协议模式
- 支持 WPA/WPA2/WPA3/WPA2-企业版/WPA3-企业版/WPS 和 DPP
- 支持 AMPDU、QoS 以及其它主要功能
- 支持使用 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
.. only:: SOC_WIFI_NAN_SUPPORT
- Wi-Fi Aware (NAN)
如何编写 Wi-Fi 应用程序
----------------------------------
@@ -1305,6 +1322,65 @@ Wi-Fi 模式
* - ``WIFI_MODE_APSTA``
- station/AP 共存模式：在此模式下，函数 :cpp:func:`esp_wifi_start()` 将同时初始化 station 和 AP。该步骤在 station 模式和 AP 模式下完成。请注意 ESP station 所连外部 AP 的信道优先于 ESP AP 信道。
.. only:: esp32c5
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等）。
.. only:: esp32c5
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 网络。
station 基本配置
+++++++++++++++++++++++++++++++++++++
@@ -1350,7 +1426,7 @@ AP 基本配置
API :cpp:func:`esp_wifi_set_config()` 可用于配置 AP。配置的参数信息会保存到 NVS 中。下表详细介绍了各个字段。
.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c6
.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c5 or esp32c6
.. list-table::
:header-rows: 1
@@ -1365,7 +1441,7 @@ API :cpp:func:`esp_wifi_set_config()` 可用于配置 AP。配置的参数信息
* - ssid_len
- SSID 的长度。如果 ssid_len 为 0，则检查 SSID 直至出现终止字符。如果 ssid_len 大于 32，请更改为 32，或者根据 ssid_len 设置 SSID 长度。
* - channel
- AP 的信道。如果信道超出范围，Wi-Fi 驱动程序将默认为信道 1。所以，请确保信道在要求的范围内。有关详细信息，请参阅 `Wi-Fi 国家/地区代码`_。
- AP 的信道。如果信道超出范围，Wi-Fi 驱动程序将返回 error。所以，请确保信道在要求的范围内。有关详细信息，请参阅 `Wi-Fi 国家/地区代码`_。
* - authmode
- ESP AP 的身份验证模式。目前，ESP AP 不支持 AUTH_WEP。如果 authmode 是一个无效值，AP 默认该值为 ``WIFI_AUTH_OPEN``。
* - ssid_hidden
@@ -1461,6 +1537,46 @@ Wi-Fi 协议模式
**此模式是乐鑫的专利模式，可以达到 1 公里视线范围。请确保 station 和 AP 同时连接至 ESP 设备。**
.. only:: esp32c5
- **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`。
.. only:: esp32c2
.. list-table::
@@ -1480,9 +1596,122 @@ Wi-Fi 协议模式
* - 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 模式。
Wi-Fi 带宽模式
++++++++++++++++++++++
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3 or esp32c6
{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_BW_HT40);
.. only:: esp32c6
{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_BW_HT40);
.. only:: esp32c5
{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_BW_HT20,
.ghz_5g = WIFI_BW_HT40
};
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_BW_HT40);
.. 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 的配置将被忽略。
- 若设置了当前频段不支持的带宽值，函数将返回错误。
.. only:: esp32c2
{IDF_TARGET_NAME} 目前仅支持 20 MHz 带宽模式。
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3 or esp32c5 or esp32c6
长距离 (LR)
+++++++++++++++++++++++++
@@ -1492,9 +1721,12 @@ Wi-Fi 协议模式
LR 兼容性
*************************
由于 LR 是乐鑫的独有 Wi-Fi 模式，只有 ESP32 芯片系列设备（ESP32-C2 除外）才能传输和接收 LR 数据。也就是说，如果连接的设备不支持 LR，ESP32 芯片系列设备（ESP32-C2 除外）则不会以 LR 数据速率传输数据。可通过配置适当的 Wi-Fi 模式使你的应用程序实现这一功能。如果协商的模式支持 LR，ESP32 芯片系列设备（ESP32-C2 除外）可能会以 LR 速率传输数据，否则，ESP32 芯片系列设备（ESP32-C2 除外）将以传统 Wi-Fi 数据速率传输所有数据。
由于 LR 是乐鑫的独有 2.4 GHz 频段 Wi-Fi 模式，只有 ESP32 芯片系列设备（ESP32-C2 除外）才能传输和接收 LR 数据。也就是说，如果连接的设备不支持 LR，ESP32 芯片系列设备（ESP32-C2 除外）则不会以 LR 数据速率传输数据。可通过配置适当的 Wi-Fi 模式使你的应用程序实现这一功能。
下表是 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
@@ -1516,7 +1748,7 @@ Wi-Fi 协议模式
| LR | - | - | - | LR | LR | LR | LR |
+-------+-----+----+---+-------+------+-----+----+
.. only:: esp32c6
.. only:: esp32c5 or esp32c6
+---------+-------+-----+----+---+---------+-------+------+-----+----+
| AP\STA | BGNAX | BGN | BG | B | BGNAXLR | BGNLR | BGLR | BLR | LR |
@@ -1579,107 +1811,243 @@ Wi-Fi 协议模式
- 需要长距离 Wi-Fi 连接和数据传输。
- 数据吞吐量要求非常小，例如远程设备控制等。
.. only:: esp32c5
动态频率选择（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 信道，确保符合监管要求。
Wi-Fi 国家/地区代码
+++++++++++++++++++++++++
调用 :cpp:func:`esp_wifi_set_country()`，设置国家/地区信息。下表详细介绍了各个字段，请在配置这些字段之前参考当地的 2.4 GHz RF 操作规定。
.. only:: esp32 or esp32c2 or esp32s2 or esp32c3 or esp32s3 or esp32c6
.. list-table::
:header-rows: 1
:widths: 15 55
调用 :cpp:func:`esp_wifi_set_country()`，设置国家/地区信息。下表详细介绍了各个字段，请在配置这些字段之前参考当地的 2.4 GHz RF 操作规定。
* - 字段
- 描述
* - cc[3]
- 国家/地区代码字符串，此属性标识 station/AP 位于的国家/地区或非国家/地区实体。如果是一个国家/地区，该字符串的前两个八位字节是 ISO/IEC3166-1 中规定的国家/地区两位字母代码。第三个八位字节应是下述之一：
.. list-table::
:header-rows: 1
:widths: 15 55
- ASCII 码空格字符，代表 station/AP 所处国家/地区的规定允许当前频段所需的所有环境。
- ASCII 码 ‘O’ 字符，代表 station/AP 所处国家/地区的规定仅允许室外环境。
- ASCII 码 ‘I’ 字符，代表 station/AP 所处国家/地区的规定仅允许室内环境。
- ASCII 码 ‘X’ 字符，代表 station/AP 位于非国家/地区实体。非国家实体的前两个八位字节是两个 ASCII 码 ‘XX’ 字符。
- 当前使用的操作类表编号的二进制形式。见 IEEE Std 802.11-2020 附件 E。
* - 字段
- 描述
* - cc[3]
- 国家/地区代码字符串，此属性标识 station/AP 位于的国家/地区或非国家/地区实体。如果是一个国家/地区，该字符串的前两个八位字节是 ISO/IEC3166-1 中规定的国家/地区两位字母代码。第三个八位字节应是下述之一：
* - schan
- 起始信道，station/AP 所处国家/地区规定的最小信道值。
* - nchan
- 规定的总信道数，比如，如果 schan=1，nchan=13，那么 station/AP 可以从信道 1 至 13 发送数据。
* - policy
- 国家/地区策略，当配置的国家/地区信息与所连 AP 的国家/地区信息冲突时，该字段决定使用哪一信息。更多策略相关信息，可参见下文。
- 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,
};
wifi_country_t config = {
.cc = "01",
.schan = 1,
.nchan = 11,
.policy = WIFI_COUNTRY_POLICY_AUTO,
};
如果 Wi-Fi 模式为 station/AP 共存模式，则它们配置的国家/地区信息相同。有时，station 所连 AP 的国家/地区信息与配置的不同。例如，配置的 station 国家/地区信息为::
如果 Wi-Fi 模式为 station/AP 共存模式，则它们配置的国家/地区信息相同。有时，station 所连 AP 的国家/地区信息与配置的不同。例如，配置的 station 国家/地区信息为::
wifi_country_t config = {
.cc = "JP",
.schan = 1,
.nchan = 14,
.policy = WIFI_COUNTRY_POLICY_AUTO,
};
wifi_country_t config = {
.cc = "JP",
.schan = 1,
.nchan = 14,
.policy = WIFI_COUNTRY_POLICY_AUTO,
};
但所连 AP 的国家/地区信息为::
但所连 AP 的国家/地区信息为::
wifi_country_t config = {
.cc = "CN",
.schan = 1,
.nchan = 13,
};
wifi_country_t config = {
.cc = "CN",
.schan = 1,
.nchan = 13,
};
此时，使用所连 AP 的国家/地区信息。
此时，使用所连 AP 的国家/地区信息。
下表描述了在不同 Wi-Fi 模式和不同国家/地区策略下使用的国家/地区信息，并描述了对主动扫描的影响。
下表描述了在不同 Wi-Fi 模式和不同国家/地区策略下使用的国家/地区信息，并描述了对主动扫描的影响。
.. list-table::
:header-rows: 1
:widths: 15 15 35
.. list-table::
:header-rows: 1
:widths: 15 15 35
* - Wi-Fi 模式
- 策略
- 描述
* - station 模式
- WIFI_COUNTRY_POLICY_AUTO
- 如果所连 AP 的 beacon 中有国家/地区的 IE，使用的国家/地区信息为 beacon 中的信息，否则，使用默认信息。
* - Wi-Fi 模式
- 策略
- 描述
* - station 模式
- WIFI_COUNTRY_POLICY_AUTO
- 如果所连 AP 的 beacon 中有国家/地区的 IE，使用的国家/地区信息为 beacon 中的信息，否则，使用默认信息。
扫描时：
扫描时：
主动扫描信道 1 至信道 11，被动扫描信道 12 至 信道 14。
主动扫描信道 1 至信道 11，被动扫描信道 12 至 信道 14。
请记住，如果带有隐藏 SSID 的 AP 和 station 被设置在被动扫描信道上，被动扫描将无法找到该 AP。也就是说，如果应用程序希望在每个信道中找到带有隐藏 SSID 的 AP，国家/地区信息应该配置为 WIFI_COUNTRY_POLICY_MANUAL。
请记住，如果带有隐藏 SSID 的 AP 和 station 被设置在被动扫描信道上，被动扫描将无法找到该 AP。也就是说，如果应用程序希望在每个信道中找到带有隐藏 SSID 的 AP，国家/地区信息应该配置为 WIFI_COUNTRY_POLICY_MANUAL。
* - station 模式
- WIFI_COUNTRY_POLICY_MANUAL
- 总是使用配置的国家/地区信息。
* - station 模式
- WIFI_COUNTRY_POLICY_MANUAL
- 总是使用配置的国家/地区信息。
扫描时：
扫描时：
主动扫描信道 schan 至信道 schan+nchan-1。
主动扫描信道 schan 至信道 schan+nchan-1。
* - AP 模式
- WIFI_COUNTRY_POLICY_AUTO
- 总是使用配置的国家/地区信息。
* - AP 模式
- WIFI_COUNTRY_POLICY_AUTO
- 总是使用配置的国家/地区信息。
* - AP 模式
- WIFI_COUNTRY_POLICY_MANUAL
- 总是使用配置的国家/地区信息。
* - 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_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 策略下使用的国家/地区信息相同。
* - station/AP 共存模式
- WIFI_COUNTRY_POLICY_MANUAL
- 该 station 与 station 模式、WIFI_COUNTRY_POLICY_MANUAL 策略下使用的国家/地区信息相同。
该 AP 与 AP 模式、WIFI_COUNTRY_POLICY_MANUAL 策略下使用的国家/地区信息相同。
.. only:: esp32c5
调用 :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 也始终使用配置的国家/地区信息。
主信道
*************************
@@ -2319,54 +2687,134 @@ Wi-Fi 多根天线
Wi-Fi 信道状态信息
------------------------------------
信道状态信息 (CSI) 是指 Wi-Fi 连接的信道信息。{IDF_TARGET_NAME} 中，CSI 由子载波的信道频率响应组成，CSI 从发送端接收数据包时开始估计。每个子载波信道频率响由两个字节的有符号字符记录，第一个字节是虚部，第二个字节是实部。根据接收数据包的类型，信道频率响应最多有三个字段。分别是 LLTF、HT-LTF 和 STBC-HT-LTF。对于在不同状态的信道上接收到的不同类型的数据包，CSI 的子载波索引和总字节数如下表所示。
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
+------------+-------------+-----------------------------------------+-----------------------------------------------------+--------------------------------------------------------+
| 信道 | 辅助信道 | | 下 | 上 |
+------------+-------------+-------------+---------------------------+---------+-------------------------------------------+---------+----------------------------------------------+
| 数据包信息 | 信号模式 | 非 HT | HT | 非 HT | HT | 非 HT | HT |
| +-------------+-------------+---------------------------+---------+---------------+---------------------------+---------+------------------+---------------------------+
| | 信道带宽 | 20 MHz | 20 MHz | 20 MHz | 20 MHz | 40 MHz | 20 MHz | 20 MHz | 40 MHz |
| +-------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
| | STBC | 非 STBC | 非 STBC | STBC | 非 STBC | 非 STBC| STBC | 非 STBC | STBC | 非 STBC | 非 STBC | STBC | 非 STBC | STBC |
+------------+-------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
| 子载波索引 | LLTF | 0~31,-32~-1 | 0~31,-32~-1 | 0~31,-32~-1 | 0~63 | 0~63 | 0~63 | 0~63 | 0~63 | -64~-1 | -64~-1 | -64~-1 | -64~-1 | -64~-1 |
| +-------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
| | HT-LTF | — | 0~31,-32~-1 | 0~31,-32~-1 | — | 0~63 | 0~62 | 0~63,-64~-1 | 0~60,-60~-1 | — | -64~-1 | -62~-1 | 0~63,-64~-1 | 0~60,-60~-1 |
| +-------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
| | STBC-HT-LTF | — | — | 0~31,-32~-1 | — | — | 0~62 | — | 0~60,-60~-1 | — | — | -62~-1 | — | 0~60,-60~-1 |
+------------+-------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
| 总字节数 | 128 | 256 | 384 | 128 | 256 | 380 | 384 | 612 | 128 | 256 | 376 | 384 | 612 |
+--------------------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
信道状态信息 (CSI) 是指 Wi-Fi 连接的信道信息。{IDF_TARGET_NAME} 中，CSI 由子载波的信道频率响应组成，CSI 从发送端接收数据包时开始估计。每个子载波信道频率响由两个字节的有符号字符记录，第一个字节是虚部，第二个字节是实部。根据接收数据包的类型，信道频率响应最多有三个字段。分别是 LLTF、HT-LTF 和 STBC-HT-LTF。对于在不同状态的信道上接收到的不同类型的数据包，CSI 的子载波索引和总字节数如下表所示。
表中的所有信息可以在 wifi_csi_info_t 结构中找到。
+------------+-------------+-----------------------------------------+-----------------------------------------------------+--------------------------------------------------------+
| 信道 | 辅助信道 | | 下 | 上 |
+------------+-------------+-------------+---------------------------+---------+-------------------------------------------+---------+----------------------------------------------+
| 数据包信息 | 信号模式 | 非 HT | HT | 非 HT | HT | 非 HT | HT |
| +-------------+-------------+---------------------------+---------+---------------+---------------------------+---------+------------------+---------------------------+
| | 信道带宽 | 20 MHz | 20 MHz | 20 MHz | 20 MHz | 40 MHz | 20 MHz | 20 MHz | 40 MHz |
| +-------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
| | STBC | 非 STBC | 非 STBC | STBC | 非 STBC | 非 STBC| STBC | 非 STBC | STBC | 非 STBC | 非 STBC | STBC | 非 STBC | STBC |
+------------+-------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
| 子载波索引 | LLTF | 0~31,-32~-1 | 0~31,-32~-1 | 0~31,-32~-1 | 0~63 | 0~63 | 0~63 | 0~63 | 0~63 | -64~-1 | -64~-1 | -64~-1 | -64~-1 | -64~-1 |
| +-------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
| | HT-LTF | — | 0~31,-32~-1 | 0~31,-32~-1 | — | 0~63 | 0~62 | 0~63,-64~-1 | 0~60,-60~-1 | — | -64~-1 | -62~-1 | 0~63,-64~-1 | 0~60,-60~-1 |
| +-------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
| | STBC-HT-LTF | — | — | 0~31,-32~-1 | — | — | 0~62 | — | 0~60,-60~-1 | — | — | -62~-1 | — | 0~60,-60~-1 |
+------------+-------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
| 总字节数 | 128 | 256 | 384 | 128 | 256 | 380 | 384 | 612 | 128 | 256 | 376 | 384 | 612 |
+--------------------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+
- 辅助信道指 rx_ctrl 字段的 secondary_channel 字段。
- 数据包的信号模式指 rx_ctrl 字段的 sig_mode 字段。
- 信道带宽指 rx_ctrl 字段中的 cwb 字段。
- STBC 指 rx_ctrl 字段的 stbc 字段。
- 总字节数指 len 字段。
- 每个长训练字段 (LTF) 类型对应的 CSI 数据存储在从 buf 字段开始的缓冲区中。每个元素以两个字节的形式存储：虚部和实部。每个元素的顺序与表中的子载波相同。LTF 的顺序是 LLTF、HT-LTF 和 STBC-HT-LTF。但是，根据信道和数据包的信息，3 个 LTF 可能都不存在（见上文）。
- 如果 :cpp:type:`wifi_csi_info_t` 的 first_word_invalid 字段为 true，表示由于 {IDF_TARGET_NAME} 的硬件限制，CSI 数据的前四个字节无效。
- 更多信息，如 RSSI，射频的噪声底，接收时间和天线 rx_ctrl 领域。
表中的所有信息可以在 wifi_csi_info_t 结构中找到。
子载波的虚部和实部的使用请参考下表。
- 辅助信道指 rx_ctrl 字段的 secondary_channel 字段。
- 数据包的信号模式指 rx_ctrl 字段的 sig_mode 字段。
- 信道带宽指 rx_ctrl 字段中的 cwb 字段。
- STBC 指 rx_ctrl 字段的 stbc 字段。
- 总字节数指 len 字段。
- 每个长训练字段 (LTF) 类型对应的 CSI 数据存储在从 buf 字段开始的缓冲区中。每个元素以两个字节的形式存储：虚部和实部。每个元素的顺序与表中的子载波相同。LTF 的顺序是 LLTF、HT-LTF 和 STBC-HT-LTF。但是，根据信道和数据包的信息，3 个 LTF 可能都不存在（见上文）。
- 如果 :cpp:type:`wifi_csi_info_t` 的 first_word_invalid 字段为 true，表示由于 {IDF_TARGET_NAME} 的硬件限制，CSI 数据的前四个字节无效。
- 更多信息，如 RSSI，射频的噪声底，接收时间和天线 rx_ctrl 领域。
+----------------+-------------------+------------------------------+------------------------------+
| PHY 标准 | 子载波范围 | 导频子载波 | 子载波个数（总数/数据子载波）|
+================+===================+==============================+==============================+
| 802.11a/g | -26 to +26 | -21, -7, +7, +21 | 52 total, 48 usable |
+----------------+-------------------+------------------------------+------------------------------+
| 802.11n, 20 MHz| -28 to +28 | -21, -7, +7, +21 | 56 total, 52 usable |
+----------------+-------------------+------------------------------+------------------------------+
| 802.11n, 40 MHz| -57 to +57 | -53, -25, -11, +11, +25, +53 | 114 total, 108 usable |
+----------------+-------------------+------------------------------+------------------------------+
子载波的虚部和实部的使用请参考下表。
.. note ::
+----------------+-------------------+------------------------------+------------------------------+
| PHY 标准 | 子载波范围 | 导频子载波 | 子载波个数（总数/数据子载波）|
+================+===================+==============================+==============================+
| 802.11a/g | -26 to +26 | -21, -7, +7, +21 | 52 total, 48 usable |
+----------------+-------------------+------------------------------+------------------------------+
| 802.11n, 20 MHz| -28 to +28 | -21, -7, +7, +21 | 56 total, 52 usable |
+----------------+-------------------+------------------------------+------------------------------+
| 802.11n, 40 MHz| -57 to +57 | -53, -25, -11, +11, +25, +53 | 114 total, 108 usable |
+----------------+-------------------+------------------------------+------------------------------+
- 对于 STBC 数据包，每个空时流都提供了 CSI，不会出现 CSD（循环移位延迟）。由于附加链上的每一次循环移位为 -200 ns，因为子载波 0 中没有信道频率响应，在 HT-LTF 和 STBC-HT-LTF 中只记录第一空时流的 CSD 角度。CSD[10:0] 是 11 位，范围从 -pi 到 pi。
.. note ::
- 如果调用 API :cpp:func:`esp_wifi_set_csi_config()` 没有使能 LLTF、HT-LTF 或 STBC-HT-LTF，则 CSI 数据的总字节数会比表中的少。例如，如果没有使能 LLTF 和 HT-LTF，而使能 STBC-HT-LTF，当接收到上述条件、HT、40 MHz 或 STBC 的数据包时，CSI 数据的总字节数为 244（(61+60)*2+2=244，结果对齐为四个字节，最后两个字节无效）。
- 对于 STBC 数据包，每个空时流都提供了 CSI，不会出现 CSD（循环移位延迟）。由于附加链上的每一次循环移位为 -200 ns，因为子载波 0 中没有信道频率响应，在 HT-LTF 和 STBC-HT-LTF 中只记录第一空时流的 CSD 角度。CSD[10:0] 是 11 位，范围从 -pi 到 pi。
- 如果调用 API :cpp:func:`esp_wifi_set_csi_config()` 没有使能 LLTF、HT-LTF 或 STBC-HT-LTF，则 CSI 数据的总字节数会比表中的少。例如，如果没有使能 LLTF 和 HT-LTF，而使能 STBC-HT-LTF，当接收到上述条件、HT、40 MHz 或 STBC 的数据包时，CSI 数据的总字节数为 244（(61+60)*2+2=244，结果对齐为四个字节，最后两个字节无效）。
.. only:: esp32c5
信道状态信息 (CSI) 是指 Wi-Fi 连接的信道信息。{IDF_TARGET_NAME} 中，CSI 由子载波的信道频率响应组成，CSI 从发送端接收数据包时开始估计。每个子载波信道频率响由两个字节的有符号字符记录，第一个字节是虚部，第二个字节是实部。除了 IEEE 802.11g 模式外，其他模式均存在两段 LTF 序列（LLTF + HT/VHT/HE-LTF）。{IDF_TARGET_NAME}可以通过 :cpp:struct:`wifi_csi_acquire_config_t` 中 ``acquire_csi_force_lltf`` 字段决定包含 LLTF 或 HT/VHT/HE-LTF。对于在不同状态的信道上接收到的不同类型的数据包，CSI 的子载波索引和总字节数如下表所示。
+------------+------------------+-----------------------------------------+--------------------------------------------+----------------------------------------------------------------+----------------------------------------------------------------+
| 信道 | 辅助信道 | | 下 | 上 |
+------------+------------------+-------------+---------------------------+--------------------------------------------+-------------+--------------------------------------------------+-------------+--------------------------------------------------+
| 数据包信息 | 信号模式 | 非 HT | HT | HE | 非 HT | HT | 非 HT | HT |
| +------------------+-------------+---------------------------+--------------------------------------------+-------------+----------------------+---------------------------+-------------+----------------------+---------------------------+
| | 信道带宽 | 20 MHz | 20 MHz | 20 MHz | 20 MHz | 20 MHz | 40 MHz | 20 MHz | 20 MHz | 40 MHz |
| +------------------+-------------+-------------+-------------+---------------+----------------------------+-------------+-------------+--------+-------------+-------------+-------------+-------------+--------+-------------+-------------+
| | STBC | 非 STBC | 非 STBC | STBC | 非 STBC | STBC | 非 STBC | 非 STBC | STBC | 非 STBC | STBC | 非 STBC | 非 STBC | STBC | 非 STBC | STBC |
+------------+------------------+-------------+-------------+-------------+---------------+----------------------------+-------------+-------------+--------+-------------+-------------+-------------+-------------+--------+-------------+-------------+
| 子载波索引 | LLTF | 0~26,-26~-1 | — | — | — | — | 0~52 | — | — | — | — | -53~-1| — | — | — | — |
| +------------------+-------------+-------------+-------------+---------------+----------------------------+-------------+-------------+--------+-------------+-------------+-------------+-------------+--------+-------------+-------------+
| | HT-LTF (HT-LTF1) | — | 0~28,-28~-1 | 0~28,-28~-1 | — | — | — | 0~56| 0~56 | 0~58,-58~-1 | 0~58,-58~-1 | — | -57~-1| -57~-1 | 0~58,-58~-1 | 0~58,-58~-1 |
| +------------------+-------------+-------------+-------------+---------------+----------------------------+-------------+-------------+--------+-------------+-------------+-------------+-------------+--------+-------------+-------------+
| | HT-LTF2 | — | — | 0~28,-28~-1 | — | — | — | — | 0~56 | — | 0~58,-58~-1 | — | — | -57~-1 | — | 0~58,-58~-1 |
| +------------------+-------------+-------------+-------------+---------------+----------------------------+-------------+-------------+--------+-------------+-------------+-------------+-------------+--------+-------------+-------------+
| | HE-LTF (HE-LTF1) | — | — | — | 0~122,-122~1 | 由CSI配置决定 | — | — | — | — | — | — | — | — | — | — |
| +------------------+-------------+-------------+-------------+---------------+ +-------------+-------------+--------+-------------+-------------+-------------+-------------+--------+-------------+-------------+
| | HE-LTF2 | — | — | — | — | | — | — | — | — | — | — | — | — | — | — |
+------------+------------------+-------------+-------------+-------------+---------------+----------------------------+-------------+-------------+--------+-------------+-------------+-------------+-------------+--------+-------------+-------------+
| 总字节数 | 106 | 114| 228 | 490 | 490 | 106 | 114| 228 | 234 | 468 | 106 | 114| 228 | 234 | 468 |
+-------------------------------+-------------+-------------+-------------+---------------+----------------------------+-------------+-------------+--------+-------------+-------------+-------------+-------------+--------+-------------+-------------+
.. note ::
- HT/VHT/HE 模式均存在两段 LTF 序列即：LLTF + HT/VHT/HE-LTF， 如果 :cpp:struct:`wifi_csi_acquire_config_t` 中 ``acquire_csi_force_lltf`` 为 false 时， CSI 数据中仅包含 HT/VHT/HE-LTF(如上表所示)， 否则 CSI 数据中仅包含 LLTF。 HT/VHT/HE 模式 LLTF 的子载波索引和 CSI 总字节数同非 HT 模式 LLTF 子载波索引和 CSI 总字节数一致。
- VHT 模式时子载波索引和 CSI 总字节数同 HT 模式的子载波索引和 CSI 总字节数一致。
表中的信息可以在 :cpp:type:`wifi_csi_info_t` 结构体中找到。
- 辅助信道指 ``rx_ctrl`` 字段的 ``second`` 字段。
- 数据包的信号模式指 ``rx_ctrl`` 字段的 ``cur_bb_format`` 字段。
- 总字节数指 ``len`` 字段。
- 每个长训练字段 (LTF) 类型对应的 CSI 数据存储在从 buf 字段开始的缓冲区中。每个元素以两个字节的形式存储：虚部和实部。每个元素的顺序与表中的子载波相同。LTF 的顺序是 LLTF、HT/VHT/HE-LTF。根据信道和数据包的信息，LTF 的存在情况见上文。
- 如果 ``first_word_invalid`` 字段为 true，表示由于 {IDF_TARGET_NAME} 的硬件限制，CSI 数据的前四个字节无效。
- 如果 ``rx_ctrl`` 字段中的 ``rx_channel_estimate_info_vld`` 为 1,表明CSI数据是有效的，否则，CSI数据是无效的。
- 更多信息，如 RSSI、射频底噪声、接收时间及天线，请参见 ``rx_ctrl`` 字段。
对于 STBC 数据包，HE-LTF 和 STBC-HE-LTF 的子载波索引由 :cpp:type:`wifi_csi_config_t` 中的 ``acquire_csi_he_stbc_mode`` 字段决定，具体请参见下表。
+---------------------+------------------+-------------------+
| acquire_csi_he_stbc | HE-LTF1 | HE-LTF2 |
+---------------------+------------------+-------------------+
| 0 | -122~-1, 0~122 | — |
+---------------------+------------------+-------------------+
| 1 | — | -122~-1, 0~122 |
+---------------------+------------------+-------------------+
| 2 | 在 HE-LTF1 和 HE-LTF2 中进行均匀采样 |
+---------------------+------------------+-------------------+
有效子载波的虚部和实部的使用请参考下表。
+-----------------------+------------------+------------------------------------------+------------------------------+
| PHY 标准 | 子载波范围 | 无效子载波 | 子载波个数（总数/数据子载波）|
+=======================+==================+==========================================+==============================+
| 802.11a/g | -26 to +26 | 0 | 53 total, 52 usable |
+-----------------------+------------------+------------------------------------------+------------------------------+
| 802.11n, 20 MHz | -28 to +28 | 0 | 57 total, 56 usable |
+-----------------------+------------------+------------------------------------------+------------------------------+
| 802.11n, 40 MHz | -58 to +58 | -1, 0, 1 | 117 total, 114 usable |
+-----------------------+------------------+------------------------------------------+------------------------------+
| 802.11ac, 20 MHz | -28 to +28 | 0 | 57 total, 56 usable |
+-----------------------+------------------+------------------------------------------+------------------------------+
| 802.11ax, 20 MHz (SU) | -122 to + 122 | -1, 0, 1 | 245 total, 242 usable |
+-----------------------+------------------+------------------------------------------+------------------------------+
.. note ::
- PHY 为 802.11ax时，MU 数据包的 CSI 子载波范围和无效子载波索引请参考协议。
.. note ::
- 对于 STBC 数据包，每个空时流都提供了 CSI，不会出现 CSD（循环移位延迟）。由于附加链上的每一次循环移位为 -200 ns，因为子载波 0 中没有信道频率响应，在 HT-LTF1 和 HT-LTF2 中只记录第一空时流的 CSD 角度。CSD[10:0] 是 11 位，范围从 -pi 到 pi。
Wi-Fi 信道状态信息配置
-------------------------------------------
@@ -2383,7 +2831,7 @@ Wi-Fi 多根天线
Wi-Fi HT20/40
-------------------------
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3 or esp32c6
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3 or esp32c6 or esp32c5
{IDF_TARGET_NAME} 支持 Wi-Fi 带宽 HT20 或 HT40，不支持 HT20/40 共存，调用函数 :cpp:func:`esp_wifi_set_bandwidth()` 可改变 station/AP 的默认带宽。{IDF_TARGET_NAME} station 和 AP 的默认带宽为 HT40。
@@ -2395,6 +2843,12 @@ Wi-Fi HT20/40
理论上，HT40 可以获得更大的吞吐量，因为 HT40 的最大原始 PHY 数据速率为 150 Mbps，而 HT20 为 72 Mbps。但是，如果设备在某些特殊环境中使用，例如，{IDF_TARGET_NAME} 周围其他 Wi-Fi 设备过多，HT40 的性能可能会降低。因此，如果应用程序需要支持相同或类似的情况，建议始终将带宽配置为 HT20。
.. only:: esp32c5
.. note::
当工作在 2.4 GHz + 5 GHz 频段模式(``WIFI_BAND_MODE_AUTO``)时，需要使用函数: :cpp:func:`esp_wifi_set_bandwidths()` 分别设置 2.4 GHz 频段 和 5 GHz 频段的带宽。
.. only:: esp32c2
{IDF_TARGET_NAME} 仅支持 Wi-Fi 带宽 HT20，不支持 Wi-Fi 带宽 HT40 或 HT20/40 共存。
@@ -2451,7 +2905,7 @@ Wi-Fi 分片
支持 Wi-Fi 接收分片，但不支持 Wi-Fi 发送分片。
.. only:: esp32c3 or esp32s3 or esp32c6
.. only:: esp32c3 or esp32s3 or esp32c6 or esp32c5
{IDF_TARGET_NAME} 支持 Wi-Fi 接收和发送分片。

14
docs/zh_CN/api-reference/network/esp_now.rst
View File

@@ -92,7 +92,15 @@ ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参
ESP-NOW 数据可以从 Station 或 SoftAP 接口发送。确保在发送 ESP-NOW 数据之前已启用该接口。
配对设备的信道范围是从 0 ~ 14。如果信道设置为 0，数据将在当前信道上发送。否则，必须使用本地设备所在的通道。
.. only:: esp32 or esp32c2 or esp32s2 or esp32s3 or esp32c3 or esp32c6
配对设备的信道范围是从 0 ~ 14。如果信道设置为 0，数据将在当前信道上发送。否则，必须使用本地设备所在的通道。
.. only:: esp32c5
2.4G频段配对设备的信道范围是从 1 ~ 14。5G频段配对设备的信道范围是[36，40，44，48，52，56，60，64，100，112，116，120，124，128，132，136，140，144，149，153，157，161，165，169，173，177]。
如果信道设置为 0，数据将在当前信道上发送。否则，必须使用本地设备所在的通道。
对于接收设备，调用 :cpp:func:`esp_now_add_peer()` 不是必需的。如果没有添加配对设备，只能接收广播包和不加密的单播包。如果需要接收加密的单播包，则必须添加配对设备并设置相同的 LMK。
@@ -100,7 +108,7 @@ ESP-NOW 数据可以从 Station 或 SoftAP 接口发送。确保在发送 ESP-NO
配对设备的最大数量是 20，其中加密设备的数量不超过 4，默认值是 2。如果想要修改加密设备的数量，在 Wi-Fi menuconfig 设置 :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`。
.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c6
.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c6 or esp32c5
配对设备的最大数量是 20，其中加密设备的数量不超过 17，默认值是 7。如果想要修改加密设备的数量，在 Wi-Fi menuconfig 设置 :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`。
@@ -124,7 +132,7 @@ ESP-NOW 数据可以从 Station 或 SoftAP 接口发送。确保在发送 ESP-NO
调用 :cpp:func:`esp_wifi_config_espnow_rate()` 配置指定接口的 ESP-NOW 速率。确保在配置速率之前启用接口。这个 API 应该在 :cpp:func:`esp_wifi_start()` 之后调用。
.. only:: esp32c6
.. only:: esp32c5 or esp32c6
调用 :cpp:func:`esp_now_set_peer_rate_config()` 配置指定 peer 的 ESP-NOW 速率。确保在配置速率之前添加 peer。这个 API 应该在 :cpp:func:`esp_wifi_start()` 和 :cpp:func:`esp_now_add_peer()` 之后调用。