diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index 21136cf56b..386beb0481 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -1,12 +1,12 @@ Wi-Fi Driver ============= -:link_to_translation:`zh_CN:[中文]` +:link_to_translation:`zh_CN:[中文]` {IDF_TARGET_NAME} Wi-Fi Feature List ------------------------------------ -- 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 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 @@ -22,7 +22,9 @@ How To Write a Wi-Fi Application Preparation +++++++++++ -Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend you to select an :example:`example `. +Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. + +This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend you to select an :example:`example `. Setting Wi-Fi Compile-time Options ++++++++++++++++++++++++++++++++++++ @@ -30,15 +32,15 @@ Refer to `Wi-Fi Menuconfig`_. Init Wi-Fi +++++++++++ -Refer to `{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_, `{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_. +Refer to `{IDF_TARGET_NAME} Wi-Fi station General Scenario`_, `{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_. Start/Connect Wi-Fi ++++++++++++++++++++ -Refer to `{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_, `{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_. +Refer to `{IDF_TARGET_NAME} Wi-Fi station General Scenario`_, `{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_. Event-Handling ++++++++++++++ -Generally, it is easy to write code in "sunny-day" scenarios, such as `WIFI_EVENT_STA_START`_, `WIFI_EVENT_STA_CONNECTED`_ etc. The hard part is to write routines in "rainy-day" scenarios, such as `WIFI_EVENT_STA_DISCONNECTED`_ etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to `{IDF_TARGET_NAME} Wi-Fi Event Description`_, `{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_, `{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_. See also :doc:`an overview of event handling in ESP-IDF`. +Generally, it is easy to write code in "sunny-day" scenarios, such as `WIFI_EVENT_STA_START`_, `WIFI_EVENT_STA_CONNECTED`_ etc. The hard part is to write routines in "rainy-day" scenarios, such as `WIFI_EVENT_STA_DISCONNECTED`_ etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to `{IDF_TARGET_NAME} Wi-Fi Event Description`_, `{IDF_TARGET_NAME} Wi-Fi station General Scenario`_, `{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_. See also :doc:`an overview of event handling in ESP-IDF`. Write Error-Recovery Routines Correctly at All Times ++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -62,8 +64,7 @@ Whether the error is critical or not depends on the API and the application scen - for non-recoverable, yet non-critical, errors, in which case printing the error code is a good method for error handling. - for non-recoverable, critical errors, in which case "assert" may be a good method for error handling. For example, if :cpp:func:`esp_wifi_set_mode` returns ESP_ERR_WIFI_NOT_INIT, it means that the Wi-Fi driver is not initialized by :cpp:func:`esp_wifi_init` successfully. You can detect this kind of error very quickly in the application development phase. -In esp_err.h, ESP_ERROR_CHECK checks the return values. It is a rather commonplace error-handling code and can be used -as the default error-handling code in the application development phase. However, we strongly recommend that API users write their own error-handling code. +In esp_err.h, ESP_ERROR_CHECK checks the return values. It is a rather commonplace error-handling code and can be used as the default error-handling code in the application development phase. However, we strongly recommend that API users write their own error-handling code. {IDF_TARGET_NAME} Wi-Fi API Parameter Initialization ---------------------------------------------------- @@ -127,6 +128,7 @@ The Wi-Fi driver can be considered a black box that knows nothing about high-lay Wi-Fi event handling is based on the :doc:`esp_event library <../api-reference/system/esp_event>`. Events are sent by the Wi-Fi driver to the :ref:`default event loop `. Application may handle these events in callbacks registered using :cpp:func:`esp_event_handler_register`. Wi-Fi events are also handled by :doc:`esp_netif component <../api-reference/network/esp_netif>` to provide a set of default behaviors. For example, when Wi-Fi station connects to an AP, esp_netif will automatically start the DHCP client (by default). + {IDF_TARGET_NAME} Wi-Fi Event Description ----------------------------------------- @@ -152,11 +154,11 @@ Refer to `{IDF_TARGET_NAME} Wi-Fi Scan`_ for a more detailed description. WIFI_EVENT_STA_START ++++++++++++++++++++++++++++++++++++ -If :cpp:func:`esp_wifi_start()` returns ESP_OK and the current Wi-Fi mode is Station or AP+Station, then this event will arise. Upon receiving this event, the event task will initialize the LwIP network interface (netif). Generally, the application event callback needs to call :cpp:func:`esp_wifi_connect()` to connect to the configured AP. +If :cpp:func:`esp_wifi_start()` returns ESP_OK and the current Wi-Fi mode is station or station/AP, then this event will arise. Upon receiving this event, the event task will initialize the LwIP network interface (netif). Generally, the application event callback needs to call :cpp:func:`esp_wifi_connect()` to connect to the configured AP. WIFI_EVENT_STA_STOP ++++++++++++++++++++++++++++++++++++ -If :cpp:func:`esp_wifi_stop()` returns ESP_OK and the current Wi-Fi mode is Station or AP+Station, then this event will arise. Upon receiving this event, the event task will release the station's IP address, stop the DHCP client, remove TCP/UDP-related connections and clear the LwIP station netif, etc. The application event callback generally does not need to do anything. +If :cpp:func:`esp_wifi_stop()` returns ESP_OK and the current Wi-Fi mode is station or station/AP, then this event will arise. Upon receiving this event, the event task will release the station's IP address, stop the DHCP client, remove TCP/UDP-related connections and clear the LwIP station netif, etc. The application event callback generally does not need to do anything. WIFI_EVENT_STA_CONNECTED ++++++++++++++++++++++++++++++++++++ @@ -166,7 +168,7 @@ WIFI_EVENT_STA_DISCONNECTED ++++++++++++++++++++++++++++++++++++ This event can be generated in the following scenarios: - - When :cpp:func:`esp_wifi_disconnect()`, or :cpp:func:`esp_wifi_stop()`, or :cpp:func:`esp_wifi_deinit()` is called and the station is already connected to the AP. + - When :cpp:func:`esp_wifi_disconnect()`, or :cpp:func:`esp_wifi_stop()` is called and the station is already connected to the AP. - When :cpp:func:`esp_wifi_connect()` is called, but the Wi-Fi driver fails to set up a connection with the AP due to certain reasons, e.g. the scan fails to find the target AP, authentication times out, etc. If there are more than one AP with the same SSID, the disconnected event is raised after the station fails to connect all of the found APs. - When the Wi-Fi connection is disrupted because of specific reasons, e.g., the station continuously loses N beacons, the AP kicks off the station, the AP's authentication mode is changed, etc. @@ -242,7 +244,7 @@ When this event is enabled, it will be raised each time the AP receives a probe {IDF_TARGET_NAME} Wi-Fi Station General Scenario ------------------------------------------------ -Below is a "big scenario" which describes some small scenarios in Station mode: +Below is a "big scenario" which describes some small scenarios in station mode: .. seqdiag:: :caption: Sample Wi-Fi Event Scenarios in Station Mode @@ -314,7 +316,7 @@ Step 1.1 ~ 1.5 is a recommended sequence that initializes a Wi-Fi-/LwIP-based ap 2. Wi-Fi Configuration Phase +++++++++++++++++++++++++++++++ -Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is Station, so you may need to call :cpp:func:`esp_wifi_set_mode` (WIFI_MODE_STA) to configure the Wi-Fi mode as Station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to `{IDF_TARGET_NAME} Wi-Fi Configuration`_. +Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is station, so you may need to call :cpp:func:`esp_wifi_set_mode` (WIFI_MODE_STA) to configure the Wi-Fi mode as station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to `{IDF_TARGET_NAME} Wi-Fi Configuration`_. Generally, we configure the Wi-Fi driver before setting up the Wi-Fi connection, but this is **NOT** mandatory, which means that you can configure the Wi-Fi connection anytime, provided that the Wi-Fi driver is initialized successfully. However, if the configuration does not need to change after the Wi-Fi connection is set up, you should configure the Wi-Fi driver at this stage, because the configuration APIs (such as :cpp:func:`esp_wifi_set_protocol`) will cause the Wi-Fi to reconnect, which may not be desirable. @@ -414,45 +416,29 @@ Below is a "big scenario" which describes some small scenarios in AP mode: {IDF_TARGET_NAME} Wi-Fi Scan ---------------------------- -Currently, the :cpp:func:`esp_wifi_scan_start()` API is supported only in Station or Station+AP mode. +Currently, the :cpp:func:`esp_wifi_scan_start()` API is supported only in station or station/AP mode. Scan Type +++++++++++++++++++++++++ -+------------------+--------------------------------------------------------------+ -| Mode | Description | -+==================+==============================================================+ -| Active Scan | Scan by sending a probe request. | -| | The default scan is an active scan. | -| | | -+------------------+--------------------------------------------------------------+ -| Passive Scan | No probe request is sent out. Just switch to the specific | -| | channel and wait for a beacon. | -| | Application can enable it via the scan_type field of | -| | wifi_scan_config_t. | -| | | -+------------------+--------------------------------------------------------------+ -| Foreground Scan | This scan is applicable when there is no Wi-Fi connection | -| | in Station mode. Foreground or background scanning is | -| | controlled by the Wi-Fi driver and cannot be configured by | -| | the application. | -+------------------+--------------------------------------------------------------+ -| Background Scan | This scan is applicable when there is a Wi-Fi connection in | -| | Station mode or in Station+AP mode. | -| | Whether it is a foreground scan or background scan depends on| -| | the Wi-Fi driver and cannot be configured by the application.| -| | | -+------------------+--------------------------------------------------------------+ -| All-Channel Scan | It scans all of the channels. | -| | If the channel field of wifi_scan_config_t is set | -| | to 0, it is an all-channel scan. | -| | | -+------------------+--------------------------------------------------------------+ -| Specific Channel | It scans specific channels only. | -| Scan | If the channel field of wifi_scan_config_t set to | -| | 1, it is a specific-channel scan. | -| | | -+------------------+--------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 50 + + * - Mode + - Description + * - Active Scan + - Scan by sending a probe request. The default scan is an active scan. + * - Passive Scan + - No probe request is sent out. Just switch to the specific channel and wait for a beacon. Application can enable it via the scan_type field of wifi_scan_config_t. + * - Foreground Scan + - This scan is applicable when there is no Wi-Fi connection in station mode. Foreground or background scanning is controlled by the Wi-Fi driver and cannot be configured by the application. + * - Background Scan + - This scan is applicable when there is a Wi-Fi connection in station mode or in station/AP mode. Whether it is a foreground scan or background scan depends on the Wi-Fi driver and cannot be configured by the application. + * - All-Channel Scan + - It scans all of the channels. If the channel field of wifi_scan_config_t is set to 0, it is an all-channel scan. + * - Specific Channel Scan + - It scans specific channels only. If the channel field of wifi_scan_config_t set to 1-14, it is a specific-channel scan. The scan modes in above table can be combined arbitrarily, so we totally have 8 different scans: @@ -470,51 +456,36 @@ Scan Configuration The scan type and other per-scan attributes are configured by :cpp:func:`esp_wifi_scan_start`. The table below provides a detailed description of wifi_scan_config_t. -+------------------+--------------------------------------------------------------+ -| Field | Description | -+==================+==============================================================+ -| ssid | If the SSID is not NULL, it is only the AP with the same | -| | SSID that can be scanned. | -| | | -+------------------+--------------------------------------------------------------+ -| bssid | If the BSSID is not NULL, it is only the AP with the same | -| | BSSID that can be scanned. | -| | | -+------------------+--------------------------------------------------------------+ -| channel | If "channel" is 0, there will be an all-channel scan; | -| | otherwise, there will be a specific-channel scan. | -| | | -+------------------+--------------------------------------------------------------+ -| show_hidden | If "show_hidden" is 0, the scan ignores the AP with a hidden | -| | SSID; otherwise, the scan considers the hidden AP a normal | -| | one. | -+------------------+--------------------------------------------------------------+ -| scan_type | If "scan_type" is WIFI_SCAN_TYPE_ACTIVE, the scan is | -| | "active"; otherwise, it is a "passive" one. | -| | | -+------------------+--------------------------------------------------------------+ -| scan_time | This field is used to control how long the scan dwells on | -| | each channel. | -| | | -| | For passive scans, scan_time.passive designates the dwell | -| | time for each channel. | -| | | -| | For active scans, dwell times for each channel are listed | -| | in the table below. Here, min is short for scan | -| | time.active.min and max is short for scan_time.active.max. | -| | | -| | - min=0, max=0: scan dwells on each channel for 120 ms. | -| | - min>0, max=0: scan dwells on each channel for 120 ms. | -| | - min=0, max>0: scan dwells on each channel for ``max`` ms. | -| | - min>0, max>0: the minimum time the scan dwells on each | -| | channel is ``min`` ms. If no AP is found during this time | -| | frame, the scan switches to the next channel. Otherwise, | -| | the scan dwells on the channel for ``max`` ms. | -| | | -| | If you want to improve the performance of the | -| | the scan, you can try to modify these two parameters. | -| | | -+------------------+--------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 50 + + * - Field + - Description + * - ssid + - If the SSID is not NULL, it is only the AP with the same SSID that can be scanned. + * - bssid + - If the BSSID is not NULL, it is only the AP with the same BSSID that can be scanned. + * - channel + - If “channel” is 0, there will be an all-channel scan; otherwise, there will be a specific-channel scan. + * - show_hidden + - If “show_hidden” is 0, the scan ignores the AP with a hidden SSID; otherwise, the scan considers the hidden AP a normal one. + * - scan_type + - If “scan_type” is WIFI_SCAN_TYPE_ACTIVE, the scan is “active”; otherwise, it is a “passive” one. + * - scan_time + - This field is used to control how long the scan dwells on each channel. + + For passive scans, scan_time.passive designates the dwell time for each channel. + + For active scans, dwell times for each channel are listed in the table below. Here, min is short for scan time.active.min and max is short for scan_time.active.max. + + - min=0, max=0: scan dwells on each channel for 120 ms. + - min>0, max=0: scan dwells on each channel for 120 ms. + - min=0, max>0: scan dwells on each channel for ``max`` ms. + - min>0, max>0: the minimum time the scan dwells on each channel is ``min`` ms. If no AP is found during this time frame, the scan switches to the next channel. Otherwise, the scan dwells on the channel for ``max`` ms. + + If you want to improve the performance of the the scan, you can try to modify these two parameters. + There are also some global scan attributes which are configured by API :cpp:func:`esp_wifi_set_config`, refer to `Station Basic Configuration`_ @@ -551,7 +522,7 @@ Scenario: } -The scenario above describes an all-channel, foreground scan. The foreground scan can only occur in Station mode where the station does not connect to any AP. Whether it is a foreground or background scan is totally determined by the Wi-Fi driver, and cannot be configured by the application. +The scenario above describes an all-channel, foreground scan. The foreground scan can only occur in station mode where the station does not connect to any AP. Whether it is a foreground or background scan is totally determined by the Wi-Fi driver, and cannot be configured by the application. Detailed scenario description: @@ -645,7 +616,7 @@ Scenario: This scan is similar to `Scan All APs on All Channels (Foreground)`_. The differences are: - s1.1: In step 1.2, the target AP will be configured to SSID/BSSID. - - s2.1~s2.N: Each time the Wi-Fi driver scans an AP, it will check whether it is a target AP or not. If the scan is WIFI_FAST_SCAN scan and the target AP is found, then the scan-done event will arise and scanning will end; otherwise, the scan will continue. Please note that the first scanned channel may not be channel 1, because the Wi-Fi driver optimizes the scanning sequence. + - s2.1 ~ s2.N: Each time the Wi-Fi driver scans an AP, it will check whether it is a target AP or not. If the scan is WIFI_FAST_SCAN scan and the target AP is found, then the scan-done event will arise and scanning will end; otherwise, the scan will continue. Please note that the first scanned channel may not be channel 1, because the Wi-Fi driver optimizes the scanning sequence. If there are multiple APs which match the target AP info, for example, if we happen to scan two APs whose SSID is "ap". If the scan is WIFI_FAST_SCAN, then only the first scanned "ap" will be found, if the scan is WIFI_ALL_CHANNEL_SCAN, both "ap" will be found and the station will connect the "ap" according to the configured strategy, refer to `Station Basic Configuration`_. @@ -762,11 +733,11 @@ Four-way Handshake Phase - s4.1, The handshake timer is enabled, the 1/4 EAPOL is not received before the handshake timer expires, `WIFI_EVENT_STA_DISCONNECTED`_ will arise and the reason-code will be WIFI_REASON_HANDSHAKE_TIMEOUT. Refer to `Wi-Fi Reason Code`_. - s4.2, The 1/4 EAPOL is received. - - s4.3, The STA replies 2/4 EAPOL. + - s4.3, The station replies 2/4 EAPOL. - s4.4, If the 3/4 EAPOL is not received before the handshake timer expires, `WIFI_EVENT_STA_DISCONNECTED`_ will arise and the reason-code will be WIFI_REASON_HANDSHAKE_TIMEOUT. Refer to `Wi-Fi Reason Code`_. - s4.5, The 3/4 EAPOL is received. - - s4.6, The STA replies 4/4 EAPOL. - - s4.7, The STA raises `WIFI_EVENT_STA_CONNECTED`_. + - s4.6, The station replies 4/4 EAPOL. + - s4.7, The station raises `WIFI_EVENT_STA_CONNECTED`_. Wi-Fi Reason Code @@ -774,259 +745,264 @@ Wi-Fi Reason Code The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first column is the macro name defined in esp_wifi_types.h. The common prefix *WIFI_REASON* is removed, which means that *UNSPECIFIED* actually stands for *WIFI_REASON_UNSPECIFIED* and so on. The second column is the value of the reason. The third column is the standard value to which this reason is mapped in section 8.4.1.7 of IEEE 802.11-2012. (For more information, refer to the standard mentioned above.) The last column is a description of the reason. -+---------------------------+-------+---------+-------------------------------------------------------------+ -| Reason code | Value |Mapped To| Description | -+===========================+=======+=========+=============================================================+ -| UNSPECIFIED | 1 | 1 | Generally, it means an internal failure, e.g., the memory | -| | | | runs out, the internal TX fails, or the reason is received | -| | | | from the remote side, etc. | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| AUTH_EXPIRE | 2 | 2 | The previous authentication is no longer valid. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - auth is timed out. | -| | | | - the reason is received from the AP. | -| | | | | -| | | | For the ESP AP, this reason is reported when: | -| | | | | -| | | | - the AP has not received any packets from the station | -| | | | in the past five minutes. | -| | | | - the AP is stopped by calling :cpp:func:`esp_wifi_stop()`.| -| | | | - the station is de-authed by calling | -| | | | :cpp:func:`esp_wifi_deauth_sta()`. | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| AUTH_LEAVE | 3 | 3 | De-authenticated, because the sending STA is | -| | | | leaving (or has left). | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| ASSOC_EXPIRE | 4 | 4 | Disassociated due to inactivity. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -| | | | For the ESP AP, this reason is reported when: | -| | | | | -| | | | - the AP has not received any packets from the | -| | | | station in the past five minutes. | -| | | | - the AP is stopped by calling :cpp:func:`esp_wifi_stop()` | -| | | | - the station is de-authed by calling | -| | | | :cpp:func:`esp_wifi_deauth_sta()` | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| ASSOC_TOOMANY | 5 | 5 | Disassociated, because the AP is unable to handle | -| | | | all currently associated STAs at the same time. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -| | | | For the ESP AP, this reason is reported when: | -| | | | | -| | | | - the stations associated with the AP reach the | -| | | | maximum number that the AP can support. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| NOT_AUTHED | 6 | 6 | Class-2 frame received from a non-authenticated STA. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -| | | | For the ESP AP, this reason is reported when: | -| | | | | -| | | | - the AP receives a packet with data from a | -| | | | non-authenticated station. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| NOT_ASSOCED | 7 | 7 | Class-3 frame received from a non-associated STA. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -| | | | For the ESP AP, this reason is reported when: | -| | | | | -| | | | - the AP receives a packet with data from a | -| | | | non-associated station. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| ASSOC_LEAVE | 8 | 8 | Disassociated, because the sending STA is leaving (or has | -| | | | left) BSS. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | - the station is disconnected by | -| | | | :cpp:func:`esp_wifi_disconnect()` and other APIs. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| ASSOC_NOT_AUTHED | 9 | 9 | STA requesting (re)association is not authenticated by the | -| | | | responding STA. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -| | | | For the ESP AP, this reason is reported when: | -| | | | | -| | | | - the AP receives packets with data from an | -| | | | associated, yet not authenticated, station. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| DISASSOC_PWRCAP_BAD | 10 | 10 | Disassociated, because the information in the Power | -| | | | Capability element is unacceptable. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| DISASSOC_SUPCHAN_BAD | 11 | 11 | Disassociated, because the information in the Supported | -| | | | Channels element is unacceptable. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| IE_INVALID | 13 | 13 | Invalid element, i.e. an element whose content does not meet| -| | | | the specifications of the Standard in frame formats clause. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -| | | | For the ESP AP, this reason is reported when: | -| | | | | -| | | | - the AP parses a wrong WPA or RSN IE. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| MIC_FAILURE | 14 | 14 | Message integrity code (MIC) failure. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, in ESP | -| | | | this reason-code is replaced with | -| | | | WIFI_REASON_HANDSHAKE_TIMEOUT. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - the handshake times out. | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| GROUP_KEY_UPDATE_TIMEOUT | 16 | 16 | Group-Key Handshake times out. | -| | | | | -| | | | For the ESP station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| IE_IN_4WAY_DIFFERS | 17 | 17 | The element in the four-way handshake is different from the | -| | | | (Re-)Association Request/Probe and Response/Beacon frame. | -| | | | | -| | | | For the ESP station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | - the station finds that the four-way handshake IE differs | -| | | | from the IE in the (Re-)Association Request/Probe and | -| | | | Response/Beacon frame. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| GROUP_CIPHER_INVALID | 18 | 18 | Invalid group cipher. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| PAIRWISE_CIPHER_INVALID | 19 | 19 | Invalid pairwise cipher. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| AKMP_INVALID | 20 | 20 | Invalid AKMP. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| UNSUPP_RSN_IE_VERSION | 21 | 21 | Unsupported RSNE version. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| INVALID_RSN_IE_CAP | 22 | 22 | Invalid RSNE capabilities. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| 802_1X_AUTH_FAILED | 23 | 23 | IEEE 802.1X. authentication failed. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -| | | | For the ESP AP, this reason is reported when: | -| | | | | -| | | | - 802.1 x authentication fails. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| CIPHER_SUITE_REJECTED | 24 | 24 | Cipher suite rejected due to security policies. | -| | | | | -| | | | For the ESP Station, this reason is reported when: | -| | | | | -| | | | - it is received from the AP. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| BEACON_TIMEOUT | 200 |reserved | Espressif-specific Wi-Fi reason-code: when the station | -| | | | loses N beacons continuously, it will disrupt the connection| -| | | | and report this reason. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| NO_AP_FOUND | 201 |reserved | Espressif-specific Wi-Fi reason-code: when the station | -| | | | fails to scan the target AP, this reason code will be | -| | | | reported. | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| AUTH_FAIL | 202 |reserved | Espressif-specific Wi-Fi reason-code: the | -| | | | authentication fails, but not because of a timeout. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| ASSOC_FAIL | 203 |reserved | Espressif-specific Wi-Fi reason-code: the association | -| | | | fails, but not because of ASSOC_EXPIRE or ASSOC_TOOMANY. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| HANDSHAKE_TIMEOUT | 204 |reserved | Espressif-specific Wi-Fi reason-code: the | -| | | | handshake fails for the same reason as that in | -| | | | WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ -| CONNECTION_FAIL | 205 |reserved | Espressif-specific Wi-Fi reason-code: the | -| | | | connection to the AP has failed. | -| | | | | -+---------------------------+-------+---------+-------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 5 10 12 40 + + * - Reason code + - Value + - Mapped To + - Description + * - UNSPECIFIED + - 1 + - 1 + - Generally, it means an internal failure, e.g., the memory runs out, the internal TX fails, or the reason is received from the remote side, etc. + * - AUTH_EXPIRE + - 2 + - 2 + - The previous authentication is no longer valid. + + For the ESP station, this reason is reported when: + + - auth is timed out. + - the reason is received from the AP. + + For the ESP AP, this reason is reported when: + + - the AP has not received any packets from the station in the past five minutes. + - the AP is stopped by calling :cpp:func:`esp_wifi_stop()`. + - the station is de-authed by calling :cpp:func:`esp_wifi_deauth_sta()`. + * - AUTH_LEAVE + - 3 + - 3 + - De-authenticated, because the sending station is leaving (or has left). + + For the ESP station, this reason is reported when: + + - it is received from the AP. + * - ASSOC_EXPIRE + - 4 + - 4 + - Disassociated due to inactivity. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + + For the ESP AP, this reason is reported when: + + - the AP has not received any packets from the station in the past five minutes. + - the AP is stopped by calling :cpp:func:`esp_wifi_stop()`. + - the station is de-authed by calling :cpp:func:`esp_wifi_deauth_sta()`. + * - ASSOC_TOOMANY + - 5 + - 5 + - Disassociated, because the AP is unable to handle all currently associated STAs at the same time. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + + For the ESP AP, this reason is reported when: + + - the stations associated with the AP reach the maximum number that the AP can support. + * - NOT_AUTHED + - 6 + - 6 + - Class-2 frame received from a non-authenticated STA. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + + For the ESP AP, this reason is reported when: + + - the AP receives a packet with data from a non-authenticated station. + * - NOT_ASSOCED + - 7 + - 7 + - Class-3 frame received from a non-associated STA. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + + For the ESP AP, this reason is reported when: + + - the AP receives a packet with data from a non-associated station. + * - ASSOC_LEAVE + - 8 + - 8 + - Disassociated, because the sending station is leaving (or has left) BSS. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + - the station is disconnected by :cpp:func:`esp_wifi_disconnect()` and other APIs. + * - ASSOC_NOT_AUTHED + - 9 + - 9 + - station requesting (re)association is not authenticated by the responding STA. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + + For the ESP AP, this reason is reported when: + + - the AP receives packets with data from an associated, yet not authenticated, station. + * - DISASSOC_PWRCAP_BAD + - 10 + - 10 + - Disassociated, because the information in the Power Capability element is unacceptable. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + * - DISASSOC_SUPCHAN_BAD + - 11 + - 11 + - Disassociated, because the information in the Supported Channels element is unacceptable. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + * - IE_INVALID + - 13 + - 13 + - Invalid element, i.e. an element whose content does not meet the specifications of the Standard in frame formats clause. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + + For the ESP AP, this reason is reported when: + + - the AP parses a wrong WPA or RSN IE. + * - MIC_FAILURE + - 14 + - 14 + - Message integrity code (MIC) failure. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + * - 4WAY_HANDSHAKE_TIMEOUT + - 15 + - 15 + - Four-way handshake times out. For legacy reasons, in ESP this reason-code is replaced with WIFI_REASON_HANDSHAKE_TIMEOUT. + + For the ESP station, this reason is reported when: + + - the handshake times out. + - it is received from the AP. + * - GROUP_KEY_UPDATE_TIMEOUT + - 16 + - 16 + - Group-Key Handshake times out. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + * - IE_IN_4WAY_DIFFERS + - 17 + - 17 + - The element in the four-way handshake is different from the (Re-)Association Request/Probe and Response/Beacon frame. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + - the station finds that the four-way handshake IE differs from the IE in the (Re-)Association Request/Probe and Response/Beacon frame. + * - GROUP_CIPHER_INVALID + - 18 + - 18 + - Invalid group cipher. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + * - PAIRWISE_CIPHER_INVALID + - 19 + - 19 + - Invalid pairwise cipher. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + * - AKMP_INVALID + - 20 + - 20 + - Invalid AKMP. + + For the ESP station, this reason is reported when: + - it is received from the AP. + * - UNSUPP_RSN_IE_VERSION + - 21 + - 21 + - Unsupported RSNE version. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + * - INVALID_RSN_IE_CAP + - 22 + - 22 + - Invalid RSNE capabilities. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + * - 802_1X_AUTH_FAILED + - 23 + - 23 + - IEEE 802.1X. authentication failed. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + + For the ESP AP, this reason is reported when: + + - IEEE 802.1X. authentication fails. + * - CIPHER_SUITE_REJECTED + - 24 + - 24 + - Cipher suite rejected due to security policies. + + For the ESP station, this reason is reported when: + + - it is received from the AP. + * - BEACON_TIMEOUT + - 200 + - reserved + - Espressif-specific Wi-Fi reason-code: when the station loses N beacons continuously, it will disrupt the connection and report this reason. + * - NO_AP_FOUND + - 201 + - reserved + - Espressif-specific Wi-Fi reason-code: when the station fails to scan the target AP, this reason code will be reported. + * - AUTH_FAIL + - 202 + - reserved + - Espressif-specific Wi-Fi reason-code: the authentication fails, but not because of a timeout. + * - ASSOC_FAIL + - 203 + - reserved + - Espressif-specific Wi-Fi reason-code: the association fails, but not because of ASSOC_EXPIRE or ASSOC_TOOMANY. + * - HANDSHAKE_TIMEOUT + - 204 + - reserved + - Espressif-specific Wi-Fi reason-code: the handshake fails for the same reason as that in WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT. + * - CONNECTION_FAIL + - 205 + - reserved + - Espressif-specific Wi-Fi reason-code: the connection to the AP has failed. + {IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found ---------------------------------------------------------------------- This scenario is similar as `{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario`_, the difference is the station will not raise the event `WIFI_EVENT_STA_DISCONNECTED`_ unless it fails to connect all of the found APs. - Wi-Fi Reconnect --------------------------- @@ -1055,103 +1031,59 @@ Wi-Fi Mode +++++++++++++++++++++++++ Call :cpp:func:`esp_wifi_set_mode()` to set the Wi-Fi mode. -+------------------+--------------------------------------------------------------+ -| Mode | Description | -+==================+==============================================================+ -| WIFI_MODE_NULL | NULL mode: in this mode, the internal data struct is not | -| | allocated to the station and the AP, while both the | -| | station and AP interfaces are not initialized for | -| | RX/TX Wi-Fi data. Generally, this mode is used for Sniffer, | -| | or when you only want to stop both the STA and the AP | -| | without calling :cpp:func:`esp_wifi_deinit()` to unload the | -| | whole Wi-Fi driver. | -+------------------+--------------------------------------------------------------+ -| WIFI_MODE_STA | Station mode: in this mode, :cpp:func:`esp_wifi_start()` will| -| | init the internal station data, while the station's interface| -| | is ready for the RX and TX Wi-Fi data. After | -| | :cpp:func:`esp_wifi_connect()` is called, the STA will | -| | connect to the target target AP. | -+------------------+--------------------------------------------------------------+ -| WIFI_MODE_AP | AP mode: in this mode, :cpp:func:`esp_wifi_start()` will init| -| | the internal AP data, while the AP's interface is ready | -| | for RX/TX Wi-Fi data. Then, the Wi-Fi driver starts broad- | -| | casting beacons, and the AP is ready to get connected | -| | to other stations. | -+------------------+--------------------------------------------------------------+ -| WIFI_MODE_APSTA | Station-AP coexistence mode: in this mode, | -| | :cpp:func:`esp_wifi_start()` will simultaneously init 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. | -+------------------+--------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 50 + + * - Mode + - Description + * - WIFI_MODE_NULL + - NULL mode: in this mode, the internal data struct is not allocated to the station and the AP, while both the station and AP interfaces are not initialized for RX/TX Wi-Fi data. Generally, this mode is used for Sniffer, or when you only want to stop both the station and the AP without calling :cpp:func:`esp_wifi_deinit()` to unload the whole Wi-Fi driver. + * - WIFI_MODE_STA + - Station mode: in this mode, :cpp:func:`esp_wifi_start()` will init the internal station data, while the station’s interface is ready for the RX and TX Wi-Fi data. After :cpp:func:`esp_wifi_connect()`, the station will connect to the target AP. + * - WIFI_MODE_AP + - AP mode: in this mode, :cpp:func:`esp_wifi_start()` will init the internal AP data, while the AP’s interface is ready for RX/TX Wi-Fi data. Then, the Wi-Fi driver starts broad-casting beacons, and the AP is ready to get connected to other stations. + * - WIFI_MODE_APSTA + - Station/AP coexistence mode: in this mode, :cpp:func:`esp_wifi_start()` will simultaneously init 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. + Station Basic Configuration +++++++++++++++++++++++++++++++++++++ API esp_wifi_set_config() can be used to configure the station. The table below describes the fields in detail. -+------------------+--------------------------------------------------------------+ -| Field | Description | -+==================+==============================================================+ -| ssid | This is the SSID of the target AP, to which the station wants| -| | to connect to. | -| | | -+------------------+--------------------------------------------------------------+ -| password | Password of the target AP. | -| | | -+------------------+--------------------------------------------------------------+ -| scan_method | For WIFI_FAST_SCAN scan, the scan ends when the first matched| -| | AP is found, for WIFI_ALL_CHANNEL_SCAN, the scan finds all | -| | matched APs on all channels. | -| | The default scan is WIFI_FAST_SCAN. | -+------------------+--------------------------------------------------------------+ -| bssid_set | If bssid_set is 0, the station connects to the AP whose SSID | -| | is the same as the field "ssid", while the field "bssid" | -| | is ignored. In all other cases, the station connects to | -| | the AP whose SSID is the same as the "ssid" field, while its | -| | BSSID is the same the "bssid" field . | -+------------------+--------------------------------------------------------------+ -| bssid | This is valid only when bssid_set is 1; see field | -| | "bssid_set". | -+------------------+--------------------------------------------------------------+ -| channel | If the channel is 0, the station scans the channel 1 ~ N to | -| | search for the target AP; otherwise, the station starts by | -| | scanning the channel whose value is the same as that of the | -| | "channel" field, and then scans others to find the target AP.| -| | If you do not know which channel the target AP is running on,| -| | set it to 0. | -+------------------+--------------------------------------------------------------+ -| sort_method | This field is only for WIFI_ALL_CHANNEL_SCAN | -| | | -| | If the sort_method is WIFI_CONNECT_AP_BY_SIGNAL, all matched | -| | APs are sorted by signal, for AP with best signal will be | -| | connected firstly. E.g. if the station want to connect AP | -| | whose ssid is "apxx", the scan finds two AP whose ssid equals| -| | to "apxx", the first AP's signal is -90 dBm, the second AP's | -| | signal is -30 dBm, the station connects the second AP | -| | firstly, it doesn't connect the first one unless it fails to | -| | connect the second one. | -| | | -| | If the sort_method is WIFI_CONNECT_AP_BY_SECURITY, all | -| | matched APs are sorted by security. E.g. if the station wants| -| | to connect AP whose ssid is "apxx", the scan finds two AP | -| | whose ssid is "apxx", the security of the first found AP is | -| | open while the second one is WPA2, the stations connects to | -| | the second AP firstly, it doesn't connect the second one | -| | unless it fails to connect the first one. | -+------------------+--------------------------------------------------------------+ -| threshold | The threshold is used to filter the found AP, if the RSSI or | -| | security mode is less than the configured threshold, the AP | -| | will be discard. | -| | | -| | If the RSSI set to 0, it means default threshold, the default| -| | RSSI threshold is -127 dBm. If the authmode threshold is set | -| | to 0, it means default threshold, the default authmode | -| | threshold is open. | -+------------------+--------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 50 + + * - Field + - Description + * - ssid + - This is the SSID of the target AP, to which the station wants to connect to. + * - password + - Password of the target AP. + * - scan_method + - For WIFI_FAST_SCAN scan, the scan ends when the first matched AP is found. For WIFI_ALL_CHANNEL_SCAN, the scan finds all matched APs on all channels. The default scan is WIFI_FAST_SCAN. + * - bssid_set + - If bssid_set is 0, the station connects to the AP whose SSID is the same as the field “ssid”, while the field “bssid” is ignored. In all other cases, the station connects to the AP whose SSID is the same as the “ssid” field, while its BSSID is the same the “bssid” field . + * - bssid + - This is valid only when bssid_set is 1; see field “bssid_set”. + * - channel + - If the channel is 0, the station scans the channel 1 ~ N to search for the target AP; otherwise, the station starts by scanning the channel whose value is the same as that of the “channel” field, and then scans others to find the target AP. If you do not know which channel the target AP is running on, set it to 0. + * - sort_method + - This field is only for WIFI_ALL_CHANNEL_SCAN. + + If the sort_method is WIFI_CONNECT_AP_BY_SIGNAL, all matched APs are sorted by signal, for AP with best signal will be connected firstly. E.g. if the station want to connect AP whose ssid is “apxx”, the scan finds two AP whose ssid equals to “apxx”, the first AP’s signal is -90 dBm, the second AP’s signal is -30 dBm, the station connects the second AP firstly, it doesn’t connect the first one unless it fails to connect the second one. + + If the sort_method is WIFI_CONNECT_AP_BY_SECURITY, all matched APs are sorted by security. E.g. if the station wants to connect AP whose ssid is “apxx”, the scan finds two AP whose ssid is “apxx”, the security of the first found AP is open while the second one is WPA2, the stations connects to the second AP firstly, it doesn’t connect the second one unless it fails to connect the first one. + * - threshold + - The threshold is used to filter the found AP, if the RSSI or security mode is less than the configured threshold, the AP will be discard. + + If the RSSI set to 0, it means default threshold, the default RSSI threshold is -127 dBm. If the authmode threshold is set to 0, it means default threshold, the default authmode threshold is open. + .. attention:: + WEP/WPA security modes are deprecated in IEEE 802.11-2016 specifications and are recommended not to be used. These modes can be rejected using authmode threshold by setting threshold as WPA2 by threshold.authmode as WIFI_AUTH_WPA2_PSK. AP Basic Configuration @@ -1159,85 +1091,59 @@ AP Basic Configuration API esp_wifi_set_config() can be used to configure the AP. The table below describes the fields in detail. -+------------------+--------------------------------------------------------------+ -| 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. + Wi-Fi Protocol Mode +++++++++++++++++++++++++ Currently, the IDF supports the following protocol modes: -+--------------------+------------------------------------------------------------+ -| Protocol Mode | Description | -+====================+============================================================+ -| 802.11 B | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B) to set | -| | the station/AP to 802.11B-only mode. | -| | | -+--------------------+------------------------------------------------------------+ -| 802.11 BG | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_ | -| | PROTOCOL_11G) to set the station/AP to 802.11BG mode. | -| | | -+--------------------+------------------------------------------------------------+ -| 802.11 BGN | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| | -| | WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) to set the station/ | -| | AP to BGN 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 | -| | Espressif-specific mode. | -+--------------------+------------------------------------------------------------+ -| 802.11 LR | Call esp_wifi_set_protocol (ifx, WIFI_PROTOCOL_LR) to set | -| | the station/AP only to the Espressif-specific 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** | -+--------------------+------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 55 + + * - 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.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.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 Espressif-specific mode. + * - 802.11 LR + - Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR) to set the station/AP only to the Espressif-specific 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. It has better reception sensitivity, stronger anti-interference ability and longer transmission distance than the traditional 802.11B mode. +Long Range (LR) mode is an Espressif-patented Wi-Fi mode which can achieve a one-kilometer line of sight range. It has better reception sensitivity, stronger anti-interference ability and longer transmission distance than the traditional 802.11b mode. LR Compatibility ************************* @@ -1282,12 +1188,12 @@ The data transmission in LR rate has no impacts on the traditional Wi-Fi device - 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 impact transmission in LR mode is similar as the impact in 802.11B mode. +In other words, the impact transmission in LR mode is similar as the impact in 802.11b mode. LR Transmission Distance ************************* -The reception sensitivity of LR has about 4 dB gain than the traditional 802.11B mode, theoretically the transmission distance is about 2 to 2.5 times the distance of 11B. +The reception sensitivity of LR has about 4 dB gain than the traditional 802.11b mode, theoretically the transmission distance is about 2 to 2.5 times the distance of 11B. LR Throughput ************************* @@ -1306,96 +1212,78 @@ The general conditions for using LR are: 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. +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. + +.. list-table:: + :header-rows: 1 + :widths: 15 55 + + * - Field + - Description + * - cc[3] + - Country code string, this attributes identify the country or noncountry entity in which the station/AP is operating. If it’s a country, the first two octets of this string is the two character country info as described in document ISO/IEC3166-1. The third octect is one of the following: + + - an ASCII space character, if the regulations under which the station/AP is operating encompass all environments for the current frequency band in the country. + - an ASCII ‘O’ character if the regulations under which the station/AP is operating are for an outdoor environment only. + - an ASCII ‘I’ character if the regulations under which the station/AP is operating are for an indoor environment only. + - an ASCII ‘X’ character if 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, IEEE Std 802.11-2012. + + * - schan + - Start channel, it’s the minimum channel number of the regulations under which the station/AP can operate. + * - nchan + - Total number of channels as per the regulations, e.g. if the schan=1, nchan=13, it means the station/AP can send data from channel 1 to 13. + * - policy + - Country policy, this field control which country info will be used if the configured country info is conflict with the connected AP’s. More description about policy is provided in following section. -+------------------+-----------------------------------------------------------------------------------+ -| Field | Description | -+==================+===================================================================================+ -| cc[3] | Country code string, this attributes identify the country or noncountry entity | -| | in which the station/AP is operating. If it's a country, the first two | -| | octets of this string is the two character country info as described in document | -| | ISO/IEC3166-1. The third octect is one of the following: | -| | | -| | - an ASCII space character, if the regulations under which the station/AP is | -| | operating encompass all environments for the current frequency band in the | -| | country. | -| | - an ASCII 'O' character if the regulations under which the station/AP is | -| | operating are for an outdoor environment only. | -| | - an ASCII 'I' character if the regulations under which the station/AP is | -| | operating are for an indoor environment only. | -| | - an ASCII 'X' character if 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, IEEE Std 802.11-2012. | -| | | -+------------------+-----------------------------------------------------------------------------------+ -| schan | Start channel, it's the minimum channel number of the regulations under which the | -| | station/AP can operate. | -| | | -+------------------+-----------------------------------------------------------------------------------+ -| nchan | Total number of channels as per the regulations, e.g. if the schan=1, nchan=13, | -| | it means the station/AP can send data from channel 1 to 13. | -| | | -+------------------+-----------------------------------------------------------------------------------+ -| policy | Country policy, this field control which country info will be used if the | -| | configured country info is conflict with the connected AP's. More description | -| | about policy is provided in following section. | -| | | -+------------------+-----------------------------------------------------------------------------------+ The default country info is {.cc="CN", .schan=1, .nchan=13, 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 {.cc="JP", .schan=1, .nchan=14, policy=WIFI_COUNTRY_POLICY_AUTO}, but the connected AP has country info {.cc="CN", .schan=1, .nchan=13}, then country info of connected AP's is used. + Following table depicts which country info is used in different Wi-Fi Mode and different country policy, also describe the impact to active scan. -+-----------+----------------------------+----------------------------------------------------------------+ -| WiFi 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 | -| | | default country info. | -| | | | -| | | For scan: | -| | | | -| | | -If schan+nchan-1 >11 : | -| | | Use active scan from schan to 11 and use passive scan | -| | | from 12 to schan+nchan-1. | -| | | | -| | | -If schan+nchan-1 <= 11 : | -| | | Use active scan from schan to schan+nchan-1. | -| | | | -| | | Always keep in mind that if an AP with hidden SSID | -| | | 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. | -| | | | -| | | For scan, scans channel "schan" to "schan+nchan-1" with active | -| | | scan. | -| | | | -+-----------+----------------------------+----------------------------------------------------------------+ -| AP | WIFI_COUNTRY_POLICY_AUTO | Always use the configured country info. | -| | | | -+-----------+----------------------------+----------------------------------------------------------------+ -| AP | WIFI_COUNTRY_POLICY_MANUAL | Always use the configured country info. | -| | | | -+-----------+----------------------------+----------------------------------------------------------------+ -|Station/AP-| WIFI_COUNTRY_POLICY_AUTO | If the station doesn't connects to any AP, the AP use the | -| | | configured country info. | -|coexistence| | If the station connects to an AP, the AP has the same | -| | | country info as the station. | -| | | | -| | | Same as station mode with policy WIFI_COUNTRY_POLICY_AUTO. | -+-----------+----------------------------+----------------------------------------------------------------+ +.. 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 default country info. + + For scan: + + - If schan+nchan-1 >11 : + + Use active scan from schan to 11 and use passive scan from 12 to schan+nchan-1. + + - If schan+nchan-1 <= 11 : + + Use active scan from schan to schan+nchan-1. + + 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. For scan, scans channel “schan” to “schan+nchan-1” with active scan. + * - AP + - WIFI_COUNTRY_POLICY_AUTO + - Always use the configured country info. + * - AP + - WIFI_COUNTRY_POLICY_MANUAL + - Always use the configured country info. + * - Station/AP-coexistence + - WIFI_COUNTRY_POLICY_AUTO + - If the station doesn’t connects to any external AP, the AP use the configured country info. If the station connects to an external AP, the AP has the same country info as the station. + + Same as station mode with policy WIFI_COUNTRY_POLICY_AUTO. + Home Channel ************************* -In AP mode, the home channel is defined as the AP channel. In Station mode, home channel is defined as the channel of AP which the station is connected to. In Station/AP-coexistence mode, the home channel of AP and station must be the same, if they are different, the station's home channel is always in priority. Take the following as an example: the AP is on channel 6, and the station connects to an AP whose channel is 9. Since the station's home channel has higher priority, the AP needs to switch its channel from 6 to make sure that it has the same home channel as the station. While switching channel, the {IDF_TARGET_NAME} in SoftAP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Station that supports channel switching will transit without disconnecting and reconnecting to the SoftAP. +In AP mode, the home channel is defined as the AP channel. In station mode, home channel is defined as the channel of AP which the station is connected to. In station/AP-coexistence mode, the home channel of AP and station must be the same, if they are different, the station's home channel is always in priority. Take the following as an example: the AP is on channel 6, and the station connects to an AP whose channel is 9. Since the station's home channel has higher priority, the AP needs to switch its channel from 6 to make sure that it has the same home channel as the station. While switching channel, the {IDF_TARGET_NAME} in AP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Station that supports channel switching will transit without disconnecting and reconnecting to the AP. Wi-Fi Vendor IE Configuration @@ -1407,17 +1295,14 @@ By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and t Wi-Fi Easy Connect™ (DPP) -------------------------- -Wi-Fi Easy Connect\ :sup:`TM` (or Device Provisioning Protocol) is a secure and standardized provisioning protocol for configuration of Wi-Fi Devices. -More information can be found on the API reference page :doc:`esp_dpp <../api-reference/network/esp_dpp>`. +Wi-Fi Easy Connect\ :sup:`TM` (or Device Provisioning Protocol) is a secure and standardized provisioning protocol for configuration of Wi-Fi Devices. More information can be found on the API reference page :doc:`esp_dpp <../api-reference/network/esp_dpp>`. WPA2-Enterprise +++++++++++++++++++++++++++++++++ -WPA2-Enterprise is the secure authentication mechanism for enterprise wireless networks. It uses RADIUS server for authentication of network users before connecting to the Access Point. The authentication process is based on 802.1X policy and comes with different Extended Authentication Protocol (EAP) methods like TLS, TTLS, PEAP etc. RADIUS server authenticates the users based on their credentials (username and password), digital certificates or both. When {IDF_TARGET_NAME} in Station mode tries to connect to an AP in enterprise mode, it sends authentication request to AP which is sent to RADIUS server by AP for authenticating the Station. Based on different EAP methods, the parameters can be set in configuration which can be opened using ``idf.py menuconfig``. WPA2_Enterprise is supported by {IDF_TARGET_NAME} only in Station mode. - - -For establishing a secure connection, AP and Station negotiate and agree on the best possible cipher suite to be used. {IDF_TARGET_NAME} supports 802.1X/EAP (WPA) method of AKM and Advanced encryption standard with Counter Mode Cipher Block Chaining Message Authentication protocol (AES-CCM) cipher suite. It also supports the cipher suites supported by mbedtls if `USE_MBEDTLS_CRYPTO` flag is set. +WPA2-Enterprise is the secure authentication mechanism for enterprise wireless networks. It uses RADIUS server for authentication of network users before connecting to the Access Point. The authentication process is based on 802.1X policy and comes with different Extended Authentication Protocol (EAP) methods like TLS, TTLS, PEAP etc. RADIUS server authenticates the users based on their credentials (username and password), digital certificates or both. When {IDF_TARGET_NAME} in station mode tries to connect to an AP in enterprise mode, it sends authentication request to AP which is sent to RADIUS server by AP for authenticating the station. Based on different EAP methods, the parameters can be set in configuration which can be opened using ``idf.py menuconfig``. WPA2_Enterprise is supported by {IDF_TARGET_NAME} only in station mode. +For establishing a secure connection, AP and station negotiate and agree on the best possible cipher suite to be used. {IDF_TARGET_NAME} supports 802.1X/EAP (WPA) method of AKM and Advanced encryption standard with Counter Mode Cipher Block Chaining Message Authentication protocol (AES-CCM) cipher suite. It also supports the cipher suites supported by mbedtls if `USE_MBEDTLS_CRYPTO` flag is set. {IDF_TARGET_NAME} currently supports the following EAP methods: - EAP-TLS: This is certificate based method and only requires SSID and EAP-IDF. @@ -1452,19 +1337,22 @@ Refer IDF example :idf_file:`examples/wifi/roaming/README.md` to set up and use Wi-Fi Location ------------------------------- - Wi-Fi Location will improve the accuracy of a device's location data beyond the Access Point, which will enable creation of new, feature-rich applications and services such as geo-fencing, network management, navigation and others. One of the protocols used to determine the device location with respect to the Access Point is Fine Timing Measurement which calculates Time-of-Flight of a WiFi frame. + Wi-Fi Location will improve the accuracy of a device's location data beyond the Access Point, which will enable creation of new, feature-rich applications and services such as geo-fencing, network management, navigation and others. One of the protocols used to determine the device location with respect to the Access Point is Fine Timing Measurement which calculates Time-of-Flight of a Wi-Fi frame. Fine Timing Measurement (FTM) +++++++++++++++++++++++++++++ FTM is used to measure Wi-Fi Round Trip Time (Wi-Fi RTT) which is the time a Wi-Fi signal takes to travel from a device to another device and back again. Using Wi-Fi RTT the distance between the devices can be calculated with a simple formula of `RTT * c / 2`, where c is the speed of light. - FTM uses timestamps given by Wi-Fi interface hardware at the time of arrival or departure of frames exchanged between a pair of devices. One entity called FTM Initiator (mostly a Station device) discovers the FTM Responder (can be a Station or an Access Point) and negotiates to start an FTM procedure. The procedure uses multiple Action frames sent in bursts and its ACK's to gather the timestamps data. FTM Initiator gathers the data in the end to calculate an average Round-Trip-Time. + + FTM uses timestamps given by Wi-Fi interface hardware at the time of arrival or departure of frames exchanged between a pair of devices. One entity called FTM Initiator (mostly a station device) discovers the FTM Responder (can be a station or an Access Point) and negotiates to start an FTM procedure. The procedure uses multiple Action frames sent in bursts and its ACK's to gather the timestamps data. FTM Initiator gathers the data in the end to calculate an average Round-Trip-Time. + {IDF_TARGET_NAME} supports FTM in below configuration: - - {IDF_TARGET_NAME} as FTM Initiator in Station mode. - - {IDF_TARGET_NAME} as FTM Responder in SoftAP mode. + - {IDF_TARGET_NAME} as FTM Initiator in station mode. + - {IDF_TARGET_NAME} as FTM Responder in AP mode. + + Distance measurement using RTT is not accurate, factors such as RF interference, multi-path travel, antenna orientation and lack of calibration increase these inaccuracies. For better results it is suggested to perform FTM between two {IDF_TARGET_NAME} devices as station and AP. - Distance measurement using RTT is not accurate, factors such as RF interference, multi-path travel, antenna orientation and lack of calibration increase these inaccuracies. For better results it is suggested to perform FTM between two {IDF_TARGET_NAME} devices as Station and SoftAP. Refer to IDF example :idf_file:`examples/wifi/ftm/README.md` for steps on how to setup and perform FTM. {IDF_TARGET_NAME} Wi-Fi Power-saving Mode @@ -1473,7 +1361,7 @@ Refer IDF example :idf_file:`examples/wifi/roaming/README.md` to set up and use Station Sleep ++++++++++++++++++++++ -Currently, {IDF_TARGET_NAME} Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode. +Currently, {IDF_TARGET_NAME} Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode. Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP. @@ -1499,64 +1387,133 @@ The table below shows the best throughput results we got in Espressif's lab and .. only:: esp32 - +----------------------+-----------------+-----------------+---------------+--------------+ - | Type/Throughput | Air In Lab | Shield-box | Test Tool | IDF Version | - | | | | | (commit ID) | - +======================+=================+=================+===============+==============+ - | Raw 802.11 Packet RX | N/A | **130 MBit/s** | Internal tool | NA | - +----------------------+-----------------+-----------------+---------------+--------------+ - | Raw 802.11 Packet TX | N/A | **130 MBit/s** | Internal tool | NA | - +----------------------+-----------------+-----------------+---------------+--------------+ - | UDP RX | 30 MBit/s | 85 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ - | UDP TX | 30 MBit/s | 75 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ - | TCP RX | 20 MBit/s | 65 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ - | TCP TX | 20 MBit/s | 75 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 10 25 + + * - Type/Throughput + - Air In Lab + - Shield-box + - Test Tool + - IDF Version (commit ID) + * - Raw 802.11 Packet RX + - N/A + - **130 MBit/s** + - Internal tool + - NA + * - Raw 802.11 Packet TX + - N/A + - **130 MBit/s** + - Internal tool + - NA + * - UDP RX + - 30 MBit/s + - 85 MBit/s + - iperf example + - 15575346 + * - UDP TX + - 30 MBit/s + - 75 MBit/s + - iperf example + - 15575346 + * - TCP RX + - 20 MBit/s + - 65 MBit/s + - iperf example + - 15575346 + * - TCP TX + - 20 MBit/s + - 75 MBit/s + - iperf example + - 15575346 When the throughput is tested by iperf example, the sdkconfig is :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32`. .. only:: esp32s2 - +----------------------+-----------------+-----------------+---------------+--------------+ - | Type/Throughput | Air In Lab | Shield-box | Test Tool | IDF Version | - | | | | | (commit ID) | - +======================+=================+=================+===============+==============+ - | Raw 802.11 Packet RX | N/A | **130 MBit/s** | Internal tool | NA | - +----------------------+-----------------+-----------------+---------------+--------------+ - | Raw 802.11 Packet TX | N/A | **130 MBit/s** | Internal tool | NA | - +----------------------+-----------------+-----------------+---------------+--------------+ - | UDP RX | 30 MBit/s | 70 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ - | UDP TX | 30 MBit/s | 50 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ - | TCP RX | 20 MBit/s | 32 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ - | TCP TX | 20 MBit/s | 37 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 10 25 + + * - Type/Throughput + - Air In Lab + - Shield-box + - Test Tool + - IDF Version (commit ID) + * - Raw 802.11 Packet RX + - N/A + - **130 MBit/s** + - Internal tool + - NA + * - Raw 802.11 Packet TX + - N/A + - **130 MBit/s** + - Internal tool + - NA + * - UDP RX + - 30 MBit/s + - 70 MBit/s + - iperf example + - 15575346 + * - UDP TX + - 30 MBit/s + - 50 MBit/s + - iperf example + - 15575346 + * - TCP RX + - 20 MBit/s + - 32 MBit/s + - iperf example + - 15575346 + * - TCP TX + - 20 MBit/s + - 37 MBit/s + - iperf example + - 15575346 When the throughput is tested by iperf example, the sdkconfig is :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32s2`. .. only:: esp32c3 - +----------------------+-----------------+-----------------+---------------+--------------+ - | Type/Throughput | Air In Lab | Shield-box | Test Tool | IDF Version | - | | | | | (commit ID) | - +======================+=================+=================+===============+==============+ - | Raw 802.11 Packet RX | N/A | **130 MBit/s** | Internal tool | NA | - +----------------------+-----------------+-----------------+---------------+--------------+ - | Raw 802.11 Packet TX | N/A | **130 MBit/s** | Internal tool | NA | - +----------------------+-----------------+-----------------+---------------+--------------+ - | UDP RX | 30 MBit/s | 50 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ - | UDP TX | 30 MBit/s | 40 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ - | TCP RX | 20 MBit/s | 35 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ - | TCP TX | 20 MBit/s | 37 MBit/s | iperf example | 15575346 | - +----------------------+-----------------+-----------------+---------------+--------------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 15 20 + + * - Type/Throughput + - Air In Lab + - Shield-box + - Test Tool + - IDF Version (commit ID) + * - Raw 802.11 Packet RX + - N/A + - **130 MBit/s** + - Internal tool + - NA + * - Raw 802.11 Packet TX + - N/A + - **130 MBit/s** + - Internal tool + - NA + * - UDP RX + - 30 MBit/s + - 50 MBit/s + - iperf example + - 15575346 + * - UDP TX + - 30 MBit/s + - 40 MBit/s + - iperf example + - 15575346 + * - TCP RX + - 20 MBit/s + - 35 MBit/s + - iperf example + - 15575346 + * - TCP TX + - 20 MBit/s + - 37 MBit/s + - iperf example + - 15575346 When the throughput is tested by iperf example, the sdkconfig is :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32c3`. @@ -1573,7 +1530,7 @@ It cannot be used for sending encrypted or QoS frames. Preconditions of Using :cpp:func:`esp_wifi_80211_tx` ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - - The Wi-Fi mode is Station, or AP, or Station+AP. + - The Wi-Fi mode is station, or AP, or station/AP. - Either esp_wifi_set_promiscuous(true), or :cpp:func:`esp_wifi_start()`, or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before :cpp:func:`esp_wifi_80211_tx` is called. In {IDF_TARGET_NAME}, both esp_wifi_set_promiscuous(true) and :cpp:func:`esp_wifi_start()` can trigger the initialization of Wi-Fi hardware. - The parameters of :cpp:func:`esp_wifi_80211_tx` are hereby correctly provided. @@ -1588,88 +1545,42 @@ Side-Effects to Avoid in Different Scenarios Theoretically, if we do not consider the side-effects the API imposes on the Wi-Fi driver or other stations/APs, we can send a raw 802.11 packet over the air, with any destination MAC, any source MAC, any BSSID, or any other type of packet. However,robust/useful applications should avoid such side-effects. The table below provides some tips/recommendations on how to avoid the side-effects of :cpp:func:`esp_wifi_80211_tx` in different scenarios. -+-----------------------------+---------------------------------------------------+ -| Scenario | Description | -+=============================+===================================================+ -| No WiFi connection | In this scenario, no Wi-Fi connection is set up, | -| | so there are no side-effects on the Wi-Fi driver. | -| | If en_sys_seq==true, the Wi-Fi driver is | -| | responsible for the sequence control. If | -| | en_sys_seq==false, the application needs to ensure| -| | that the buffer has the correct sequence. | -| | | -| | Theoretically, the MAC address can be any address.| -| | However, this may impact other stations/APs | -| | with the same MAC/BSSID. | -| | | -| | Side-effect example#1 | -| | The application calls esp_wifi_80211_tx to send | -| | a beacon with BSSID == mac_x in AP mode, but | -| | the mac_x is not the MAC of the AP interface. | -| | Moreover, there is another AP, say | -| | "other-AP", whose bssid is mac_x. If this | -| | happens, an "unexpected behavior" may occur, | -| | because the stations which connect to the | -| | "other-AP" cannot figure out whether the beacon is| -| | from the "other-AP" or the esp_wifi_80211_tx. | -| | | -| | To avoid the above-mentioned side-effects, we | -| | recommend that: | -| | | -| | - If esp_wifi_80211_tx is called in Station mode,| -| | the first MAC should be a multicast MAC or the | -| | exact target-device's MAC, while the second MAC| -| | should be that of the station interface. | -| | - If esp_wifi_80211_tx is called in AP mode, | -| | the first MAC should be a multicast MAC or the | -| | exact target-device's MAC, while the second MAC| -| | should be that of the AP interface. | -| | | -| | The recommendations above are only for avoiding | -| | side-effects and can be ignored when there are | -| | good reasons for doing this. | -+-----------------------------+---------------------------------------------------+ -| Have WiFi connection | When the Wi-Fi connection is already set up, and | -| | the sequence is controlled by the application, the| -| | latter may impact the sequence control of the | -| | Wi-Fi connection, as a whole. So, the | -| | en_sys_seq need to be true, otherwise | -| | ESP_ERR_WIFI_ARG is returned. | -| | | -| | The MAC-address recommendations in the | -| | "No WiFi connection" scenario also apply to this | -| | scenario. | -| | | -| | If the WiFi mode is station mode and the MAC | -| | address1 is the MAC of AP to which the station is | -| | connected, the MAC address2 is the MAC of station | -| | interface, we say the packets is from the station | -| | to AP. On the other hand, if the WiFi mode is | -| | AP mode and the MAC address1 is the MAC of | -| | the station who connects to this AP, the MAC | -| | address2 is the MAC of AP interface, we say | -| | the packet is from the AP to station. | -| | To avoid conflicting with WiFi connections, the | -| | following checks are applied: | -| | | -| | - If the packet type is data and is from the | -| | station to AP, the ToDS bit in IEEE 80211 | -| | frame control should be 1, the FromDS bit | -| | should be 0, otherwise the packet will be | -| | discarded by WiFi driver. | -| | - If the packet type is data and is from the | -| | AP to station, the ToDS bit in IEEE 80211 | -| | frame control should be 0, the FromDS bit | -| | should be 1, otherwise the packet will be | -| | discarded by WiFi driver. | -| | - If the packet is from station to AP or | -| | from AP to station, the Power Management, | -| | More Data, Re-Transmission bits should be 0, | -| | otherwise the packet will be discarded by WiFi | -| | driver. | -| | | -| | ESP_ERR_WIFI_ARG is returned if any check fails. | -+-----------------------------+---------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 10 50 + + * - Scenario + - Description + * - No Wi-Fi connection + - In this scenario, no Wi-Fi connection is set up, so there are no side-effects on the Wi-Fi driver. If en_sys_seq==true, the Wi-Fi driver is responsible for the sequence control. If en_sys_seq==false, the application needs to ensure that the buffer has the correct sequence. + + Theoretically, the MAC address can be any address. However, this may impact other stations/APs with the same MAC/BSSID. + + Side-effect example#1 The application calls esp_wifi_80211_tx to send a beacon with BSSID == mac_x in AP mode, but the mac_x is not the MAC of the AP interface. Moreover, there is another AP, say “other-AP”, whose bssid is mac_x. If this happens, an “unexpected behavior” may occur, because the stations which connect to the “other-AP” cannot figure out whether the beacon is from the “other-AP” or the esp_wifi_80211_tx. + + To avoid the above-mentioned side-effects, we recommend that: + + - If esp_wifi_80211_tx is called in station mode, the first MAC should be a multicast MAC or the exact target-device’s MAC, while the second MAC should be that of the station interface. + + - If esp_wifi_80211_tx is called in AP mode, the first MAC should be a multicast MAC or the exact target-device’s MAC, while the second MAC should be that of the AP interface. + + The recommendations above are only for avoiding side-effects and can be ignored when there are good reasons for doing this. + + * - Have Wi-Fi connection + - When the Wi-Fi connection is already set up, and the sequence is controlled by the application, the latter may impact the sequence control of the Wi-Fi connection, as a whole. So, the en_sys_seq need to be true, otherwise ESP_ERR_WIFI_ARG is returned. + + The MAC-address recommendations in the “No Wi-Fi connection” scenario also apply to this scenario. + + If the Wi-Fi mode is station mode and the MAC address1 is the MAC of AP to which the station is connected, the MAC address2 is the MAC of station interface, we say the packets is from the station to AP. On the other hand, if the Wi-Fi mode is AP mode and the MAC address1 is the MAC of the station who connects to this AP, the MAC address2 is the MAC of AP interface, we say the packet is from the AP to station. To avoid conflicting with Wi-Fi connections, the following checks are applied: + + - If the packet type is data and is from the station to AP, the ToDS bit in IEEE 80211 frame control should be 1, the FromDS bit should be 0, otherwise the packet will be discarded by Wi-Fi driver. + + - If the packet type is data and is from the AP to station, the ToDS bit in IEEE 80211 frame control should be 0, the FromDS bit should be 1, otherwise the packet will be discarded by Wi-Fi driver. + + - If the packet is from station to AP or from AP to station, the Power Management, More Data, Re-Transmission bits should be 0, otherwise the packet will be discarded by Wi-Fi driver. + + ESP_ERR_WIFI_ARG is returned if any check fails. + Wi-Fi Sniffer Mode --------------------------- @@ -1680,10 +1591,11 @@ The Wi-Fi sniffer mode can be enabled by esp_wifi_set_promiscuous(). If the snif - 802.11 Data frame, including MPDU, AMPDU, AMSDU, etc. - 802.11 MIMO frame, for MIMO frame, the sniffer only dumps the length of the frame. - 802.11 Control frame. + - 802.11 CRC error frame. The following packets will **NOT** be dumped to the application: - - 802.11 error frame, such as the frame with a CRC error, etc. + - Other 802.11 error frames. For frames that the sniffer **can** dump, the application can additionally decide which specific type of packets can be filtered to the application by using :cpp:func:`esp_wifi_set_promiscuous_filter()` and :cpp:func:`esp_wifi_set_promiscuous_ctrl_filter()`. By default, it will filter all 802.11 data and management frames to the application. @@ -1779,13 +1691,14 @@ All of the information in the table can be found in the structure wifi_csi_info_ - 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). + - 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. .. 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-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 is invalid). Wi-Fi Channel State Information Configure @@ -1793,7 +1706,7 @@ Wi-Fi Channel State Information Configure To use Wi-Fi CSI, the following steps need to be done. - - Select Wi-Fi CSI in menuconfig. It is "Menuconfig --> Components config --> Wi-Fi --> WiFi CSI(Channel State Information)". + - Select Wi-Fi CSI in menuconfig. It is "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`. @@ -1818,7 +1731,7 @@ Wi-Fi QoS {IDF_TARGET_NAME} supports all the mandatory features required in WFA Wi-Fi QoS Certification. -Four ACs(Access Category) are defined in Wi-Fi specification, each AC has a its own priority to access the Wi-Fi channel. Moreover a map rule is defined to map the QoS priority of other protocol, such as 802.11D or TCP/IP precedence to Wi-Fi AC. +Four ACs (Access Category) are defined in Wi-Fi specification, each AC has a its own priority to access the Wi-Fi channel. Moreover a map rule is defined to map the QoS priority of other protocol, such as 802.11D or TCP/IP precedence to Wi-Fi AC. Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in {IDF_TARGET_NAME}, it also indicates whether the AMPDU is supported for this AC. The table is sorted with priority descending order, namely, the AC_VO has highest priority. @@ -1953,18 +1866,18 @@ Increasing the size or number of the buffers mentioned above properly can improv This parameter indicates the size of the AMPDU BA Window at the receiving end. This parameter should be configured to the smaller value between twice of :ref:`CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM` and :ref:`CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM`. - :ref:`CONFIG_LWIP_TCP_WND_DEFAULT` - This parameter represents the RX buffer size of the LWIP layer for each TCP stream. Its value should be configured to the value of WIFI_DYNAMIC_RX_BUFFER_NUM(KB) to reach a high and stable performance. Meanwhile, in case of multiple streams, this value needs to be reduced proportionally. + This parameter represents the RX buffer size of the LWIP layer for each TCP stream. Its value should be configured to the value of WIFI_DYNAMIC_RX_BUFFER_NUM (KB) to reach a high and stable performance. Meanwhile, in case of multiple streams, this value needs to be reduced proportionally. **TX direction:** - - :ref:`CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM` + - :ref:`CONFIG_ESP32_WIFI_TX_BUFFER` This parameter indicates the type of TX buffer, it is recommended to configure it as a dynamic buffer, which can make full use of memory. - :ref:`CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM` This parameter indicates the number of TX buffer on the Wi-Fi layer. Increasing this parameter will improve the performance of packet sending. The parameter value needs to match the TX buffer size of the LWIP layer. - :ref:`CONFIG_LWIP_TCP_SND_BUF_DEFAULT` - This parameter represents the TX buffer size of the LWIP layer for each TCP stream. Its value should be configured to the value of WIFI_DYNAMIC_TX_BUFFER_NUM(KB) to reach a high and stable performance. In case of multiple streams, this value needs to be reduced proportionally. + This parameter represents the TX buffer size of the LWIP layer for each TCP stream. Its value should be configured to the value of WIFI_DYNAMIC_TX_BUFFER_NUM (KB) to reach a high and stable performance. In case of multiple streams, this value needs to be reduced proportionally. **Throughput optimization by placing code in IRAM:** @@ -2003,145 +1916,378 @@ The parameters not mentioned in the following table should be set to the default .. only:: esp32 - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | Rank | Iperf | TX prior | High-performance | RX prior | Default | Memory saving | Minimum | - +============================+=======+==========+==================+==========+=========+===============+=========+ - | Available memory(KB) | 37.1 | 113.8 | 123.3 | 145.5 | 144.5 | 170.2 | 185.2 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | WIFI_STATIC_RX_BUFFER_NUM | 16 | 6 | 6 | 6 | 6 | 6 | 4 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 64 | 16 | 24 | 34 | 20 | 12 | 8 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | WIFI_DYNAMIC_TX_BUFFER_NUM | 64 | 28 | 24 | 18 | 20 | 12 | 8 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | WIFI_RX_BA_WIN | 32 | 8 | 12 | 12 | 10 | 6 | Disable | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | TCP_SND_BUF_DEFAULT(KB) | 65 | 28 | 24 | 18 | 20 | 12 | 8 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | TCP_WND_DEFAULT(KB) | 65 | 16 | 24 | 34 | 20 | 12 | 8 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 15 | 15 | 15 | 15 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 16 | 16 | 16 | 16 | 16 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 13 | 13 | 13 | 13 | 13 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | TCP TX throughput (Mbit/s) | 74.6 | 50.8 | 46.5 | 39.9 | 44.2 | 33.8 | 25.6 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | TCP RX throughput (Mbit/s) | 63.6 | 35.5 | 42.3 | 48.5 | 40.5 | 30.1 | 27.8 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | UDP TX throughput (Mbit/s) | 76.2 | 75.1 | 74.1 | 72.4 | 69.6 | 64.1 | 36.5 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ - | UDP RX throughput (Mbit/s) | 83.1 | 66.3 | 75.1 | 75.6 | 73.1 | 65.3 | 54.7 | - +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ + .. list-table:: + :header-rows: 1 + :widths: 10 5 5 10 5 5 10 5 + + * - Rank + - Iperf + - TX prior + - High-performance + - RX prior + - Default + - Memory saving + - Minimum + * - Available memory (KB) + - 37.1 + - 113.8 + - 123.3 + - 145.5 + - 144.5 + - 170.2 + - 185.2 + * - WIFI_STATIC_RX_BUFFER_NUM + - 16 + - 6 + - 6 + - 6 + - 6 + - 6 + - 4 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 64 + - 16 + - 24 + - 34 + - 20 + - 12 + - 8 + * - WIFI_DYNAMIC_TX_BUFFER_NUM + - 64 + - 28 + - 24 + - 18 + - 20 + - 12 + - 8 + * - WIFI_RX_BA_WIN + - 32 + - 8 + - 12 + - 12 + - 10 + - 6 + - Disable + * - TCP_SND_BUF_DEFAULT (KB) + - 65 + - 28 + - 24 + - 18 + - 20 + - 12 + - 8 + * - TCP_WND_DEFAULT (KB) + - 65 + - 16 + - 24 + - 34 + - 20 + - 12 + - 8 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 15 + - 15 + - 15 + - 15 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 16 + - 16 + - 16 + - 16 + - 16 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 13 + - 13 + - 13 + - 13 + - 13 + - 13 + * - TCP TX throughput (Mbit/s) + - 74.6 + - 50.8 + - 46.5 + - 39.9 + - 44.2 + - 33.8 + - 25.6 + * - TCP RX throughput (Mbit/s) + - 63.6 + - 35.5 + - 42.3 + - 48.5 + - 40.5 + - 30.1 + - 27.8 + * - UDP TX throughput (Mbit/s) + - 76.2 + - 75.1 + - 74.1 + - 72.4 + - 69.6 + - 64.1 + - 36.5 + * - UDP RX throughput (Mbit/s) + - 83.1 + - 66.3 + - 75.1 + - 75.6 + - 73.1 + - 65.3 + - 54.7 + .. only:: esp32s2 - +----------------------------+-------+------------------+---------+---------------+---------+ - | Rank | Iperf | High-performance | Default | Memory saving | Minimum | - +============================+=======+==================+=========+===============+=========+ - | Available memory (KB) | 4.1 | 24.2 | 78.4 | 86.5 | 116.4 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | WIFI_STATIC_RX_BUFFER_NUM | 8 |6 | 6 | 4 | 3 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 24 | 18 | 12 | 8 | 6 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | WIFI_DYNAMIC_TX_BUFFER_NUM | 24 | 18 | 12 | 8 | 6 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | WIFI_RX_BA_WIN | 12 | 9 | 6 | 4 | 3 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | TCP_SND_BUF_DEFAULT (KB) | 24 | 18 | 12 | 8 | 6 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | TCP_WND_DEFAULT(KB) | 24 | 18 | 12 | 8 | 6 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 15 | 0 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 16 | 0 | 0 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 0 | 0 | 0 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | INSTRUCTION_CACHE | 16 | 16 | 16 | 16 | 8 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | INSTRUCTION_CACHE_LINE | 16 | 16 | 16 | 16 | 16 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | TCP TX throughput (Mbit/s) | 37.6 | 33.1 | 22.5 | 12.2 | 5.5 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | TCP RX throughput (Mbit/s) | 31.5 | 28.1 | 20.1 | 13.1 | 7.2 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | UDP TX throughput (Mbit/s) | 58.1 | 57.3 | 28.1 | 22.6 | 8.7 | - +----------------------------+-------+------------------+---------+---------------+---------+ - | UDP RX throughput (Mbit/s) | 78.1 | 66.7 | 65.3 | 53.8 | 28.5 | - +----------------------------+-------+------------------+---------+---------------+---------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 10 10 10 + + * - Rank + - Iperf + - High-performance + - Default + - Memory saving + - Minimum + * - Available memory (KB) + - 4.1 + - 24.2 + - 78.4 + - 86.5 + - 116.4 + * - WIFI_STATIC_RX_BUFFER_NUM + - 8 + - 6 + - 6 + - 4 + - 3 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 24 + - 18 + - 12 + - 8 + - 6 + * - WIFI_DYNAMIC_TX_BUFFER_NUM + - 24 + - 18 + - 12 + - 8 + - 6 + * - WIFI_RX_BA_WIN + - 12 + - 9 + - 6 + - 4 + - 3 + * - TCP_SND_BUF_DEFAULT (KB) + - 24 + - 18 + - 12 + - 8 + - 6 + * - TCP_WND_DEFAULT (KB) + - 24 + - 18 + - 12 + - 8 + - 6 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 15 + - 0 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 16 + - 0 + - 0 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 13 + - 0 + - 0 + - 0 + * - INSTRUCTION_CACHE + - 16 + - 16 + - 16 + - 16 + - 8 + * - INSTRUCTION_CACHE_LINE + - 16 + - 16 + - 16 + - 16 + - 16 + * - TCP TX throughput (Mbit/s) + - 37.6 + - 33.1 + - 22.5 + - 12.2 + - 5.5 + * - TCP RX throughput (Mbit/s) + - 31.5 + - 28.1 + - 20.1 + - 13.1 + - 7.2 + * - UDP TX throughput (Mbit/s) + - 58.1 + - 57.3 + - 28.1 + - 22.6 + - 8.7 + * - UDP RX throughput (Mbit/s) + - 78.1 + - 66.7 + - 65.3 + - 53.8 + - 28.5 .. only:: esp32c3 - +----------------------------+-------+---------+---------+ - | Rank | Iperf | Default | Minimum | - +============================+=======+=========+=========+ - | Available memory(KB) | 59 | 160 | 180 | - +----------------------------+-------+---------+---------+ - | WIFI_STATIC_RX_BUFFER_NUM | 20 | 8 | 3 | - +----------------------------+-------+---------+---------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 40 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | WIFI_DYNAMIC_TX_BUFFER_NUM | 40 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | WIFI_RX_BA_WIN | 32 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | TCP_SND_BUF_DEFAULT(KB) | 40 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | TCP_WND_DEFAULT(KB) | 40 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 0 | - +----------------------------+-------+---------+---------+ - | TCP TX throughput (Mbit/s) | 38.1 | 27.2 | 20.4 | - +----------------------------+-------+---------+---------+ - | TCP RX throughput (Mbit/s) | 35.3 | 24.2 | 17.4 | - +----------------------------+-------+---------+---------+ - | UDP TX throughput (Mbit/s) | 40.6 | 38.9 | 34.1 | - +----------------------------+-------+---------+---------+ - | UDP RX throughput (Mbit/s) | 52.4 | 44.5 | 44.2 | - +----------------------------+-------+---------+---------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 15 + + * - Rank + - Iperf + - Default + - Minimum + * - Available memory (KB) + - 59 + - 160 + - 180 + * - WIFI_STATIC_RX_BUFFER_NUM + - 20 + - 8 + - 3 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 40 + - 16 + - 6 + * - WIFI_DYNAMIC_TX_BUFFER_NUM + - 40 + - 16 + - 6 + * - WIFI_RX_BA_WIN + - 32 + - 16 + - 6 + * - TCP_SND_BUF_DEFAULT (KB) + - 40 + - 16 + - 6 + * - TCP_WND_DEFAULT (KB) + - 40 + - 16 + - 6 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 13 + - 0 + * - TCP TX throughput (Mbit/s) + - 38.1 + - 27.2 + - 20.4 + * - TCP RX throughput (Mbit/s) + - 35.3 + - 24.2 + - 17.4 + * - UDP TX throughput (Mbit/s) + - 40.6 + - 38.9 + - 34.1 + * - UDP RX throughput (Mbit/s) + - 52.4 + - 44.5 + - 44.2 .. only:: esp32s3 - +----------------------------+-------+---------+---------+ - | Rank | Iperf | Default | Minimum | - +============================+=======+=========+=========+ - | Available memory(KB) | 133.9 | 183.9 | 273.6 | - +----------------------------+-------+---------+---------+ - | WIFI_STATIC_RX_BUFFER_NUM | 24 | 8 | 3 | - +----------------------------+-------+---------+---------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 64 | 32 | 6 | - +----------------------------+-------+---------+---------+ - | WIFI_DYNAMIC_TX_BUFFER_NUM | 64 | 32 | 6 | - +----------------------------+-------+---------+---------+ - | WIFI_RX_BA_WIN | 32 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | TCP_SND_BUF_DEFAULT (KB) | 64 | 32 | 6 | - +----------------------------+-------+---------+---------+ - | TCP_WND_DEFAULT (KB) | 64 | 32 | 6 | - +----------------------------+-------+---------+---------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | - +----------------------------+-------+---------+---------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 16 | - +----------------------------+-------+---------+---------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 0 | - +----------------------------+-------+---------+---------+ - | INSTRUCTION_CACHE | 32 | 32 | 16 | - +----------------------------+-------+---------+---------+ - | INSTRUCTION_CACHE_LINE | 32 | 32 | 32 | - +----------------------------+-------+---------+---------+ - | INSTRUCTION_CACHE_WAYS | 8 | 8 | 4 | - +----------------------------+-------+---------+---------+ - | TCP TX throughput (Mbit/s) | 83.93 | 64.28 | 23.17 | - +----------------------------+-------+---------+---------+ - | TCP RX throughput (Mbit/s) | 73.98 | 60.39 | 18.11 | - +----------------------------+-------+---------+---------+ - | UDP TX throughput (Mbit/s) | 98.69 | 96.28 | 48.78 | - +----------------------------+-------+---------+---------+ - | UDP RX throughput (Mbit/s) | 88.58 | 86.57 | 59.45 | - +----------------------------+-------+---------+---------+ + .. list-table:: + :header-rows: 1 + :widths: 25 20 25 25 + + * - Rank + - Iperf + - Default + - Minimum + * - Available memory (KB) + - 133.9 + - 183.9 + - 273.6 + * - WIFI_STATIC_RX_BUFFER_NUM + - 24 + - 8 + - 3 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 64 + - 32 + - 6 + * - WIFI_DYNAMIC_TX_BUFFER_NUM + - 64 + - 32 + - 6 + * - WIFI_RX_BA_WIN + - 32 + - 16 + - 6 + * - TCP_SND_BUF_DEFAULT (KB) + - 64 + - 32 + - 6 + * - TCP_WND_DEFAULT (KB) + - 64 + - 32 + - 6 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 16 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 13 + - 0 + * - INSTRUCTION_CACHE + - 32 + - 32 + - 16 + * - INSTRUCTION_CACHE_LINE + - 32 + - 32 + - 32 + * - INSTRUCTION_CACHE_WAYS + - 8 + - 8 + - 4 + * - TCP TX throughput (Mbit/s) + - 83.93 + - 64.28 + - 23.17 + * - TCP RX throughput (Mbit/s) + - 73.98 + - 60.39 + - 18.11 + * - UDP TX throughput (Mbit/s) + - 98.69 + - 96.28 + - 48.78 + * - UDP RX throughput (Mbit/s) + - 88.58 + - 86.57 + - 59.45 .. only:: esp32 or esp32s3 @@ -2222,79 +2368,187 @@ The parameters not mentioned in the following table should be set to the default .. only:: esp32 - +----------------------------+-------+---------+---------------+---------+ - | Rank | Iperf | Default | Memory saving | Minimum | - +============================+=======+=========+===============+=========+ - | Available memory (KB) | 113.8 | 152.4 | 181.2 | 202.6 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_STATIC_RX_BUFFER_NUM | 16 | 8 | 4 | 2 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 128 | 128 | 128 | 128 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_STATIC_TX_BUFFER_NUM | 16 | 8 | 4 | 2 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_RX_BA_WIN | 16 | 16 | 8 | Disable | - +----------------------------+-------+---------+---------------+---------+ - | TCP_SND_BUF_DEFAULT (KB) | 65 | 65 | 65 | 65 | - +----------------------------+-------+---------+---------------+---------+ - | TCP_WND_DEFAULT (KB) | 65 | 65 | 65 | 65 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | - +----------------------------+-------+---------+---------------+---------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | - +----------------------------+-------+---------+---------------+---------+ - | TCP TX throughput (Mbit/s) | 37.5 | 31.7 | 21.7 | 14.6 | - +----------------------------+-------+---------+---------------+---------+ - | TCP RX throughput (Mbit/s) | 31.5 | 29.8 | 26.5 | 21.1 | - +----------------------------+-------+---------+---------------+---------+ - | UDP TX throughput (Mbit/s) | 69.1 | 31.5 | 27.1 | 24.1 | - +----------------------------+-------+---------+---------------+---------+ - | UDP RX throughput (Mbit/s) | 40.1 | 38.5 | 37.5 | 36.9 | - +----------------------------+-------+---------+---------------+---------+ + .. list-table:: + :header-rows: 1 + :widths: 15 10 10 15 10 + + * - Rank + - Iperf + - Default + - Memory saving + - Minimum + * - Available memory (KB) + - 113.8 + - 152.4 + - 181.2 + - 202.6 + * - WIFI_STATIC_RX_BUFFER_NUM + - 16 + - 8 + - 4 + - 2 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 128 + - 128 + - 128 + - 128 + * - WIFI_STATIC_TX_BUFFER_NUM + - 16 + - 8 + - 4 + - 2 + * - WIFI_RX_BA_WIN + - 16 + - 16 + - 8 + - Disable + * - TCP_SND_BUF_DEFAULT (KB) + - 65 + - 65 + - 65 + - 65 + * - TCP_WND_DEFAULT (KB) + - 65 + - 65 + - 65 + - 65 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 0 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 0 + - 0 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 0 + - 0 + - 0 + * - TCP TX throughput (Mbit/s) + - 37.5 + - 31.7 + - 21.7 + - 14.6 + * - TCP RX throughput (Mbit/s) + - 31.5 + - 29.8 + - 26.5 + - 21.1 + * - UDP TX throughput (Mbit/s) + - 69.1 + - 31.5 + - 27.1 + - 24.1 + * - UDP RX throughput (Mbit/s) + - 40.1 + - 38.5 + - 37.5 + - 36.9 .. only:: esp32s2 - +----------------------------+-------+---------+---------------+---------+ - | Rank | Iperf | Default | Memory saving | Minimum | - +============================+=======+=========+===============+=========+ - | Available memory (KB) | 70.6 | 96.4 | 118.8 | 148.2 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_STATIC_RX_BUFFER_NUM | 8 | 8 | 6 | 4 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 64 | 64 | 64 | 64 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_STATIC_TX_BUFFER_NUM | 16 | 8 | 6 | 4 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_RX_BA_WIN | 16 | 6 | 6 | Disable | - +----------------------------+-------+---------+---------------+---------+ - | TCP_SND_BUF_DEFAULT (KB) | 32 | 32 | 32 | 32 | - +----------------------------+-------+---------+---------------+---------+ - | TCP_WND_DEFAULT (KB) | 32 | 32 | 32 | 32 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | - +----------------------------+-------+---------+---------------+---------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | - +----------------------------+-------+---------+---------------+---------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | - +----------------------------+-------+---------+---------------+---------+ - | INSTRUCTION_CACHE | 16 | 16 | 16 | 8 | - +----------------------------+-------+---------+---------------+---------+ - | INSTRUCTION_CACHE_LINE | 16 | 16 | 16 | 16 | - +----------------------------+-------+---------+---------------+---------+ - | DATA_CACHE | 8 | 8 | 8 | 8 | - +----------------------------+-------+---------+---------------+---------+ - | DATA_CACHE_LINE | 32 | 32 | 32 | 32 | - +----------------------------+-------+---------+---------------+---------+ - | TCP TX throughput (Mbit/s) | 40.1 | 29.2 | 20.1 | 8.9 | - +----------------------------+-------+---------+---------------+---------+ - | TCP RX throughput (Mbit/s) | 21.9 | 16.8 | 14.8 | 9.6 | - +----------------------------+-------+---------+---------------+---------+ - | UDP TX throughput (Mbit/s) | 50.1 | 25.7 | 22.4 | 10.2 | - +----------------------------+-------+---------+---------------+---------+ - | UDP RX throughput (Mbit/s) | 45.3 | 43.1 | 28.5 | 15.1 | - +----------------------------+-------+---------+---------------+---------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 10 15 + + * - Rank + - Iperf + - Default + - Memory saving + - Minimum + * - Available memory (KB) + - 70.6 + - 96.4 + - 118.8 + - 148.2 + * - WIFI_STATIC_RX_BUFFER_NUM + - 8 + - 8 + - 6 + - 4 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 64 + - 64 + - 64 + - 64 + * - WIFI_STATIC_TX_BUFFER_NUM + - 16 + - 8 + - 6 + - 4 + * - WIFI_RX_BA_WIN + - 16 + - 6 + - 6 + - Disable + * - TCP_SND_BUF_DEFAULT (KB) + - 32 + - 32 + - 32 + - 32 + * - TCP_WND_DEFAULT (KB) + - 32 + - 32 + - 32 + - 32 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 0 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 0 + - 0 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 0 + - 0 + - 0 + * - INSTRUCTION_CACHE + - 16 + - 16 + - 16 + - 8 + * - INSTRUCTION_CACHE_LINE + - 16 + - 16 + - 16 + - 16 + * - DATA_CACHE + - 8 + - 8 + - 8 + - 8 + * - DATA_CACHE_LINE + - 32 + - 32 + - 32 + - 32 + * - TCP TX throughput (Mbit/s) + - 40.1 + - 29.2 + - 20.1 + - 8.9 + * - TCP RX throughput (Mbit/s) + - 21.9 + - 16.8 + - 14.8 + - 9.6 + * - UDP TX throughput (Mbit/s) + - 50.1 + - 25.7 + - 22.4 + - 10.2 + * - UDP RX throughput (Mbit/s) + - 45.3 + - 43.1 + - 28.5 + - 15.1 .. note:: Reaching peak performance may cause task watchdog. It is a normal phenomenon considering the CPU may have no time for lower priority tasks. @@ -2303,99 +2557,238 @@ The parameters not mentioned in the following table should be set to the default **PSRAM with 4 lines:** - +----------------------------+-------+--------+---------------+----------+ - | Rank | Iperf | Default| Memory saving | Minimum | - +============================+=======+========+===============+==========+ - | Available memory (KB) | 50.3 | 158.7 | 198.2 | 228.9 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_STATIC_RX_BUFFER_NUM | 24 | 8 | 6 | 4 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 85 | 64 | 32 | 32 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_STATIC_TX_BUFFER_NUM | 32 | 32 | 6 | 4 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_RX_BA_WIN | 32 | 16 | 12 | Disable | - +----------------------------+-------+--------+---------------+----------+ - | TCP_SND_BUF_DEFAULT (KB) | 85 | 32 | 32 | 32 | - +----------------------------+-------+--------+---------------+----------+ - | TCP_WND_DEFAULT (KB) | 85 | 32 | 32 | 32 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | - +----------------------------+-------+--------+---------------+----------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | - +----------------------------+-------+--------+---------------+----------+ - | LWIP_UDP_RECVMBOX_SIZE | 16 | 16 | 16 | 16 | - +----------------------------+-------+--------+---------------+----------+ - | INSTRUCTION_CACHE | 32 | 16 | 16 | 16 | - +----------------------------+-------+--------+---------------+----------+ - | INSTRUCTION_CACHE_LINE | 32 | 16 | 16 | 16 | - +----------------------------+-------+--------+---------------+----------+ - | INSTRUCTION_CACHE_WAYS | 8 | 8 | 8 | 8 | - +----------------------------+-------+--------+---------------+----------+ - | DATA_CACHE | 64 | 16 | 16 | 16 | - +----------------------------+-------+--------+---------------+----------+ - | DATA_CACHE_LINE | 32 | 32 | 32 | 32 | - +----------------------------+-------+--------+---------------+----------+ - | DATA_CACHE_WAYS | 8 | 8 | 8 | 8 | - +----------------------------+-------+--------+---------------+----------+ - | TCP TX throughput (Mbit/s) | 93.1 | 62.5 | 41.3 | 42.7 | - +----------------------------+-------+--------+---------------+----------+ - | TCP RX throughput (Mbit/s) | 88.9 | 46.5 | 46.2 | 37.9 | - +----------------------------+-------+--------+---------------+----------+ - | UDP TX throughput (Mbit/s) | 106.4 | 106.2 | 60.7 | 50.0 | - +----------------------------+-------+--------+---------------+----------+ - | UDP RX throughput (Mbit/s) | 99.8 | 92.6 | 94.3 | 53.3 | - +----------------------------+-------+--------+---------------+----------+ + .. list-table:: + :header-rows: 1 + :widths: 25 20 25 25 25 + + * - Rank + - Iperf + - Default + - Memory saving + - Minimum + * - Available memory (KB) + - 50.3 + - 158.7 + - 198.2 + - 228.9 + * - WIFI_STATIC_RX_BUFFER_NUM + - 24 + - 8 + - 6 + - 4 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 85 + - 64 + - 32 + - 32 + * - WIFI_STATIC_TX_BUFFER_NUM + - 32 + - 32 + - 6 + - 4 + * - WIFI_RX_BA_WIN + - 32 + - 16 + - 12 + - Disable + * - TCP_SND_BUF_DEFAULT (KB) + - 85 + - 32 + - 32 + - 32 + * - TCP_WND_DEFAULT (KB) + - 85 + - 32 + - 32 + - 32 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 0 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 0 + - 0 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 0 + - 0 + - 0 + * - LWIP_UDP_RECVMBOX_SIZE + - 16 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE + - 32 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE_LINE + - 32 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE_WAYS + - 8 + - 8 + - 8 + - 8 + * - DATA_CACHE + - 64 + - 16 + - 16 + - 16 + * - DATA_CACHE_LINE + - 32 + - 32 + - 32 + - 32 + * - DATA_CACHE_WAYS + - 8 + - 8 + - 8 + - 8 + * - TCP TX throughput (Mbit/s) + - 93.1 + - 62.5 + - 41.3 + - 42.7 + * - TCP RX throughput (Mbit/s) + - 88.9 + - 46.5 + - 46.2 + - 37.9 + * - UDP TX throughput (Mbit/s) + - 106.4 + - 106.2 + - 60.7 + - 50 + * - UDP RX throughput (Mbit/s) + - 99.8 + - 92.6 + - 94.3 + - 53.3 **PSRAM with 8 lines:** - +----------------------------+-------+--------+---------------+----------+ - | Rank | Iperf | Default| Memory saving | Minimum | - +============================+=======+========+===============+==========+ - | Available memory (KB) | 49.1 | 151.3 | 215.3 | 243.6 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_STATIC_RX_BUFFER_NUM | 24 | 8 | 6 | 4 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 85 | 64 | 32 | 32 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_STATIC_TX_BUFFER_NUM | 32 | 32 | 6 | 4 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_RX_BA_WIN | 32 | 16 | 12 | Disable | - +----------------------------+-------+--------+---------------+----------+ - | TCP_SND_BUF_DEFAULT (KB) | 85 | 32 | 32 | 32 | - +----------------------------+-------+--------+---------------+----------+ - | TCP_WND_DEFAULT (KB) | 85 | 32 | 32 | 32 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | - +----------------------------+-------+--------+---------------+----------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | - +----------------------------+-------+--------+---------------+----------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | - +----------------------------+-------+--------+---------------+----------+ - | LWIP_UDP_RECVMBOX_SIZE | 16 | 16 | 16 | 16 | - +----------------------------+-------+--------+---------------+----------+ - | INSTRUCTION_CACHE | 32 | 16 | 16 | 16 | - +----------------------------+-------+--------+---------------+----------+ - | INSTRUCTION_CACHE_LINE | 32 | 16 | 16 | 16 | - +----------------------------+-------+--------+---------------+----------+ - | INSTRUCTION_CACHE_WAYS | 8 | 8 | 8 | 8 | - +----------------------------+-------+--------+---------------+----------+ - | DATA_CACHE | 64 | 16 | 16 | 16 | - +----------------------------+-------+--------+---------------+----------+ - | DATA_CACHE_LINE | 32 | 32 | 32 | 32 | - +----------------------------+-------+--------+---------------+----------+ - | DATA_CACHE_WAYS | 8 | 8 | 8 | 8 | - +----------------------------+-------+--------+---------------+----------+ - | TCP TX throughput (Mbit/s) | 93.3 | 58.4 | 37.1 | 35.6 | - +----------------------------+-------+--------+---------------+----------+ - | TCP RX throughput (Mbit/s) | 86.1 | 43.6 | 42.5 | 35.0 | - +----------------------------+-------+--------+---------------+----------+ - | UDP TX throughput (Mbit/s) | 104.7 | 82.2 | 60.4 | 47.9 | - +----------------------------+-------+--------+---------------+----------+ - | UDP RX throughput (Mbit/s) | 104.6 |104.8 | 104.0 | 55.7 | - +----------------------------+-------+--------+---------------+----------+ + .. list-table:: + :header-rows: 1 + :widths: 25 20 25 25 25 + + * - Rank + - Iperf + - Default + - Memory saving + - Minimum + * - Available memory (KB) + - 49.1 + - 151.3 + - 215.3 + - 243.6 + * - WIFI_STATIC_RX_BUFFER_NUM + - 24 + - 8 + - 6 + - 4 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 85 + - 64 + - 32 + - 32 + * - WIFI_STATIC_TX_BUFFER_NUM + - 32 + - 32 + - 6 + - 4 + * - WIFI_RX_BA_WIN + - 32 + - 16 + - 12 + - Disable + * - TCP_SND_BUF_DEFAULT (KB) + - 85 + - 32 + - 32 + - 32 + * - TCP_WND_DEFAULT (KB) + - 85 + - 32 + - 32 + - 32 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 0 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 0 + - 0 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 0 + - 0 + - 0 + * - LWIP_UDP_RECVMBOX_SIZE + - 16 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE + - 32 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE_LINE + - 32 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE_WAYS + - 8 + - 8 + - 8 + - 8 + * - DATA_CACHE + - 64 + - 16 + - 16 + - 16 + * - DATA_CACHE_LINE + - 32 + - 32 + - 32 + - 32 + * - DATA_CACHE_WAYS + - 8 + - 8 + - 8 + - 8 + * - TCP TX throughput (Mbit/s) + - 93.3 + - 58.4 + - 37.1 + - 35.6 + * - TCP RX throughput (Mbit/s) + - 86.1 + - 43.6 + - 42.5 + - 35 + * - UDP TX throughput (Mbit/s) + - 104.7 + - 82.2 + - 60.4 + - 47.9 + * - UDP RX throughput (Mbit/s) + - 104.6 + - 104.8 + - 104 + - 55.7 + Wi-Fi Menuconfig ----------------------- @@ -2481,80 +2874,58 @@ Description: The diagram shows the configuration of the Wi-Fi internal buffer. -+------------------+------------+------------+--------------+---------------------------------------+ -| Buffer Type | Alloc Type | Default | Configurable | Description | -+==================+============+============+==============+=======================================+ -| Static RX Buffer | Static | 10 * | Yes | This is a kind of DMA memory. It is | -| (Hardware RX | | 1600 Bytes | | initialized in | -| Buffer) | | | | :cpp:func:`esp_wifi_init()` and freed | -| | | | | in :cpp:func:`esp_wifi_deinit()`. The | -| | | | | 'Static Rx Buffer' forms the hardware | -| | | | | receiving list. Upon receiving a frame| -| | | | | over the air, hardware writes the | -| | | | | frame into the buffer and raises an | -| | | | | interrupt to the CPU. Then, the Wi-Fi | -| | | | | driver reads the content from the | -| | | | | buffer and returns the buffer back to | -| | | | | the list. | -| | | | | | -| | | | | If the application want to reduce the | -| | | | | the memory statically allocated by | -| | | | | Wi-Fi, they can reduce this value from| -| | | | | 10 to 6 to save 6400 Bytes memory. | -| | | | | It's not recommended to reduce the | -| | | | | configuration to a value less than 6 | -| | | | | unless the AMPDU feature is disabled. | -| | | | | | -+------------------+------------+------------+--------------+---------------------------------------+ -| Dynamic RX Buffer| Dynamic | 32 | Yes | The buffer length is variable and it | -| | | | | depends on the received frames' | -| | | | | length. When the Wi-Fi driver receives| -| | | | | a frame from the 'Hardware Rx Buffer',| -| | | | | the 'Dynamic Rx Buffer' needs to be | -| | | | | allocated from the heap. The number of| -| | | | | the Dynamic Rx Buffer, configured in | -| | | | | the menuconfig, is used to limit the | -| | | | | total un-freed Dynamic Rx Buffer | -| | | | | number. | -+------------------+------------+------------+--------------+---------------------------------------+ -| Dynamic TX Buffer| Dynamic | 32 | Yes | This is a kind of DMA memory. It is | -| | | | | allocated to the heap. When the upper-| -| | | | | layer (LwIP) sends packets to the | -| | | | | Wi-Fi driver, it firstly allocates a | -| | | | | 'Dynamic TX Buffer' and makes a copy | -| | | | | of the upper-layer buffer. | -| | | | | | -| | | | | The Dynamic and Static TX Buffers are | -| | | | | mutually exclusive. | -+------------------+------------+------------+--------------+---------------------------------------+ -| Static TX Buffer | Static | 16 * | Yes | This is a kind of DMA memory. It is | -| | | 1600Bytes | | initialized in | -| | | | | :cpp:func:`esp_wifi_init()` and freed | -| | | | | in :cpp:func:`esp_wifi_deinit()`. When| -| | | | | the upper-layer (LwIP) sends packets | -| | | | | to the Wi-Fi driver, it firstly | -| | | | | allocates a 'Static TX Buffer' and | -| | | | | makes a copy of the upper-layer | -| | | | | buffer. | -| | | | | | -| | | | | The Dynamic and Static TX Buffer are | -| | | | | mutually exclusive. | -| | | | | | -| | | | | Since the TX buffer must be DMA | -| | | | | buffer, so when PSRAM is enabled, the | -| | | | | TX buffer must be static. | -+------------------+------------+------------+--------------+---------------------------------------+ -| Management Short | Dynamic | 8 | NO | Wi-Fi driver's internal buffer. | -| Buffer | | | | | -+------------------+------------+------------+--------------+---------------------------------------+ -| Management Long | Dynamic | 32 | NO | Wi-Fi driver's internal buffer. | -| Buffer | | | | | -+------------------+------------+------------+--------------+---------------------------------------+ -| Management Long | Dynamic | 32 | NO | Wi-Fi driver's internal buffer. | -| Long Buffer | | | | | -+------------------+------------+------------+--------------+---------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 10 10 10 10 25 + * - Buffer Type + - Alloc Type + - Default + - Configurable + - Description + * - Static RX Buffer (Hardware RX Buffer) + - Static + - 10 * 1600 Bytes + - Yes + - This is a kind of DMA memory. It is initialized in :cpp:func:`esp_wifi_init()` and freed in :cpp:func:`esp_wifi_deinit()`. The ‘Static Rx Buffer’ forms the hardware receiving list. Upon receiving a frame over the air, hardware writes the frame into the buffer and raises an interrupt to the CPU. Then, the Wi-Fi driver reads the content from the buffer and returns the buffer back to the list. + If the application want to reduce the the memory statically allocated by Wi-Fi, they can reduce this value from 10 to 6 to save 6400 Bytes memory. It’s not recommended to reduce the configuration to a value less than 6 unless the AMPDU feature is disabled. + * - Dynamic RX Buffer + - Dynamic + - 32 + - Yes + - The buffer length is variable and it depends on the received frames’ length. When the Wi-Fi driver receives a frame from the ‘Hardware Rx Buffer’, the ‘Dynamic Rx Buffer’ needs to be allocated from the heap. The number of the Dynamic Rx Buffer, configured in the menuconfig, is used to limit the total un-freed Dynamic Rx Buffer number. + * - Dynamic TX Buffer + - Dynamic + - 32 + - Yes + - This is a kind of DMA memory. It is allocated to the heap. When the upper- layer (LwIP) sends packets to the Wi-Fi driver, it firstly allocates a ‘Dynamic TX Buffer’ and makes a copy of the upper-layer buffer. + + The Dynamic and Static TX Buffers are mutually exclusive. + * - Static TX Buffer + - Static + - 16 * 1600Bytes + - Yes + - This is a kind of DMA memory. It is initialized in :cpp:func:`esp_wifi_init()` and freed in :cpp:func:`esp_wifi_deinit()`. When the upper-layer (LwIP) sends packets to the Wi-Fi driver, it firstly allocates a ‘Static TX Buffer’ and makes a copy of the upper-layer buffer. + + The Dynamic and Static TX Buffer are mutually exclusive. + + Since the TX buffer must be DMA buffer, so when PSRAM is enabled, the TX buffer must be static. + * - Management Short Buffer + - Dynamic + - 8 + - NO + - Wi-Fi driver’s internal buffer. + * - Management Long Buffer + - Dynamic + - 32 + - NO + - Wi-Fi driver’s internal buffer. + * - Management Long Long Buffer + - Dynamic + - 32 + - NO + - Wi-Fi driver’s internal buffer. Wi-Fi NVS Flash +++++++++++++++++++++ diff --git a/docs/zh_CN/api-guides/wifi.rst b/docs/zh_CN/api-guides/wifi.rst index 397b55fd5b..3df58418f9 100644 --- a/docs/zh_CN/api-guides/wifi.rst +++ b/docs/zh_CN/api-guides/wifi.rst @@ -1,18 +1,18 @@ Wi-Fi 驱动程序 ================== + :link_to_translation:`en:[English]` {IDF_TARGET_NAME} Wi-Fi 功能列表 ------------------------------------ - 支持仅 station 模式、仅 AP 模式、station/AP 共存模式 -- 支持使用 IEEE 802.11B、IEEE 802.11G、IEEE 802.11N 和 API 配置协议模式 -- 支持 WPA/WPA2/WPA2-企业版和 WPS +- 支持使用 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 -- 支持用于 Wi-Fi 连接的 fast_crypto 算法与普通算法的切换 - 支持快速扫描和全信道扫描 - 支持多个天线 - 支持获取信道状态信息 @@ -40,7 +40,7 @@ Wi-Fi 初始化 事件处理 ++++++++++++++ -通常，在晴好环境下编写代码难度并不大，如 `WIFI_EVENT_STA_START`_、`WIFI_EVENT_STA_CONNECTED`_ 中所述。难度在于如何在阴翳的困难环境下编写代码，如 `WIFI_EVENT_STA_DISCONNECTED`_ 中所述。能否在后者情况下完美地解决各类事件冲突，是编写一个强健的 Wi-Fi 应用程序的根本。请参阅 `{IDF_TARGET_NAME} Wi-Fi station 一般情况`_、`{IDF_TARGET_NAME} Wi-Fi AP 一般情况`_。另可参阅 ESP-IDF 中的事件处理概述 `Event Handling `_。 +通常，在理想环境下编写代码难度并不大，如 `WIFI_EVENT_STA_START`_、`WIFI_EVENT_STA_CONNECTED`_ 中所述。难度在于如何在现实的困难环境下编写代码，如 `WIFI_EVENT_STA_DISCONNECTED`_ 中所述。能否在后者情况下完美地解决各类事件冲突，是编写一个强健的 Wi-Fi 应用程序的根本。请参阅 `{IDF_TARGET_NAME} Wi-Fi 事件描述`_, `{IDF_TARGET_NAME} Wi-Fi station 一般情况`_, `{IDF_TARGET_NAME} Wi-Fi AP 一般情况`_。另可参阅 ESP-IDF 中的 `事件处理概述 `_。 编写错误恢复程序 ++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -64,7 +64,7 @@ Wi-Fi 初始化 - 不可恢复非关键性错误，打印错误代码可以帮助您更好地处理该类错误。 - 不可恢复关键性错误，可使用 "assert" 语句处理该类错误。例如，如果 :cpp:func:`esp_wifi_set_mode` 返回 ESP_ERR_WIFI_NOT_INIT，该值意为 :cpp:func:`esp_wifi_init` 未成功初始化 Wi-Fi 驱动程序。您可以在应用程序开发阶段非常快速地检测到此类错误。 -在 esp_err.h 中，ESP_ERROR_CHECK 负责检查返回值。这是一个较为常见的错误处理代码，可在应用程序开发阶段作为默认的错误处理代码。但是，我们强烈建议 API 的使用者自己编写错误处理代码。 +在 esp_err.h 中，ESP_ERROR_CHECK 负责检查返回值。这是一个较为常见的错误处理代码，可在应用程序开发阶段作为默认的错误处理代码。但是，我们强烈建议 API 的使用者编写自己的错误处理代码。 初始化 {IDF_TARGET_NAME} Wi-Fi API 参数 ---------------------------------------------------- @@ -128,6 +128,7 @@ Wi-Fi 驱动程序可以看作是一个无法感知上层代码（如 TCP/IP 堆 Wi-Fi 事件处理是在 :doc:`esp_event 库 <../api-reference/system/esp_event>` 的基础上进行的。Wi-Fi 驱动程序将事件发送至 :ref:`默认事件循环 `，应用程序便可以使用 :cpp:func:`esp_event_handler_register` 中的回调函数处理这些事件。除此之外，:doc:`esp_netif 组件 <../api-reference/network/esp_netif>` 也负责处理 Wi-Fi 事件，并产生一系列默认行为。例如，当 Wi-Fi station 连接至一个 AP 时，esp_netif 将自动开启 DHCP 客户端服务（系统默认）。 + {IDF_TARGET_NAME} Wi-Fi 事件描述 ----------------------------------------- @@ -167,9 +168,9 @@ WIFI_EVENT_STA_DISCONNECTED ++++++++++++++++++++++++++++++++++++ 此事件将在以下情况下产生： - - 调用了函数 :cpp:func:`esp_wifi_disconnect()`、:cpp:func:`esp_wifi_stop()` 或 :cpp:func:`esp_wifi_deinit()`，且 Wi-Fi station 已成功连接至 AP。 + - 调用了函数 :cpp:func:`esp_wifi_disconnect()` 或 :cpp:func:`esp_wifi_stop()`，且 Wi-Fi station 已成功连接至 AP。 - 调用了函数 :cpp:func:`esp_wifi_connect()`，但 Wi-Fi 驱动程序因为某些原因未能成功连接至 AP，例如：未扫描到目标 AP、验证超时等。或存在多个 SSID 相同的 AP，station 无法连接所有已找到的 AP，也将产生该事件。 - - Wi-Fi 连接因为某些原因而中断，例如：station 连续多次丢失 N beacon、AP 脱离 station 连接、AP 验证模式改变等。 + - Wi-Fi 连接因为某些原因而中断，例如：station 连续多次丢失 N beacon、AP 踢掉 station、AP 认证模式改变等。 接收到此事件后，事件任务的默认动作为： @@ -178,7 +179,7 @@ WIFI_EVENT_STA_DISCONNECTED 应用程序处理此事件最常用的方法为：调用函数 :cpp:func:`esp_wifi_connect()` 重新连接 Wi-Fi。但是，如果此事件是由函数 :cpp:func:`esp_wifi_disconnect()` 引发的，则应用程序不应调用 :cpp:func:`esp_wifi_connect()` 来重新连接。应用程序须明确区分此事件的引发原因，因为某些情况下应使用其它更好的方式进行重新连接。请参阅 `Wi-Fi 重新连接`_ 和 `连接 Wi-Fi 时扫描`_。 -需要注意的另一点是：接收到此事件后，LwIP 的默认动作为终止所有 TCP 套接字连接。大多数情况下，该动作不会造成影响。但对某些特殊应用程序可能除外。例如： +需要注意的另一点是：接收到此事件后，LwIP 的默认动作是终止所有 TCP 套接字连接。大多数情况下，该动作不会造成影响。但对某些特殊应用程序可能除外。例如： - 应用程序创建一个了 TCP 连接，以维护每 60 秒发送一次的应用程序级、保持活动状态的数据。 - 由于某些原因，Wi-Fi 连接被切断并引发了 `WIFI_EVENT_STA_DISCONNECTED` 事件。根据当前实现，此时所有 TCP 连接都将被移除，且保持活动的套接字将处于错误的状态中。但是，由于应用程序设计者认为网络层 **不应** 考虑这个 Wi-Fi 层的错误，因此应用程序不会关闭套接字。 @@ -223,7 +224,7 @@ WIFI_EVENT_AP_STOP WIFI_EVENT_AP_STACONNECTED ++++++++++++++++++++++++++++++++++++ -每当有一个 station 成功连接 {IDF_TARGET_NAME} AP 时，将引发此事件。接收到此事件后，事件任务将不做任何响应，应用程序的回调函数也可忽略这一事件。但是，您可以在此时进行一些操作，例如：获取已连接 STA 的信息等。 +每当有一个 station 成功连接 {IDF_TARGET_NAME} AP 时，将引发此事件。接收到此事件后，事件任务将不做任何响应，应用程序的回调函数也可忽略这一事件。但是，您可以在此时进行一些操作，例如：获取已连接 station 的信息等。 WIFI_EVENT_AP_STADISCONNECTED ++++++++++++++++++++++++++++++++++++ @@ -264,42 +265,42 @@ WIFI_EVENT_AP_PROBEREQRECVED LwIP_TASK [label = "LwIP\ntask"]; WIFI_TASK [label = "Wi-Fi\ntask"]; - === 1.初始化阶段 === + === 1. 初始化阶段 === MAIN_TASK -> LwIP_TASK [label="1.1> 创建/初始化 LwIP"]; MAIN_TASK -> EVENT_TASK [label="1.2> 创建/初始化事件"]; MAIN_TASK -> WIFI_TASK [label="1.3> 创建/初始化 Wi-Fi"]; MAIN_TASK -> APP_TASK [label="1.4> 创建应用程序任务"]; - === 2.配置阶段 === + === 2. 配置阶段 === MAIN_TASK -> WIFI_TASK [label="2> 配置 Wi-Fi"]; - === 3.启动阶段 === + === 3. 启动阶段 === MAIN_TASK -> WIFI_TASK [label="3.1> 启动 Wi-Fi"]; EVENT_TASK <- WIFI_TASK [label="3.2> WIFI_EVENT_STA_START"]; APP_TASK <- EVENT_TASK [label="3.3> WIFI_EVENT_STA_START"]; - === 4.连接阶段 === + === 4. 连接阶段 === APP_TASK -> WIFI_TASK [label="4.1> 连接 Wi-Fi"]; EVENT_TASK <- WIFI_TASK [label="4.2> WIFI_EVENT_STA_CONNECTED"]; APP_TASK <- EVENT_TASK [label="4.3> WIFI_EVENT_STA_CONNECTED"]; - === 5.获取 IP 阶段 === + === 5. 获取 IP 阶段 === EVENT_TASK -> LwIP_TASK [label="5.1> 启动 DHCP 客户端"]; EVENT_TASK <- LwIP_TASK [label="5.2> IP_EVENT_STA_GOT_IP"]; APP_TASK <- EVENT_TASK [label="5.3> IP_EVENT_STA_GOT_IP"]; APP_TASK -> APP_TASK [label="5.4> 套接字相关初始化"]; - === 6.断开阶段 === + === 6. 断开阶段 === EVENT_TASK <- WIFI_TASK [label="6.1> WIFI_EVENT_STA_DISCONNECTED"]; APP_TASK <- EVENT_TASK [label="6.2> WIFI_EVENT_STA_DISCONNECTED"]; APP_TASK -> APP_TASK [label="6.3> 断开处理"]; - === 7.IP 更改阶段 === + === 7. IP 更改阶段 === EVENT_TASK <- LwIP_TASK [label="7.1> IP_EVENT_STA_GOT_IP"]; APP_TASK <- EVENT_TASK [label="7.2> IP_EVENT_STA_GOT_IP"]; APP_TASK -> APP_TASK [label="7.3> 套接字错误处理"]; - === 8.清理阶段 === + === 8. 清理阶段 === APP_TASK -> WIFI_TASK [label="8.1> 断开 Wi-Fi 连接"]; APP_TASK -> WIFI_TASK [label="8.2> 终止 Wi-Fi"]; APP_TASK -> WIFI_TASK [label="8.3> 清理 Wi-Fi"]; } -1.Wi-Fi/LwIP 初始化阶段 +1. Wi-Fi/LwIP 初始化阶段 ++++++++++++++++++++++++++++++ - s1.1：主任务通过调用函数 :cpp:func:`esp_netif_init()` 创建一个 LwIP 核心任务，并初始化 LwIP 相关工作。 @@ -313,7 +314,7 @@ WIFI_EVENT_AP_PROBEREQRECVED 推荐按照 s1.1 ~ s1.5 的步骤顺序针对基于 Wi-Fi/LwIP 的应用程序进行初始化。但这一顺序 **并非** 强制，您可以在第 s1.1 步创建应用程序任务，然后在该应用程序任务中进行所有其它初始化操作。不过，如果您的应用程序任务依赖套接字，那么在初始化阶段创建应用程序任务可能并不适用。此时，您可以在接收到 IP 后再进行任务创建。 -2.Wi-Fi 配置阶段 +2. Wi-Fi 配置阶段 +++++++++++++++++++++++++++++++ Wi-Fi 驱动程序初始化成功后，可以进入到配置阶段。该场景下，Wi-Fi 驱动程序处于 station 模式。因此，首先您需调用函数 :cpp:func:`esp_wifi_set_mode` (WIFI_MODE_STA) 将 Wi-Fi 模式配置为 station 模式。可通过调用其它 esp_wifi_set_xxx API 进行更多设置，例如：协议模式、国家代码、带宽等。请参阅 `{IDF_TARGET_NAME} Wi-Fi 配置`_。 @@ -321,13 +322,13 @@ Wi-Fi 驱动程序初始化成功后，可以进入到配置阶段。该场景 如果 menuconfig 已使能 Wi-Fi NVS flash，则不论当前阶段还是后续的 Wi-Fi 配置信息都将被存储至该 flash 中。那么，当主板上电/重新启动时，就不需从头开始配置 Wi-Fi 驱动程序。您只需调用函数 esp_wifi_get_xxx API 获取之前存储的配置信息。当然，如果不想使用之前的配置，您依然可以重新配置 Wi-Fi 驱动程序。 -3.Wi-Fi 启动阶段 +3. Wi-Fi 启动阶段 ++++++++++++++++++++++++++++++++ - s3.1：调用函数 :cpp:func:`esp_wifi_start()` 启动 Wi-Fi 驱动程序。 - s3.2：Wi-Fi 驱动程序将事件 `WIFI_EVENT_STA_START`_ 发布到事件任务中，然后，事件任务将执行一些正常操作并调用应用程序的事件回调函数。 - s3.3：应用程序的事件回调函数将事件 `WIFI_EVENT_STA_START`_ 中继到应用程序任务中。推荐您此时调用函数 :cpp:func:`esp_wifi_connect()` 进行 Wi-Fi 连接。当然，您也可以等待在 `WIFI_EVENT_STA_START`_ 事件发生后的其它阶段再调用此函数。 -4.Wi-Fi 连接阶段 +4. Wi-Fi 连接阶段 +++++++++++++++++++++++++++++++++ - s4.1：调用函数 :cpp:func:`esp_wifi_connect()` 后，Wi-Fi 驱动程序将启动内部扫描/连接过程。 @@ -337,26 +338,26 @@ Wi-Fi 驱动程序初始化成功后，可以进入到配置阶段。该场景 步骤 s4.2 中 Wi-Fi 连接可能会由于某些原因而失败，例如：密码错误、未找到 AP 等。这种情况下，将引发 `WIFI_EVENT_STA_DISCONNECTED`_ 事件并提示连接错误原因。有关如何处理中断 Wi-Fi 连接的事件，请参阅下文阶段 6 的描述。 -5.Wi-Fi 获取 IP 阶段 +5. Wi-Fi 获取 IP 阶段 +++++++++++++++++++++++++++++++++ - s5.1：一旦步骤 4.2 中的 DHCP 客户端初始化完成，Wi-Fi 驱动程序将进入 *获取 IP* 阶段。 - s5.2：如果 Wi-Fi 成功从 DHCP 服务器接收到 IP 地址，则将引发 `IP_EVENT_STA_GOT_IP`_ 事件，事件任务将执行正常处理。 - s5.3：应用程序的事件回调函数将事件 `IP_EVENT_STA_GOT_IP`_ 中继到应用程序任务中。对于那些基于 LwIP 构建的应用程序，此事件较为特殊，因为它意味着应用程序已准备就绪，可以开始任务，例如：创建 TCP/UDP 套接字等。此时较为容易犯的一个错误就是在接收到 `IP_EVENT_STA_GOT_IP`_ 事件之前就初始化套接字。**切忌在接收到 IP 之前启动任何套接字相关操作。** -6.Wi-Fi 断开阶段 +6. Wi-Fi 断开阶段 +++++++++++++++++++++++++++++++++ - s6.1：当 Wi-Fi 因为某些原因（例如：AP 掉电、RSSI 较弱等）连接中断时，将产生 `WIFI_EVENT_STA_DISCONNECTED`_ 事件。此事件也可能在上文阶段 3 中发生。在这里，事件任务将通知 LwIP 任务清除/移除所有 UDP/TCP 连接。然后，所有应用程序套接字都将处于错误状态。也就是说，`WIFI_EVENT_STA_DISCONNECTED`_ 事件发生时，任何套接字都无法正常工作。 - s6.2：上述情况下，应用程序的事件回调函数会将 `WIFI_EVENT_STA_DISCONNECTED`_ 事件中继到应用程序任务中。推荐您调用函数 :cpp:func:`esp_wifi_connect()` 重新连接 Wi-Fi，关闭所有套接字，并在必要时重新创建套接字。请参阅 `WIFI_EVENT_STA_DISCONNECTED`_。 -7.Wi-Fi IP 更改阶段 +7. Wi-Fi IP 更改阶段 ++++++++++++++++++++++++++++++++++ - s7.1：如果 IP 地址发生更改，将引发 `IP_EVENT_STA_GOT_IP`_ 事件，其中 "ip_change" 被置为 "true"。 - s7.2：**此事件对应用程序至关重要。这一事件发生时，适合关闭所有已创建的套接字并进行重新创建。** -8.Wi-Fi 清理阶段 +8. Wi-Fi 清理阶段 ++++++++++++++++++++++++++++ - s8.1：调用函数 :cpp:func:`esp_wifi_disconnect()` 断开 Wi-Fi 连接。 @@ -387,25 +388,25 @@ Wi-Fi 驱动程序初始化成功后，可以进入到配置阶段。该场景 LwIP_TASK [label = "LwIP\ntask"]; WIFI_TASK [label = "Wi-Fi\ntask"]; - === 1.初始化阶段 === + === 1. 初始化阶段 === MAIN_TASK -> LwIP_TASK [label="1.1> 创建/初始化 LwIP"]; MAIN_TASK -> EVENT_TASK [label="1.2> 创建/初始化事件"]; MAIN_TASK -> WIFI_TASK [label="1.3> 创建/初始化 Wi-Fi"]; MAIN_TASK -> APP_TASK [label="1.4> 创建应用程序任务"]; - === 2.配置阶段 === + === 2. 配置阶段 === MAIN_TASK -> WIFI_TASK [label="2> 配置 Wi-Fi"]; - === 3.启动阶段 === + === 3. 启动阶段 === MAIN_TASK -> WIFI_TASK [label="3.1> 启动 Wi-Fi"]; EVENT_TASK <- WIFI_TASK [label="3.2> WIFI_EVENT_AP_START"]; APP_TASK <- EVENT_TASK [label="3.3> WIFI_EVENT_AP_START"]; - === 4.连接阶段 === + === 4. 连接阶段 === EVENT_TASK <- WIFI_TASK [label="4.1> WIFI_EVENT_AP_STACONNECTED"]; APP_TASK <- EVENT_TASK [label="4.2> WIFI_EVENT_AP_STACONNECTED"]; - === 5.断开阶段 === + === 5. 断开阶段 === EVENT_TASK <- WIFI_TASK [label="5.1> WIFI_EVENT_AP_STADISCONNECTED"]; APP_TASK <- EVENT_TASK [label="5.2> WIFI_EVENT_AP_STADISCONNECTED"]; APP_TASK -> APP_TASK [label="5.3> 断开处理"]; - === 6.清理阶段 === + === 6. 清理阶段 === APP_TASK -> WIFI_TASK [label="6.1> 断开 Wi-Fi 连接"]; APP_TASK -> WIFI_TASK [label="6.2> 终止 Wi-Fi"]; APP_TASK -> WIFI_TASK [label="6.3> 清理 Wi-Fi"]; @@ -420,25 +421,24 @@ Wi-Fi 驱动程序初始化成功后，可以进入到配置阶段。该场景 扫描类型 +++++++++++++++++++++++++ -+--------------+---------------------------------------------------------------------------------------------------+ -| 模式 | 描述 | -+==============+===================================================================================================+ -| 主动扫描 | 通过发送 probe request 进行扫描。该模式为默认的扫描模式。 | -+--------------+---------------------------------------------------------------------------------------------------+ -| 被动扫描 | 跳至某一特定信道并等待 beacon。应用程序可通过wifi_scan_config_t 中的 scan_type 字段使能被动扫描。 | -+--------------+---------------------------------------------------------------------------------------------------+ -| 前端扫描 | 不发出 probe request。在 station 模式下 Wi-Fi 未连接时，可进行前端扫描。 | -| | Wi-Fi 驱动程序决定进行前端扫描还是后端扫描，应用程序无法配置这两种模式。 | -+--------------+---------------------------------------------------------------------------------------------------+ -| 后端扫描 | 在 station 模式或 station/AP 共存模式下 Wi-Fi 已连接时，可进行后端扫描。 | -| | Wi-Fi 驱动程序决定进行前端扫描还是后端扫描，应用程序无法配置这两种模式。 | -+--------------+---------------------------------------------------------------------------------------------------+ -| 全信道扫描 | 扫描所有信道。wifi_scan_config_t 中的 channel 字段为 0 时， | -| | 当前模式为全信道扫描。 | -+--------------+---------------------------------------------------------------------------------------------------+ -| 特定信道扫描 | 仅扫描特定的信道。wifi_scan_config_t 中的 channel 字段为 1 | -| | 时，当前模式为特定信道扫描。 | -+--------------+---------------------------------------------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 50 + + * - 模式 + - 描述 + * - 主动扫描 + - 通过发送 probe request 进行扫描。该模式为默认的扫描模式。 + * - 被动扫描 + - 不发送 probe request。跳至某一特定信道并等待 beacon。应用程序可通过 wifi_scan_config_t 中的 scan_type 字段使能被动扫描。 + * - 前端扫描 + - 在 station 模式下 Wi-Fi 未连接时，可进行前端扫描。Wi-Fi 驱动程序决定进行前端扫描还是后端扫描，应用程序无法配置这两种模式。 + * - 后端扫描 + - 在 station 模式或 station/AP 共存模式下 Wi-Fi 已连接时，可进行后端扫描。Wi-Fi 驱动程序决定进行前端扫描还是后端扫描，应用程序无法配置这两种模式。 + * - 全信道扫描 + - 扫描所有信道。wifi_scan_config_t 中的 channel 字段为 0 时，当前模式为全信道扫描。 + * - 特定信道扫描 + - 仅扫描特定的信道。wifi_scan_config_t 中的 channel 字段为 1-14 时，当前模式为特定信道扫描。 上表中的扫描模式可以任意组合，因此共有 8 种不同扫描方式： @@ -451,42 +451,41 @@ Wi-Fi 驱动程序初始化成功后，可以进入到配置阶段。该场景 - 特定信道前端主动扫描 - 特定信道前端被动扫描 - 扫描配置 +++++++++++++++++ 扫描类型与其他扫描属性通过函数 :cpp:func:`esp_wifi_scan_start` 进行配置。下表详细描述了函数 wifi_scan_config_t 各字段信息。 -+-------------+----------------------------------------------------------------------------------------------------------------------+ -| 字段 | 描述 | -+=============+======================================================================================================================+ -| ssid | 如果该字段的值不为 NULL，则仅可扫描到具有相同 SSID 值的 AP。 | -+-------------+----------------------------------------------------------------------------------------------------------------------+ -| bssid | 如果该字段的值不为 NULL，则仅可扫描到具有相同 BSSID 值的 AP。 | -+-------------+----------------------------------------------------------------------------------------------------------------------+ -| channel | 如果该字段值为 0，将进行全信道扫描；反之，将针对特定信道进行扫描。 | -+-------------+----------------------------------------------------------------------------------------------------------------------+ -| show_hidden | 如果该字段值为 0，本次扫描将忽略具有隐藏 SSID 的 AP； | -| | 反之，这些 AP 也会在扫描时被视为正常 AP。 | -+-------------+----------------------------------------------------------------------------------------------------------------------+ -| scan_type | 如果该字段值为为 WIFI_SCAN_TYPE_ACTIVE，则本次扫描为主动扫描； | -| | 反之，将被视为被动扫描。 | -+-------------+----------------------------------------------------------------------------------------------------------------------+ -| scan_time | 该字段用于控制每个信道的扫描时间。 | -| | | -| | 被动扫描时，scan_time.passive 字段负责为每个信道指定扫描时间。 | -| | | -| | 主动扫描时，每个信道的扫描时间如下列表所示。其中，min 代表 | -| | scan_time_active_min，max 代表 scan_time_active_max。 | -| | | -| | - min=0, max=0：每个信道的扫描时间为 120 ms。 | -| | - min>0, max=0：每个信道的扫描时间为 120 ms。 | -| | - min=0, max>0：每个信道的扫描时间为 ``max`` ms。 | -| | - min>0, max>0：每个信道扫描的最短时间为 ``min`` ms。 如果在这段时间内未找到 AP，将跳转至下一个信道。如这段时间内 | -| | 找到 AP，则该信道的扫描时间为 ``max`` ms。 | -| | | -| | 如希望提升 Wi-Fi 扫描性能，则可修改上述两个参数。 | -+-------------+----------------------------------------------------------------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 50 + + * - 字段 + - 描述 + * - ssid + - 如果该字段的值不为 NULL，则仅可扫描到具有相同 SSID 值的 AP。 + * - bssid + - 如果该字段的值不为 NULL，则仅可扫描到具有相同 BSSID 值的 AP。 + * - channel + - 如果该字段值为 0，将进行全信道扫描；反之，将针对特定信道进行扫描。 + * - show_hidden + - 如果该字段值为 0，本次扫描将忽略具有隐藏 SSID 的 AP；反之，这些 AP 也会在扫描时被视为正常 AP。 + * - scan_type + - 如果该字段值为为 WIFI_SCAN_TYPE_ACTIVE，则本次扫描为主动扫描；反之，将被视为被动扫描。 + * - scan_time + - 该字段用于控制每个信道的扫描时间。 + + 被动扫描时，scan_time.passive 字段负责为每个信道指定扫描时间。 + + 主动扫描时，每个信道的扫描时间如下列表所示。其中，min 代表 scan_time_active_min，max 代表 scan_time_active_max。 + + - min=0, max=0：每个信道的扫描时间为 120 ms。 + - min>0, max=0：每个信道的扫描时间为 120 ms。 + - min=0, max>0：每个信道的扫描时间为 ``max`` ms。 + - min>0, max>0：每个信道扫描的最短时间为 ``min`` ms。 如果在这段时间内未找到 AP，将跳转至下一个信道。如这段时间内找到 AP，则该信道的扫描时间为 ``max`` ms。 + + 如希望提升 Wi-Fi 扫描性能，则可修改上述两个参数。 + 调用 API :cpp:func:`esp_wifi_set_config` 可全局配置一些扫描属性，请参阅 `station 基本配置`_。 @@ -581,7 +580,7 @@ Wi-Fi 驱动程序内部扫描阶段 APP_TASK <- EVENT_TASK [label="3.2 > WIFI_EVENT_SCAN_DONE"]; } -上述场景为一次全信道后端扫描。与 `在所有信道中扫描全部 AP（前端）`_ 相比，全信道后端扫描的不同之处在于：在跳至下一个信道之前，Wi-Fi 驱动程序会先返回主信道进行 30 ms 扫描，以便 Wi-Fi 连接有一定的时间发送/接收数据。 +上述场景为一次全信道后端扫描。与 `在所有信道中扫描全部 AP（前端）`_ 相比，全信道后端扫描的不同之处在于：在跳至下一个信道之前，Wi-Fi 驱动程序会先返回主信道停留 30 ms，以便 Wi-Fi 连接有一定的时间发送/接收数据。 在所有信道中扫描特定 AP +++++++++++++++++++++++++++++++++++++++ @@ -682,15 +681,15 @@ Wi-Fi 驱动程序内部扫描阶段 WIFI_TASK [label = "Wi-Fi\ntask"]; AP [label = "AP"]; - === 1.扫描阶段 === + === 1. 扫描阶段 === WIFI_TASK -> WIFI_TASK [label="1.1 > 扫描"]; EVENT_TASK <- WIFI_TASK [label="1.2 > WIFI_EVENT_STA_DISCONNECTED"]; - === 2.认证阶段 === + === 2. 认证阶段 === WIFI_TASK -> AP [label="2.1 > Auth request"]; EVENT_TASK <- WIFI_TASK [label="2.2 > WIFI_EVENT_STA_DISCONNECTED"]; WIFI_TASK <- AP [label="2.3 > Auth response"]; EVENT_TASK <- WIFI_TASK [label="2.4 > WIFI_EVENT_STA_DISCONNECTED"]; - === 3.关联阶段 === + === 3. 关联阶段 === WIFI_TASK -> AP [label="3.1 > Assoc request"]; EVENT_TASK <- WIFI_TASK [label="3.2 > WIFI_EVENT_STA_DISCONNECTED"]; WIFI_TASK <- AP [label="3.3 > Assoc response"]; @@ -746,211 +745,257 @@ Wi-Fi 原因代码 下表罗列了 {IDF_TARGET_NAME} 中定义的原因代码。其中，第一列为 esp_wifi_types.h 中定义的宏名称。名称中省去了前缀 *WIFI_REASON*，也就是说，名称 *UNSPECIFIED* 实际应为 *WIFI_REASON_UNSPECIFIED*，以此类推。第二列为原因代码的相应数值。第三列为该原因映射到 IEEE 802.11-2012 中 8.4.1.7 段的标准值。（更多详细信息，请参阅前文描述。）最后一列为这一原因的描述。 +.. list-table:: + :header-rows: 1 + :widths: 5 10 12 40 -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| 原因代码 | 数值 | 映射值 | 描述 | -+==========================+======+==========+=========================================================================+ -| UNSPECIFIED | 1 | 1 | 出现内部错误，例如：存储器已满，内部发送失败，或该原因已 被远端接收等。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| AUTH_EXPIRE | 2 | 2 | 先前的 authentication 已失效。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时将报告该代码： | -| | | | | -| | | | - authentication 超时； | -| | | | - 从 AP 接收到该代码。 | -| | | | | -| | | | 对于 ESP AP，出现以下情况时将报告该代码： | -| | | | | -| | | | - 在过去五分钟之内，AP 未从 station 接收到任何数据包； | -| | | | - 由于调用了函数 :cpp:func:`esp_wifi_stop()` 导致 AP 终止； | -| | | | - 由于调用了函数 :cpp:func:`esp_wifi_deauth_sta()` 导致 station 的 auth | -| | | | 取消。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| AUTH_LEAVE | 3 | 3 | authentication 取消，因为发送 STA 正在离开（或已经离开）。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| ASSOC_EXPIRE | 4 | 4 | association 取消，因为 AP 不活跃。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -| | | | | -| | | | 对于 ESP AP，出现以下情况时报告该代码： | -| | | | | -| | | | - 在过去五分钟之内， AP 未从 station 接收到任何数据包； | -| | | | - 由于调用了函数 :cpp:func:`esp_wifi_stop()` 导致 AP 终止； | -| | | | - 由于调用了函数 :cpp:func:`esp_wifi_deauth_sta()` 导致 station 的 auth | -| | | | 取消。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| ASSOC_TOOMANY | 5 | 5 | association 取消，因为 AP 无法同时处理所有当前已关联的 STA。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -| | | | | -| | | | 对于 ESP AP，出现以下情况时报告该代码： | -| | | | | -| | | | - 与 AP 相关联的 station 数量已到达 AP 可支持的最大值。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| NOT_AUTHED | 6 | 6 | 从一个未认证 STA 接收到 class-2 frame。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -| | | | | -| | | | 对于 ESP AP，出现以下情况时报告该代码： | -| | | | | -| | | | - AP 从一个未认证 station 接收到数据包。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| NOT_ASSOCED | 7 | 7 | 从一个未关联 STA 接收到的 class-3 frame。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -| | | | | -| | | | 对于 ESP AP，出现以下情况时报告该代码： | -| | | | | -| | | | - AP 从未关联 station 接收到数据包。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| ASSOC_LEAVE | 8 | 8 | association 取消，因为发送 STA 正在离开（或已经离开）BSS。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码； | -| | | | - 由于调用 :cpp:func:`esp_wifi_disconnect()` 其它 API， | -| | | | station 断开连接。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| ASSOC_NOT_AUTHED | 9 | 9 | STA 的 re(association) 请求未被响应 STA 认证。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -| | | | | -| | | | 对于 ESP AP，出现以下情况时报告该代码： | -| | | | | -| | | | - AP 从一个已关联，但未认证的 station 接收到数据包。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| DISASSOC_PWRCAP_BAD | 10 | 10 | association 取消，因为无法接收功率能力 (Power Capability) | -| | | | 元素中的信息。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| DISASSOC_SUPCHAN_BAD | 11 | 11 | association 取消，因为无法接收支持的信道 (Supported Channels) | -| | | | 元素中的信息。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| IE_INVALID | 13 | 13 | 无效元素，即内容不符合 Wi-Fi 协议中帧格式 (Frame formats) | -| | | | 章节所描述标准的元素。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -| | | | | -| | | | 对于 ESP AP，出现以下情况时报告该代码： | -| | | | | -| | | | - AP 解析了一个错误的 WPA 或 RSN IE。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| MIC_FAILURE | 14 | 14 | 消息完整性代码 (MIC) 出错。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | 四次握手超时。由于某些历史原因，在 ESP 中该原因代码实为 | -| | | | WIFI_REASON_HANDSHAKE_TIMEOUT。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 握手超时； | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| GROUP_KEY_UPDATE_TIMEOUT | 16 | 16 | 组密钥 (Group-Key) 握手超时。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| IE_IN_4WAY_DIFFERS | 17 | 17 | 四次握手中产生的元素与 (re-)association 后的 request/probe 以及 | -| | | | response/beacon frame 中的信息不同。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码； | -| | | | - station 发现四次握手的 IE 与 (re-)association 后的 request/probe | -| | | | 以及 response/beacon frame 中的 IE 不同。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| GROUP_CIPHER_INVALID | 18 | 18 | 无效组密文。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| PAIRWISE_CIPHER_INVALID | 19 | 19 | 无效成对密文。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| AKMP_INVALID | 20 | 20 | 无效 AKMP。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| UNSUPP_RSN_IE_VERSION | 21 | 21 | RSNE 版本不支持。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| INVALID_RSN_IE_CAP | 22 | 22 | 无效的 RSNE 性能。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| 802_1X_AUTH_FAILED | 23 | 23 | IEEE 802.1X. authentication 失败。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -| | | | | -| | | | 对于 ESP AP，出现以下情况时报告该代码： | -| | | | | -| | | | - IEEE 802.1X. authentication 失败。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| CIPHER_SUITE_REJECTED | 24 | 24 | 因安全策略，安全密钥算法套件 (cipher suite) 被拒。 | -| | | | | -| | | | 对于 ESP station，出现以下情况时报告该代码： | -| | | | | -| | | | - 从 AP 接收到该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| BEACON_TIMEOUT | 200 | reserved | 乐鑫特有的 Wi-Fi 原因代码： 当 station 连续失去 N 个 beacon， | -| | | | 将中断连接并报告该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| NO_AP_FOUND | 201 | reserved | 乐鑫特有的 Wi-Fi 原因代码： 当 station 未扫描到目标 AP 时， | -| | | | 将报告该代码。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| AUTH_FAIL | 202 | reserved | 乐鑫特有的 Wi-Fi 原因代码： authentication 失败， | -| | | | 但并非由超时而引发。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| ASSOC_FAIL | 203 | reserved | 乐鑫特有的 Wi-Fi 原因代码： association 失败，但并非由 | -| | | | ASSOC_EXPIRE 或 ASSOC_TOOMANY 引发。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| HANDSHAKE_TIMEOUT | 204 | reserved | 乐鑫特有的 Wi-Fi 原因代码： 握手失败，与 | -| | | | WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT 中失败原因相同。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ -| CONNECTION_FAIL | 205 | reserved | 乐鑫特有的 Wi-Fi 原因代码： AP 连接失败。 | -+--------------------------+------+----------+-------------------------------------------------------------------------+ + * - 原因代码 + - 数值 + - 映射值 + - 描述 + * - UNSPECIFIED + - 1 + - 1 + - 出现内部错误，例如：内存已满，内部发送失败，或该原因已被远端接收等。 + * - AUTH_EXPIRE + - 2 + - 2 + - 先前的 authentication 已失效。 + 对于 ESP station，出现以下情况时将报告该代码： + + - authentication 超时； + - 从 AP 接收到该代码。 + + 对于 ESP AP，出现以下情况时将报告该代码： + + - 在过去五分钟之内，AP 未从 station 接收到任何数据包； + - 由于调用了函数 :cpp:func:`esp_wifi_stop()` 导致 AP 终止； + - 由于调用了函数 :cpp:func:`esp_wifi_deauth_sta()` 导致 station 的 authentication 取消。 + * - AUTH_LEAVE + - 3 + - 3 + - authentication 取消，因为发送 station 正在离开（或已经离开）。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + * - ASSOC_EXPIRE + - 4 + - 4 + - 因为 AP 不活跃，association 取消。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + + 对于 ESP AP，出现以下情况时将报告该代码： + + - 在过去五分钟之内， AP 未从 station 接收到任何数据包； + - 由于调用了函数 :cpp:func:`esp_wifi_stop()` 导致 AP 终止； + - 由于调用了函数 :cpp:func:`esp_wifi_deauth_sta()` 导致 station 的 authentication 取消。 + * - ASSOC_TOOMANY + - 5 + - 5 + - association 取消，因为 AP 无法同时处理所有当前已关联的 STA。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + + 对于 ESP AP，出现以下情况时将报告该代码： + + - 与 AP 相关联的 station 数量已到达 AP 可支持的最大值。 + * - NOT_AUTHED + - 6 + - 6 + - 从一个未认证 station 接收到 class-2 frame。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + + 对于 ESP AP，出现以下情况时将报告该代码： + + - AP 从一个未认证 station 接收到数据包。 + * - NOT_ASSOCED + - 7 + - 7 + - 从一个未关联 station 接收到的 class-3 frame。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + + 对于 ESP AP，出现以下情况时将报告该代码： + + - AP 从未关联 station 接收到数据包。 + * - ASSOC_LEAVE + - 8 + - 8 + - association 取消，因为发送 station 正在离开（或已经离开）BSS。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + - 由于调用 :cpp:func:`esp_wifi_disconnect()` 和其它 API，station 断开连接。 + * - ASSOC_NOT_AUTHED + - 9 + - 9 + - station 的 re(association) 请求未被响应 station 认证。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + + 对于 ESP AP，出现以下情况时将报告该代码： + + - AP 从一个已关联，但未认证的 station 接收到数据包。 + * - DISASSOC_PWRCAP_BAD + - 10 + - 10 + - association 取消，因为无法接收功率能力 (Power Capability) 元素中的信息。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + * - DISASSOC_SUPCHAN_BAD + - 11 + - 11 + - association 取消，因为无法接收支持的信道 (Supported Channels) 元素中的信息。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + * - IE_INVALID + - 13 + - 13 + - 无效元素，即内容不符合 Wi-Fi 协议中帧格式 (Frame formats) 章节所描述标准的元素。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + + 对于 ESP AP，出现以下情况时将报告该代码： + + - AP 解析了一个错误的 WPA 或 RSN IE。 + * - MIC_FAILURE + - 14 + - 14 + - 消息完整性代码 (MIC) 出错。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + * - 4WAY_HANDSHAKE_TIMEOUT + - 15 + - 15 + - 四次握手超时。由于某些历史原因，在 ESP 中该原因代码实为 WIFI_REASON_HANDSHAKE_TIMEOUT。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 握手超时。 + - 从 AP 接收到该代码。 + * - GROUP_KEY_UPDATE_TIMEOUT + - 16 + - 16 + - 组密钥 (Group-Key) 握手超时。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + * - IE_IN_4WAY_DIFFERS + - 17 + - 17 + - 四次握手中产生的元素与 (re-)association 后的 request/probe 以及 response/beacon frame 中的信息不同。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + - station 发现四次握手的 IE 与 (re-)association 后的 request/probe 以及 response/beacon frame 中的 IE 不同。 + * - GROUP_CIPHER_INVALID + - 18 + - 18 + - 无效组密文。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + * - PAIRWISE_CIPHER_INVALID + - 19 + - 19 + - 无效成对密文。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + * - AKMP_INVALID + - 20 + - 20 + - 无效 AKMP。 + + 对于 ESP station，出现以下情况时报告该代码： + - 从 AP 接收到该代码。 + * - UNSUPP_RSN_IE_VERSION + - 21 + - 21 + - 不支持的 RSNE 版本。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + * - INVALID_RSN_IE_CAP + - 22 + - 22 + - 无效的 RSNE 性能。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + * - 802_1X_AUTH_FAILED + - 23 + - 23 + - IEEE 802.1X. authentication 失败。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + + 对于 ESP AP，出现以下情况时将报告该代码： + + - IEEE 802.1X. authentication 失败。 + * - CIPHER_SUITE_REJECTED + - 24 + - 24 + - 因安全策略，安全密钥算法套件 (cipher suite) 被拒。 + + 对于 ESP station，出现以下情况时报告该代码： + + - 从 AP 接收到该代码。 + * - BEACON_TIMEOUT + - 200 + - 保留 + - 乐鑫特有的 Wi-Fi 原因代码： 当 station 连续失去 N 个 beacon，将中断连接并报告该代码。 + * - NO_AP_FOUND + - 201 + - 保留 + - 乐鑫特有的 Wi-Fi 原因代码： 当 station 未扫描到目标 AP 时，将报告该代码。 + * - AUTH_FAIL + - 202 + - 保留 + - 乐鑫特有的 Wi-Fi 原因代码： authentication 失败，但并非由超时而引发。 + * - ASSOC_FAIL + - 203 + - 保留 + - 乐鑫特有的 Wi-Fi 原因代码： association 失败，但并非由 ASSOC_EXPIRE 或 ASSOC_TOOMANY 引发。 + * - HANDSHAKE_TIMEOUT + - 204 + - 保留 + - 乐鑫特有的 Wi-Fi 原因代码： 握手失败，与 WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT 中失败原因相同。 + * - CONNECTION_FAIL + - 205 + - 保留 + - 乐鑫特有的 Wi-Fi 原因代码： AP 连接失败。 找到多个 AP 时的 {IDF_TARGET_NAME} Wi-Fi station 连接 @@ -958,7 +1003,6 @@ Wi-Fi 原因代码 该场景与 `{IDF_TARGET_NAME} Wi-Fi station 连接场景`_ 相似，不同之处在于该场景中不会产生 `WIFI_EVENT_STA_DISCONNECTED`_ 事件，除非 station 无法连接所有找到的 AP。 - Wi-Fi 重新连接 --------------------------- @@ -978,7 +1022,6 @@ Wi-Fi beacon 超时 beacon 超时发生后，station 将向 AP 发送 5 个 probe request，如果仍未从 AP 接收到 probe response 或 beacon，station 将与 AP 断开连接并产生 `WIFI_EVENT_STA_DISCONNECTED`_ 事件。 - {IDF_TARGET_NAME} Wi-Fi 配置 ------------------------------------- @@ -988,69 +1031,56 @@ Wi-Fi 模式 +++++++++++++++++++++++++ 调用函数 :cpp:func:`esp_wifi_set_mode()` 设置 Wi-Fi 模式。 -+-----------------+------------------------------------------------------------------------------+ -| 模式 | 描述 | -+-----------------+------------------------------------------------------------------------------+ -| WIFI_MODE_NULL | NULL 模式：此模式下，内部数据结构不分配给 station 和 AP，同时，station 和 AP | -| | 接口不会为发送/接收 Wi-Fi 数据进行初始化。通常，此模式用于 | -| | Sniffer，或者您不想通过调用函数 :cpp:func:`esp_wifi_deinit()` 卸载整个 | -| | Wi-Fi 驱动程序来同时停止 station 和 AP。 | -+-----------------+------------------------------------------------------------------------------+ -| WIFI_MODE_STA | Station 模式：此模式下，:cpp:func:`esp_wifi_start()` 将初始化内部 | -| | station 数据，同时 station 接口准备发送/接收 Wi-Fi 数据。调用函数 | -| | :cpp:func:`esp_wifi_connect()` 后，station 将连接到目标 AP。 | -+-----------------+------------------------------------------------------------------------------+ -| WIFI_MODE_AP | AP 模式：在此模式下，:cpp:func:`esp_wifi_start()` 将初始化内部 AP | -| | 数据，同时 AP 接口准备发送/接收 Wi-Fi 数据。随后，Wi-Fi | -| | 驱动程序开始广播 beacon，AP 即可与其它 station 连接。 | -+-----------------+------------------------------------------------------------------------------+ -| WIFI_MODE_APSTA | Station/AP 共存模式：在此模式下，函数 :cpp:func:`esp_wifi_start()` | -| | 将同时初始化 station 和 AP。该步骤在 Station 模式和 AP | -| | 模式下完成。请注意 ESP Station 所连外部 AP 的信道优先于 ESP AP 信道。 | -+-----------------+------------------------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 50 -Station 基本配置 + * - 模式 + - 描述 + * - WIFI_MODE_NULL + - NULL 模式：此模式下，内部数据结构不分配给 station 和 AP，同时，station 和 AP 接口不会为发送/接收 Wi-Fi 数据进行初始化。通常，此模式用于 Sniffer，或者您不想通过调用函数 :cpp:func:`esp_wifi_deinit()` 卸载整个 Wi-Fi 驱动程序来同时停止 station 和 AP。 + * - WIFI_MODE_STA + - station 模式：此模式下，:cpp:func:`esp_wifi_start()` 将初始化内部 station 数据，同时 station 接口准备发送/接收 Wi-Fi 数据。调用函数 :cpp:func:`esp_wifi_connect()` 后，station 将连接到目标 AP。 + * - WIFI_MODE_AP + - AP 模式：在此模式下，:cpp:func:`esp_wifi_start()` 将初始化内部 AP 数据，同时 AP 接口准备发送/接收 Wi-Fi 数据。随后，Wi-Fi 驱动程序开始广播 beacon，AP 即可与其它 station 连接。 + * - WIFI_MODE_APSTA + - station/AP 共存模式：在此模式下，函数 :cpp:func:`esp_wifi_start()` 将同时初始化 station 和 AP。该步骤在 station 模式和 AP 模式下完成。请注意 ESP station 所连外部 AP 的信道优先于 ESP AP 信道。 + + +station 基本配置 +++++++++++++++++++++++++++++++++++++ API esp_wifi_set_config() 可用于配置 station。下表详细介绍了各个字段。 +.. list-table:: + :header-rows: 1 + :widths: 15 45 + + * - 字段 + - 描述 + * - ssid + - station 想要连接的目标 AP 的 SSID。 + * - password + - 目标 AP 的密码。 + * - scan_method + - WIFI_FAST_SCAN 模式下，扫描到一个匹配的 AP 时即结束。WIFI_ALL_CHANNEL_SCAN 模式下，在所有信道扫描所有匹配的 AP。默认扫描模式是 WIFI_FAST_SCAN。 + * - bssid_set + - 如果 bssid_set 为 0，station 连接 SSID 与 “ssid” 字段相同的 AP，同时忽略字段 “bssid”。其他情况下，station 连接 SSID 与 “ssid” 字段相同、BSSID 与 “bssid” 字段也相同的 AP。 + * - bssid + - 只有当 bssid_set 为 1 时有效。见字段 “bssid_set”。 + * - channel + - 该字段为 0 时，station 扫描信道 1 ~ N 寻找目标 AP；否则，station 首先扫描值与 “channel” 字段相同的信道，再扫描其他信道。如果您不知道目标 AP 在哪个信道，请将该字段设置为 0。 + * - sort_method + - 该字段仅用于 WIFI_ALL_CHANNEL_SCAN 模式。 + + 如果设置为 WIFI_CONNECT_AP_BY_SIGNAL，所有匹配的 AP 将会按照信号强度排序，信号最好的 AP 会被首先连接。比如，如果 station 想要连接 ssid 为 “apxx” 的 AP，且扫描到两个这样的 AP。第一个 AP 的信号为 -90 dBm，第二个 AP 的信号为 -30 dBm，station 首先连接第二个 AP。除非失败，才会连接第一个。 + + 如果设置为 WIFI_CONNECT_AP_BY_SECURITY，所有匹配的 AP 将会按照安全性排序。比如，如果 station 想要连接 ssid 为 “apxx” 的 AP，并且扫描到两个这样的 AP。第一个 AP 为开放式，第二个 AP 为 WPA2 加密，station 首先连接第二个 AP。除非失败，才会连接第一个。 + * - threshold + - 该字段用来筛选找到的 AP，如果 AP 的 RSSI 或安全模式小于配置的阈值，则不会被连接。 + + 如果 RSSI 设置为 0，则表示默认阈值、默认 RSSI 阈值为 -127 dBm。如果 authmode 阈值设置为 0，则表示默认阈值，默认 authmode 阈值无授权。 -+-------------+---------------------------------------------------------------------------+ -| 字段 | 描述 | -+=============+===========================================================================+ -| ssid | station 想要连接的目标 AP 的 SSID。 | -+-------------+---------------------------------------------------------------------------+ -| password | 目标 AP 的密码。 | -+-------------+---------------------------------------------------------------------------+ -| scan_method | WIFI_FAST_SCAN 模式下，扫描到一个匹配的 AP 时即结束。WIFI_ALL_CHANNEL_SCA | -| | 模式下，在所有信道扫描所有匹配的 AP。默认扫描模式是 WIFI_FAST_SCAN。 | -+-------------+---------------------------------------------------------------------------+ -| bssid_set | 如果 bssid_set 为 0，station 连接 SSID 与 "ssid" 字段相同的 | -| | AP，同时忽略字段 "bssid"。其他情况下，station 连接 SSID | -| | 与 "ssid" 字段相同、BSSID 与 "bssid" 字段也相同的 AP。 | -+-------------+---------------------------------------------------------------------------+ -| bssid | 只有当 bssid_set 为 1 时有效。见字段 "bssid_set"。 | -+-------------+---------------------------------------------------------------------------+ -| channel | 该字段为 0 时，station 扫描信道 1~N 寻找目标 AP；否则，station | -| | 首先扫描值与 "channel" 字段相同的信道，再扫描其他信道。如果您不知道目标 | -| | AP 在哪个信道，请将该字段设置为 0。 | -+-------------+---------------------------------------------------------------------------+ -| sort_method | 该字段仅用于 WIFI_ALL_CHANNEL_SCAN 模式。如果设置为 | -| | WIFI_CONNECT_AP_BY_SIGNAL，所有匹配的 AP | -| | 将会按照信号强度排序，信号最好的 AP 会被首先连接。比如，如果 | -| | station 想要连接 ssid 为 "apxx" 的 AP，且扫描到两个这样的 | -| | AP。第一个 AP 的信号为 -90 dBm，第二个 AP 的信号为 -30 dBm，station | -| | 首先连接第二个 AP。除非失败，才会连接第一个。如果设置为 | -| | WIFI_CONNECT_AP_BY_SECURITY，所有匹配的 AP 将会按照安全性排序。比如，如果 | -| | station 想要连接 ssid 为 "apxx"的 AP，并且扫描到两个这样的 AP。第一个 | -| | AP 为开放式，第二个 AP 为 WPA2 加密，station 首先连接第二个 | -| | AP。除非失败，才会连接第一个。 | -+-------------+---------------------------------------------------------------------------+ -| threshold | 该字段用来筛选找到的 AP，如果 AP 的 RSSI | -| | 或安全模式小于配置的阈值，则不会被连接。如果 RSSI | -| | 设置为 0，则取 RSSI 的默认阈值 -127 dBm。如果 | -| | authmode 设置为 0，则取 authmode 默认阈值无授权。 | -+-------------+---------------------------------------------------------------------------+ .. attention:: @@ -1061,60 +1091,54 @@ AP 基本配置 API esp_wifi_set_config() 可用于配置 AP。下表详细介绍了各个字段。 -+-----------------+----------------------------------------------------------------------------------+ -| 字段 | 描述 | -+-----------------+----------------------------------------------------------------------------------+ -| 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。 | -+-----------------+----------------------------------------------------------------------------------+ +.. 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。 + Wi-Fi 协议模式 +++++++++++++++++++++++++ 目前，IDF 支持以下协议模式： -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 协议模式 | 描述 | -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 802.11b | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_11B)，将 | -| | station/AP 设置为仅 802.11b 模式。 | -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 802.11bg | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G)，将 station/AP 设置为 | -| | 802.11bg 模式。 | -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 802.11bgn | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)，将 | -| | station/AP 设置为 802.11bgn 模式。 | -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 802.11 BGNLR | 调用函数 :cpp:func:`esp_wifi_set_protocol` | -| | (ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR)，将 station/AP 设置为 802.11bgn | -| | 和乐鑫专属模式。 | -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 802.11 LR | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_LR)，将 | -| | station/AP 设置为仅乐鑫专属模式。 | -| | | -| | **此模式是乐鑫的专利模式，可以达到 1 公里视线范围。请确保 | -| | station 和 AP 同时连接至 ESP 设备。** | -+--------------+------------------------------------------------------------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 55 + + * - 协议模式 + - 描述 + * - 802.11b + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B)，将 station/AP 设置为仅 802.11b 模式。 + * - 802.11bg + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G)，将 station/AP 设置为 802.11bg 模式。 + * - 802.11bgn + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)，将 station/AP 设置为 802.11bgn 模式。 + * - 802.11 BGNLR + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR)，将 station/AP 设置为 802.11bgn 和乐鑫专属模式。 + * - 802.11 LR + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR)，将 station/AP 设置为仅乐鑫专属模式。 + + **此模式是乐鑫的专利模式，可以达到 1 公里视线范围。请确保 station 和 AP 同时连接至 ESP 设备。** + 远程 (LR) +++++++++++++++++++++++++ @@ -1150,7 +1174,7 @@ LR 兼容性 根据上表，得出以下结论： - - 对于已使能 LR 的 {IDF_TARGET_NAME} AP，由于不是以 LR 模式发送 beacon，因此与传统的 802.11 模式不兼容。 + - 对于已使能 LR 的 {IDF_TARGET_NAME} AP，由于以 LR 模式发送 beacon，因此与传统的 802.11 模式不兼容。 - 对于已使能 LR 且并非仅 LR 模式的 {IDF_TARGET_NAME} station，与传统 802.11 模式兼容。 - 如果 station 和 AP 都是 {IDF_TARGET_NAME} 设备，并且两者都使能 LR 模式，则协商的模式支持 LR。 @@ -1169,92 +1193,97 @@ LR 对传统 Wi-Fi 设备的影响 LR 传输距离 ************************* -LR 的接收灵敏度比传统的 802.11B 模式高 4 dB，理论上，传输距离约为 802.11B 的 2 至 2.5 倍。 +LR 的接收灵敏度比传统的 802.11b 模式高 4 dB，理论上，传输距离约为 802.11b 的 2 至 2.5 倍。 LR 吞吐量 ************************* -因为原始 PHY 数据传输速率为 1×2 Mbit 和 1/4 Mbit，LR 的吞吐量有限。 +因为原始 PHY 数据传输速率为 1/2 Mbit 和 1/4 Mbit，LR 的吞吐量有限。 何时使用 LR ************************* 通常使用 LR 的场景包括： - - AP 和 station 都是设备。 + - AP 和 station 都是 {IDF_TARGET_NAME} 设备。 - 需要长距离 Wi-Fi 连接和数据传输。 - 数据吞吐量要求非常小，例如远程设备控制等。 Wi-Fi 国家/地区代码 +++++++++++++++++++++++++ -调用 :cpp:func:`esp_wifi_set_country()`，设置国家/地区信息。下表详细介绍了各个字段，请在配置这些字段之前参考当地的 2.4GHz RF 操作规定。 +调用 :cpp:func:`esp_wifi_set_country()`，设置国家/地区信息。下表详细介绍了各个字段，请在配置这些字段之前参考当地的 2.4 GHz RF 操作规定。 -+--------+----------------------------------------------------------------------------------------------------------------+ -| 字段 | 描述 | -+--------+----------------------------------------------------------------------------------------------------------------+ -| cc[3] | 国家/地区代码字符串，此属性标识 station/AP | -| | 位于的国家/地区或非国家/地区实体。如果是一个国家/地区，该字符串的前两个八位字节是 | -| | ISO/IEC3166-1 中规定的国家/地区两位字母代码。第三个八位字节应是下述之一： | -| | | -| | -ASCII 码空格字符，代表 station/AP 所处国家/地区的规定允许当前频段所需的所有环境。 | -| | | -| | -ASCII 码 'O' 字符，代表 station/AP 所处国家/地区的规定仅允许室外环境。 | -| | | -| | -ASCII 码 'I' 字符，代表 station/AP 所处国家/地区的规定仅允许室内环境。 | -| | | -| | -ASCII 码 'X' 字符，代表 station/AP 位于非国家/地区实体。非国家实体的前两个八位字节是两个ASCII 码 'XX' 字符。 | -| | | -| | -当前使用的操作类表编号的二进制形式。见 IEEE Std 802.11-2012 附件 E。 | -+--------+----------------------------------------------------------------------------------------------------------------+ -| schan | 起始信道，station/AP 所处国家/地区规定的最小信道数。 | -+--------+----------------------------------------------------------------------------------------------------------------+ -| nchan | 规定的总信道数，比如，如果 schan=1，nchan=13，那么 station/AP 可以从信道 1 至 13 发送数据。 | -+--------+----------------------------------------------------------------------------------------------------------------+ -| policy | 国家/地区政策，当配置的国家/地区信息与所连 AP | -| | 的国家/地区信息冲突时，该字段决定使用哪一信息。更多政策相关信息，可参见下文。 | -+--------+----------------------------------------------------------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 55 + + * - 字段 + - 描述 + * - cc[3] + - 国家/地区代码字符串，此属性标识 station/AP 位于的国家/地区或非国家/地区实体。如果是一个国家/地区，该字符串的前两个八位字节是 ISO/IEC3166-1 中规定的国家/地区两位字母代码。第三个八位字节应是下述之一： + + - ASCII 码空格字符，代表 station/AP 所处国家/地区的规定允许当前频段所需的所有环境。 + - ASCII 码 ‘O’ 字符，代表 station/AP 所处国家/地区的规定仅允许室外环境。 + - ASCII 码 ‘I’ 字符，代表 station/AP 所处国家/地区的规定仅允许室内环境。 + - ASCII 码 ‘X’ 字符，代表 station/AP 位于非国家/地区实体。非国家实体的前两个八位字节是两个 ASCII 码 ‘XX’ 字符。 + - 当前使用的操作类表编号的二进制形式。见 IEEE Std 802.11-2012 附件 E。 + + * - schan + - 起始信道，station/AP 所处国家/地区规定的最小信道数。 + * - nchan + - 规定的总信道数，比如，如果 schan=1，nchan=13，那么 station/AP 可以从信道 1 至 13 发送数据。 + * - policy + - 国家/地区政策，当配置的国家/地区信息与所连 AP 的国家/地区信息冲突时，该字段决定使用哪一信息。更多政策相关信息，可参见下文。 + + +默认国家/地区信息为 {.cc="CN", .schan=1, .nchan=13, policy=WIFI_COUNTRY_POLICY_AUTO}，如果 Wi-Fi 模式为 station/AP 共存模式，则它们配置的国家/地区信息相同。有时，station 所连 AP 的国家/地区信息与配置的不同。例如，配置的 station 国家/地区信息为 {.cc="JP", .schan=1, .nchan=14, policy=WIFI_COUNTRY_POLICY_AUTO}，但所连 AP 的国家/地区信息为 {.cc="CN", .schan=1, .nchan=13}，此时，使用所连 AP 的国家/地区信息。 -默认国家/地区信息为 {.cc="CN", .schan=1, .nchan=13, policy=WIFI_COUNTRY_POLICY_AUTO}，如果 Wi-Fi 模式为 AP-STA 共存模式，则它们配置的国家/地区信息相同。有时，station 所连 AP 的国家/地区信息与配置的不同。例如，配置的 station 国家/地区信息为 {.cc="JP", .schan=1, .nchan=14, policy=WIFI_COUNTRY_POLICY_AUTO}，但所连 AP 的国家/地区信息为 {.cc="CN", .schan=1, .nchan=13}，此时，使用 AP 的国家/地区信息。 下表描述了在不同 Wi-Fi 模式和不同国家/地区政策下使用的国家/地区信息，并描述了对主动扫描的影响。 -+---------------------+----------------------------+------------------------------------------------------------------------------+ -| Wi-Fi 模式 | 政策 | 描述 | -+---------------------+----------------------------+------------------------------------------------------------------------------+ -| Station 模式 | WIFI_COUNTRY_POLICY_AUTO | 如果所连 AP 的 beacon 中有国家/地区的 IE，使用的国家/地区信息为 beacon | -| | | 中的信息，否则，使用默认信息。 | -| | | | -| | | 扫描时： | -| | | | -| | | -如果 schan+nchan-1>11， | -| | | 主动扫描起始信道至信道 11，被动扫描信道 12 至 信道 | -| | | schan+nchan-1。 | -| | | | -| | | -如果 schan+nchan-1<=11， | -| | | 主动扫描起始信道至信道 schan+nchan-1。 | -| | | | -| | | 请记住，如果 AP 带有隐藏 SSID | -| | | 且被设置为被动扫描信道，被动扫描将无法找到该 | -| | | AP。也就是说，如果应用程序希望在每个信道中找到带有隐藏 | -| | | SSID 的 AP，国家/地区信息应该配置为 | -| | | WIFI_COUNTRY_POLICY_MANUAL。 | -+---------------------+----------------------------+------------------------------------------------------------------------------+ -| Station 模式 | WIFI_COUNTRY_POLICY_MANUAL | 总是使用配置的国家/地区信息。 扫描时，主动扫描起始信道至信道 schan+nchan-1。 | -+---------------------+----------------------------+------------------------------------------------------------------------------+ -| AP 模式 | WIFI_COUNTRY_POLICY_AUTO | 总是使用配置的国家/地区信息。 | -+---------------------+----------------------------+------------------------------------------------------------------------------+ -| AP 模式 | WIFI_COUNTRY_POLICY_MANUAL | 总是使用配置的国家/地区信息。 | -+---------------------+----------------------------+------------------------------------------------------------------------------+ -| Station/AP 共存模式 | WIFI_COUNTRY_POLICY_AUTO | 如果 station 不连接任何 AP，AP 使用配置的国家/地区信息。如果 station | -| | | 连接一个 AP，该 AP 的国家/地区信息与该 station 相同。与 | -| | | Station 模式、WIFI_COUNTRY_POLICY_AUTO 政策下使用的国家/地区信息相同。 | -+---------------------+----------------------------+------------------------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 15 35 + + * - Wi-Fi 模式 + - 政策 + - 描述 + * - station 模式 + - WIFI_COUNTRY_POLICY_AUTO + - 如果所连 AP 的 beacon 中有国家/地区的 IE，使用的国家/地区信息为 beacon 中的信息，否则，使用默认信息。 + + 扫描时： + + - 如果 schan+nchan-1>11： + + 主动扫描起始信道至信道 11，被动扫描信道 12 至 信道 schan+nchan-1。 + + - 如果 schan+nchan-1<=11： + + 主动扫描起始信道至信道 schan+nchan-1。 + + 请记住，如果 AP 带有隐藏 SSID 且 station 被设置为被动扫描信道，被动扫描将无法找到该 AP。也就是说，如果应用程序希望在每个信道中找到带有隐藏 SSID 的 AP，国家/地区信息应该配置为 WIFI_COUNTRY_POLICY_MANUAL。 + + * - station 模式 + - WIFI_COUNTRY_POLICY_MANUAL + - 总是使用配置的国家/地区信息。 扫描时，主动扫描起始信道至信道 schan+nchan-1。 + * - AP 模式 + - WIFI_COUNTRY_POLICY_AUTO + - 总是使用配置的国家/地区信息。 + * - AP 模式 + - WIFI_COUNTRY_POLICY_MANUAL + - 总是使用配置的国家/地区信息。 + * - station/AP 共存模式 + - WIFI_COUNTRY_POLICY_AUTO + - 如果 station 不连接任何外部 AP，AP 使用配置的国家/地区信息。如果 station 连接一个外部 AP，该 AP 的国家/地区信息与该 station 相同。 + + 与 station 模式、WIFI_COUNTRY_POLICY_AUTO 政策下使用的国家/地区信息相同。 主信道 ************************* -AP 模式下，AP 的信道定义为主信道。Station 模式下，station 所连 AP 的信道定义为主信道。Station/AP 共存模式下，AP 和 station 的主信道必须相同。如果不同，station 的主信道始终优先。比如，初始时，AP 位于信道 6 ，但 station 连接信道 9 的 AP。因为 station 的主信道具有优先性，该 AP 需要将信道从 6 切换至 9，确保与 station 主信道相同。切换信道时，SoftAP 模式下的 {IDF_TARGET_NAME} 将使用信道切换公告 (CSA) 通知连接的station。支持信道切换的 station 将直接通过，无需与 SoftAP 断连再重新连接。 +AP 模式下，AP 的信道定义为主信道。station 模式下，station 所连 AP 的信道定义为主信道。station/AP 共存模式下，AP 和 station 的主信道必须相同。如果不同，station 的主信道始终优先。比如，初始时，AP 位于信道 6，但 station 连接信道 9 的 AP。因为 station 的主信道具有优先性，该 AP 需要将信道从 6 切换至 9，确保与 station 主信道相同。切换信道时，AP 模式下的 {IDF_TARGET_NAME} 将使用信道切换公告 (CSA) 通知连接的 station。支持信道切换的 station 将直接通过，无需与 AP 断连再重新连接。 Wi-Fi 供应商 IE 配置 @@ -1262,48 +1291,77 @@ Wi-Fi 供应商 IE 配置 默认情况下，所有 Wi-Fi 管理帧都由 Wi-Fi 驱动程序处理，应用程序不需要任何操作。但是，某些应用程序可能需要处理 beacon、probe request、probe response 和其他管理帧。例如，如果在管理帧中插入一些只针对供应商的 IE，则只有包含此 IE 的管理帧才能得到处理。{IDF_TARGET_NAME} 中，:cpp:func:`esp_wifi_set_vendor_ie()` 和 :cpp:func:`esp_wifi_set_vendor_ie_cb()` 负责此类任务。 -Wi-Fi 安全性 -------------------------------- -除了传统的安全保障方法 (WEP/WPA-TKIP/WPA2-CCMP)，{IDF_TARGET_NAME} Wi-Fi 如今还支持最先进的安全协议，即基于 802.11w 标准的“受保护的管理帧” (PMF) 和 Wi-Fi Protected Access 3 (WPA3-Personal) 技术。PMF 与 WPA3 一道，提供更好的隐私性，也能更强地抵御传统模式下的已知攻击。 +Wi-Fi Easy Connect™ (DPP) +-------------------------- -受保护的管理帧 (PMF) -++++++++++++++++++++++++++++++++++ +Wi-Fi Easy Connect\ :sup:`TM`（也称为设备配置协议）是一个安全且标准化的配置协议，用于配置 Wi-Fi 设备。更多信息请参考 :doc:`esp_dpp <../api-reference/network/esp_dpp>`。 -在 Wi-Fi 中，非 AP station 使用 beacon、探测器、(de)authentication、(dis)association 等管理帧来扫描和连接 AP。与数据帧不同，这些帧发送时未加密。 -攻击者可以使用窃听和数据包注入等方式在恰当的时间发送虚假的 (de)authentication 和 (dis)association 帧，如果未受保护的管理帧发生改变，将出现以下攻击。 - - - 在攻击者范围内对一个或所有 client 进行 DOS 攻击。 - - 通过发送关联请求取消 AP 端的现有关联。 - - 如果 PSK 遭到破坏，强制 client 再次执行 4 次握手，以获得 PTK。 - - 从关联请求获取隐藏网络的 SSID。 - - 强制 client 从合法 AP 中 (de)authentication，并关联到流氓 AP，发起中间人攻击。 - -PMF 通过对单播管理帧进行加密，并检查广播管理帧的完整性，阻止上述攻击。其中包括 (de)authentication、(dis)association 和强奸的管理帧。PMF 同样提供“安全关联” (SA) 拆解机制，阻止欺骗 association/authentication frame 断开已连接的 client。 - -关于PMF，{IDF_TARGET_NAME} 支持以下三种操作模式。 - - - 不支持 PMF：此模式下，{IDF_TARGET_NAME} 向 AP 表示在关联过程中不能支持管理保护。实际上，此模式下的安全性与传统模式相同。 - - 支持但未要求使用 PMF：此模式下，{IDF_TARGET_NAME} 向AP表示能够支持 PMF。如果 AP 授权 PMF 或至少能支持 PMF，将使用管理保护。 - - 支持且需要 PMF：此模式下，如果 AP 支持 PMF，{IDF_TARGET_NAME} 将仅连接该 AP。如果不支持，{IDF_TARGET_NAME} 将拒绝连接该 AP。 - -通过在 `pmf_cfg` 参数中设置适当标志，:cpp:func:`esp_wifi_set_config` 可以用来配置 PMF 模式。目前，仅 station 模式支持 PMF。 - - -WPA3-Personal +WPA2-Enterprise +++++++++++++++++++++++++++++++++ -Wi-Fi Protected Access-3 (WPA3) 是一套增强 Wi-Fi 接入安全性的措施，旨在取代目前的 WPA2 标准。为了提供更强健的认证方式，WPA3 采用了等值同时认证 (SAE) 算法，即基于 Diffie-Hellman 密钥交换的密码认证密钥协议方法。与 WPA2 不同，该技术可以抵御离线字典攻击，即攻击者试图在没有任何进一步网络交互的情况下，根据捕获的 4 次握手来确定共享密码。WPA3 还提供前向保密功能，即数据传输后，即使密码泄露，也无法对捕获的数据进行解密。更多详细信息，请见 Wi-Fi 联盟官方网站 `Security `_ 一章。 +WPA2-Enterprise 是企业无线网络的安全认证机制。在连接到接入点之前，它使用 RADIUS 服务器对网络用户进行身份验证。身份验证过程基于 802.1X 标准，并有不同的扩展身份验证协议 (EAP) 方法，如 TLS、TTLS、PEAP 等。RADIUS 服务器根据用户的凭据（用户名和密码）、数字证书或两者对用户进行身份验证。当处于 station 模式的 {IDF_TARGET_NAME} 尝试连接到企业模式的 AP 时，它会向 AP 发送身份验证请求，AP 会将该请求发送到 RADIUS 服务器以对 station 进行身份验证。根据不同的 EAP 方式，可以通过 ``idf.py menuconfig`` 打开配置，并在配置中设置参数。{IDF_TARGET_NAME} 仅在 station 模式下支持 WPA2_Enterprise。 -要使能 WPA3-Personal，请在 menuconfig 中选择 "Enable WPA3-Personal"。使能后，如果 AP 支持，{IDF_TARGET_NAME} 会使用 SAE 进行身份认证。由于 WPA3 强制要求 PMF，{IDF_TARGET_NAME} 要使用 WPA3 模式，至少应该将 PMF 模式设置为 "PMF capable, but not required"（支持但未要求使用 PMF）。应用程序的安全模式已经选用最高级别，因此开发者无需担心。请注意，使用 WPA3 时，Wi-Fi 协议栈大小要求将增加约 3 k。目前，仅 Station 模式支持 WPA3。 +为了建立安全连接，AP 和 station 协商并就要使用的最佳密码套件达成一致。{IDF_TARGET_NAME} 支持 AKM 的 802.1X/EAP (WPA) 方法和 AES-CCM（高级加密标准-带密码块链消息验证码协议的计数器模式）支持的密码套件。如果设置了 `USE_MBEDTLS_CRYPTO` 标志，{IDF_TARGET_NAME} 也支持 mbedtls 支持的密码套件。 + +目前，{IDF_TARGET_NAME} 支持以下 EAP 方法： + - EAP-TLS: 这是基于证书的方法，只需要 SSID 和 EAP-IDF。 + - PEAP: - PEAP：这是受保护的 EAP 方法。用户名和密码是必填项。 + - EAP-TTLS: 这是基于凭据的方法。只有服务器身份验证是强制性的，而用户身份验证是可选的。用户名和密码是必填项。 它支持不同的 Phase2 方法，例如： + - PAP: 密码认证协议 + - CHAP: 询问握手身份验证协议 + - MSCHAP 和 MSCHAP-V2 + + +请查看 :example:`wifi/wifi_enterprise` 获取关于证书创建以及如何在 {IDF_TARGET_NAME} 上运行 wpa2_enterprise 示例的详细信息。 + +无线网络管理 +---------------------------- + +无线网络管理让客户端设备能够交换有关网络拓扑结构的信息，包括与射频环境相关的信息。这使每个客户端都能感知网络状况，从而促进无线网络性能的整体改进。这是 802.11v 规范的一部分。它还使客户端能够支持网络辅助漫游。 +网络辅助漫游让 WLAN 能够向关联的客户端发送消息，从而使客户端与具有更好链路指标的 AP 关联。这对于促进负载平衡以及引导连接不良的客户端都很有用。 + +目前 802.11v 的实现支持 BSS 过渡管理帧。 + +无线资源管理 +--------------------------- + +无线电资源测量（802.11k）旨在改善网络内流量的分配方式。在无线局域网中，一般情况下，无线设备会连接发射信号最强的接入点 (AP)。根据用户的数量和地理位置，这种分配方式有时会导致某个接入点超负荷而其它接入点利用不足，从而导致整体网络性能下降。在符合 802.11k 规范的网络中，如果信号最强的 AP 已满负荷加载，无线设备则转移到其它未充分利用的 AP。尽管信号可能较弱，但由于更有效地利用了网络资源，总体吞吐量会更大。 + +目前 802.11k 的实现支持信标测量报告、链路测量报告和邻居请求。 + +请参考 IDF 示例程序 :idf_file:`examples/wifi/roaming/README.md` 来设置和使用这些 API。示例代码只演示了如何使用这些 API，应用程序应根据需要定义自己的算法和案例。 + +.. only:: esp32s2 or esp32c3 + + Wi-Fi Location + ------------------------------- + + Wi-Fi Location 将提高 AP 以外设备位置数据的准确性，这有助于创建新的、功能丰富的应用程序和服务，例如地理围栏、网络管理、导航等。用于确定设备相对于接入点的位置的协议之一是精细定时测量 (FTM)，它会计算 Wi-Fi 帧的飞行时间。 + + 精细定时测量 (FTM) + +++++++++++++++++++++++++++++ + + FTM 用于测量 Wi-Fi 往返时间（Wi-Fi RTT)，即 Wi-Fi 信号从一个设备到另一个设备并返回所需的时间。使用 Wi-Fi RTT，设备之间的距离可以用一个简单的公式 `RTT * c / 2` 来计算，其中 c 是光速。 + + 对于设备之间交换的帧，FTM 在帧到达或离开时使用时间戳，这个时间戳由 Wi-Fi 接口硬件提供。FTM 发起方（主要是 station 设备）发现 FTM 响应方（可以是 station 或 AP），并协商启动 FTM 程序。该程序以突发形式发送的多个动作帧及其 ACK 来收集时间戳数据。FTM 发起方最后收集数据以计算平均往返时间。 + + {IDF_TARGET_NAME} 在以下配置中支持 FTM： + + - {IDF_TARGET_NAME} 在 station 模式下为 FTM 发起方。 + - {IDF_TARGET_NAME} 在 AP 模式下为 FTM 响应方。 + + 使用 RTT 的距离测量并不准确，RF 干扰、多径传播、天线方向和缺乏校准等因素会增加这些不准确度。为了获得更好的结果，建议在两个 {IDF_TARGET_NAME} 设备之间执行 FTM，这两个设备可分别设置为 station 和 AP 模式。 + + 请参考 IDF 示例 :idf_file:`examples/wifi/ftm/README.md` 了解设置和执行 FTM 的详细步骤。 {IDF_TARGET_NAME} Wi-Fi 节能模式 ----------------------------------------- -Station 睡眠 +station 睡眠 ++++++++++++++++++++++ -目前， {IDF_TARGET_NAME} Wi-Fi 支持 Modem-sleep 模式，该模式是 IEEE 802.11 协议中的传统节能模式。仅 Station 模式支持该模式，station 必须先连接到 AP。如果使能了 Modem-sleep 模式，station 将定期在活动状态和睡眠状态之间切换。在睡眠状态下，RF、PHY 和 BB 处于关闭状态，以减少功耗。Modem-sleep 模式下，station 可以与 AP 保持连接。 +目前， {IDF_TARGET_NAME} Wi-Fi 支持 Modem-sleep 模式，该模式是 IEEE 802.11 协议中的传统节能模式。仅 station 模式支持该模式，station 必须先连接到 AP。如果使能了 Modem-sleep 模式，station 将定期在活动状态和睡眠状态之间切换。在睡眠状态下，RF、PHY 和 BB 处于关闭状态，以减少功耗。Modem-sleep 模式下，station 可以与 AP 保持连接。 Modem-sleep 模式包括最小和最大节能模式。在最小节能模式下，每个 DTIM 间隔，station 都将唤醒以接收 beacon。广播数据在 DTIM 之后传输，因此不会丢失。但是，由于 DTIM 间隔长短由 AP 决定，如果该间隔时间设置较短，则省电效果不大。 @@ -1329,69 +1387,139 @@ AP 睡眠 .. only:: esp32 - +----------------------------+----------------+------------+---------------+----------------------+ - | 类型/吞吐量 | 实验室空气状况 | 屏蔽箱 | 测试工具 | IDF 版本 (commit ID) | - +----------------------------+----------------+------------+---------------+----------------------+ - | 原始 802.11 数据包接收数据 | N/A | 130 MBit/s | 内部工具 | N/A | - +----------------------------+----------------+------------+---------------+----------------------+ - | 原始 802.11 数据包发送数据 | N/A | 130 MBit/s | 内部工具 | N/A | - +----------------------------+----------------+------------+---------------+----------------------+ - | UDP 接收数据 | 30 MBit/s | 85 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ - | UDP 发送数据 | 30 MBit/s | 75 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ - | TCP 接收数据 | 20 MBit/s | 65 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ - | TCP 发送数据 | 20 MBit/s | 75 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 15 20 + + * - 类型/吞吐量 + - 实验室空气状况 + - 屏蔽箱 + - 测试工具 + - IDF 版本 (commit ID) + * - 原始 802.11 数据包接收数据 + - N/A + - **130 MBit/s** + - 内部工具 + - N/A + * - 原始 802.11 数据包发送数据 + - N/A + - **130 MBit/s** + - 内部工具 + - N/A + * - UDP 接收数据 + - 30 MBit/s + - 85 MBit/s + - iperf example + - 15575346 + * - UDP 发送数据 + - 30 MBit/s + - 75 MBit/s + - iperf example + - 15575346 + * - TCP 接收数据 + - 20 MBit/s + - 65 MBit/s + - iperf example + - 15575346 + * - TCP 发送数据 + - 20 MBit/s + - 75 MBit/s + - iperf example + - 15575346 使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:` 示例/wifi/iperf/sdkconfig.defaults.esp32`。 .. only:: esp32s2 - +----------------------------+----------------+------------+---------------+----------------------+ - | 类型/吞吐量 | 实验室空气状况 | 屏蔽箱 | 测试工具 | IDF 版本 (commit ID) | - +----------------------------+----------------+------------+---------------+----------------------+ - | 原始 802.11 数据包接收数据 | N/A | 130 MBit/s | 内部工具 | N/A | - +----------------------------+----------------+------------+---------------+----------------------+ - | 原始 802.11 数据包发送数据 | N/A | 130 MBit/s | 内部工具 | N/A | - +----------------------------+----------------+------------+---------------+----------------------+ - | UDP 接收数据 | 30 MBit/s | 70 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ - | UDP 发送数据 | 30 MBit/s | 50 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ - | TCP 接收数据 | 20 MBit/s | 32 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ - | TCP 发送数据 | 20 MBit/s | 37 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 15 20 + + * - 类型/吞吐量 + - 实验室空气状况 + - 屏蔽箱 + - 测试工具 + - IDF 版本 (commit ID) + * - 原始 802.11 数据包接收数据 + - N/A + - **130 MBit/s** + - 内部工具 + - N/A + * - 原始 802.11 数据包发送数据 + - N/A + - **130 MBit/s** + - 内部工具 + - N/A + * - UDP 接收数据 + - 30 MBit/s + - 70 MBit/s + - iperf example + - 15575346 + * - UDP 发送数据 + - 30 MBit/s + - 50 MBit/s + - iperf example + - 15575346 + * - TCP 接收数据 + - 20 MBit/s + - 32 MBit/s + - iperf example + - 15575346 + * - TCP 发送数据 + - 20 MBit/s + - 37 MBit/s + - iperf example + - 15575346 使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:` 示例/wifi/iperf/sdkconfig.defaults.esp32s2`。 .. only:: esp32c3 - +----------------------------+----------------+------------+---------------+----------------------+ - | 类型/吞吐量 | 实验室空气状况 | 屏蔽箱 | 测试工具 | IDF 版本 (commit ID) | - +----------------------------+----------------+------------+---------------+----------------------+ - | 原始 802.11 数据包接收数据 | N/A | 130 MBit/s | 内部工具 | N/A | - +----------------------------+----------------+------------+---------------+----------------------+ - | 原始 802.11 数据包发送数据 | N/A | 130 MBit/s | 内部工具 | N/A | - +----------------------------+----------------+------------+---------------+----------------------+ - | UDP 接收数据 | 30 MBit/s | 50 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ - | UDP 发送数据 | 30 MBit/s | 40 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ - | TCP 接收数据 | 20 MBit/s | 35 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ - | TCP 发送数据 | 20 MBit/s | 37 MBit/s | iperf example | 15575346 | - +----------------------------+----------------+------------+---------------+----------------------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 15 20 + + * - 类型/吞吐量 + - 实验室空气状况 + - 屏蔽箱 + - 测试工具 + - IDF 版本 (commit ID) + * - 原始 802.11 数据包接收数据 + - N/A + - **130 MBit/s** + - 内部工具 + - N/A + * - 原始 802.11 数据包发送数据 + - N/A + - **130 MBit/s** + - 内部工具 + - N/A + * - UDP 接收数据 + - 30 MBit/s + - 50 MBit/s + - iperf example + - 15575346 + * - UDP 发送数据 + - 30 MBit/s + - 40 MBit/s + - iperf example + - 15575346 + * - TCP 接收数据 + - 20 MBit/s + - 35 MBit/s + - iperf example + - 15575346 + * - TCP 发送数据 + - 20 MBit/s + - 37 MBit/s + - iperf example + - 15575346 使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:` 示例/wifi/iperf/sdkconfig.defaults.esp32c3`。 Wi-Fi 80211 数据包发送 --------------------------- -**重要说明：API esp_wifi_80211_tx 在 IDF 2.1 中不可用，即将发布的版本将可以使用。** - :cpp:func:`esp_wifi_80211_tx` API 可用于： - 发送 beacon、probe request、probe response 和 action 帧。 @@ -1402,95 +1530,76 @@ Wi-Fi 80211 数据包发送 使用 :cpp:func:`esp_wifi_80211_tx` 的前提条件 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ - - Wi-Fi 模式为 Station 模式， AP 模式，或 Station/AP 共存模式。 - - API esp_wifi_set_promiscuous(true) 或 :cpp:func:`esp_wifi_start()`，或者二者都返回 ESP_OK。这是为确保调用函数 :cpp:func:`esp_wifi_80211_tx()` 前，Wi-Fi 硬件已经初始化。对于 {IDF_TARGET_NAME}，esp_wifi_set_promiscuous(true) 和 :cpp:func:`esp_wifi_start()` 都可以触发 Wi-Fi 硬件初始化。 + - Wi-Fi 模式为 station 模式，AP 模式，或 station/AP 共存模式。 + - API esp_wifi_set_promiscuous(true) 或 :cpp:func:`esp_wifi_start()`，或者二者都返回 ESP_OK。这是为确保在调用函数 :cpp:func:`esp_wifi_80211_tx()` 前，Wi-Fi 硬件已经初始化。对于 {IDF_TARGET_NAME}，esp_wifi_set_promiscuous(true) 和 :cpp:func:`esp_wifi_start()` 都可以触发 Wi-Fi 硬件初始化。 - 提供正确的 :cpp:func:`esp_wifi_80211_tx` 参数。 传输速率 +++++++++++++++++++++++++++++ - 如果没有 Wi-Fi 连接，传输速率为 1 Mbps。 - - 如果有 WiFi 连接，且数据包是从 station 到 AP 或从 AP 到 station，则传输速率与 Wi-Fi 连接相同。否则，传输速率为 1 Mbps。 + - 如果有 Wi-Fi 连接，且数据包是从 station 到 AP 或从 AP 到 station，则传输速率与 Wi-Fi 连接相同。否则，传输速率为 1 Mbps。 在不同情况下需要避免的副作用 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 理论上，如果不考虑 API 对 Wi-Fi 驱动程序或其他 station 或 AP 的副作用，可以通过空中发送一个原始的 802.11 数据包，包括任何目的地址的 MAC、任何源地址的 MAC、任何 BSSID、或任何其他类型的数据包。但是，一个具有强健、有用的应用程序应该避免这种副作用。下表针对如何避免 :cpp:func:`esp_wifi_80211_tx` 的副作用提供了一些提示或建议。 -+---------------+--------------------------------------------------------------------------------------------+ -| 场景 | 描述 | -+---------------+--------------------------------------------------------------------------------------------+ -| 无 Wi-Fi 连接 | 在这种情况下，因为没有 Wi-Fi 连接，Wi-Fi 驱动程序不会受到副作用影响。如果 | -| | en_sys_seq==true，则 Wi-Fi 驱动程序负责序列控制。如果 | -| | en_sys_seq==false，应用程序需要确保缓冲区的序列正确。 | -| | | -| | 理论上，MAC 地址可以是任何地址。但是，这样可能会影响其他使用相同 MAC/BSSID 的 station/AP。 | -| | | -| | 例如，AP 模式下，应用程序调用函数 | -| | :cpp:func:`esp_wifi_80211_tx` 发送带有 BSSID == mac_x 的 beacon，但是 mac_x | -| | 并非 AP 接口的 MAC。而且，还有 另一个 AP（我们称之为 "other-AP"）的 bssid 是 | -| | mac_x。因此，连接到 "other-AP" 的 station 无法分辨 beacon 来自 "other-AP" 还是 | -| | :cpp:func:`esp_wifi_80211_tx`，就会出现 “意外行为”。 | -| | | -| | 为了避免上述副作用，我们建议： | -| | | -| | -如果在 Station 模式下调用函数 :cpp:func:`esp_wifi_80211_tx`，第一个 MAC 应该是组播 | -| | | -| | MAC 或是目标设备的 MAC，第二个 MAC 应该是 station 接口的 MAC。 | -| | | -| | -如果在 AP 模式下调用函数 esp_wifi_80211_tx，第一个 MAC 应该是组播 MAC 或是目标设备的 | -| | | -| | MAC， 第二个 MAC 应该是 AP 接口的 MAC。 | -| | | -| | 上述建议仅供避免副作用，在有充分理由的情况下可以忽略。 | -+---------------+--------------------------------------------------------------------------------------------+ -| 有 Wi-Fi 连接 | 当 Wi-Fi 已连接，且序列由应用程序控制，应用程序可能会影响整个 Wi-Fi | -| | 连接的序列控制。 因此，en_sys_seq 要为 true，否则将返回 ESP_ERR_WIFI_ARG。 | -| | | -| | “无 Wi-Fi 连接” 情况下的 MAC 地址建议也适用于此情况。如果 Wi-Fi | -| | 模式是 Station 模式，MAC 的地址 1 是 station 所连 AP 的 MAC，地址 | -| | 2 是 station 接口的 MAC，那么就称数据包是从 station 发送到 AP。另一方面，如果 Wi-Fi | -| | 模式是 AP 模式，且 MAC 地址 1 是该 AP 所连 station 的 MAC，地址 2 是 | -| | AP 接口的 MAC，那么就称数据包是从 AP 发送到 station。为避免与 | -| | Wi-Fi 连接冲突，可采用以下检查方法： | -| | | -| | -如果数据包类型是数据，且是从 station 发送到 AP，IEEE 802.11 | -| | | -| | Frame control 字段中的 ToDS 位应该为 1，FromDS 位为 0，否则，Wi-Fi | -| | | -| | 驱动程序不接受该数据包。 | -| | | -| | -如果数据包类型是数据，且是从 AP 发送到 station，IEEE 802.11 | -| | | -| | Frame control 字段中的 ToDS 位应该为 0，FromDS 位为 1，否则，Wi-Fi | -| | | -| | 驱动程序不接受该数据包。 | -| | | -| | -如果数据包是从 station 发送到 AP，或从 AP 到 station，Power Management、More | -| | | -| | Data 和 Re-Transmission 位应该为 0，否则，Wi-Fi 驱动程序不接受该数据包。 | -| | | -| | 如果任何检查失败，将返回 ESP_ERR_WIFI_ARG。 | -+---------------+--------------------------------------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 10 55 + + * - 场景 + - 描述 + * - 无 Wi-Fi 连接 + - 在这种情况下，因为没有 Wi-Fi 连接，Wi-Fi 驱动程序不会受到副作用影响。如果 en_sys_seq==true，则 Wi-Fi 驱动程序负责序列控制。如果 en_sys_seq==false，应用程序需要确保缓冲区的序列正确。 + + 理论上，MAC 地址可以是任何地址。但是，这样可能会影响其他使用相同 MAC/BSSID 的 station/AP。 + + 例如，AP 模式下，应用程序调用函数 esp_wifi_80211_tx() 发送带有 BSSID == mac_x 的 beacon，但是 mac_x 并非 AP 接口的 MAC。而且，还有另一个 AP（我们称之为 “other-AP”）的 bssid 是 mac_x。因此，连接到 “other-AP” 的 station 无法分辨 beacon 来自 “other-AP” 还是 esp_wifi_80211_tx()，就会出现 “意外行为”。 + + 为了避免上述副作用，我们建议： + + - 如果在 station 模式下调用函数 esp_wifi_80211_tx()，第一个 MAC 应该是组播 MAC 或是目标设备的 MAC，第二个 MAC 应该是 station 接口的 MAC。 + + - 如果在 AP 模式下调用函数 esp_wifi_80211_tx，第一个 MAC 应该是组播 MAC 或是目标设备的 MAC，第二个 MAC 应该是 AP 接口的 MAC。 + + 上述建议仅供避免副作用，在有充分理由的情况下可以忽略。 + + * - 有 Wi-Fi 连接 + - 当 Wi-Fi 已连接，且序列由应用程序控制，应用程序可能会影响整个 Wi-Fi 连接的序列控制。 因此，en_sys_seq 要为 true，否则将返回 ESP_ERR_WIFI_ARG。 + + “无 Wi-Fi 连接”情况下的 MAC 地址建议也适用于此情况。 + + 如果 Wi-Fi 模式是 station 模式，MAC 的地址 1 是 station 所连 AP 的 MAC，地址 2 是 station 接口的 MAC，那么就称数据包是从 station 发送到 AP。另一方面，如果 Wi-Fi 模式是 AP 模式，且 MAC 地址 1 是该 AP 所连 station 的 MAC，地址 2 是 AP 接口的 MAC，那么就称数据包是从 AP 发送到 station。为避免与 Wi-Fi 连接冲突，可采用以下检查方法： + + - 如果数据包类型是数据，且是从 station 发送到 AP，IEEE 802.11 Frame control 字段中的 ToDS 位应该为 1，FromDS 位为 0，否则，Wi-Fi 驱动程序不接受该数据包。 + + - 如果数据包类型是数据，且是从 AP 发送到 station，IEEE 802.11 Frame control 字段中的 ToDS 位应该为 0，FromDS 位为 1，否则，Wi-Fi 驱动程序不接受该数据包。 + + - 如果数据包是从 station 发送到 AP，或从 AP 到 station，Power Management、More Data 和 Re-Transmission 位应该为 0，否则，Wi-Fi 驱动程序不接受该数据包。 + + 如果任何检查失败，将返回 ESP_ERR_WIFI_ARG。 + Wi-Fi Sniffer 模式 --------------------------- -Wi-Fi Sniffer 模式可以通过 :cpp:func:`esp_wifi_set_promiscuous()` 使能。如果使能 Sniffer 模式， **可以** -向应用程序转储以下数据包。 +Wi-Fi Sniffer 模式可以通过 :cpp:func:`esp_wifi_set_promiscuous()` 使能。如果使能 Sniffer 模式， **可以** 向应用程序转储以下数据包。 - 802.11 管理帧 - 802.11 数据帧，包括 MPDU、AMPDU、AMSDU 等 - 802.11 MIMO 帧，Sniffer 模式仅转储 MIMO 帧的长度。 - 802.11 控制帧 + - 802.11 CRC 错误帧 **不可以** 向应用程序转储以下数据包。 - - 802.11 错误帧，如有 CRC 错误的帧等。 + - 802.11 其它错误帧 -对于Sniffer 模式 **可以** 转储的帧，应用程序可以另外使用 :cpp:func:`esp_wifi_set_promiscuous_filter()` 和 :cpp:func:`esp_wifi_set_promiscuous_ctrl_filter()` 决定筛选哪些特定类型的数据包。应用程序默认筛选所有 802.11 数据和管理帧。 +对于 Sniffer 模式 **可以** 转储的帧，应用程序可以另外使用 :cpp:func:`esp_wifi_set_promiscuous_filter()` 和 :cpp:func:`esp_wifi_set_promiscuous_ctrl_filter()` 决定筛选哪些特定类型的数据包。应用程序默认筛选所有 802.11 数据和管理帧。 -可以在 WIFI_MODE_NULL、WIFI_MODE_STA、WIFI_MODE_AP、WIFI_MODE_APSTA 等Wi-Fi 模式下使能 Wi-Fi Sniffer 模式。也就是说，当 station 连接到 AP，或者 AP 有 Wi-Fi 连接时，就可以使能。请注意，Sniffer 模式对 station/AP Wi-Fi 连接的吞吐量有 **很大影响**。通常，除非有特别原因，当 station/AP Wi-Fi 连接出现大量流量，不应使能。 +可以在 WIFI_MODE_NULL、WIFI_MODE_STA、WIFI_MODE_AP、WIFI_MODE_APSTA 等 Wi-Fi 模式下使能 Wi-Fi Sniffer 模式。也就是说，当 station 连接到 AP，或者 AP 有 Wi-Fi 连接时，就可以使能。请注意，Sniffer 模式对 station/AP Wi-Fi 连接的吞吐量有 **很大影响**。通常，除非有特别原因，当 station/AP Wi-Fi 连接出现大量流量，不应使能。 该模式下还应注意回调函数 wifi_promiscuous_cb_t 的使用。该回调将直接在 Wi-Fi 驱动程序任务中进行，所以如果应用程序需处理大量过滤的数据包，建议在回调中向应用程序任务发布一个事件，把真正的工作推迟到应用程序任务中完成。 @@ -1523,7 +1632,6 @@ Wi-Fi 多根天线 - 因为发送数据天线基于 WIFI_ANT_MODE_AUTO 类型的接收数据天线选择算法，只有接收数据的天线模式为 WIFI_ANT_MODE_AUTO 时，发送数据天线才能设置为 WIFI_ANT_MODE_AUTO。 - 目前，Bluetooth® 不支持多根天线功能，请不要使用与多根天线有关的 API。 - - 目前不支持 Bluetooth/Bluetooth LE SoftAP 共存模式。 推荐在以下场景中使用多根天线： @@ -1565,7 +1673,7 @@ Wi-Fi 信道状态信息 | +-------------+-------------+---------------------------+---------+---------------+---------------------------+---------+------------------+---------------------------+ | | 信道带宽 | 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 | 非 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 | | +-------------+-------------+-------------+-------------+---------+--------+------+-------------+-------------+---------+---------+--------+-------------+-------------+ @@ -1583,22 +1691,22 @@ Wi-Fi 信道状态信息 - 信道带宽指 rx_ctrl 字段中的 cwb 字段。 - STBC 指 rx_ctrl 字段的 stbc 字段。 - 总字节数指 len 字段。 - - 每个长训练字段 (LTF) 类型对应的CSI数据存储在从 buf 字段开始的缓冲区中。每个项目以两个字节的形式存储：虚部和实部。每个项目的顺序与表中的子载波相同。LTF 的顺序是 LLTF、HT-LTF 和 STBC-HT-LTF。但是，根据信道和数据包的信息，3 个 LTF 可能都不存在（见上文）。 + - 每个长训练字段 (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 领域。 + - 更多信息，如 RSSI，射频的噪声底，接收时间和天线 rx_ctrl 领域。 .. note :: - 对于 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，结果对齐为四个字节，最后两个字节无效）。 + - 如果调用 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 信道状态信息配置 ------------------------------------------- 要使用 Wi-Fi CSI，需要执行以下步骤。 - - 在菜单配置中选择 Wi-Fi CSI。方法是“菜单配置 - > 组件配置 -- > Wi-Fi -- > WiFi 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。 @@ -1610,13 +1718,13 @@ 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。 -Station 模式下，实际带宽首先在 Wi-Fi 连接时协商。只有当 station 和所连 AP 都支持 HT40 时，带宽才为 HT40，否则为 HT20。如果所连的 AP 的带宽发生变化，则在不断开 Wi-Fi 连接的情况下再次协商实际带宽。 +station 模式下，实际带宽首先在 Wi-Fi 连接时协商。只有当 station 和所连 AP 都支持 HT40 时，带宽才为 HT40，否则为 HT20。如果所连的 AP 的带宽发生变化，则在不断开 Wi-Fi 连接的情况下再次协商实际带宽。 同样，在 AP 模式下，在 AP 与所连 station 协商实际带宽。如果 AP 和其中一个 station 支持 HT40， 则为 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。 +在 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 数据速率为 150Mbps，而 HT20 为 72Mbps。但是，如果设备在某些特殊环境中使用，例如，{IDF_TARGET_NAME} 周围其他 Wi-Fi 设备过多，HT40 的性能可能会降低。因此，如果应用程序需要支持相同或类似的情况，建议始终将带宽配置为 HT20。 +理论上，HT40 可以获得更大的吞吐量，因为 HT40 的最大原始 PHY 数据速率为 150 Mbps，而 HT20 为 72 Mbps。但是，如果设备在某些特殊环境中使用，例如，{IDF_TARGET_NAME} 周围其他 Wi-Fi 设备过多，HT40 的性能可能会降低。因此，如果应用程序需要支持相同或类似的情况，建议始终将带宽配置为 HT20。 Wi-Fi QoS ------------------------- @@ -1649,7 +1757,7 @@ Wi-Fi 协议中定义了四个 AC （访问类别），每个 AC 有各自的优 理论上，高优先级的 AC 比低优先级 AC 具有更好的性能，但并非总是如此，下面是一些关于如何使用 Wi-Fi QoS 的建议： - 可以把一些真正重要的应用程序流量放到 AC_VO 队列中。避免通过 AC_VO 队列发送大流量。一方面，AC_VO 队列不支持 AMPDU，如果流量很大，性能不会优于其他队列。另一方面，可能会影响同样使用 AC_VO 队列的管理帧。 - - 避免使用 AMPDU 支持的、两个以上的不同优先级，比如 socket A 使用优先级 0，socket B 使用优先级 1，socket C 使用优先级 2。因为可能需要更多的内存，不是好的设计。具体来说，Wi-Fi 驱动程序可能会为每个优先级生成一个 Block Ack 会话，如果设置了Block Ack会话，则需要更多内存。 + - 避免使用 AMPDU 支持的、两个以上的不同优先级，比如 socket A 使用优先级 0，socket B 使用优先级 1，socket C 使用优先级 2。因为可能需要更多的内存，不是好的设计。具体来说，Wi-Fi 驱动程序可能会为每个优先级生成一个 Block Ack 会话，如果设置了 Block Ack 会话，则需要更多内存。 Wi-Fi AMSDU @@ -1671,7 +1779,7 @@ Wi-Fi 分片 WPS 注册 ------------------------- -在 Wi-Fi 模式 WIFI_MODE_STA 或 WIFI_MODE_APSTA 下，{IDF_TARGET_NAME} 支持 WPS注册功能。目前，{IDF_TARGET_NAME} 支持的 WPS enrollee 类型有 PBC 和 PIN。 +在 Wi-Fi 模式 WIFI_MODE_STA 或 WIFI_MODE_APSTA 下，{IDF_TARGET_NAME} 支持 WPS 注册功能。目前，{IDF_TARGET_NAME} 支持的 WPS enrollee 类型有 PBC 和 PIN。 .. _wifi-buffer-usage: @@ -1723,7 +1831,7 @@ Wi-Fi 使用的堆内存峰值是 Wi-Fi 驱动程序 **理论上消耗的最大 如何提高 Wi-Fi 性能 ---------------------------------- -{IDF_TARGET_NAME} Wi-Fi 的性能收到许多参数的影响，各参数之间存在相互制约。如果配置地合理，不仅可以提高性能，还可以增加应用程序的可用内存，提高稳定性。 +{IDF_TARGET_NAME} Wi-Fi 的性能受许多参数的影响，各参数之间存在相互制约。如果配置地合理，不仅可以提高性能，还可以增加应用程序的可用内存，提高稳定性。 在本节中，我们将简单介绍 Wi-Fi/LWIP 协议栈的工作模式，并说明各个参数的作用。我们将推荐几种配置等级，您可以根据使用场景选择合适的等级。 @@ -1758,18 +1866,18 @@ Wi-Fi 使用的堆内存峰值是 Wi-Fi 驱动程序 **理论上消耗的最大 该参数表示接收端 AMPDU BA 窗口的大小，应配置为 :ref:`CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM` 和 :ref:`CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM` 的二倍数值中较小的数值。 - :ref:`CONFIG_LWIP_TCP_WND_DEFAULT` - 该参数表示 LWIP 层用于每个 TCP 流的的接收数据缓冲区大小，应配置为 WIFI_DYNAMIC_RX_BUFFER_NUM(KB) 的值，从而实现高稳定性能。同时，在有多个流的情况下，应相应降低该参数。 + 该参数表示 LWIP 层用于每个 TCP 流的的接收数据缓冲区大小，应配置为 WIFI_DYNAMIC_RX_BUFFER_NUM (KB) 的值，从而实现高稳定性能。同时，在有多个流的情况下，应相应降低该参数值。 **发送数据方向：** - - :ref:`CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM` + - :ref:`CONFIG_ESP32_WIFI_TX_BUFFER` 该参数表示发送数据缓冲区的类型，建议配置为动态缓冲区，该配置可以充分利用内存。 - :ref:`CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM` 该参数表示 Wi-Fi 层发送数据缓冲区数量。提高该参数可以增强数据包发送的性能。该参数值需要与 LWIP 层的发送数据缓冲区大小相匹配。 - :ref:`CONFIG_LWIP_TCP_SND_BUF_DEFAULT` - 该参数表示 LWIP 层用于每个 TCP 流的的发送数据缓冲区大小，应配置为 WIFI_DYNAMIC_TX_BUFFER_NUM(KB) 的值，从而实现高稳定性能。在有多个流的情况下，应相应降低该参数。 + 该参数表示 LWIP 层用于每个 TCP 流的的发送数据缓冲区大小，应配置为 WIFI_DYNAMIC_TX_BUFFER_NUM (KB) 的值，从而实现高稳定性能。在有多个流的情况下，应相应降低该参数值。 **通过在 IRAM 中放置代码优化吞吐量：** @@ -1808,161 +1916,396 @@ Wi-Fi 使用的堆内存峰值是 Wi-Fi 驱动程序 **理论上消耗的最大 .. only:: esp32 - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | 等级 | Iperf | 发送数据优先 | 高性能 | 接收数据优先 | 默认值 | 节省内存 | 最小 | - +============================+=======+==============+========+==============+========+==========+=======+ - | 可用内存 (KB) | 37.1 | 113.8 | 123.3 | 145.5 | 144.5 | 170.2 | 185.2 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | WIFI_STATIC_RX_BUFFER_NUM | 16 | 6 | 6 | 6 | 6 | 6 | 4 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 64 | 16 | 24 | 34 | 20 | 12 | 8 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | WIFI_DYNAMIC_TX_BUFFER_NUM | 64 | 28 | 24 | 18 | 20 | 12 | 8 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | WIFI_RX_BA_WIN | 32 | 8 | 12 | 12 | 10 | 6 | 禁用 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | TCP_SND_BUF_DEFAULT (KB) | 65 | 28 | 24 | 18 | 20 | 12 | 8 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | TCP_WND_DEFAULT (KB) | 65 | 16 | 24 | 34 | 20 | 12 | 8 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 15 | 15 | 15 | 15 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 16 | 16 | 16 | 16 | 16 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 13 | 13 | 13 | 13 | 13 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | TCP 发送数据吞吐量 (Mbit/s)| 74.6 | 50.8 | 46.5 | 39.9 | 44.2 | 33.8 | 25.6 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | TCP 接收数据吞吐量 (Mbit/s)| 63.6 | 35.5 | 42.3 | 48.5 | 40.5 | 30.1 | 27.8 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | UDP 发送数据吞吐量 (Mbit/s)| 76.2 | 75.1 | 74.1 | 72.4 | 69.6 | 64.1 | 36.5 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ - | UDP 接收数据吞吐量 (Mbit/s)| 83.1 | 66.3 | 75.1 | 75.6 | 73.1 | 65.3 | 54.7 | - +----------------------------+-------+--------------+--------+--------------+--------+----------+-------+ + .. list-table:: + :header-rows: 1 + :widths: 10 5 5 10 5 5 10 5 + + * - 等级 + - Iperf + - 发送数据优先 + - 高性能 + - 接收数据优先 + - 默认值 + - 节省内存 + - 最小 + * - 可用内存 (KB) + - 37.1 + - 113.8 + - 123.3 + - 145.5 + - 144.5 + - 170.2 + - 185.2 + * - WIFI_STATIC_RX_BUFFER_NUM + - 16 + - 6 + - 6 + - 6 + - 6 + - 6 + - 4 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 64 + - 16 + - 24 + - 34 + - 20 + - 12 + - 8 + * - WIFI_DYNAMIC_TX_BUFFER_NUM + - 64 + - 28 + - 24 + - 18 + - 20 + - 12 + - 8 + * - WIFI_RX_BA_WIN + - 32 + - 8 + - 12 + - 12 + - 10 + - 6 + - 禁用 + * - TCP_SND_BUF_DEFAULT (KB) + - 65 + - 28 + - 24 + - 18 + - 20 + - 12 + - 8 + * - TCP_WND_DEFAULT (KB) + - 65 + - 16 + - 24 + - 34 + - 20 + - 12 + - 8 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 15 + - 15 + - 15 + - 15 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 16 + - 16 + - 16 + - 16 + - 16 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 13 + - 13 + - 13 + - 13 + - 13 + - 13 + * - TCP 发送数据吞吐量 (Mbit/s) + - 74.6 + - 50.8 + - 46.5 + - 39.9 + - 44.2 + - 33.8 + - 25.6 + * - TCP 接收数据吞吐量 (Mbit/s) + - 63.6 + - 35.5 + - 42.3 + - 48.5 + - 40.5 + - 30.1 + - 27.8 + * - UDP 发送数据吞吐量 (Mbit/s) + - 76.2 + - 75.1 + - 74.1 + - 72.4 + - 69.6 + - 64.1 + - 36.5 + * - UDP 接收数据吞吐量 (Mbit/s) + - 83.1 + - 66.3 + - 75.1 + - 75.6 + - 73.1 + - 65.3 + - 54.7 .. only:: esp32s2 - +----------------------------+-------+--------+------+----------+-------+ - | 等级 | Iperf | 高性能 | 默认 | 节省内存 | 最小 | - +============================+=======+========+======+==========+=======+ - | 可用内存 (KB) | 4.1 | 24.2 | 78.4 | 86.5 | 116.4 | - +----------------------------+-------+--------+------+----------+-------+ - | WIFI_STATIC_RX_BUFFER_NUM | 8 | 6 | 6 | 4 | 3 | - +----------------------------+-------+--------+------+----------+-------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 24 | 18 | 12 | 8 | 6 | - +----------------------------+-------+--------+------+----------+-------+ - | WIFI_DYNAMIC_TX_BUFFER_NUM | 24 | 18 | 12 | 8 | 6 | - +----------------------------+-------+--------+------+----------+-------+ - | WIFI_RX_BA_WIN | 12 | 9 | 6 | 4 | 3 | - +----------------------------+-------+--------+------+----------+-------+ - | TCP_SND_BUF_DEFAULT (KB) | 24 | 18 | 12 | 8 | 6 | - +----------------------------+-------+--------+------+----------+-------+ - | TCP_WND_DEFAULT (KB) | 24 | 18 | 12 | 8 | 6 | - +----------------------------+-------+--------+------+----------+-------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 15 | 0 | - +----------------------------+-------+--------+------+----------+-------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 16 | 0 | 0 | - +----------------------------+-------+--------+------+----------+-------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 0 | 0 | 0 | - +----------------------------+-------+--------+------+----------+-------+ - | INSTRUCTION_CACHE | 16 | 16 | 16 | 16 | 8 | - +----------------------------+-------+--------+------+----------+-------+ - | INSTRUCTION_CACHE_LINE | 16 | 16 | 16 | 16 | 16 | - +----------------------------+-------+--------+------+----------+-------+ - | TCP 发送数据吞吐量 (Mbit/s)| 37.6 | 33.1 | 22.5 | 12.2 | 5.5 | - +----------------------------+-------+--------+------+----------+-------+ - | TCP 接收数据吞吐量 (Mbit/s)| 31.5 | 28.1 | 20.1 | 13.1 | 7.2 | - +----------------------------+-------+--------+------+----------+-------+ - | UDP 发送数据吞吐量 (Mbit/s)| 58.1 | 57.3 | 28.1 | 22.6 | 8.7 | - +----------------------------+-------+--------+------+----------+-------+ - | UDP 接收数据吞吐量 (Mbit/s)| 78.1 | 66.7 | 65.3 | 53.8 | 28.5 | - +----------------------------+-------+--------+------+----------+-------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 10 10 10 + + * - 等级 + - Iperf + - 高性能 + - 默认 + - 节省内存 + - 最小 + * - 可用内存 (KB) + - 4.1 + - 24.2 + - 78.4 + - 86.5 + - 116.4 + * - WIFI_STATIC_RX_BUFFER_NUM + - 8 + - 6 + - 6 + - 4 + - 3 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 24 + - 18 + - 12 + - 8 + - 6 + * - WIFI_DYNAMIC_TX_BUFFER_NUM + - 24 + - 18 + - 12 + - 8 + - 6 + * - WIFI_RX_BA_WIN + - 12 + - 9 + - 6 + - 4 + - 3 + * - TCP_SND_BUF_DEFAULT (KB) + - 24 + - 18 + - 12 + - 8 + - 6 + * - TCP_WND_DEFAULT (KB) + - 24 + - 18 + - 12 + - 8 + - 6 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 15 + - 0 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 16 + - 0 + - 0 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 13 + - 0 + - 0 + - 0 + * - INSTRUCTION_CACHE + - 16 + - 16 + - 16 + - 16 + - 8 + * - INSTRUCTION_CACHE_LINE + - 16 + - 16 + - 16 + - 16 + - 16 + * - TCP 发送数据吞吐量 (Mbit/s) + - 37.6 + - 33.1 + - 22.5 + - 12.2 + - 5.5 + * - TCP 接收数据吞吐量 (Mbit/s) + - 31.5 + - 28.1 + - 20.1 + - 13.1 + - 7.2 + * - UDP 发送数据吞吐量 (Mbit/s) + - 58.1 + - 57.3 + - 28.1 + - 22.6 + - 8.7 + * - UDP 接收数据吞吐量 (Mbit/s) + - 78.1 + - 66.7 + - 65.3 + - 53.8 + - 28.5 .. only:: esp32c3 - +----------------------------+-------+---------+---------+ - | 等级 | Iperf | 默认 | 最小 | - +============================+=======+=========+=========+ - | 可用内存 (KB) | 59 | 160 | 180 | - +----------------------------+-------+---------+---------+ - | WIFI_STATIC_RX_BUFFER_NUM | 20 | 8 | 3 | - +----------------------------+-------+---------+---------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 40 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | WIFI_DYNAMIC_TX_BUFFER_NUM | 40 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | WIFI_RX_BA_WIN | 32 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | TCP_SND_BUF_DEFAULT (KB) | 40 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | TCP_WND_DEFAULT (KB) | 40 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 0 | - +----------------------------+-------+---------+---------+ - | TCP 发送数据吞吐量 (Mbit/s)| 38.1 | 27.2 | 20.4 | - +----------------------------+-------+---------+---------+ - | TCP 接收数据吞吐量 (Mbit/s)| 35.3 | 24.2 | 17.4 | - +----------------------------+-------+---------+---------+ - | UDP 发送数据吞吐量 (Mbit/s)| 40.6 | 38.9 | 34.1 | - +----------------------------+-------+---------+---------+ - | UDP 接收数据吞吐量 (Mbit/s)| 52.4 | 44.5 | 44.2 | - +----------------------------+-------+---------+---------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 15 + + * - 等级 + - Iperf + - 默认 + - 最小 + * - 可用内存 (KB) + - 59 + - 160 + - 180 + * - WIFI_STATIC_RX_BUFFER_NUM + - 20 + - 8 + - 3 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 40 + - 16 + - 6 + * - WIFI_DYNAMIC_TX_BUFFER_NUM + - 40 + - 16 + - 6 + * - WIFI_RX_BA_WIN + - 32 + - 16 + - 6 + * - TCP_SND_BUF_DEFAULT (KB) + - 40 + - 16 + - 6 + * - TCP_WND_DEFAULT (KB) + - 40 + - 16 + - 6 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 13 + - 0 + * - TCP 发送数据吞吐量 (Mbit/s) + - 38.1 + - 27.2 + - 20.4 + * - TCP 接收数据吞吐量 (Mbit/s) + - 35.3 + - 24.2 + - 17.4 + * - UDP 发送数据吞吐量 (Mbit/s) + - 40.6 + - 38.9 + - 34.1 + * - UDP 接收数据吞吐量 (Mbit/s) + - 52.4 + - 44.5 + - 44.2 .. only:: esp32s3 - +----------------------------+-------+---------+---------+ - | 等级 | Iperf | 默认 | 最小 | - +============================+=======+=========+=========+ - | 可用内存 (KB) | 133.9 | 183.9 | 273.6 | - +----------------------------+-------+---------+---------+ - | WIFI_STATIC_RX_BUFFER_NUM | 24 | 8 | 3 | - +----------------------------+-------+---------+---------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 64 | 32 | 6 | - +----------------------------+-------+---------+---------+ - | WIFI_DYNAMIC_TX_BUFFER_NUM | 64 | 32 | 6 | - +----------------------------+-------+---------+---------+ - | WIFI_RX_BA_WIN | 32 | 16 | 6 | - +----------------------------+-------+---------+---------+ - | TCP_SND_BUF_DEFAULT (KB) | 64 | 32 | 6 | - +----------------------------+-------+---------+---------+ - | TCP_WND_DEFAULT (KB) | 64 | 32 | 6 | - +----------------------------+-------+---------+---------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | - +----------------------------+-------+---------+---------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 16 | - +----------------------------+-------+---------+---------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 0 | - +----------------------------+-------+---------+---------+ - | INSTRUCTION_CACHE | 32 | 32 | 16 | - +----------------------------+-------+---------+---------+ - | INSTRUCTION_CACHE_LINE | 32 | 32 | 32 | - +----------------------------+-------+---------+---------+ - | INSTRUCTION_CACHE_WAYS | 8 | 8 | 4 | - +----------------------------+-------+---------+---------+ - | TCP 发送数据吞吐量 (Mbit/s)| 83.93 | 64.28 | 23.17 | - +----------------------------+-------+---------+---------+ - | TCP 接收数据吞吐量 (Mbit/s)| 73.98 | 60.39 | 18.11 | - +----------------------------+-------+---------+---------+ - | UDP 发送数据吞吐量 (Mbit/s)| 98.69 | 96.28 | 48.78 | - +----------------------------+-------+---------+---------+ - | UDP 接收数据吞吐量 (Mbit/s)| 88.58 | 86.57 | 59.45 | - +----------------------------+-------+---------+---------+ + .. list-table:: + :header-rows: 1 + :widths: 25 20 25 25 + + * - 等级 + - Iperf + - 默认 + - 最小 + * - 可用内存 (KB) + - 133.9 + - 183.9 + - 273.6 + * - WIFI_STATIC_RX_BUFFER_NUM + - 24 + - 8 + - 3 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 64 + - 32 + - 6 + * - WIFI_DYNAMIC_TX_BUFFER_NUM + - 64 + - 32 + - 6 + * - WIFI_RX_BA_WIN + - 32 + - 16 + - 6 + * - TCP_SND_BUF_DEFAULT (KB) + - 64 + - 32 + - 6 + * - TCP_WND_DEFAULT (KB) + - 64 + - 32 + - 6 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 16 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 13 + - 0 + * - INSTRUCTION_CACHE + - 32 + - 32 + - 16 + * - INSTRUCTION_CACHE_LINE + - 32 + - 32 + - 32 + * - INSTRUCTION_CACHE_WAYS + - 8 + - 8 + - 4 + * - TCP 发送数据吞吐量 (Mbit/s) + - 83.93 + - 64.28 + - 23.17 + * - TCP 接收数据吞吐量 (Mbit/s) + - 73.98 + - 60.39 + - 18.11 + * - UDP 发送数据吞吐量 (Mbit/s) + - 98.69 + - 96.28 + - 48.78 + * - UDP 接收数据吞吐量 (Mbit/s) + - 88.58 + - 86.57 + - 59.45 .. only:: esp32 or esp32s3 .. note:: - 以上结果使用华硕RT-N66U路由器，在屏蔽箱中进行单流测试得出。{IDF_TARGET_NAME} 的 CPU 为双核，频率为 240 MHz，flash 为 QIO 模式，频率为 80 MHz。 + 以上结果使用华硕 RT-N66U 路由器，在屏蔽箱中进行单流测试得出。 + {IDF_TARGET_NAME} 的 CPU 为双核，频率为 240 MHz，flash 为 QIO 模式，频率为 80 MHz。 .. only:: esp32s2 .. note:: - 以上结果使用华硕RT-N66U路由器，在屏蔽箱中进行单流测试得出。{IDF_TARGET_NAME} 的 CPU 为单核，频率为 240 MHz，flash 为 QIO 模式，频率为 80 MHz。 + 以上结果使用华硕 RT-N66U 路由器，在屏蔽箱中进行单流测试得出。 + {IDF_TARGET_NAME} 的 CPU 为单核，频率为 240 MHz，flash 为 QIO 模式，频率为 80 MHz。 .. only:: esp32c3 .. note:: - 以上结果使用华硕RT-N66U路由器，在屏蔽箱中进行单流测试得出。{IDF_TARGET_NAME} 的 CPU 为单核，频率为 160 MHz，flash 为 QIO 模式，频率为 80 MHz。 + 以上结果使用华硕 RT-N66U 路由器，在屏蔽箱中进行单流测试得出。 + {IDF_TARGET_NAME} 的 CPU 为单核，频率为 160 MHz，flash 为 QIO 模式，频率为 80 MHz。 .. only:: esp32 @@ -1975,7 +2318,7 @@ Wi-Fi 使用的堆内存峰值是 Wi-Fi 驱动程序 **理论上消耗的最大 {IDF_TARGET_NAME} 的高性能配置等级，适用于应用程序占用内存较少且有高性能要求的场景。在该等级中，您可以根据使用场景选择使用接收数据优先等级或发送数据优先等级。 - **默认等级** - IDF_TARGET_NAME} 的默认配置等级、兼顾可用内存和性能。 + {IDF_TARGET_NAME} 的默认配置等级、兼顾可用内存和性能。 - **节省内存等级** 该等级适用于应用程序需要大量内存的场景，在这一等级下，收发器的性能会有所降低。 @@ -1994,7 +2337,7 @@ Wi-Fi 使用的堆内存峰值是 Wi-Fi 驱动程序 **理论上消耗的最大 {IDF_TARGET_NAME} 的高性能配置等级，适用于应用程序占用内存较少且有高性能要求的场景。 - **默认等级** - IDF_TARGET_NAME} 的默认配置等级、兼顾可用内存和性能。 + {IDF_TARGET_NAME} 的默认配置等级、兼顾可用内存和性能。 - **节省内存等级** 该等级适用于应用程序需要大量内存的场景，在这一等级下，收发器的性能会有所降低。 @@ -2010,7 +2353,7 @@ Wi-Fi 使用的堆内存峰值是 Wi-Fi 驱动程序 **理论上消耗的最大 {IDF_TARGET_NAME} 极端性能等级，用于测试极端性能。 - **默认等级** - IDF_TARGET_NAME} 的默认配置等级、兼顾可用内存和性能。 + {IDF_TARGET_NAME} 的默认配置等级、兼顾可用内存和性能。 - **最小等级** {IDF_TARGET_NAME} 的最小配置等级。协议栈只使用运行所需的内存。适用于对性能没有要求，而应用程序需要大量内存的场景。 @@ -2021,181 +2364,431 @@ Wi-Fi 使用的堆内存峰值是 Wi-Fi 驱动程序 **理论上消耗的最大 ++++++++++++++++++++++++++++ PSRAM 一般在应用程序占用大量内存时使用。在该模式下，:ref:`CONFIG_ESP32_WIFI_TX_BUFFER` 被强制为静态。:ref:`CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM` 表示硬件层 DMA 缓冲区数量，提高这一参数可以增强性能。 - 我们推荐以下 PSRAM 等级。 + 以下是使用 PSRAM 时的推荐等级。 .. only:: esp32 - +----------------------------+-------+-------+----------+-------+ - | 等级 | Iperf | 默认 | 节省内存 | 最小 | - +============================+=======+=======+==========+=======+ - | 可用内存 (KB) | 113.8 | 152.4 | 181.2 | 202.6 | - +----------------------------+-------+-------+----------+-------+ - | WIFI_STATIC_RX_BUFFER_NUM | 16 | 8 | 4 | 2 | - +----------------------------+-------+-------+----------+-------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 128 | 128 | 128 | 128 | - +----------------------------+-------+-------+----------+-------+ - | WIFI_STATIC_TX_BUFFER_NUM | 16 | 8 | 4 | 2 | - +----------------------------+-------+-------+----------+-------+ - | WIFI_RX_BA_WIN | 16 | 16 | 8 | 禁用 | - +----------------------------+-------+-------+----------+-------+ - | TCP_SND_BUF_DEFAULT (KB) | 65 | 65 | 65 | 65 | - +----------------------------+-------+-------+----------+-------+ - | TCP_WND_DEFAULT (KB) | 65 | 65 | 65 | 65 | - +----------------------------+-------+-------+----------+-------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | - +----------------------------+-------+-------+----------+-------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | - +----------------------------+-------+-------+----------+-------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | - +----------------------------+-------+-------+----------+-------+ - | TCP 发送数据吞吐量 (Mbit/s)| 37.5 | 31.7 | 21.7 | 14.6 | - +----------------------------+-------+-------+----------+-------+ - | TCP 接收数据吞吐量 (Mbit/s)| 31.5 | 29.8 | 26.5 | 21.1 | - +----------------------------+-------+-------+----------+-------+ - | UDP 发送数据吞吐量 (Mbit/s)| 69.1 | 31.5 | 27.1 | 24.1 | - +----------------------------+-------+-------+----------+-------+ - | UDP 接收数据吞吐量 (Mbit/s)| 40.1 | 38.5 | 37.5 | 36.9 | - +----------------------------+-------+-------+----------+-------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 10 15 + + * - 等级 + - Iperf + - 默认 + - 节省内存 + - 最小 + * - 可用内存 (KB) + - 113.8 + - 152.4 + - 181.2 + - 202.6 + * - WIFI_STATIC_RX_BUFFER_NUM + - 16 + - 8 + - 4 + - 2 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 128 + - 128 + - 128 + - 128 + * - WIFI_STATIC_TX_BUFFER_NUM + - 16 + - 8 + - 4 + - 2 + * - WIFI_RX_BA_WIN + - 16 + - 16 + - 8 + - 禁用 + * - TCP_SND_BUF_DEFAULT (KB) + - 65 + - 65 + - 65 + - 65 + * - TCP_WND_DEFAULT (KB) + - 65 + - 65 + - 65 + - 65 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 0 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 0 + - 0 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 0 + - 0 + - 0 + * - TCP 发送数据吞吐量 (Mbit/s) + - 37.5 + - 31.7 + - 21.7 + - 14.6 + * - TCP 接收数据吞吐量 (Mbit/s) + - 31.5 + - 29.8 + - 26.5 + - 21.1 + * - UDP 发送数据吞吐量 (Mbit/s) + - 69.1 + - 31.5 + - 27.1 + - 24.1 + * - UDP 接收数据吞吐量 (Mbit/s) + - 40.1 + - 38.5 + - 37.5 + - 36.9 .. only:: esp32s2 - +----------------------------+-------+------+----------+-------+ - | 等级 | Iperf | 默认 | 节省内存 | 最小 | - +============================+=======+======+==========+=======+ - | 可用内存 (KB) | 70.6 | 96.4 | 118.8 | 148.2 | - +----------------------------+-------+------+----------+-------+ - | WIFI_STATIC_RX_BUFFER_NUM | 8 | 8 | 6 | 4 | - +----------------------------+-------+------+----------+-------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 64 | 64 | 64 | 64 | - +----------------------------+-------+------+----------+-------+ - | WIFI_STATIC_TX_BUFFER_NUM | 16 | 8 | 6 | 4 | - +----------------------------+-------+------+----------+-------+ - | WIFI_RX_BA_WIN | 16 | 6 | 6 | 禁用 | - +----------------------------+-------+------+----------+-------+ - | TCP_SND_BUF_DEFAULT (KB) | 32 | 32 | 32 | 32 | - +----------------------------+-------+------+----------+-------+ - | TCP_WND_DEFAULT (KB) | 32 | 32 | 32 | 32 | - +----------------------------+-------+------+----------+-------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | - +----------------------------+-------+------+----------+-------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | - +----------------------------+-------+------+----------+-------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | - +----------------------------+-------+------+----------+-------+ - | INSTRUCTION_CACHE | 16 | 16 | 16 | 8 | - +----------------------------+-------+------+----------+-------+ - | INSTRUCTION_CACHE_LINE | 16 | 16 | 16 | 16 | - +----------------------------+-------+------+----------+-------+ - | DATA_CACHE | 8 | 8 | 8 | 8 | - +----------------------------+-------+------+----------+-------+ - | DATA_CACHE_LINE | 32 | 32 | 32 | 32 | - +----------------------------+-------+------+----------+-------+ - | TCP 发送数据吞吐量 (Mbit/s)| 40.1 | 29.2 | 20.1 | 8.9 | - +----------------------------+-------+------+----------+-------+ - | TCP 接收数据吞吐量 (Mbit/s)| 21.9 | 16.8 | 14.8 | 9.6 | - +----------------------------+-------+------+----------+-------+ - | UDP 发送数据吞吐量 (Mbit/s)| 50.1 | 25.7 | 22.4 | 10.2 | - +----------------------------+-------+------+----------+-------+ - | UDP 接收数据吞吐量 (Mbit/s)| 45.3 | 43.1 | 28.5 | 15.1 | - +----------------------------+-------+------+----------+-------+ + .. list-table:: + :header-rows: 1 + :widths: 10 10 10 10 15 + + * - 等级 + - Iperf + - 默认 + - 节省内存 + - 最小 + * - 可用内存 (KB) + - 70.6 + - 96.4 + - 118.8 + - 148.2 + * - WIFI_STATIC_RX_BUFFER_NUM + - 8 + - 8 + - 6 + - 4 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 64 + - 64 + - 64 + - 64 + * - WIFI_STATIC_TX_BUFFER_NUM + - 16 + - 8 + - 6 + - 4 + * - WIFI_RX_BA_WIN + - 16 + - 6 + - 6 + - 禁用 + * - TCP_SND_BUF_DEFAULT (KB) + - 32 + - 32 + - 32 + - 32 + * - TCP_WND_DEFAULT (KB) + - 32 + - 32 + - 32 + - 32 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 0 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 0 + - 0 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 0 + - 0 + - 0 + * - INSTRUCTION_CACHE + - 16 + - 16 + - 16 + - 8 + * - INSTRUCTION_CACHE_LINE + - 16 + - 16 + - 16 + - 16 + * - DATA_CACHE + - 8 + - 8 + - 8 + - 8 + * - DATA_CACHE_LINE + - 32 + - 32 + - 32 + - 32 + * - TCP 发送数据吞吐量 (Mbit/s) + - 40.1 + - 29.2 + - 20.1 + - 8.9 + * - TCP 接收数据吞吐量 (Mbit/s) + - 21.9 + - 16.8 + - 14.8 + - 9.6 + * - UDP 发送数据吞吐量 (Mbit/s) + - 50.1 + - 25.7 + - 22.4 + - 10.2 + * - UDP 接收数据吞吐量 (Mbit/s) + - 45.3 + - 43.1 + - 28.5 + - 15.1 + + .. note:: + 达到性能的峰值可能会触发任务看门狗，由于 CPU 可能没有时间处理低优先级的任务，这是一个正常现象。 .. only:: esp32s3 - **四线PSRAM：** + **四线 PSRAM：** - +----------------------------+-------+------+----------+-------+ - | 等级 | Iperf | 默认 | 节省内存 | 最小 | - +============================+=======+======+==========+=======+ - | 可用内存 (KB) | 50.3 | 158.7| 198.2 | 228.9 | - +----------------------------+-------+------+----------+-------+ - | WIFI_STATIC_RX_BUFFER_NUM | 24 | 8 | 6 | 4 | - +----------------------------+-------+------+----------+-------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 85 | 64 | 32 | 32 | - +----------------------------+-------+------+----------+-------+ - | WIFI_STATIC_TX_BUFFER_NUM | 32 | 32 | 6 | 4 | - +----------------------------+-------+------+----------+-------+ - | WIFI_RX_BA_WIN | 32 | 16 | 12 | 禁用 | - +----------------------------+-------+------+----------+-------+ - | TCP_SND_BUF_DEFAULT (KB) | 85 | 32 | 32 | 32 | - +----------------------------+-------+------+----------+-------+ - | TCP_WND_DEFAULT (KB) | 85 | 32 | 32 | 32 | - +----------------------------+-------+------+----------+-------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | - +----------------------------+-------+------+----------+-------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | - +----------------------------+-------+------+----------+-------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | - +----------------------------+-------+------+----------+-------+ - | LWIP_UDP_RECVMBOX_SIZE | 16 | 16 | 16 | 16 | - +----------------------------+-------+------+----------+-------+ - | INSTRUCTION_CACHE | 32 | 16 | 16 | 16 | - +----------------------------+-------+------+----------+-------+ - | INSTRUCTION_CACHE_LINE | 32 | 16 | 16 | 16 | - +----------------------------+-------+------+----------+-------+ - | INSTRUCTION_CACHE_WAYS | 8 | 8 | 8 | 8 | - +----------------------------+-------+------+----------+-------+ - | DATA_CACHE | 64 | 16 | 16 | 16 | - +----------------------------+-------+------+----------+-------+ - | DATA_CACHE_LINE | 32 | 32 | 32 | 32 | - +----------------------------+-------+------+----------+-------+ - | DATA_CACHE_WAYS | 8 | 8 | 8 | 8 | - +----------------------------+-------+------+----------+-------+ - | TCP 发送数据吞吐量 (Mbit/s)| 93.1 | 62.5 | 41.3 | 42.7 | - +----------------------------+-------+------+----------+-------+ - | TCP 接收数据吞吐量 (Mbit/s)| 88.9 | 46.5 | 46.2 | 37.9 | - +----------------------------+-------+------+----------+-------+ - | UDP 发送数据吞吐量 (Mbit/s)| 106.4 | 106.2| 60.7 | 50.0 | - +----------------------------+-------+------+----------+-------+ - | UDP 接收数据吞吐量 (Mbit/s)| 99.8 | 92.6 | 94.3 | 53.3 | - +----------------------------+-------+------+----------+-------+ + .. list-table:: + :header-rows: 1 + :widths: 25 20 25 25 25 - **八线PSRAM：** + * - 等级 + - Iperf + - 默认 + - 节省内存 + - 最小 + * - 可用内存 (KB) + - 50.3 + - 158.7 + - 198.2 + - 228.9 + * - WIFI_STATIC_RX_BUFFER_NUM + - 24 + - 8 + - 6 + - 4 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 85 + - 64 + - 32 + - 32 + * - WIFI_STATIC_TX_BUFFER_NUM + - 32 + - 32 + - 6 + - 4 + * - WIFI_RX_BA_WIN + - 32 + - 16 + - 12 + - 禁用 + * - TCP_SND_BUF_DEFAULT (KB) + - 85 + - 32 + - 32 + - 32 + * - TCP_WND_DEFAULT (KB) + - 85 + - 32 + - 32 + - 32 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 0 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 0 + - 0 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 0 + - 0 + - 0 + * - LWIP_UDP_RECVMBOX_SIZE + - 16 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE + - 32 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE_LINE + - 32 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE_WAYS + - 8 + - 8 + - 8 + - 8 + * - DATA_CACHE + - 64 + - 16 + - 16 + - 16 + * - DATA_CACHE_LINE + - 32 + - 32 + - 32 + - 32 + * - DATA_CACHE_WAYS + - 8 + - 8 + - 8 + - 8 + * - TCP 发送数据吞吐量 (Mbit/s) + - 93.1 + - 62.5 + - 41.3 + - 42.7 + * - TCP 接收数据吞吐量 (Mbit/s) + - 88.9 + - 46.5 + - 46.2 + - 37.9 + * - UDP 发送数据吞吐量 (Mbit/s) + - 106.4 + - 106.2 + - 60.7 + - 50 + * - UDP 接收数据吞吐量 (Mbit/s) + - 99.8 + - 92.6 + - 94.3 + - 53.3 + + **八线 PSRAM：** + + .. list-table:: + :header-rows: 1 + :widths: 25 20 25 25 25 + + * - 等级 + - Iperf + - 默认 + - 节省内存 + - 最小 + * - 可用内存 (KB) + - 49.1 + - 151.3 + - 215.3 + - 243.6 + * - WIFI_STATIC_RX_BUFFER_NUM + - 24 + - 8 + - 6 + - 4 + * - WIFI_DYNAMIC_RX_BUFFER_NUM + - 85 + - 64 + - 32 + - 32 + * - WIFI_STATIC_TX_BUFFER_NUM + - 32 + - 32 + - 6 + - 4 + * - WIFI_RX_BA_WIN + - 32 + - 16 + - 12 + - 禁用 + * - TCP_SND_BUF_DEFAULT (KB) + - 85 + - 32 + - 32 + - 32 + * - TCP_WND_DEFAULT (KB) + - 85 + - 32 + - 32 + - 32 + * - WIFI_IRAM_OPT + - 15 + - 15 + - 15 + - 0 + * - WIFI_RX_IRAM_OPT + - 16 + - 16 + - 0 + - 0 + * - LWIP_IRAM_OPTIMIZATION + - 13 + - 0 + - 0 + - 0 + * - LWIP_UDP_RECVMBOX_SIZE + - 16 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE + - 32 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE_LINE + - 32 + - 16 + - 16 + - 16 + * - INSTRUCTION_CACHE_WAYS + - 8 + - 8 + - 8 + - 8 + * - DATA_CACHE + - 64 + - 16 + - 16 + - 16 + * - DATA_CACHE_LINE + - 32 + - 32 + - 32 + - 32 + * - DATA_CACHE_WAYS + - 8 + - 8 + - 8 + - 8 + * - TCP 发送数据吞吐量 (Mbit/s) + - 93.3 + - 58.4 + - 37.1 + - 35.6 + * - TCP 接收数据吞吐量 (Mbit/s) + - 86.1 + - 43.6 + - 42.5 + - 35 + * - UDP 发送数据吞吐量 (Mbit/s) + - 104.7 + - 82.2 + - 60.4 + - 47.9 + * - UDP 接收数据吞吐量 (Mbit/s) + - 104.6 + - 104.8 + - 104 + - 55.7 - +----------------------------+-------+------+----------+-------+ - | 等级 | Iperf | 默认 | 节省内存 | 最小 | - +============================+=======+======+==========+=======+ - | 可用内存 (KB) | 49.1 | 151.3| 215.3 | 243.6 | - +----------------------------+-------+------+----------+-------+ - | WIFI_STATIC_RX_BUFFER_NUM | 24 | 8 | 6 | 4 | - +----------------------------+-------+------+----------+-------+ - | WIFI_DYNAMIC_RX_BUFFER_NUM | 85 | 64 | 32 | 32 | - +----------------------------+-------+------+----------+-------+ - | WIFI_STATIC_TX_BUFFER_NUM | 32 | 32 | 6 | 4 | - +----------------------------+-------+------+----------+-------+ - | WIFI_RX_BA_WIN | 32 | 16 | 12 | 禁用 | - +----------------------------+-------+------+----------+-------+ - | TCP_SND_BUF_DEFAULT (KB) | 85 | 32 | 32 | 32 | - +----------------------------+-------+------+----------+-------+ - | TCP_WND_DEFAULT (KB) | 85 | 32 | 32 | 32 | - +----------------------------+-------+------+----------+-------+ - | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | - +----------------------------+-------+------+----------+-------+ - | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | - +----------------------------+-------+------+----------+-------+ - | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | - +----------------------------+-------+------+----------+-------+ - | LWIP_UDP_RECVMBOX_SIZE | 16 | 16 | 16 | 16 | - +----------------------------+-------+------+----------+-------+ - | INSTRUCTION_CACHE | 32 | 16 | 16 | 16 | - +----------------------------+-------+------+----------+-------+ - | INSTRUCTION_CACHE_LINE | 32 | 16 | 16 | 16 | - +----------------------------+-------+------+----------+-------+ - | INSTRUCTION_CACHE_WAYS | 8 | 8 | 8 | 8 | - +----------------------------+-------+------+----------+-------+ - | DATA_CACHE | 64 | 16 | 16 | 16 | - +----------------------------+-------+------+----------+-------+ - | DATA_CACHE_LINE | 32 | 32 | 32 | 32 | - +----------------------------+-------+------+----------+-------+ - | DATA_CACHE_WAYS | 8 | 8 | 8 | 8 | - +----------------------------+-------+------+----------+-------+ - | TCP 发送数据吞吐量 (Mbit/s)| 93.3 | 58.4 | 37.1 | 35.6 | - +----------------------------+-------+------+----------+-------+ - | TCP 接收数据吞吐量 (Mbit/s)| 86.1 | 43.6 | 42.5 | 35.0 | - +----------------------------+-------+------+----------+-------+ - | UDP 发送数据吞吐量 (Mbit/s)| 104.7 | 82.2 | 60.4 | 47.9 | - +----------------------------+-------+------+----------+-------+ - | UDP 接收数据吞吐量 (Mbit/s)| 104.6 |104.8 | 104.0 | 55.7 | - +----------------------------+-------+------+----------+-------+ Wi-Fi Menuconfig ----------------------- @@ -2281,44 +2874,58 @@ Wi-Fi 缓冲区配置 下表是 Wi-Fi 内部缓冲区的配置情况。 -+------------------------+----------+-----------------+------------+---------------------------------------------------------------+ -| 缓冲区类型 | 分配类型 | 默认 | 是否可配置 | 描述 | -+========================+==========+=================+============+===============================================================+ -| 静态接收数据缓冲区 | 静态 | 10 * 1600 Bytes | 是 | 这是一种 DMA 内存，在函数 :cpp:func:`esp_wifi_init()` | -| | | | | 中初始化，在函数 :cpp:func:`esp_wifi_deinit()` 中释放。 | -| （硬件接收数据缓冲区） | | | | 该缓冲区形成硬件接收列表。当通过空中接收到一个帧时，硬件将 | -| | | | | 该帧写入缓冲区，并向 CPU 发起一个中断。然后，Wi-Fi 驱动程 | -| | | | | 序从缓冲区中读取内容，并将缓冲区返回到列表中。 如果应用程序 | -| | | | | 希望减少 Wi-Fi 静态分配的内存，可以将该值从 10 减少到 6， | -| | | | | 从而节省 6400 Bytes 的内存。除非禁用 AMPDU 功能，否则不 | -| | | | | 建议将该值降低到 6 以下。 | -+------------------------+----------+-----------------+------------+---------------------------------------------------------------+ -| 动态接收数据缓冲区 | 动态 | 32 | 是 | 缓冲区的长度可变，取决于所接收帧的长度。当 Wi-Fi 驱动程序 | -| | | | | 从“硬件接收数据缓冲区”接收到一帧时，需要从堆中分配“动态接收 | -| | | | | 数据缓冲区”。在 Menuconfig 中配置的“动态接收数据缓冲区” | -| | | | | 数量用来限制未释放的“动态接收数据缓冲区”总数量。 | -+------------------------+----------+-----------------+------------+---------------------------------------------------------------+ -| 动态发送数据缓冲区 | 动态 | 32 | 是 | 这是一种DMA内存，位于堆内存中。当上层 (LwIP) 向 Wi-Fi | -| | | | | 驱动程序发送数据包时，该缓冲区首先分配一个“动态发送数据缓 | -| | | | | 冲区”，并复制上层缓冲区。动态发送数据缓冲区和静态发送数据 | -| | | | | 缓冲区相互排斥。 | -+------------------------+----------+-----------------+------------+---------------------------------------------------------------+ -| 静态发送数据缓冲区 | 静态 | 16 * 1600 Bytes | 是 | 这是一种 DMA 内存，在函数 :cpp:func:`esp_wifi_init()` | -| | | | | 中初始化，在函数 :cpp:func:`esp_wifi_deinit()` 中释放。 | -| | | | | 当上层 (LwIP) 向 Wi-Fi 驱动程序发送数据包时，该缓冲区首先 | -| | | | | 分配一个“静态发送数据缓冲区”，并复制上层缓冲区。动态发送数据 | -| | | | | 缓冲区和静态发送数据缓冲区相互排斥。由于发送数据缓冲区必须是 | -| | | | | DMA 缓冲区，所以当使能 PSRAM 时，发送数据缓冲区必须是静态 | -| | | | | 的。 | -+------------------------+----------+-----------------+------------+---------------------------------------------------------------+ -| 管理短缓冲区 | 动态 | 8 | 否 | Wi-Fi 驱动程序的内部缓冲区。 | -+------------------------+----------+-----------------+------------+---------------------------------------------------------------+ -| 管理长缓冲区 | 动态 | 32 | 否 | Wi-Fi 驱动程序的内部缓冲区。 | -+------------------------+----------+-----------------+------------+---------------------------------------------------------------+ -| 管理超长缓冲区 | 动态 | 32 | 否 | Wi-Fi 驱动程序的内部缓冲区。 | -+------------------------+----------+-----------------+------------+---------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 10 10 10 10 25 + * - 缓冲区类型 + - 分配类型 + - 默认 + - 是否可配置 + - 描述 + * - 静态接收数据缓冲区（硬件接收数据缓冲区） + - 静态 + - 10 * 1600 Bytes + - 是 + - 这是一种 DMA 内存，在函数 :cpp:func:`esp_wifi_init()` 中初始化，在函数 :cpp:func:`esp_wifi_deinit()` 中释放。 该缓冲区形成硬件接收列表。当通过空中接收到一个帧时，硬件将该帧写入缓冲区，并向 CPU 发起一个中断。然后，Wi-Fi 驱动程序从缓冲区中读取内容，并将缓冲区返回到列表中。 + 如果应用程序希望减少 Wi-Fi 静态分配的内存，可以将该值从 10 减少到 6， 从而节省 6400 Bytes 的内存。除非禁用 AMPDU 功能，否则不建议将该值降低到 6 以下。 + * - 动态接收数据缓冲区 + - 动态 + - 32 + - 是 + - 缓冲区的长度可变，取决于所接收帧的长度。当 Wi-Fi 驱动程序 从“硬件接收数据缓冲区”接收到一帧时，需要从堆中分配“动态接收数据缓冲区”。在 Menuconfig 中配置的“动态接收数据缓冲区” 数量用来限制未释放的“动态接收数据缓冲区”总数量。 + * - 动态发送数据缓冲区 + - 动态 + - 32 + - 是 + - 这是一种 DMA 内存，位于堆内存中。当上层 (LwIP) 向 Wi-Fi 驱动程序发送数据包时，该缓冲区首先分配一个“动态发送数据缓 冲区”，并复制上层缓冲区。 + + 动态发送数据缓冲区和静态发送数据缓冲区相互排斥。 + * - 静态发送数据缓冲区 + - 静态 + - 16 * 1600 Bytes + - 是 + - 这是一种 DMA 内存，在函数 :cpp:func:`esp_wifi_init()` 中初始化，在函数 :cpp:func:`esp_wifi_deinit()` 中释放。 当上层 (LwIP) 向 Wi-Fi 驱动程序发送数据包时，该缓冲区首先 分配一个“静态发送数据缓冲区”，并复制上层缓冲区。 + + 动态发送数据缓冲区和静态发送数据缓冲区相互排斥。 + + 由于发送数据缓冲区必须是 DMA 缓冲区，所以当使能 PSRAM 时，发送数据缓冲区必须是静态的。 + * - 管理短缓冲区 + - 动态 + - 8 + - 否 + - Wi-Fi 驱动程序的内部缓冲区。 + * - 管理长缓冲区 + - 动态 + - 32 + - 否 + - Wi-Fi 驱动程序的内部缓冲区。 + * - 管理超长缓冲区 + - 动态 + - 32 + - 否 + - Wi-Fi 驱动程序的内部缓冲区。 Wi-Fi NVS Flash +++++++++++++++++++++ @@ -2339,4 +2946,4 @@ Wi-Fi AMPDU .. toctree:: :hidden: - wireshark-user-guide \ No newline at end of file + wireshark-user-guide