mirror
/
esp-idf
kopia lustrzana https://github.com/espressif/esp-idf
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

doc: esp32c2 wifi programming guide doc.

pull/9357/head
Mu Hai Dong 2022-07-07 14:13:11 +08:00 zatwierdzone przez morris
rodzic 0d86ca59a6
commit eb4421bf33
11 zmienionych plików z 512 dodań i 333 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

16
docs/conf_common.py
Wyświetl plik

@ -111,7 +111,9 @@ ESP32_DOCS = ['api-reference/system/himem.rst',
'api-reference/peripherals/secure_element.rst',
'api-reference/peripherals/dac.rst',
'hw-reference/esp32/**',
'api-guides/RF_calibration.rst'] + FTDI_JTAG_DOCS
'api-guides/RF_calibration.rst',
'api-guides/esp-wifi-mesh.rst',
'api-reference/network/esp-wifi-mesh.rst'] + FTDI_JTAG_DOCS
ESP32S2_DOCS = ['hw-reference/esp32s2/**',
'api-guides/usb-console.rst',
@ -120,16 +122,22 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**',
'api-reference/peripherals/temp_sensor.rst',
'api-reference/system/async_memcpy.rst',
'api-reference/peripherals/touch_element.rst',
'api-guides/RF_calibration.rst'] + FTDI_JTAG_DOCS
'api-guides/RF_calibration.rst',
'api-guides/esp-wifi-mesh.rst',
'api-reference/network/esp-wifi-mesh.rst'] + FTDI_JTAG_DOCS
ESP32S3_DOCS = ['hw-reference/esp32s3/**',
'api-reference/system/ipc.rst',
'api-guides/flash_psram_config.rst',
'api-guides/RF_calibration.rst']
'api-guides/RF_calibration.rst',
'api-guides/esp-wifi-mesh.rst',
'api-reference/network/esp-wifi-mesh.rst']
# No JTAG docs for this one as it gets gated on SOC_USB_SERIAL_JTAG_SUPPORTED down below.
ESP32C3_DOCS = ['hw-reference/esp32c3/**',
'api-guides/RF_calibration.rst']
'api-guides/RF_calibration.rst',
'api-guides/esp-wifi-mesh.rst',
'api-reference/network/esp-wifi-mesh.rst']
# format: {tag needed to include: documents to included}, tags are parsed from sdkconfig and peripheral_caps.h headers
conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,

4
docs/docs_not_updated/esp32c2.txt
Wyświetl plik

@ -38,11 +38,9 @@ api-guides/lwip
api-guides/flash_psram_config
api-guides/usb-serial-jtag-console
api-guides/linker-script-generation
api-guides/wifi
api-guides/usb-otg-console
api-guides/wireshark-user-guide
api-guides/bootloader
api-guides/esp-wifi-mesh
api-guides/ulp-legacy
api-guides/build-system
api-guides/freertos-smp
@ -93,9 +91,7 @@ api-reference/network/esp_netif_driver
api-reference/network/tcpip_adapter_migration
api-reference/network/esp_dpp
api-reference/network/esp_now
api-reference/network/esp-wifi-mesh
api-reference/network/esp_smartconfig
api-reference/network/esp_wifi
api-reference/network/index
api-reference/network/esp_netif
api-reference/system/sleep_modes

6
docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst
Wyświetl plik

@ -16,9 +16,11 @@ Please see the :doc:`ble-mesh-architecture` for information about the implementa
ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.1, users can refer `here <https://launchstudio.bluetooth.com/ListingDetails/94304>`_ for the certification details of ESP-BLE-MESH.
.. note::
.. only:: SOC_WIFI_MESH_SUPPORT
.. note::
If you are looking for Wi-Fi based implementation of mesh for {IDF_TARGET_NAME}, please check another product by Espressif called ESP-WIF-MESH. For more information and documentation see :doc:`ESP-WIFI-MESH <../../api-reference/network/esp-wifi-mesh>`.
If you are looking for Wi-Fi based implementation of mesh for {IDF_TARGET_NAME}, please check another product by Espressif called ESP-WIFI-MESH. For more information and documentation see :doc:`ESP-WIFI-MESH <../../api-reference/network/esp-wifi-mesh>`.
.. _getting-started-with-ble-mesh:

9
docs/en/api-guides/event-handling.rst
Wyświetl plik

@ -127,10 +127,13 @@ Event IDs and Corresponding Data Structures
| (SYSTEM_EVENT_ETH_LOST_IP) | |
+------------------------------------+-----------------------------------------------+
Mesh Events
-----------
.. only:: SOC_WIFI_MESH_SUPPORT
Mesh Events
-----------
ESP-WIFI-MESH uses a system similar to the :ref:`legacy-event-loop` to deliver events to the application. See :ref:`mesh-events` for details.
ESP-WIFI-MESH uses a system similar to the :ref:`legacy-event-loop` to deliver events to the application. See :ref:`mesh-events` for details.
Bluetooth Events
----------------

2
docs/en/api-guides/index.rst
Wyświetl plik

@ -16,7 +16,7 @@ API Guides
error-handling
:SOC_BT_SUPPORTED: esp-ble-mesh/ble-mesh-index
freertos-smp
esp-wifi-mesh
:SOC_WIFI_MESH_SUPPORT: esp-wifi-mesh
event-handling
fatal-errors
../security/flash-encryption

393
docs/en/api-guides/wifi.rst
Wyświetl plik

@ -5,18 +5,36 @@ Wi-Fi Driver
{IDF_TARGET_NAME} Wi-Fi Feature List
------------------------------------
- Support 4 virtual WiFi interfaces, which are STA, AP, Sniffer and reserved.
- Support station-only mode, AP-only mode, station/AP-coexistence mode
- Support IEEE 802.11b, IEEE 802.11g, IEEE 802.11n, and APIs to configure the protocol mode
- Support WPA/WPA2/WPA3/WPA2-Enterprise and WPS
- Support AMPDU, HT40, QoS, and other key features
- Support Modem-sleep
- Support the Espressif-specific ESP-NOW protocol and Long Range mode, 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
- Support Sniffer
- Support both fast scan and all-channel scan
- Support multiple antennas
- Support channel state information
The following features are supported:
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
- 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/WAPI/WPS and DPP
- AMSDU, AMPDU, HT40, QoS, and other key features
- Modem-sleep
- The Espressif-specific ESP-NOW protocol and Long Range mode, 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
.. only:: esp32c2
- 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
- AMSDU, 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
How To Write a Wi-Fi Application
----------------------------------
@ -1099,28 +1117,56 @@ AP Basic Configuration
API esp_wifi_set_config() can be used to configure the AP. The table below describes the fields in detail.
.. list-table::
:header-rows: 1
:widths: 15 55
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
* - Field
- Description
* - ssid
- SSID of AP; if the ssid[0] is 0xFF and ssid[1] is 0xFF, the AP defaults the SSID to ESP_aabbcc, where “aabbcc” is the last three bytes of the AP MAC.
* - password
- Password of AP; if the auth mode is WIFI_AUTH_OPEN, this field will be ignored.
* - 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 the channel to channel 1. 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 Wi-Fi does not support AUTH_WEP. If the authmode is an invalid value, AP defaults the value to WIFI_AUTH_OPEN.
* - ssid_hidden
- If ssid_hidden is 1, AP does not broadcast the SSID; otherwise, it does broadcast the SSID.
* - max_connection
- Currently, ESP Wi-Fi supports up to 10 Wi-Fi connections. If max_connection > 10, AP defaults the value to 10.
* - beacon_interval
- Beacon interval; the value is 100 ~ 60000 ms, with default value being 100 ms. If the value is out of range, AP defaults it to 100 ms.
.. list-table::
:header-rows: 1
:widths: 15 55
* - Field
- Description
* - ssid
- SSID of AP; if the ssid[0] is 0xFF and ssid[1] is 0xFF, the AP defaults the SSID to ESP_aabbcc, where “aabbcc” is the last three bytes of the AP MAC.
* - password
- Password of AP; if the auth mode is WIFI_AUTH_OPEN, this field will be ignored.
* - 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 the channel to channel 1. 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 Wi-Fi does not support AUTH_WEP. If the authmode is an invalid value, AP defaults the value to WIFI_AUTH_OPEN.
* - ssid_hidden
- If ssid_hidden is 1, AP does not broadcast the SSID; otherwise, it does broadcast the SSID.
* - max_connection
- Currently, ESP Wi-Fi supports up to 10 Wi-Fi connections. If max_connection > 10, AP defaults the value to 10.
* - beacon_interval
- Beacon interval; the value is 100 ~ 60000 ms, with default value being 100 ms. If the value is out of range, AP defaults it to 100 ms.
.. only:: esp32c2
.. list-table::
:header-rows: 1
:widths: 15 55
* - Field
- Description
* - ssid
- SSID of AP; if the ssid[0] is 0xFF and ssid[1] is 0xFF, the AP defaults the SSID to ESP_aabbcc, where “aabbcc” is the last three bytes of the AP MAC.
* - password
- Password of AP; if the auth mode is WIFI_AUTH_OPEN, this field will be ignored.
* - 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 the channel to channel 1. 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 Wi-Fi does not support AUTH_WEP. If the authmode is an invalid value, AP defaults the value to WIFI_AUTH_OPEN.
* - ssid_hidden
- If ssid_hidden is 1, AP does not broadcast the SSID; otherwise, it does broadcast the SSID.
* - max_connection
- Currently, ESP Wi-Fi supports up to 4 Wi-Fi connections. If max_connection > 4, AP defaults the value to 4.
* - beacon_interval
- Beacon interval; the value is 100 ~ 60000 ms, with default value being 100 ms. If the value is out of range, AP defaults it to 100 ms.
Wi-Fi Protocol Mode
@ -1128,98 +1174,125 @@ Wi-Fi Protocol Mode
Currently, the ESP-IDF supports the following protocol modes:
.. list-table::
:header-rows: 1
:widths: 15 55
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
* - Protocol Mode
- Description
* - 802.11b
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B) to set the station/AP to 802.11b-only mode.
* - 802.11bg
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) to set the station/AP to 802.11bg mode.
* - 802.11g
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) and esp_wifi_config_11b_rate(ifx, true) to set the station/AP to 802.11g mode.
* - 802.11bgn
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) to set the station/ AP to BGN mode.
* - 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.
* - 802.11 BGNLR
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR) to set the station/AP to BGN and the LR mode.
* - 802.11 LR
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR) to set the station/AP only to the LR mode.
.. list-table::
:header-rows: 1
:widths: 15 55
**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.**
* - Protocol Mode
- Description
* - 802.11b
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B) to set the station/AP to 802.11b-only mode.
* - 802.11bg
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) to set the station/AP to 802.11bg mode.
* - 802.11g
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) and esp_wifi_config_11b_rate(ifx, true) to set the station/AP to 802.11g mode.
* - 802.11bgn
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) to set the station/ AP to BGN mode.
* - 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.
* - 802.11 BGNLR
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR) to set the station/AP to BGN and the LR mode.
* - 802.11 LR
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR) to set the station/AP only to the LR mode.
**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.**
Long Range (LR)
+++++++++++++++++++++++++
Long Range (LR) mode is an Espressif-patented Wi-Fi mode which can achieve a one-kilometer line of sight range. Compared to the traditional 802.11b mode, it has better reception sensitivity, stronger anti-interference ability, and longer transmission distance.
.. only:: esp32c2
LR Compatibility
*************************
.. list-table::
:header-rows: 1
:widths: 15 55
Since LR is Espressif-unique Wi-Fi mode, only {IDF_TARGET_NAME} devices can transmit and receive the LR data. In other words, the {IDF_TARGET_NAME} device should NOT transmit the data in LR data rate if the connected device does not support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the {IDF_TARGET_NAME} may transmit data in LR rate. Otherwise, {IDF_TARGET_NAME} will transmit all data in traditional Wi-Fi data rate.
* - Protocol Mode
- Description
* - 802.11b
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B) to set the station/AP to 802.11b-only mode.
* - 802.11bg
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) to set the station/AP to 802.11bg mode.
* - 802.11g
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) and esp_wifi_config_11b_rate(ifx, true) to set the station/AP to 802.11g mode.
* - 802.11bgn
- Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) to set the station/ AP to BGN mode.
* - 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.
The following table depicts the Wi-Fi mode negotiation:
+-------+-----+----+---+-------+------+-----+----+
|AP\STA | BGN | BG | B | BGNLR | BGLR | BLR | LR |
+=======+=====+====+===+=======+======+=====+====+
| BGN | BGN | BG | B | BGN | BG | B | - |
+-------+-----+----+---+-------+------+-----+----+
| BG | BG | BG | B | BG | BG | B | - |
+-------+-----+----+---+-------+------+-----+----+
| B | B | B | B | B | B | B | - |
+-------+-----+----+---+-------+------+-----+----+
| BGNLR | - | - | - | BGNLR | BGLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| BGLR | - | - | - | BGLR | BGLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| BLR | - | - | - | BLR | BLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| LR | - | - | - | LR | LR | LR | LR |
+-------+-----+----+---+-------+------+-----+----+
In the above table, the row is the Wi-Fi mode of AP and the column is the Wi-Fi mode of station. The "-" indicates Wi-Fi mode of the AP and station are not compatible.
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
According to the table, the following conclusions can be drawn:
Long Range (LR)
+++++++++++++++++++++++++
- For LR-enabled AP of {IDF_TARGET_NAME}, it is incompatible with traditional 802.11 mode, because the beacon is sent in LR mode.
- For LR-enabled station of {IDF_TARGET_NAME} whose mode is NOT LR-only mode, it is compatible with traditional 802.11 mode.
- If both station and AP are {IDF_TARGET_NAME} devices and both of them have enabled LR mode, the negotiated mode supports LR.
Long Range (LR) mode is an Espressif-patented Wi-Fi mode which can achieve a one-kilometer line of sight range. Compared to the traditional 802.11b mode, it has better reception sensitivity, stronger anti-interference ability, and longer transmission distance.
If the negotiated Wi-Fi mode supports both traditional 802.11 mode and LR mode, it is the Wi-Fi driver's responsibility to automatically select the best data rate in different Wi-Fi modes and the application can ignore it.
LR Compatibility
*************************
LR Impacts to Traditional Wi-Fi Device
***************************************
Since LR is Espressif-unique Wi-Fi mode, only {IDF_TARGET_NAME} devices can transmit and receive the LR data. In other words, the {IDF_TARGET_NAME} device should NOT transmit the data in LR data rate if the connected device does not support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the {IDF_TARGET_NAME} may transmit data in LR rate. Otherwise, {IDF_TARGET_NAME} will transmit all data in traditional Wi-Fi data rate.
The data transmission in LR rate has no impacts on the traditional Wi-Fi device because:
The following table depicts the Wi-Fi mode negotiation:
- The CCA and backoff process in LR mode are consistent with 802.11 specification.
- The traditional Wi-Fi device can detect the LR signal via CCA and do backoff.
+-------+-----+----+---+-------+------+-----+----+
|AP\STA | BGN | BG | B | BGNLR | BGLR | BLR | LR |
+=======+=====+====+===+=======+======+=====+====+
| BGN | BGN | BG | B | BGN | BG | B | - |
+-------+-----+----+---+-------+------+-----+----+
| BG | BG | BG | B | BG | BG | B | - |
+-------+-----+----+---+-------+------+-----+----+
| B | B | B | B | B | B | B | - |
+-------+-----+----+---+-------+------+-----+----+
| BGNLR | - | - | - | BGNLR | BGLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| BGLR | - | - | - | BGLR | BGLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| BLR | - | - | - | BLR | BLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| LR | - | - | - | LR | LR | LR | LR |
+-------+-----+----+---+-------+------+-----+----+
In other words, the transmission impact in LR mode is similar to that in 802.11b mode.
In the above table, the row is the Wi-Fi mode of AP and the column is the Wi-Fi mode of station. The "-" indicates Wi-Fi mode of the AP and station are not compatible.
LR Transmission Distance
*************************
According to the table, the following conclusions can be drawn:
The reception sensitivity gain of LR is about 4 dB larger than that of the traditional 802.11b mode. Theoretically, the transmission distance is about 2 to 2.5 times the distance of 11B.
- For LR-enabled AP of {IDF_TARGET_NAME}, it is incompatible with traditional 802.11 mode, because the beacon is sent in LR mode.
- For LR-enabled station of {IDF_TARGET_NAME} whose mode is NOT LR-only mode, it is compatible with traditional 802.11 mode.
- If both station and AP are {IDF_TARGET_NAME} devices and both of them have enabled LR mode, the negotiated mode supports LR.
LR Throughput
*************************
If the negotiated Wi-Fi mode supports both traditional 802.11 mode and LR mode, it is the Wi-Fi driver's responsibility to automatically select the best data rate in different Wi-Fi modes and the application can ignore it.
The LR rate has very limited throughput, because the raw PHY data rate LR is 1/2 Mbps and 1/4 Mbps.
LR Impacts to Traditional Wi-Fi Device
***************************************
When to Use LR
*************************
The data transmission in LR rate has no impacts on the traditional Wi-Fi device because:
The general conditions for using LR are:
- The CCA and backoff process in LR mode are consistent with 802.11 specification.
- The traditional Wi-Fi device can detect the LR signal via CCA and do backoff.
In other words, the transmission impact in LR mode is similar to that in 802.11b mode.
LR Transmission Distance
*************************
The reception sensitivity gain of LR is about 4 dB larger than that of the traditional 802.11b mode. Theoretically, the transmission distance is about 2 to 2.5 times the distance of 11B.
LR Throughput
*************************
The LR rate has very limited throughput, because the raw PHY data rate LR is 1/2 Mbps and 1/4 Mbps.
When to Use LR
*************************
The general conditions for using LR are:
- Both the AP and station are Espressif devices.
- Long distance Wi-Fi connection and data transmission is required.
- Data throughput requirements are very small, such as remote device control.
- Both the AP and station are Espressif devices.
- Long distance Wi-Fi connection and data transmission is required.
- Data throughput requirements are very small, such as remote device control.
Wi-Fi Country Code
+++++++++++++++++++++++++
@ -1756,82 +1829,90 @@ Generally, following steps can be taken to configure the multiple antennas:
.enabled_ant1 = 3
};
Wi-Fi Channel State Information
------------------------------------
.. only:: SOC_WIFI_CSI_SUPPORT
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.
Wi-Fi Channel State Information
------------------------------------
+-------------+--------------------+-----------------------------------------+--------------------------------------------------------+----------------------------------------------------------+
| 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 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 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, 20MHz | -28 to +28 | -21, -7, +7, +21 | 56 total, 52 usable |
+----------------+-------------------+------------------------------+-------------------------+
| 802.11n, 40MHz | -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, 20MHz | -28 to +28 | -21, -7, +7, +21 | 56 total, 52 usable |
+----------------+-------------------+------------------------------+-------------------------+
| 802.11n, 40MHz | -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.
Wi-Fi Channel State Information Configure
-------------------------------------------
- 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).
To use Wi-Fi CSI, the following steps need to be done.
Wi-Fi Channel State Information Configure
-------------------------------------------
- Select Wi-Fi CSI in menuconfig. Go to ``Menuconfig`` > ``Components config`` > ``Wi-Fi`` > ``Wi-Fi CSI (Channel State Information)``.
- Set CSI receiving callback function by calling API :cpp:func:`esp_wifi_set_csi_rx_cb()`.
- Configure CSI by calling API :cpp:func:`esp_wifi_set_csi_config()`.
- Enable CSI by calling API :cpp:func:`esp_wifi_set_csi()`.
To use Wi-Fi CSI, the following steps need to be done.
The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy operations in the callback function. Instead, post necessary data to a queue and handle it from a lower priority task. Because station does not receive any packet when it is disconnected and only receives packets from AP when it is connected, it is suggested to enable sniffer mode to receive more CSI data by calling :cpp:func:`esp_wifi_set_promiscuous()`.
- Select Wi-Fi CSI in menuconfig. Go to ``Menuconfig`` > ``Components config`` > ``Wi-Fi`` > ``Wi-Fi CSI (Channel State Information)``.
- Set CSI receiving callback function by calling API :cpp:func:`esp_wifi_set_csi_rx_cb()`.
- Configure CSI by calling API :cpp:func:`esp_wifi_set_csi_config()`.
- Enable CSI by calling API :cpp:func:`esp_wifi_set_csi()`.
The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy operations in the callback function. Instead, post necessary data to a queue and handle it from a lower priority task. Because station does not receive any packet when it is disconnected and only receives packets from AP when it is connected, it is suggested to enable sniffer mode to receive more CSI data by calling :cpp:func:`esp_wifi_set_promiscuous()`.
Wi-Fi HT20/40
-------------------------
{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.
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
In station mode, the actual bandwidth is firstly negotiated during the Wi-Fi connection. It is HT40 only if both the station and the connected AP support HT40, otherwise it is HT20. If the bandwidth of connected AP is changes, the actual bandwidth is negotiated again without Wi-Fi disconnecting.
{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.
Similarly, in AP mode, the actual bandwidth is negotiated between AP and the stations that connect to the AP. It is HT40 if the AP and one of the stations support HT40, otherwise it is HT20.
In station mode, the actual bandwidth is firstly negotiated during the Wi-Fi connection. It is HT40 only if both the station and the connected AP support HT40, otherwise it is HT20. If the bandwidth of connected AP is changes, the actual bandwidth is negotiated again without Wi-Fi disconnecting.
In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in {IDF_TARGET_NAME}. For example, the configured bandwidth of AP is HT40, the configured primary channel is 6, and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically.
Similarly, in AP mode, the actual bandwidth is negotiated between AP and the stations that connect to the AP. It is HT40 if the AP and one of the stations support HT40, otherwise it is HT20.
Theoretically, the HT40 can gain better throughput because the maximum raw physicial (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.
In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in {IDF_TARGET_NAME}. For example, the configured bandwidth of AP is HT40, the configured primary channel is 6, and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically.
Theoretically, the HT40 can gain better throughput because the maximum raw physicial (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:: esp32c2
{IDF_TARGET_NAME} supports Wi-Fi bandwidth HT20 and does not support Wi-Fi bandwidth HT40 or HT20/40 coexist.
Wi-Fi QoS
-------------------------

7
docs/en/api-reference/network/index.rst
Wyświetl plik

@ -10,14 +10,17 @@ Wi-Fi
:maxdepth: 1
esp_now
esp-wifi-mesh
:SOC_WIFI_MESH_SUPPORT: esp-wifi-mesh
esp_smartconfig
esp_wifi
esp_dpp
Code examples for the Wi-Fi API are provided in the :example:`wifi` directory of ESP-IDF examples.
Code examples for ESP-WIFI-MESH are provided in the :example:`mesh` directory of ESP-IDF examples.
.. only:: SOC_WIFI_MESH_SUPPORT
Code examples for ESP-WIFI-MESH are provided in the :example:`mesh` directory of ESP-IDF examples.
Ethernet

7
docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst
Wyświetl plik

@ -19,9 +19,12 @@ ESP-BLE-MESH 基于 Zephyr 蓝牙 Mesh 协议栈的顶端，其实现支持设
ESP-BLE-MESH 的实现和认证基于最新的 `Mesh Profile v1.0.1 <https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=457092>`_ 。有关 ESP-BLE-MESH 认证的细节，请参考 `此处 <https://launchstudio.bluetooth.com/ListingDetails/94304>`_ 。
.. note::
.. only:: SOC_WIFI_MESH_SUPPORT
.. note::
如果您在寻找 ESP32 基于 Wi-Fi 的 mesh 方案，请查阅乐鑫的另一款产品 ESP-WIFI-MESH。更多相关信息及文档，请参见 :doc:`ESP-WIFI-MESH <../../api-reference/network/esp-wifi-mesh>`。
如果您在寻找 ESP32 基于 Wi-Fi 的 mesh 方案，请查阅乐鑫的另一款产品 ESP-WIFI-MESH。更多相关信息及文档，请参见 :doc:`ESP-WIFI-MESH <../../api-reference/network/esp-wifi-mesh>`。
.. _getting-started-with-ble-mesh:

2
docs/zh_CN/api-guides/index.rst
Wyświetl plik

@ -16,7 +16,7 @@ API 指南
error-handling
:SOC_BT_SUPPORTED: esp-ble-mesh/ble-mesh-index
freertos-smp
esp-wifi-mesh
:SOC_WIFI_MESH_SUPPORT: esp-wifi-mesh
event-handling
fatal-errors
../security/flash-encryption

392
docs/zh_CN/api-guides/wifi.rst
Wyświetl plik

@ -5,18 +5,34 @@
{IDF_TARGET_NAME} Wi-Fi 功能列表
------------------------------------
- 支持 4 个虚拟接口，即STA、AP、Sniffer 和 reserved。
- 支持仅 station 模式、仅 AP 模式、station/AP 共存模式
- 支持使用 IEEE 802.11b、IEEE 802.11g、IEEE 802.11n 和 API 配置协议模式
- 支持 WPA/WPA2/WPA3/WPA2-企业版和 WPS
- 支持 AMPDU、HT40、QoS 以及其它主要功能
- 支持 Modem-sleep
- 支持乐鑫专属协议，可实现 **1 km** 数据通信量
- 空中数据传输最高可达 20 MBit/s TCP 吞吐量和 30 MBit/s UDP 吞吐量
- 支持 Sniffer
- 支持快速扫描和全信道扫描
- 支持多个天线
- 支持获取信道状态信息
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
- 支持 4 个虚拟接口，即STA、AP、Sniffer 和 reserved。
- 支持仅 station 模式、仅 AP 模式、station/AP 共存模式
- 支持使用 IEEE 802.11b、IEEE 802.11g、IEEE 802.11n 和 API 配置协议模式
- 支持 WPA/WPA2/WPA3/WPA2-企业版/WPA3-企业版/WAPI/WPS 和 DPP
- 支持 AMSDU、AMPDU、HT40、QoS 以及其它主要功能
- 支持 Modem-sleep
- 支持乐鑫专属协议，可实现 **1 km** 数据通信量
- 空中数据传输最高可达 20 MBit/s TCP 吞吐量和 30 MBit/s UDP 吞吐量
- 支持 Sniffer
- 支持快速扫描和全信道扫描
- 支持多个天线
- 支持获取信道状态信息
.. only:: esp32c2
- 支持 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
- 支持 AMSDU、AMPDU、QoS 以及其它主要功能
- 支持 Modem-sleep
- 空中数据传输最高可达 20 MBit/s TCP 吞吐量和 30 MBit/s UDP 吞吐量
- 支持 Sniffer
- 支持快速扫描和全信道扫描
- 支持多个天线
如何编写 Wi-Fi 应用程序
----------------------------------
@ -1099,28 +1115,57 @@ AP 基本配置
API esp_wifi_set_config() 可用于配置 AP。下表详细介绍了各个字段。
.. list-table::
:header-rows: 1
:widths: 15 55
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
.. list-table::
:header-rows: 1
:widths: 15 55
* - 字段
- 描述
* - ssid
- 指 AP 的 SSID。如果 ssid[0] 和 ssid[1] 均为 0xFF，AP 默认 SSID 为 ESP_aabbcc，”aabbcc” 是 AP MAC 的最后三个字节。
* - password
- AP 的密码。如果身份验证模式为 WIFI_AUTH_OPEN，此字段将被忽略。
* - ssid_len
- SSID 的长度。如果 ssid_len 为 0，则检查 SSID 直至出现终止字符。如果 ssid_len 大于 32，请更改为 32，或者根据 ssid_len 设置 SSID 长度。
* - channel
- AP 的信道。如果信道超出范围，Wi-Fi 驱动程序将默认该信道为信道 1。所以，请确保信道在要求的范围内。有关详细信息，请参阅 `Wi-Fi 国家/地区代码`_。
* - authmode
- ESP AP 的身份验证模式。目前，ESP Wi-Fi 不支持 AUTH_WEP。如果 authmode 是一个无效值，AP 默认该值为 WIFI_AUTH_OPEN。
* - ssid_hidden
- 如果 ssid_hidden 为 1，AP 不广播 SSID。若为其他值，则广播。
* - max_connection
- 目前，ESP Wi-Fi 支持 10 个 Wi-Fi 连接。如果 max_connection 大于 10，AP 默认该值为 10。
* - beacon_interval
- beacon 间隔。值为 100 ~ 60000 ms，默认值为 100 ms。如果该值不在上述范围，AP 默认取 100 ms。
.. only:: esp32c2
.. list-table::
:header-rows: 1
:widths: 15 55
* - 字段
- 描述
* - ssid
- 指 AP 的 SSID。如果 ssid[0] 和 ssid[1] 均为 0xFF，AP 默认 SSID 为 ESP_aabbcc，”aabbcc” 是 AP MAC 的最后三个字节。
* - password
- AP 的密码。如果身份验证模式为 WIFI_AUTH_OPEN，此字段将被忽略。
* - ssid_len
- SSID 的长度。如果 ssid_len 为 0，则检查 SSID 直至出现终止字符。如果 ssid_len 大于 32，请更改为 32，或者根据 ssid_len 设置 SSID 长度。
* - channel
- AP 的信道。如果信道超出范围，Wi-Fi 驱动程序将默认该信道为信道 1。所以，请确保信道在要求的范围内。有关详细信息，请参阅 `Wi-Fi 国家/地区代码`_。
* - authmode
- ESP AP 的身份验证模式。目前，ESP Wi-Fi 不支持 AUTH_WEP。如果 authmode 是一个无效值，AP 默认该值为 WIFI_AUTH_OPEN。
* - ssid_hidden
- 如果 ssid_hidden 为 1，AP 不广播 SSID。若为其他值，则广播。
* - max_connection
- 目前，ESP Wi-Fi 支持 4 个 Wi-Fi 连接。如果 max_connection 大于 4，AP 默认该值为 4。
* - beacon_interval
- beacon 间隔。值为 100 ~ 60000 ms，默认值为 100 ms。如果该值不在上述范围，AP 默认取 100 ms。
* - 字段
- 描述
* - ssid
- 指 AP 的 SSID。如果 ssid[0] 和 ssid[1] 均为 0xFF，AP 默认 SSID 为 ESP_aabbcc，”aabbcc” 是 AP MAC 的最后三个字节。
* - password
- AP 的密码。如果身份验证模式为 WIFI_AUTH_OPEN，此字段将被忽略。
* - ssid_len
- SSID 的长度。如果 ssid_len 为 0，则检查 SSID 直至出现终止字符。如果 ssid_len 大于 32，请更改为 32，或者根据 ssid_len 设置 SSID 长度。
* - channel
- AP 的信道。如果信道超出范围，Wi-Fi 驱动程序将默认该信道为信道 1。所以，请确保信道在要求的范围内。有关详细信息，请参阅 `Wi-Fi 国家/地区代码`_。
* - authmode
- ESP AP 的身份验证模式。目前，ESP Wi-Fi 不支持 AUTH_WEP。如果 authmode 是一个无效值，AP 默认该值为 WIFI_AUTH_OPEN。
* - ssid_hidden
- 如果 ssid_hidden 为 1，AP 不广播 SSID。若为其他值，则广播。
* - max_connection
- 目前，ESP Wi-Fi 支持 10 个 Wi-Fi 连接。如果 max_connection 大于 10，AP 默认该值为 10。
* - beacon_interval
- beacon 间隔。值为 100 ~ 60000 ms，默认值为 100 ms。如果该值不在上述范围，AP 默认取 100 ms。
Wi-Fi 协议模式
@ -1128,98 +1173,125 @@ Wi-Fi 协议模式
目前，IDF 支持以下协议模式：
.. list-table::
:header-rows: 1
:widths: 15 55
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
* - 协议模式
- 描述
* - 802.11b
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B)，将 station/AP 设置为仅 802.11b 模式。
* - 802.11bg
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G)，将 station/AP 设置为 802.11bg 模式。
* - 802.11g
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11g 模式。
* - 802.11bgn
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)，将 station/AP 设置为 802.11bgn 模式。
* - 802.11gn
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11gn 模式。
* - 802.11 BGNLR
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR)，将 station/AP 设置为 802.11bgn 和 LR 模式。
* - 802.11 LR
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR)，将 station/AP 设置为 LR 模式。
.. list-table::
:header-rows: 1
:widths: 15 55
**此模式是乐鑫的专利模式，可以达到 1 公里视线范围。请确保 station 和 AP 同时连接至 ESP 设备。**
* - 协议模式
- 描述
* - 802.11b
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B)，将 station/AP 设置为仅 802.11b 模式。
* - 802.11bg
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G)，将 station/AP 设置为 802.11bg 模式。
* - 802.11g
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11g 模式。
* - 802.11bgn
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)，将 station/AP 设置为 802.11bgn 模式。
* - 802.11gn
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11gn 模式。
* - 802.11 BGNLR
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR)，将 station/AP 设置为 802.11bgn 和 LR 模式。
* - 802.11 LR
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR)，将 station/AP 设置为 LR 模式。
**此模式是乐鑫的专利模式，可以达到 1 公里视线范围。请确保 station 和 AP 同时连接至 ESP 设备。**
长距离 (LR)
+++++++++++++++++++++++++
长距离 (LR) 模式是乐鑫的一项专利 Wi-Fi 模式，可达到 1 公里视线范围。与传统 802.11b 模式相比，接收灵敏度更高，抗干扰能力更强，传输距离更长。
.. only:: esp32c2
LR 兼容性
*************************
.. list-table::
:header-rows: 1
:widths: 15 55
由于 LR 是乐鑫的独有 Wi-Fi 模式，只有 {IDF_TARGET_NAME} 设备才能传输和接收 LR 数据。也就是说，如果连接的设备不支持 LR，{IDF_TARGET_NAME} 设备则不会以 LR 数据速率传输数据。可通过配置适当的 Wi-Fi 模式使您的应用程序实现这一功能。如果协商的模式支持 LR，{IDF_TARGET_NAME} 可能会以 LR 速率传输数据，否则，{IDF_TARGET_NAME} 将以传统 Wi-Fi 数据速率传输所有数据。
* - 协议模式
- 描述
* - 802.11b
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B)，将 station/AP 设置为仅 802.11b 模式。
* - 802.11bg
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G)，将 station/AP 设置为 802.11bg 模式。
* - 802.11g
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11g 模式。
* - 802.11bgn
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)，将 station/AP 设置为 802.11bgn 模式。
* - 802.11gn
- 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11gn 模式。
下表是 Wi-Fi 模式协商：
+-------+-----+----+---+-------+------+-----+----+
| APSTA | BGN | BG | B | BGNLR | BGLR | BLR | LR |
+=======+=====+====+===+=======+======+=====+====+
| BGN | BGN | BG | B | BGN | BG | B | - |
+-------+-----+----+---+-------+------+-----+----+
| BG | BG | BG | B | BG | BG | B | - |
+-------+-----+----+---+-------+------+-----+----+
| B | B | B | B | B | B | B | - |
+-------+-----+----+---+-------+------+-----+----+
| BGNLR | - | - | - | BGNLR | BGLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| BGLR | - | - | - | BGLR | BGLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| BLR | - | - | - | BLR | BLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| LR | - | - | - | LR | LR | LR | LR |
+-------+-----+----+---+-------+------+-----+----+
上表中，行是 AP 的 Wi-Fi 模式，列是 station 的 Wi-Fi 模式。"-" 表示 AP 和 station 的 Wi-Fi 模式不兼容。
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
根据上表，得出以下结论：
长距离 (LR)
+++++++++++++++++++++++++
- 对于已使能 LR 的 {IDF_TARGET_NAME} AP，由于以 LR 模式发送 beacon，因此与传统的 802.11 模式不兼容。
- 对于已使能 LR 且并非仅 LR 模式的 {IDF_TARGET_NAME} station，与传统 802.11 模式兼容。
- 如果 station 和 AP 都是 {IDF_TARGET_NAME} 设备，并且两者都使能 LR 模式，则协商的模式支持 LR。
长距离 (LR) 模式是乐鑫的一项专利 Wi-Fi 模式，可达到 1 公里视线范围。与传统 802.11b 模式相比，接收灵敏度更高，抗干扰能力更强，传输距离更长。
如果协商的 Wi-Fi 模式同时支持传统的 802.11 模式和 LR 模式，则 Wi-Fi 驱动程序会在不同的 Wi-Fi 模式下自动选择最佳数据速率，应用程序无需任何操作。
LR 兼容性
*************************
LR 对传统 Wi-Fi 设备的影响
***************************************
由于 LR 是乐鑫的独有 Wi-Fi 模式，只有 {IDF_TARGET_NAME} 设备才能传输和接收 LR 数据。也就是说，如果连接的设备不支持 LR，{IDF_TARGET_NAME} 设备则不会以 LR 数据速率传输数据。可通过配置适当的 Wi-Fi 模式使您的应用程序实现这一功能。如果协商的模式支持 LR，{IDF_TARGET_NAME} 可能会以 LR 速率传输数据，否则，{IDF_TARGET_NAME} 将以传统 Wi-Fi 数据速率传输所有数据。
以 LR 速率进行的数据传输不会影响传统 Wi-Fi 设备，因为：
下表是 Wi-Fi 模式协商：
- LR 模式下的 CCA 和回退过程符合 802.11 协议。
- 传统的 Wi-Fi 设备可以通过 CCA 检测 LR 信号并进行回退。
+-------+-----+----+---+-------+------+-----+----+
| APSTA | BGN | BG | B | BGNLR | BGLR | BLR | LR |
+=======+=====+====+===+=======+======+=====+====+
| BGN | BGN | BG | B | BGN | BG | B | - |
+-------+-----+----+---+-------+------+-----+----+
| BG | BG | BG | B | BG | BG | B | - |
+-------+-----+----+---+-------+------+-----+----+
| B | B | B | B | B | B | B | - |
+-------+-----+----+---+-------+------+-----+----+
| BGNLR | - | - | - | BGNLR | BGLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| BGLR | - | - | - | BGLR | BGLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| BLR | - | - | - | BLR | BLR | BLR | LR |
+-------+-----+----+---+-------+------+-----+----+
| LR | - | - | - | LR | LR | LR | LR |
+-------+-----+----+---+-------+------+-----+----+
也就是说，LR 模式下传输效果与 802.11b 模式相似。
上表中，行是 AP 的 Wi-Fi 模式，列是 station 的 Wi-Fi 模式。"-" 表示 AP 和 station 的 Wi-Fi 模式不兼容。
LR 传输距离
*************************
根据上表，得出以下结论：
LR 的接收灵敏度比传统的 802.11b 模式高 4 dB，理论上，传输距离约为 802.11b 的 2 至 2.5 倍。
- 对于已使能 LR 的 {IDF_TARGET_NAME} AP，由于以 LR 模式发送 beacon，因此与传统的 802.11 模式不兼容。
- 对于已使能 LR 且并非仅 LR 模式的 {IDF_TARGET_NAME} station，与传统 802.11 模式兼容。
- 如果 station 和 AP 都是 {IDF_TARGET_NAME} 设备，并且两者都使能 LR 模式，则协商的模式支持 LR。
LR 吞吐量
*************************
如果协商的 Wi-Fi 模式同时支持传统的 802.11 模式和 LR 模式，则 Wi-Fi 驱动程序会在不同的 Wi-Fi 模式下自动选择最佳数据速率，应用程序无需任何操作。
因为原始 PHY 数据传输速率为 1/2 Mbps 和 1/4 Mbps，LR 的吞吐量有限。
LR 对传统 Wi-Fi 设备的影响
***************************************
何时使用 LR
*************************
以 LR 速率进行的数据传输不会影响传统 Wi-Fi 设备，因为：
通常使用 LR 的场景包括：
- LR 模式下的 CCA 和回退过程符合 802.11 协议。
- 传统的 Wi-Fi 设备可以通过 CCA 检测 LR 信号并进行回退。
也就是说，LR 模式下传输效果与 802.11b 模式相似。
LR 传输距离
*************************
LR 的接收灵敏度比传统的 802.11b 模式高 4 dB，理论上，传输距离约为 802.11b 的 2 至 2.5 倍。
LR 吞吐量
*************************
因为原始 PHY 数据传输速率为 1/2 Mbps 和 1/4 Mbps，LR 的吞吐量有限。
何时使用 LR
*************************
通常使用 LR 的场景包括：
- AP 和 station 都是乐鑫设备。
- 需要长距离 Wi-Fi 连接和数据传输。
- 数据吞吐量要求非常小，例如远程设备控制等。
- AP 和 station 都是乐鑫设备。
- 需要长距离 Wi-Fi 连接和数据传输。
- 数据吞吐量要求非常小，例如远程设备控制等。
Wi-Fi 国家/地区代码
+++++++++++++++++++++++++
@ -1756,82 +1828,90 @@ Wi-Fi 多根天线配置
.enabled_ant1 = 3
};
Wi-Fi 信道状态信息
------------------------------------
.. only:: SOC_WIFI_CSI_SUPPORT
信道状态信息 (CSI) 是指 Wi-Fi 连接的信道信息。{IDF_TARGET_NAME} 中，CSI由子载波的信道频率响应组成，CSI从发送端接收数据包时开始估计。每个子载波信道频率响由两个字节的有符号字符记录，第一个字节是虚部，第二个字节是实部。根据接收数据包的类型，信道频率响应最多有三个字段。分别是 LLTF、HT-LTF 和 STBC-HT-LTF。对于在不同状态的信道上接收到的不同类型的数据包，CSI 的子载波索引和总字节数如下表所示。
Wi-Fi 信道状态信息
------------------------------------
+------------+-------------+-----------------------------------------+-----------------------------------------------------+--------------------------------------------------------+
| 信道 | 辅助信道 | | 下 | 上 |
+------------+-------------+-------------+---------------------------+---------+-------------------------------------------+---------+----------------------------------------------+
| 数据包信息 | 信号模式 | 非 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 可能都不存在（见上文）。
- 如果 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 可能都不存在（见上文）。
- 如果 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, 20MHz | -28 to +28 | -21, -7, +7, +21 | 56 total, 52 usable |
+----------------+-------------------+------------------------------+------------------------------+
| 802.11n, 40MHz | -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, 20MHz | -28 to +28 | -21, -7, +7, +21 | 56 total, 52 usable |
+----------------+-------------------+------------------------------+------------------------------+
| 802.11n, 40MHz | -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。
Wi-Fi 信道状态信息配置
-------------------------------------------
- 如果调用 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，结果对齐为四个字节，最后两个字节无效）。
要使用 Wi-Fi CSI，需要执行以下步骤。
Wi-Fi 信道状态信息配置
-------------------------------------------
- 在菜单配置中选择 Wi-Fi CSI。方法是“菜单配置 - > 组件配置 -- > Wi-Fi -- > Wi-Fi CSI（信道状态信息）”。
- 调用 API :cpp:func:`esp_wifi_set_csi_rx_cb()` 设置 CSI 接收回调函数。
- 调用 API :cpp:func:`esp_wifi_set_csi_config()` 配置 CSI。
- 调用 API :cpp:func:`esp_wifi_set_csi()` 使能 CSI。
要使用 Wi-Fi CSI，需要执行以下步骤。
CSI 接收回调函数从 Wi-Fi 任务中运行。因此，不要在回调函数中进行冗长的操作。可以将需要的数据发布到队列中，并从一个较低优先级的任务中处理。由于 station 在断开连接时不会收到任何数据包，只有在连接时才会收到来自 AP 的数据包，因此建议通过调用函数 :cpp:func:`esp_wifi_set_promiscuous()` 使能 Sniffer 模式接收更多 CSI 数据。
- 在菜单配置中选择 Wi-Fi CSI。方法是“菜单配置 - > 组件配置 -- > Wi-Fi -- > Wi-Fi CSI（信道状态信息）”。
- 调用 API :cpp:func:`esp_wifi_set_csi_rx_cb()` 设置 CSI 接收回调函数。
- 调用 API :cpp:func:`esp_wifi_set_csi_config()` 配置 CSI。
- 调用 API :cpp:func:`esp_wifi_set_csi()` 使能 CSI。
CSI 接收回调函数从 Wi-Fi 任务中运行。因此，不要在回调函数中进行冗长的操作。可以将需要的数据发布到队列中，并从一个较低优先级的任务中处理。由于 station 在断开连接时不会收到任何数据包，只有在连接时才会收到来自 AP 的数据包，因此建议通过调用函数 :cpp:func:`esp_wifi_set_promiscuous()` 使能 Sniffer 模式接收更多 CSI 数据。
Wi-Fi HT20/40
-------------------------
{IDF_TARGET_NAME} 支持 Wi-Fi 带宽 HT20 或 HT40，不支持 HT20/40 共存，调用函数 :cpp:func:`esp_wifi_set_bandwidth()` 可改变 station/AP 的默认带宽。{IDF_TARGET_NAME} station 和 AP 的默认带宽为 HT40。
.. only:: esp32 or esp32s2 or esp32c3 or esp32s3
station 模式下，实际带宽首先在 Wi-Fi 连接时协商。只有当 station 和所连 AP 都支持 HT40 时，带宽才为 HT40，否则为 HT20。如果所连的 AP 的带宽发生变化，则在不断开 Wi-Fi 连接的情况下再次协商实际带宽。
{IDF_TARGET_NAME} 支持 Wi-Fi 带宽 HT20 或 HT40，不支持 HT20/40 共存，调用函数 :cpp:func:`esp_wifi_set_bandwidth()` 可改变 station/AP 的默认带宽。{IDF_TARGET_NAME} station 和 AP 的默认带宽为 HT40。
同样，在 AP 模式下，在 AP 与所连 station 协商实际带宽。如果 AP 和其中一个 station 支持 HT40， 则为 HT40， 否则为 HT20。
station 模式下，实际带宽首先在 Wi-Fi 连接时协商。只有当 station 和所连 AP 都支持 HT40 时，带宽才为 HT40，否则为 HT20。如果所连的 AP 的带宽发生变化，则在不断开 Wi-Fi 连接的情况下再次协商实际带宽。
在 station/AP 共存模式下，station 和 AP 都可独立配置为 HT20/40。如果 station 和 AP 都协商为 HT40，由于 {IDF_TARGET_NAME} 中，station 的优先级总高于 AP，HT40 信道是 station 的信道。例如，AP 的配置带宽为 HT40，配置的主信道为 6，配置的辅助信道为 10。如果，station 所连路由器的主信道为 6、辅助信道为 2，AP 的实际信道将自动更改为主 6 和辅 2。
同样，在 AP 模式下，在 AP 与所连 station 协商实际带宽。如果 AP 和其中一个 station 支持 HT40， 则为 HT40， 否则为 HT20。
理论上，HT40 可以获得更大的吞吐量，因为 HT40 的最大原始 PHY 数据速率为 150 Mbps，而 HT20 为 72 Mbps。但是，如果设备在某些特殊环境中使用，例如，{IDF_TARGET_NAME} 周围其他 Wi-Fi 设备过多，HT40 的性能可能会降低。因此，如果应用程序需要支持相同或类似的情况，建议始终将带宽配置为 HT20。
在 station/AP 共存模式下，station 和 AP 都可独立配置为 HT20/40。如果 station 和 AP 都协商为 HT40，由于 {IDF_TARGET_NAME} 中，station 的优先级总高于 AP，HT40 信道是 station 的信道。例如，AP 的配置带宽为 HT40，配置的主信道为 6，配置的辅助信道为 10。如果，station 所连路由器的主信道为 6、辅助信道为 2，AP 的实际信道将自动更改为主 6 和辅 2。
理论上，HT40 可以获得更大的吞吐量，因为 HT40 的最大原始 PHY 数据速率为 150 Mbps，而 HT20 为 72 Mbps。但是，如果设备在某些特殊环境中使用，例如，{IDF_TARGET_NAME} 周围其他 Wi-Fi 设备过多，HT40 的性能可能会降低。因此，如果应用程序需要支持相同或类似的情况，建议始终将带宽配置为 HT20。
.. only:: esp32c2
{IDF_TARGET_NAME} 仅支持 Wi-Fi 带宽 HT20，不支持 Wi-Fi 带宽 HT40 或 HT20/40 共存。
Wi-Fi QoS
-------------------------

7
docs/zh_CN/api-reference/network/index.rst
Wyświetl plik

@ -10,14 +10,17 @@ Wi-Fi
:maxdepth: 1
esp_now
esp-wifi-mesh
:SOC_WIFI_MESH_SUPPORT: esp-wifi-mesh
esp_smartconfig
esp_wifi
esp_dpp
本部分的 Wi-Fi API 示例代码存放在 ESP-IDF 示例项目的 :example:`wifi` 目录下。
ESP-WIFI-MESH 的示例代码存放在 ESP-IDF 示例项目的 :example:`mesh` 目录下。
.. only:: SOC_WIFI_MESH_SUPPORT
ESP-WIFI-MESH 的示例代码存放在 ESP-IDF 示例项目的 :example:`mesh` 目录下。
以太网