From c1022ac22b89ca383a43bd5db5d0cb78b1760e23 Mon Sep 17 00:00:00 2001 From: Liu Zhi Fu Date: Wed, 7 Nov 2018 22:08:29 +0800 Subject: [PATCH] docs: udpate wifi document Update WiFi document --- docs/en/api-guides/wifi.rst | 764 +++++++++++++++++++++++----------- examples/wifi/iperf/README.md | 11 +- 2 files changed, 532 insertions(+), 243 deletions(-) diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index 9951c9957a..a85518a7c1 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -3,7 +3,7 @@ Wi-Fi Driver ESP32 Wi-Fi Feature List ------------------------- -- Support Station-only mode, SoftAP-only mode, Station/SoftAP-coexistence mode +- Support Station-only mode, AP-only mode, Station/AP-coexistence mode - Support IEEE-802.11B, IEEE-802.11G, IEEE802.11N and APIs to configure the protocol mode - Support WPA/WPA2/WPA2-Enterprise and WPS - Support AMPDU, HT40, QoS and other key features @@ -29,15 +29,15 @@ Refer to <`Wi-Fi Menuconfig`_> Init Wi-Fi +++++++++++ -Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi soft-AP General Scenario`_>. +Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>. Start/Connect Wi-Fi ++++++++++++++++++++ -Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi soft-AP General Scenario`_>. +Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>. Event-Handling ++++++++++++++ -Generally, it is easy to write code in "sunny-day" scenarios, such as <`SYSTEM_EVENT_STA_START`_>, <`SYSTEM_EVENT_STA_CONNECTED`_> etc. The hard part is to write routines in "rainy-day" scenarios, such as <`SYSTEM_EVENT_STA_DISCONNECTED`_> etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to <`ESP32 Wi-Fi Event Description`_>, <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi soft-AP General Scenario`_> +Generally, it is easy to write code in "sunny-day" scenarios, such as <`SYSTEM_EVENT_STA_START`_>, <`SYSTEM_EVENT_STA_CONNECTED`_> etc. The hard part is to write routines in "rainy-day" scenarios, such as <`SYSTEM_EVENT_STA_DISCONNECTED`_> etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to <`ESP32 Wi-Fi Event Description`_>, <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_> Write Error-Recovery Routines Correctly at All Times ++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -61,7 +61,16 @@ Whether the error is critical or not depends on the API and the application scen - for non-recoverable, critical errors, in which case "assert" may be a good method for error handling. For example, if esp_wifi_set_mode returns ESP_ERR_WIFI_NOT_INIT, it means that the Wi-Fi driver is not initialized by 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 the API user writes their own error-handling code. +as the default error-handling code in the application development phase. However, we strongly recommend that API users write their own error-handling code. + +ESP32 Wi-Fi API Parameter Initialization +------------------------------------------ + +When initializing struct parameters for the API, one of two approaches should be followed: +- explicitly set all fields of the parameter or +- use get API to get current configuration first, then set application specific fields + +Initializing or getting the entire structure is very important because most of the time the value 0 indicates the default value is used. More fields may be added to the struct in the future and initializing these to zero ensures the application will still work correctly after IDF is updated to a new release. ESP32 Wi-Fi Programming Model ------------------------------ @@ -149,11 +158,11 @@ Refer to 'ESP32 Wi-Fi Scan' for a more detailed description. SYSTEM_EVENT_STA_START ++++++++++++++++++++++++++++++++++++ -If esp_wifi_start() returns ESP_OK and the current Wi-Fi mode is Station or SoftAP+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 esp_wifi_connect() to connect to the configured AP. +If 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 esp_wifi_connect() to connect to the configured AP. SYSTEM_EVENT_STA_STOP ++++++++++++++++++++++++++++++++++++ -If esp_wifi_stop() returns ESP_OK and the current Wi-Fi mode is Station or SoftAP+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 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. SYSTEM_EVENT_STA_CONNECTED ++++++++++++++++++++++++++++++++++++ @@ -164,22 +173,23 @@ SYSTEM_EVENT_STA_DISCONNECTED This event can be generated in the following scenarios: - When esp_wifi_disconnect(), or esp_wifi_stop(), or esp_wifi_deinit(), or esp_wifi_restart() is called and the station is already connected to the AP. - - When 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. + - When 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. -Upon receiving this event, the event task will shut down the station's LwIP netif and notify the LwIP task to clear the UDP/TCP connections which cause the wrong status to all sockets. **For socket-based applications, the application callback needs to close all sockets and re-create them, if necessary, upon receiving this event.** +Upon receiving this event, the default behavior of the event task is: +- Shuts down the station's LwIP netif. +- Notifies the LwIP task to clear the UDP/TCP connections which cause the wrong status to all sockets. For socket-based applications, the application callback can choose to close all sockets and re-create them, if necessary, upon receiving this event. -Now, let us consider the following scenario: +The most common event handle code for this event in application is to call esp_wifi_connect() to reconnect the Wi-Fi. However, if the event is raised because esp_wifi_disconnect() is called, the application should not call esp_wifi_connect() to reconnect. It's application's responsibility to distinguish whether the event is caused by esp_wifi_disconnect() or other reasons. Sometimes a better reconnect strategy is required, refer to <`Wi-Fi Reconnect`_> and <`Scan When Wi-Fi Is Connecting`_>. - - The application creates a TCP connection to maintain the application-level keep-alive data that is sent out every 60 seconds. - - Due to certain reasons, the Wi-Fi connection is cut off, and the <`SYSTEM_EVENT_STA_DISCONNECTED`_> is raised. According to the current implementation, **all TCP connections will be removed and the keep-alive socket will be in a wrong status**. However, since the application designer believes that the network layer should NOT care about this error at the Wi-Fi layer, the application does not close the socket. - - Five seconds later, the Wi-Fi connection is restored because esp_wifi_connect() is called in the application event callback function. - - Sixty seconds later, when the application sends out data with the keep-alive socket, the socket returns an error and the application closes the socket and re-creates it when necessary. +Another thing deserves our attention is that the default behavior of LwIP is to abort all TCP socket connections on receiving the disconnect. Most of time it is not a problem. However, for some special application, this may not be what they want, consider following scenarios: -Generally, if the application has a correct error-handling code, upon receiving <`SYSTEM_EVENT_STA_DISCONNECTED`_> the socket can quickly detect the failure without having to wait for 55 seconds. For applications similar to the keep-alive example, we suggest that you close all sockets, once the <`SYSTEM_EVENT_STA_DISCONNECTED`_> is received, and that you restart the application when SYSTEM_EVENT_STA_CONNECTED arises. - -Ideally, the application sockets and the network layer should not be affected, since the Wi-Fi connection only fails temporarily and recovers very quickly. In future IDF releases, we are going to provide a more robust solution for handling events that disrupt Wi-Fi connection, as ESP32's Wi-Fi functionality continuously improves. +- The application creates a TCP connection to maintain the application-level keep-alive data that is sent out every 60 seconds. +- Due to certain reasons, the Wi-Fi connection is cut off, and the is raised. According to the current implementation, all TCP connections will be removed and the keep-alive socket will be in a wrong status. However, since the application designer believes that the network layer should NOT care about this error at the Wi-Fi layer, the application does not close the socket. +- Five seconds later, the Wi-Fi connection is restored because esp_wifi_connect() is called in the application event callback function. **Moreover, the station connects to the same AP and gets the same IPV4 address as before**. +- Sixty seconds later, when the application sends out data with the keep-alive socket, the socket returns an error and the application closes the socket and re-creates it when necessary. +In above scenario, ideally, the application sockets and the network layer should not be affected, since the Wi-Fi connection only fails temporarily and recovers very quickly. The application can enable "Keep TCP connections when IP changed" via LwIP menuconfig. SYSTEM_EVENT_STA_AUTHMODE_CHANGE ++++++++++++++++++++++++++++++++++++ @@ -187,17 +197,29 @@ This event arises when the AP to which the station is connected changes its auth SYSTEM_EVENT_STA_GOT_IP ++++++++++++++++++++++++++++++++++++ +This event arises when the DHCP client successfully gets the IPV4 address from the DHCP server, or when the IPV4 address is changed. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets). + +The IPV4 may be changed because of the following reasons: + + - The DHCP client fails to renew/rebind the IPV4 address, and the station's IPV4 is reset to 0. + - The DHCP client rebinds to a different address. + - The static-configured IPV4 address is changed. + +Whether the IPV4 address is changed or NOT is indicated by field "ip_change" of system_event_sta_got_ip_t. + +The socket is based on the IPV4 address, which means that, if the IPV4 changes, all sockets relating to this IPV4 will become abnormal. Upon receiving this event, the application needs to close all sockets and recreate the application when the IPV4 changes to a valid one. + SYSTEM_EVENT_AP_STA_GOT_IP6 ++++++++++++++++++++++++++++++++++++ -This event arises when the DHCP client successfully gets the IP address from the DHCP server. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets). +This event arises when the IPV6 SLAAC supports auto-configures an address for the ESP32, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets). -The IP may be changed because of the following reasons: +SYSTEM_EVENT_STA_LOST_IP +++++++++++++++++++++++++++++++++++++ +This event arises when the IPV4 address become invalid. - - The DHCP client fails to renew/rebind the IP address, and the station's IP is reset to 0. - - The DHCP client rebinds to a different address. - - The static-configured IP address is changed. +SYSTEM_EVENT_STA_LOST_IP doesn't arise immediately after the WiFi disconnects, instead it starts an IPV4 address lost timer, if the IPV4 address is got before ip lost timer expires, SYSTEM_EVENT_STA_LOST_IP doesn't happen. Otherwise, the event arises when IPV4 address lost timer expires. -The socket is based on the IP address, which means that, if the IP changes, all sockets relating to this IP will become abnormal. Upon receiving this event, the application needs to close all sockets and recreate the application when the IP changes to a valid one. +Generally the application don't need to care about this event, it is just a debug event to let the application know that the IPV4 address is lost. SYSTEM_EVENT_AP_START ++++++++++++++++++++++++++++++++++++ @@ -209,21 +231,23 @@ Similar to <`SYSTEM_EVENT_STA_STOP`_>. SYSTEM_EVENT_AP_STACONNECTED ++++++++++++++++++++++++++++++++++++ -Every time a station is connected to ESP32 SoftAP, the <`SYSTEM_EVENT_AP_STACONNECTED`_> will arise. Upon receiving this event, the event task will do nothing, and the application callback can also ignore it. However, you may want to do something, for example, to get the info of the connected STA, etc. +Every time a station is connected to ESP32 AP, the <`SYSTEM_EVENT_AP_STACONNECTED`_> will arise. Upon receiving this event, the event task will do nothing, and the application callback can also ignore it. However, you may want to do something, for example, to get the info of the connected STA, etc. SYSTEM_EVENT_AP_STADISCONNECTED ++++++++++++++++++++++++++++++++++++ This event can happen in the following scenarios: - The application calls esp_wifi_disconnect(), or esp_wifi_deauth_sta(), to manually disconnect the station. - - The Wi-Fi driver kicks off the station, e.g. because the SoftAP has not received any packets in the past five minutes, etc. - - The station kicks off the SoftAP. + - The Wi-Fi driver kicks off the station, e.g. because the AP has not received any packets in the past five minutes, etc. + - The station kicks off the AP. When this event happens, the event task will do nothing, but the application event callback needs to do something, e.g., close the socket which is related to this station, etc. SYSTEM_EVENT_AP_PROBEREQRECVED ++++++++++++++++++++++++++++++++++++ -Currently, the ESP32 implementation will never generate this event. It may be removed in future releases. + +This event is disabled by default. The application can enable it via API esp_wifi_set_event_mask(). +When this event is enabled, it will be raised each time the AP receives a probe request. ESP32 Wi-Fi Station General Scenario --------------------------------------- @@ -245,11 +269,11 @@ Below is a "big scenario" which describes some small scenarios in Station mode: MAIN_TASK [label = "Main\ntask"]; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; - LWIP_TASK [label = "LwIP\ntask"]; + LwIP_TASK [label = "LwIP\ntask"]; WIFI_TASK [label = "Wi-Fi\ntask"]; === 1. Init Phase === - MAIN_TASK -> LWIP_TASK [label="1.1> Create / init LwIP"]; + MAIN_TASK -> LwIP_TASK [label="1.1> Create / init LwIP"]; MAIN_TASK -> EVENT_TASK [label="1.2> Create / init event"]; MAIN_TASK -> WIFI_TASK [label="1.3> Create / init Wi-Fi"]; MAIN_TASK -> APP_TASK [label="1.4> Create app task"]; @@ -264,8 +288,8 @@ Below is a "big scenario" which describes some small scenarios in Station mode: EVENT_TASK <- WIFI_TASK [label="4.2> SYSTEM_EVENT_STA_CONNECTED"]; APP_TASK <- EVENT_TASK [label="4.3> SYSTEM_EVENT_STA_CONNECTED"]; === 5. Got IP Phase === - EVENT_TASK -> LWIP_TASK [label="5.1> Start DHCP client"]; - EVENT_TASK <- LWIP_TASK [label="5.2> SYSTEM_EVENT_STA_GOT_IP"]; + EVENT_TASK -> LwIP_TASK [label="5.1> Start DHCP client"]; + EVENT_TASK <- LwIP_TASK [label="5.2> SYSTEM_EVENT_STA_GOT_IP"]; APP_TASK <- EVENT_TASK [label="5.3> SYSTEM_EVENT_STA_GOT_IP"]; APP_TASK -> APP_TASK [label="5.4> socket related init"]; === 6. Disconnect Phase === @@ -273,7 +297,7 @@ Below is a "big scenario" which describes some small scenarios in Station mode: APP_TASK <- EVENT_TASK [label="6.2> SYSTEM_EVENT_STA_DISCONNECTED"]; APP_TASK -> APP_TASK [label="6.3> disconnect handling"]; === 7. IP Change Phase === - EVENT_TASK <- LWIP_TASK [label="7.1> SYSTEM_EVENT_STA_GOT_IP"]; + EVENT_TASK <- LwIP_TASK [label="7.1> SYSTEM_EVENT_STA_GOT_IP"]; APP_TASK <- EVENT_TASK [label="7.2> SYSTEM_EVENT_STA_GOT_IP"]; APP_TASK -> APP_TASK [label="7.3> Socket error handling"]; === 8. Deinit Phase === @@ -334,7 +358,7 @@ In step 4.2, the Wi-Fi connection may fail because, for example, the password is 7. Wi-Fi IP Change Phase ++++++++++++++++++++++++++++++++++ - - s7.1: If the IP address is changed, the <`SYSTEM_EVENT_STA_GOT_IP`_> will arise. + - s7.1: If the IP address is changed, the <`SYSTEM_EVENT_STA_GOT_IP`_> will arise with "ip_change" set to true. - s7.2: **This event is important to the application. When it occurs, the timing is good for closing all created sockets and recreating them.** @@ -346,12 +370,12 @@ In step 4.2, the Wi-Fi connection may fail because, for example, the password is - s8.3: Call esp_wifi_deinit() to unload the Wi-Fi driver. -ESP32 Wi-Fi soft-AP General Scenario +ESP32 Wi-Fi AP General Scenario --------------------------------------------- -Below is a "big scenario" which describes some small scenarios in Soft-AP mode: +Below is a "big scenario" which describes some small scenarios in AP mode: .. seqdiag:: - :caption: Sample Wi-Fi Event Scenarios in Soft-AP Mode + :caption: Sample Wi-Fi Event Scenarios in AP Mode :align: center seqdiag sample-scenarios-soft-ap-mode { @@ -366,11 +390,11 @@ Below is a "big scenario" which describes some small scenarios in Soft-AP mode: MAIN_TASK [label = "Main\ntask"]; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; - LWIP_TASK [label = "LwIP\ntask"]; + LwIP_TASK [label = "LwIP\ntask"]; WIFI_TASK [label = "Wi-Fi\ntask"]; === 1. Init Phase === - MAIN_TASK -> LWIP_TASK [label="1.1> Create / init LwIP"]; + MAIN_TASK -> LwIP_TASK [label="1.1> Create / init LwIP"]; MAIN_TASK -> EVENT_TASK [label="1.2> Create / init event"]; MAIN_TASK -> WIFI_TASK [label="1.3> Create / init Wi-Fi"]; MAIN_TASK -> APP_TASK [label="1.4> Create app task"]; @@ -397,7 +421,7 @@ Below is a "big scenario" which describes some small scenarios in Soft-AP mode: ESP32 Wi-Fi Scan ------------------------ -Currently, the esp_wifi_scan_start() API is supported only in Station or Station+SoftAP mode. +Currently, the esp_wifi_scan_start() API is supported only in Station or Station+AP mode. Scan Type +++++++++++++++++++++++++ @@ -421,7 +445,7 @@ Scan Type | | the application. | +------------------+--------------------------------------------------------------+ | Background Scan | This scan is applicable when there is a Wi-Fi connection in | -| | Station mode or in Station+SoftAP mode. | +| | 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.| | | | @@ -450,7 +474,7 @@ The scan modes in above table can be combined arbitrarily, so we totally have 8 Scan Configuration +++++++++++++++++++++++++++++++++++++++ -The scan type and other scan attributes are configured by esp_wifi_scan_start. The table below provides a detailed description of wifi_scan_config_t. +The scan type and other per-scan attributes are configured by esp_wifi_scan_start. The table below provides a detailed description of wifi_scan_config_t. +------------------+--------------------------------------------------------------+ | Field | Description | @@ -498,6 +522,8 @@ The scan type and other scan attributes are configured by esp_wifi_scan_start. T | | | +------------------+--------------------------------------------------------------+ +There also some global scan attributes which is configured by API esp_wifi_set_config, refer to `Station Basic Configuration`_ + Scan All APs In All Channels(foreground) +++++++++++++++++++++++++++++++++++++++++++ @@ -538,7 +564,7 @@ Detailed scenario description: Scan Configuration Phase ************************** - - s1.1: Call esp_wifi_set_country() to set the country code. For China/Japan, the channel value ranges from 1 to 14; for the USA, it ranges from 1 to 11; and for Europe, it ranges from 1 to 13. The default country is China. + - s1.1: Call esp_wifi_set_country() to set the country info if the default country info is not what you want, refer to <`Wi-Fi Country Code`_>. - s1.2: Call esp_wifi_scan_start() to configure the scan. To do so, you can refer to <`Scan Configuration`_>. Since this is an all-channel scan, just set the SSID/BSSID/channel to 0. @@ -625,9 +651,9 @@ Scenario: This scan is similar to `Scan All APs In 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 it is a target AP, 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 more than one APs which match the target AP info, for example, if we happen to scan two APs whose SSID is "ap", then only the first AP will be returned. However, if the first AP is not the one you want, e.g., if its password is wrong, then the Wi-Fi driver will detect a four-way handshake failure and try to scan the next AP. If two APs have the same SSID, BSSID and password, then the Wi-Fi driver will choose the first one to connect to. +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`_. You can scan a specific AP, or all of them, in any given channel. These two scenarios are very similar. @@ -643,11 +669,30 @@ If the block parameter of esp_wifi_scan_start() is true, then the scan is a bloc Parallel Scan +++++++++++++ -Two application tasks may call esp_wifi_scan() at the same time, or the same application task calls esp_wifi_scan_start() before it gets a scan-done event. Both scenarios can happen. **However, in IDF2.1, the Wi-Fi driver does not support parallel scans adequately. As a result, a parallel scan should be avoided.** The parallel scan will be enhanced in future releases, as the ESP32's Wi-Fi functionality improves continuously. +Two application tasks may call esp_wifi_scan_start() at the same time, or the same application task calls esp_wifi_scan_start() before it gets a scan-done event. Both scenarios can happen. **However, the Wi-Fi driver does not support multiple concurrent scans adequately. As a result, concurrent scans should be avoided.** Support for concurrent scan will be enhanced in future releases, as the ESP32's Wi-Fi functionality improves continuously. +Scan When Wi-Fi Is Connecting ++++++++++++++++++++++++++++++++ + +The esp_wifi_scan_start() fails immediately if the Wi-Fi is in connecting process because the connecting has higher priority than the scan. If scan fails because of connecting, the recommended strategy is to delay sometime and retry scan again, the scan will succeed once the connecting is completed. + +However, the retry/delay strategy may not work all the time. Considering following scenario: +- The station is connecting a non-existed AP or if the station connects the existed AP with a wrong password, it always raises the event <`SYSTEM_EVENT_STA_DISCONNECTED`_>. +- The application call esp_wifi_connect() to do reconnection on receiving the disconnect event. +- Another application task, e.g. the console task, call esp_wifi_scan_start() to do scan, the scan always fails immediately because the station is keeping connecting. +- When scan fails, the application simply delay sometime and retry the scan. + +In above scenario the scan will never succeed because the connecting is in process. So if the application supports similar scenario, it needs to implement a better reconnect strategy. E.g. +- The application can choose to define a maximum continuous reconnect counter, stop reconnect once the reconnect reaches the max counter. +- The application can choose to do reconnect immediately in the first N continous reconnect, then give a delay sometime and reconnect again. + +The application can define its own reconnect strategy to avoid the scan starve to death. Refer to <`Wi-Fi Reconnect`_>. ESP32 Wi-Fi Station Connecting Scenario ---------------------------------------- + +This scenario only depicts the case when there is only one target AP are found in scan phase, for the scenario that more than one AP with the same SSID are found, refer to <`ESP32 Wi-Fi Station Connecting When Multiple APs Are Found`_>. + Generally, the application does not need to care about the connecting process. Below is a brief introduction to the process for those who are really interested. Scenario: @@ -707,7 +752,7 @@ Auth Phase - s2.1, The authentication request packet is sent and the auth timer is enabled. - s2.2, If the authentication response packet is not received before the authentication timer times out, <`SYSTEM_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_AUTH_EXPIRE. Refer to <`Wi-Fi Reason Code`_>. - s2.3, The auth-response packet is received and the auth-timer is stopped. - - s2.4, The AP rejects authentication in the response and <`SYSTEM_EVENT_STA_DISCONNECTED`_> arises, while the reason-code is WIFI_REASON_AUTH_FAIL or the reasons specified by the soft-AP. Refer to <`Wi-Fi Reason Code`_>. + - s2.4, The AP rejects authentication in the response and <`SYSTEM_EVENT_STA_DISCONNECTED`_> arises, while the reason-code is WIFI_REASON_AUTH_FAIL or the reasons specified by the AP. Refer to <`Wi-Fi Reason Code`_>. Association Phase +++++++++++++++++++++ @@ -744,13 +789,13 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | For the ESP32 Station, this reason is reported when: | | | | | | | | | | - auth is timed out | -| | | | - the reason is received from the soft-AP. | +| | | | - the reason is received from the AP. | | | | | | -| | | | For the ESP32 SoftAP, this reason is reported when: | +| | | | For the ESP32 AP, this reason is reported when: | | | | | | -| | | | - the soft-AP has not received any packets from the station| +| | | | - the AP has not received any packets from the station | | | | | in the past five minutes. | -| | | | - the soft-AP is stopped by calling esp_wifi_stop(). | +| | | | - the AP is stopped by calling esp_wifi_stop(). | | | | | - the station is de-authed by calling esp_wifi_deauth_sta()| | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ @@ -759,20 +804,20 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | ASSOC_EXPIRE | 4 | 4 | Disassociated due to inactivity. | | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | -| | | | For the ESP32 Soft-AP, this reason is reported when: | +| | | | For the ESP32 AP, this reason is reported when: | | | | | | -| | | | - the soft-AP has not received any packets from the | +| | | | - the AP has not received any packets from the | | | | | station in the past five minutes. | -| | | | - the soft-AP is stopped by calling esp_wifi_stop(). | +| | | | - the AP is stopped by calling esp_wifi_stop(). | | | | | - the station is de-authed by calling esp_wifi_deauth_sta()| | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ @@ -780,24 +825,24 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | all currently associated STAs at the same time. | | | | | | | | | | For the ESP32 Station, this reason is reported when: | -| | | | | -| | | | - it is received from the soft-AP. | -| | | | | -| | | | For the ESP32 Soft-AP, this reason is reported when: | | | | | | -| | | | - the stations associated with the soft-AP reach the | -| | | | maximum number that the soft-AP can support. | +| | | | - it is received from the AP. | +| | | | | +| | | | For the ESP32 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 ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | -| | | | For the ESP32 Soft-AP, this reason is reported when: | +| | | | For the ESP32 AP, this reason is reported when: | | | | | | -| | | | - the soft-AP receives a packet with data from a | +| | | | - the AP receives a packet with data from a | | | | | non-authenticated station. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ @@ -805,11 +850,11 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | -| | | | For the ESP32 Soft-AP, this reason is reported when: | +| | | | For the ESP32 AP, this reason is reported when: | | | | | | -| | | | - the soft-AP receives a packet with data from a | +| | | | - the AP receives a packet with data from a | | | | | non-associated station. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ @@ -818,7 +863,7 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | - the station is disconnected by esp_wifi_disconnect() and | | | | | other APIs. | | | | | | @@ -828,11 +873,11 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | -| | | | For the ESP32 Soft-AP, this reason is reported when: | +| | | | For the ESP32 AP, this reason is reported when: | | | | | | -| | | | - the soft-AP receives packets with data from an | +| | | | - the AP receives packets with data from an | | | | | associated, yet not authenticated, station. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ @@ -841,7 +886,7 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | DISASSOC_SUPCHAN_BAD | 11 | 11 | Disassociated, because the information in the Supported | @@ -849,7 +894,7 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | IE_INVALID | 13 | 13 | Invalid element, i.e. an element whose content does not meet| @@ -857,18 +902,18 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP | +| | | | - it is received from the AP | | | | | | -| | | | For the ESP32 Soft-AP, this reason is reported when: | +| | | | For the ESP32 AP, this reason is reported when: | | | | | | -| | | | - the soft-AP parses a wrong WPA or RSN IE. | +| | | | - the AP parses a wrong WPA or RSN IE. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | MIC_FAILURE | 14 | 14 | Message integrity code (MIC) failure. | | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, in ESP32 | @@ -878,14 +923,14 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | For the ESP32 Station, this reason is reported when: | | | | | | | | | | - the handshake times out | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | GROUP_KEY_UPDATE_TIMEOUT | 16 | 16 | Group-Key Handshake times out. | | | | | | | | | | For the ESP32 station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | IE_IN_4WAY_DIFFERS | 17 | 17 | The element in the four-way handshake is different from the | @@ -893,7 +938,7 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | | | | | For the ESP32 station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - 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. | @@ -903,44 +948,44 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | PAIRWISE_CIPHER_INVALID | 19 | 19 | Invalid pairwise cipher. | | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | AKMP_INVALID | 20 | 20 | Invalid AKMP. | | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | UNSUPP_RSN_IE_VERSION | 21 | 21 | Unsupported RSNE version. | | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | INVALID_RSN_IE_CAP | 22 | 22 | Invalid RSNE capabilities. | | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | 802_1X_AUTH_FAILED | 23 | 23 | IEEE 802.1X. authentication failed. | | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | -| | | | For the ESP32 soft-AP, this reason is reported when: | +| | | | For the ESP32 AP, this reason is reported when: | | | | | | | | | | - 802.1 x authentication fails. | | | | | | @@ -949,7 +994,7 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | | | | | For the ESP32 Station, this reason is reported when: | | | | | | -| | | | - it is received from the soft-AP. | +| | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | BEACON_TIMEOUT | 200 |reserved | Espressif-specific Wi-Fi reason-code: when the station | @@ -975,6 +1020,30 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ +ESP32 Wi-Fi Station Connecting When Multiple APs Are Found +--------------------------------------------------------------- + +This scenario is similar as <`ESP32 Wi-Fi Station Connecting Scenario`_>, the difference is the station will not raise the event <`SYSTEM_EVENT_STA_DISCONNECTED`_> unless it fails to connect all of the found APs. + + +Wi-Fi Reconnect +--------------------------- + +The station may disconnect due to many reasons, e.g. the connected AP is restarted etc. It's the application's responsibility to do the reconnect. The recommended reconnect strategy is to call esp_wifi_connect() on receiving event <`SYSTEM_EVENT_STA_DISCONNECTED`_>. + +Sometimes the application needs more complex reconnect strategy: +- If the disconnect event is raised because the esp_wifi_disconnect() is called, the application may not want to do reconnect. +- If the esp_wifi_scan_start() may be called at anytime, a better reconnect strategy is necessary, refer to <`Scan When Wi-Fi Is Connecting`_>. + +Another thing we need to consider is the reconnect may not connect the same AP if there are more than one APs with the same SSID. The reconnect always select current best APs to connect. + +Wi-Fi Beacon Timeout +--------------------------- + +The beacon timeout mechanism is used by ESP32 station to detect whether the AP is alive or not. If the station continuously loses 60 beacons of the connected AP, the beacon timeout happens. + +After the beacon timeout happens, the station sends 5 probe requests to AP, it disconnects the AP and raises the event <`SYSTEM_EVENT_STA_DISCONNECTED`_> if still no probe response or beacon is received from AP. + ESP32 Wi-Fi Configuration --------------------------- @@ -988,8 +1057,8 @@ Call 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 soft-AP, while both the | -| | station and soft-AP interfaces are not initialized for | +| | 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 esp_wifi_deinit() to unload the whole Wi-Fi | @@ -1000,18 +1069,18 @@ Call esp_wifi_set_mode() to set the Wi-Fi mode. | | for the RX and TX Wi-Fi data. After esp_wifi_connect() is | | | called, the STA will connect to the target AP. | +------------------+--------------------------------------------------------------+ -| WIFI_MODE_AP | Soft-AP mode: in this mode, esp_wifi_start() will init the | -| | internal soft-AP data, while the soft-AP's interface is ready| +| WIFI_MODE_AP | AP mode: in this mode, 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 soft-AP is ready to get connected | +| | casting beacons, and the AP is ready to get connected | | | to other stations. | +------------------+--------------------------------------------------------------+ | WIFI_MODE_APSTA | Station-AP coexistence mode: in this mode, esp_wifi_start() | -| | will simultaneously init both the station and the soft-AP. | -| | This is done in station mode and soft-AP mode. Please note | +| | 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 ESP32 Station | -| | is connected to, has higher priority over the ESP32 Soft-AP | -| | channel. Refer to `Wi-Fi Channel Management`_. | +| | is connected to, has higher priority over the ESP32 AP | +| | channel. | +------------------+--------------------------------------------------------------+ Station Basic Configuration @@ -1029,6 +1098,11 @@ API esp_wifi_set_config() can be used to configure the station. The table below | 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 in 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 | @@ -1045,22 +1119,50 @@ API esp_wifi_set_config() can be used to configure the station. The table below | | 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 -90dBm, the second AP's | +| | signal is -30dBm, 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 -127dBm. If the authmode threshold is set | +| | to 0, it means default threshold, the default authmode | +| | threshold is open. | ++------------------+--------------------------------------------------------------+ -Soft-AP Basic Configuration +AP Basic Configuration +++++++++++++++++++++++++++++++++++++ -API esp_wifi_set_config() can be used to configure the soft-AP. The table below describes the fields in detail. +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 soft-AP; if the ssid[0] is 0xFF and ssid[1] is 0xFF, | -| | the soft-AP defaults the SSID to ESP_aabbcc, where "aabbcc" | -| | is the last three bytes of the soft-AP MAC. | +| 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 soft-AP; if the auth mode is WIFI_AUTH_OPEN, | +| password | Password of AP; if the auth mode is WIFI_AUTH_OPEN, | | | this field will be ignored. | | | | +------------------+--------------------------------------------------------------+ @@ -1069,27 +1171,27 @@ API esp_wifi_set_config() can be used to configure the soft-AP. The table below | | 32; otherwise, set the SSID length according to ssid_len. | | | | +------------------+--------------------------------------------------------------+ -| channel | Channel of soft-AP; if the channel is out of range, the Wi-Fi| +| 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 <`Channel Range`_>. | +| | For more details, refer to <`Wi-Fi Country Code`_>. | +------------------+--------------------------------------------------------------+ -| authmode | Auth mode of ESP32 soft-AP; currently, ESP32 Wi-Fi does not | +| authmode | Auth mode of ESP32 AP; currently, ESP32 Wi-Fi does not | | | support AUTH_WEP. If the authmode is an invalid value, | -| | soft-AP defaults the value to WIFI_AUTH_OPEN. | +| | AP defaults the value to WIFI_AUTH_OPEN. | | | | +------------------+--------------------------------------------------------------+ -| ssid_hidden | If ssid_hidden is 1, soft-AP does not broadcast the SSID; | +| ssid_hidden | If ssid_hidden is 1, AP does not broadcast the SSID; | | | otherwise, it does broadcast the SSID. | | | | +------------------+--------------------------------------------------------------+ | max_connection | Currently, ESP32 Wi-Fi supports up to 10 Wi-Fi connections. | -| | If max_connection > 10, soft-AP defaults the value to 10. | +| | 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, | -| | soft-AP defaults it to 100 ms. | +| | AP defaults it to 100 ms. | +------------------+--------------------------------------------------------------+ Wi-Fi Protocol Mode @@ -1101,56 +1203,198 @@ 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/soft-AP to 802.11B-only mode. | +| | 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/soft-AP to 802.11BG mode. | +| | 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/ | -| | soft-AP to BGN mode. | +| | 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/soft-AP to BGN and the | +| | 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/soft-AP only to the Espressif-specific mode. | +| | 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 soft-AP are connected to an | +| | the station and the AP are connected to an | | | ESP32 device** | +--------------------+------------------------------------------------------------+ -Wi-Fi Channel Management +Long Range (LR) +++++++++++++++++++++++++ -Channel Range +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 Compitability ************************* -Call esp_wifi_set_country() to set the country code which limits the channel range. +Since LR is Espressif unique Wi-Fi mode, only ESP32 devices can transmit and receive the LR data. In other words, the ESP32 device should NOT transmit the data in LR data rate if the connected device doesn't support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the ESP32 may transmit data in LR rate, otherwise, ESP32 will transmit all data in traditional Wi-Fi data rate. -+------------------+---------------------+ -| Country | Channel Range | -+==================+=====================+ -| China | 1,2,3 ... 14 | -+------------------+---------------------+ -| Japan | 1,2,3 ... 14 | -+------------------+---------------------+ -| USA | 1,2,3 ... 11 | -+------------------+---------------------+ -| Europe | 1,2,3 ... 13 | -+------------------+---------------------+ +Following table depicts the Wi-Fi mode negotiation: + ++-------+-----+----+---+-------+------+-----+----+ +|AP\STA | BGN | BG | B | BGNLR | BGLR | BLR | LR | ++=======+=====+====+===+=======+======+=====+====+ +| BGN | BGN | BG | B | BGN | BG | B | - | ++-------+-----+----+---+-------+------+-----+----+ +| BG | BG | BG | B | BG | BG | B | - | ++-------+-----+----+---+-------+------+-----+----+ +| B | B | B | B | B | B | B | - | ++-------+-----+----+---+-------+------+-----+----+ +| BGNLR | - | - | - | BGNLR | BGLR | BLR | LR | ++-------+-----+----+---+-------+------+-----+----+ +| BGLR | - | - | - | BGLR | BGLR | BLR | LR | ++-------+-----+----+---+-------+------+-----+----+ +| BLR | - | - | - | BLR | BLR | BLR | LR | ++-------+-----+----+---+-------+------+-----+----+ +| LR | - | - | - | LR | LR | LR | LR | ++-------+-----+----+---+-------+------+-----+----+ + +In above table, the row is the Wi-Fi mode of AP and the column is the Wi-Fi mode of station. The "-" indicates Wi-Fi mode of the AP and station are not compatible. + +According to the table, we can conclude that: + - For LR enabled in ESP32 AP, it's incompatible with traditional 802.11 mode because the beacon is sent in LR mode. + - For LR enabled in ESP32 station and the mode is NOT LR only mode, it's compatible with traditional 802.11 mode. + - If both station and AP are ESP32 devices and both of them enable LR mode, the negotiated mode supports LR. + +If the negotiated Wi-Fi mode supports both traditional 802.11 mode and LR mode, it's the WiFi driver's responsibility to automatically select the best data rate in different Wi-Fi mode and the application don't need to care about it. + +LR Impacts to Traditional Wi-Fi device +*************************************** + +The data transmission in LR rate has no impacts on the traditional Wi-Fi device because: + - 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. + +LR Transmission Distance +************************* + +The reception sensitivity of LR has about 4 dB gain than the traditional 802.11 B mode, theoretically the transmission distance is about 2 to 2.5 times the distance of 11B. + +LR Throughput +************************* + +The LR rate has very limited throughput because the raw PHY data rate LR is 1/2 Mbits and 1/4 Mbits. + +When to Use LR +************************* + +The general conditions for using LR are: + - Both the AP and station are ESP32 devices. + - Long distance WiFi connection and data transmission is required. + - Data throughput requirements are very small, such as remote device control, etc. + +Wi-Fi Country Code ++++++++++++++++++++++++++ + +Call esp_wifi_set_country() to set the country info. +The table below describes the fields in detail, please consult local 2.4GHz RF operating regulations before configuring these fields. + ++------------------+-----------------------------------------------------------------------------------+ +| 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, or | +| | - 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 ASSCII 'XX' | +| | characters. | +| | - the binary representation of the Operating Class table number currently in use.| +| | Refer 802.11-2012 Annex E. | +| | | ++------------------+-----------------------------------------------------------------------------------+ +| schan | Start channel, it's the minimum channel number of the regulations under which the | +| | station/AP can operate. | +| | | ++------------------+-----------------------------------------------------------------------------------+ +| snum | Total channel number of 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 WiFi 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 WiFi 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: | +| | | | +| | | - before the station connects to the AP, scans channel | +| | | "schan" to "min(11, schan+nchan-1)" with active scan and | +| | | channel min(12, schan+nchan)" to 14 with passive scan. | +| | | E.g. if the used country info is | +| | | {.cc="CN", .schan=1, .nchan=6} then 1 to 6 is active scan | +| | | and 7 to 14 is passive scan | +| | | If the used country info is | +| | | {.cc="CN", .schan=1, .nchan=12} then 1 to 11 is active scan | +| | | and 12 to 14 is passive scan | +| | | | +| | | - after the station connects to the AP, scans channel | +| | | "schan" to "schan+nchan-1" with active scan and channel | +| | | "schan+nchan" to 14 with passive scan | +| | | | +| | | Always keep in mind that if if a AP with 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. | +| coexit | | 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 | ++-----------+----------------------------+----------------------------------------------------------------+ Home Channel ************************* -In soft-AP mode, the home channel is defined as that of the soft-AP channel. In Station mode, the home channel is defined as the channel of the AP to which the station is connected. In Station+SoftAP mode, the home channel of soft-AP and station must be the same. If the home channels of Station and Soft-AP are different, the station's home channel is always in priority. Take the following as an example: at the beginning, the soft-AP is on channel 6, then the station connects to an AP whose channel is 9. Since the station's home channel has a higher priority, the soft-AP needs to switch its channel from 6 to 9 to make sure that both station and soft-AP have the same home channel. +In AP mode, the home channel is defined as that of the AP channel. In Station mode, the home channel is defined as the channel of the AP to which the station is connected. In Station+AP mode, the home channel of AP and station must be the same. If the home channels of Station and AP are different, the station's home channel is always in priority. Take the following as an example: at the beginning, the AP is on channel 6, then the station connects to an AP whose channel is 9. Since the station's home channel has a higher priority, the AP needs to switch its channel from 6 to 9 to make sure that both station and AP have the same home channel. Wi-Fi Vendor IE Configuration @@ -1160,12 +1404,29 @@ By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and t ESP32 Wi-Fi Power-saving Mode ----------------------------------- + +Station Sleep +++++++++++++++++++++++ + Currently, ESP32 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. In maximum power save mode, station wakes up every listen interval to receive beacon. Broadcast data may be lost because station may be in sleep state at DTIM time. If listen interval is longer, more power is saved but broadcast data is more easy to lose. Listen interval can be configured by calling API :cpp:func:`esp_wifi_set_config` before connecting to AP. +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. + +In maximum power save mode, station wakes up every listen interval to receive beacon. This listen interval can be set longer than the AP DTIM period. Broadcast data may be lost because station may be in sleep state at DTIM time. If listen interval is longer, more power is saved but broadcast data is more easy to lose. Listen interval can be configured by calling API :cpp:func:`esp_wifi_set_config` before connecting to AP. Call ``esp_wifi_set_ps(WIFI_PS_MIN_MODEM)`` to enable Modem-sleep minimum power save mode or ``esp_wifi_set_ps(WIFI_PS_MAX_MODEM)`` to enable Modem-sleep maximum power save mode after calling :cpp:func:`esp_wifi_init`. When station connects to AP, Modem-sleep will start. When station disconnects from AP, Modem-sleep will stop. +Call `esp_wifi_set_ps(WIFI_PS_MIN_MODEM)` to disable modem sleep entirely. This has much higher power consumption, but provides minimum latency for receiving Wi-Fi data in real time. When modem sleep is enabled, received Wi-Fi data can be delayed for as long as the DTIM period (minimum power save mode) or the listen interval (maximum power save mode). + +The default Modem-sleep mode is WIFI_PS_MIN_MODEM. + +AP Sleep ++++++++++++++++++++++++++++++++ + +Currently ESP32 AP doesn't support all of the power save feature defined in Wi-Fi specification. To be specific, the AP only caches unicast data for the stations connect to this AP, but doesn't cache the multicast data for the stations. If stations connected to the ESP32 AP are power save enabled, they may experience multicast packet loss. + +In future, all power save features will be supported on ESP32 AP. + ESP32 Wi-Fi Connect Crypto ----------------------------------- Now ESP32 have two group crypto functions can be used when do wifi connect, one is the original functions, the other is optimized by ESP hardware: @@ -1180,73 +1441,24 @@ ESP32 Wi-Fi Throughput The table below shows the best throughput results we got in Espressif's lab and in a shield box. -+----------------------+-----------------+-----------------+ -| Type/Throughput | Air In Lab | Shield-box | -+======================+=================+=================+ -| Raw 802.11 Packet RX | N/A | **130 MBit/sec**| -+----------------------+-----------------+-----------------+ -| Raw 802.11 Packet TX | N/A | **130 MBit/sec**| -+----------------------+-----------------+-----------------+ -| UDP RX | 30 MBit/sec | 80 MBit/sec | -+----------------------+-----------------+-----------------+ -| UDP TX | 30 MBit/sec | 80 MBit/sec | -+----------------------+-----------------+-----------------+ -| TCP RX | 20 MBit/sec | 25 MBit/sec | -+----------------------+-----------------+-----------------+ -| TCP TX | 20 MBit/sec | 25 MBit/sec | -+----------------------+-----------------+-----------------+ ++----------------------+-----------------+-----------------+---------------+--------------+ +| Type/Throughput | Air In Lab | Shield-box | Test Tool | IDF Version | +| | | | | (commit ID) | ++======================+=================+=================+===============+==============+ +| Raw 802.11 Packet RX | N/A | **130 MBit/sec**| Internal tool | NA | ++----------------------+-----------------+-----------------+---------------+--------------+ +| Raw 802.11 Packet TX | N/A | **130 MBit/sec**| Internal tool | NA | ++----------------------+-----------------+-----------------+---------------+--------------+ +| UDP RX | 30 MBit/sec | 90 MBit/sec | iperf example | 05838641 | ++----------------------+-----------------+-----------------+---------------+--------------+ +| UDP TX | 30 MBit/sec | 60 MBit/sec | iperf example | 05838641 | ++----------------------+-----------------+-----------------+---------------+--------------+ +| TCP RX | 20 MBit/sec | 50 MBit/sec | iperf example | 05838641 | ++----------------------+-----------------+-----------------+---------------+--------------+ +| TCP TX | 20 MBit/sec | 50 MBit/sec | iperf example | 05838641 | ++----------------------+-----------------+-----------------+---------------+--------------+ -The throughput result heavily depends on hardware and software configurations, such as CPU frequency, memory configuration, or whether the CPU is running in dual-core mode, etc. The table below shows the configurations with which we got the above-mentioned throughput results. In ESP32 IDF, the default configuration is based on "very conservative" calculations, so if you want to get the best throughput result, the first thing you need to do is to adjust the relevant configurations. - -+------------------+---------------------+------------------------------+ -| Type | Value | How to configure | -+==================+=====================+==============================+ -| CPU Core Mode | Dual Core | Menuconfig | -+------------------+---------------------+------------------------------+ -| CPU Frequency | 240 MHz | Menuconfig | -+------------------+---------------------+------------------------------+ -| Static RX Buffer | 15 | Menuconfig | -+------------------+---------------------+------------------------------+ -| Dynamic RX Buffer| Unlimited | Menuconfig | -+------------------+---------------------+------------------------------+ -| Dynamic TX Buffer| Unlimited | Menuconfig | -+------------------+---------------------+------------------------------+ -| TCP RX Window | 12*1460 Bytes | Release 2.1/2.0 and earlier: | -| | | TCP_WND_DEFAULT in lwipopts.h| -| | | | -| | | After the 2.1 Release: | -| | | Menuconfig | -+------------------+---------------------+------------------------------+ -| TCP TX Window | 12*1460 Bytes | Release 2.1/2.0 and earlier: | -| | | TCP_SND_BUF_DEFAULT in | -| | | lwipopts.h | -| | | | -| | | After the 2.1 Release: | -| | | Menuconfig | -+------------------+---------------------+------------------------------+ -| TCP RX MBOX | 12 | Release 2.1/2.0 and earlier: | -| | | DEFAULT_TCP_RECVMBOX_SIZE in | -| | | lwipopts.h | -| | | | -| | | After the 2.1 Release: | -| | | Menuconfig | -+------------------+---------------------+------------------------------+ -| RX BA Window | 9~16 | Release 2.1/2.0 and earlier: | -| | | not configurable | -| | | | -| | | After the 2.1 Release: | -| | | Menuconfig | -+------------------+---------------------+------------------------------+ -| TX BA Window | 9~16 | Release 2.1/2.0 and earlier: | -| | | not configurable | -| | | | -| | | After the 2.1 Release: | -| | | Menuconfig | -+------------------+---------------------+------------------------------+ - -Once you adjust the configurations, you can then run your own test code to test the performance. You can also run the iperf example to test the performance. However, the iperf example is not provided in release 2.1 and earlier ones, but will be so in the upcoming release. Those who really care about the performance should seek support from Espressif directly, so that we can provide them with the iperf version bin for their testing. - -If you decide to modify some of the configurations in order to gain better throughput for your application, please consider the memory usage very carefully. For a more detailed description, refer to <`Wi-Fi Buffer Usage`_> and <`Wi-Fi Buffer Configure`_>. +When the throughput is tested by iperf example, the sdkconfig is :idf_file:`examples/wifi/iperf/sdkconfig.defaults.99` Wi-Fi 80211 Packet Send --------------------------- @@ -1263,7 +1475,7 @@ It cannot be used for sending encrypted or QoS frames. Preconditions of Using esp_wifi_80211_tx ++++++++++++++++++++++++++++++++++++++++++++ - - The Wi-Fi mode is Station, or SoftAP, or Station+SoftAP. + - The Wi-Fi mode is Station, or AP, or Station+AP. - Either esp_wifi_set_promiscuous(true), or 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 esp_wifi_80211_tx() is called. In ESP32, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware. - The parameters of esp_wifi_80211_tx are hereby correctly provided. @@ -1271,12 +1483,12 @@ Data rate +++++++++++++++++++++++++++++++++++++++++++++++ - If there is no WiFi connection, the data rate is 1Mbps. - - If there is WiFi connection and the packet is from station to SoftAP or from SoftAP to station, the data rate is same as the WiFi connection. Otherwise the data rate is 1Mbps. + - If there is WiFi connection and the packet is from station to AP or from AP to station, the data rate is same as the WiFi connection. Otherwise the data rate is 1Mbps. 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/soft-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 esp_wifi_80211_tx 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 esp_wifi_80211_tx in different scenarios. +-----------------------------+---------------------------------------------------+ | Scenario | Description | @@ -1289,14 +1501,14 @@ Theoretically, if we do not consider the side-effects the API imposes on the Wi- | | that the buffer has the correct sequence. | | | | | | Theoretically, the MAC address can be any address.| -| | However, this may impact other stations/soft-APs | +| | 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 SoftAP mode, but | -| | the mac_x is not the MAC of the SoftAP interface. | -| | Moreover, there is another soft-AP, say | +| | 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 | @@ -1310,10 +1522,10 @@ Theoretically, if we do not consider the side-effects the API imposes on the Wi- | | 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 SoftAP mode, | +| | - 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 soft-AP interface. | +| | should be that of the AP interface. | | | | | | The recommendations above are only for avoiding | | | side-effects and can be ignored when there are | @@ -1334,26 +1546,26 @@ Theoretically, if we do not consider the side-effects the API imposes on the Wi- | | 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 SoftAP. On the other hand, if the WiFi mode is | -| | SoftAP mode and the MAC address1 is the MAC of | -| | the station who connects to this SoftAP, the MAC | -| | address2 is the MAC of SoftAP interface, we say | -| | the packet is from the SoftAP to 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 SoftAP, the ToDS bit in ieee80211 | +| | station to AP, the ToDS bit in ieee80211 | | | 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 | -| | softAP to station, the ToDS bit in ieee80211 | +| | AP to station, the ToDS bit in ieee80211 | | | 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 SoftAP or | -| | from SoftAP to station, the Power Management, | +| | - 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. | @@ -1369,15 +1581,15 @@ The Wi-Fi sniffer mode can be enabled by esp_wifi_set_promiscuous(). If the snif - 802.11 Management frame - 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 The following packets will **NOT** be dumped to the application: - - 802.11 Control frame - 802.11 error frame, such as the frame with a CRC error, etc. -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 esp_wifi_set_promiscuous_filter(). By default, it will filter all 802.11 data and management frames to the application. +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 esp_wifi_set_promiscuous_filter() and esp_wifi_set_promiscuous_ctrl_filter(). By default, it will filter all 802.11 data and management frames to the application. -The Wi-Fi sniffer mode can be enabled in the Wi-Fi mode of WIFI_MODE_NULL, or WIFI_MODE_STA, or WIFI_MODE_AP, or WIFI_MODE_APSTA. In other words, the sniffer mode is active when the station is connected to the soft-AP, or when the soft-AP has a Wi-Fi connection. Please note that the sniffer has a **great impact** on the throughput of the station or soft-AP Wi-Fi connection. Generally, we should **NOT** enable the sniffer, when the station/soft-AP Wi-Fi connection experiences heavy traffic unless we have special reasons. +The Wi-Fi sniffer mode can be enabled in the Wi-Fi mode of WIFI_MODE_NULL, or WIFI_MODE_STA, or WIFI_MODE_AP, or WIFI_MODE_APSTA. In other words, the sniffer mode is active when the station is connected to the AP, or when the AP has a Wi-Fi connection. Please note that the sniffer has a **great impact** on the throughput of the station or AP Wi-Fi connection. Generally, we should **NOT** enable the sniffer, when the station/AP Wi-Fi connection experiences heavy traffic unless we have special reasons. Another noteworthy issue about the sniffer is the callback wifi_promiscuous_cb_t. The callback will be called directly in the Wi-Fi driver task, so if the application has a lot of work to do for each filtered packet, the recommendation is to post an event to the application task in the callback and defer the real work to the application task. @@ -1487,6 +1699,67 @@ To use Wi-Fi CSI, the following steps need to be done. The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy operations in the callback function. Instead, post necessary data to a queue and handle it from a lower priority task. Because station does not receive any packet when it is disconnected and only receives packets from AP when it is connected, it is suggested to enable sniffer mode to receive more CSI data by calling :cpp:func:`esp_wifi_set_promiscuous`. +Wi-Fi HT20/40 +------------------------- + +ESP32 supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. `esp_wifi_set_bandwidth` can be used to change the default bandwidth of station or AP. The default bandwidth for ESP32 station and AP is HT40. + +In station mode, the actual bandwidth is firstly negotiated during the Wi-Fi connection. It is HT40 only if both the station and the connected AP support HT40, otherwise it's HT20. If the bandwidth of connected AP is changes, the actual bandwidth is negotiated again without Wi-Fi disconnecting. + +Similarly, in AP mode, the actual bandwidth is negotiated between AP and the stations that connect to the AP. It's HT40 only if the AP and all the stations support HT40, otherwise it's HT40. + +In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in ESP32. E.g. the configured bandwidth of AP is HT40, the configured primary channel is 6 and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically. + +Theoretically the HT40 can gain better throughput because the maximum raw physicial (PHY) data rate for HT40 is 150Mbps while it's 72Mbps for HT20. However, if the device is used in some special environment, e.g. there are too many other Wi-Fi devices around the ESP32 device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, it's recommended that the bandwidth is always configured to HT20. + +Wi-Fi QoS +------------------------- + +ESP32 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. + +Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in ESP32, 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. + ++------------------+------------------------+-----------------+ +| IP Precedence | Wi-Fi AC | Support AMPDU? | ++==================+========================+=================+ +| 6, 7 | AC_VO (Voice) | No | ++------------------+------------------------+-----------------+ +| 4, 5 | AC_VI (Video) | Yes | ++------------------+------------------------+-----------------+ +| 3, 0 | AC_BE (Best Effort) | Yes | ++------------------+------------------------+-----------------+ +| 1, 2 | AC_BK (Background) | Yes | ++------------------+------------------------+-----------------+ + +The application can make use of the QoS feature by configuring the IP precedence via socket option IP_TOS. Here is an example to make the socket to use VI queue:: + + const int ip_precedence_vi = 4; + const int ip_precedence_offset = 5; + int priority = (ip_precedence_vi << ip_precedence_offset); + setsockopt(socket_id, IPPROTO_IP, IP_TOS, &priority, sizeof(priority)); + +Theoretically the higher priority AC has better performance than the low priority AC, however, it's not always be true, here are some suggestions about how to use the Wi-Fi QoS: + - For some really important application traffic, can put it into AC_VO queue. Avoid sending big traffic via AC_VO queue. On one hand, the AC_VO queue doesn't support AMPDU and it can't get better performance than other queue if the traffic is big, on the other hand, it may impact the the management frames that also use AC_VO queue. + - Avoid using more than two different AMPDU supported precedences, e.g. socket A uses precedence 0, socket B uses precedence 1, socket C uses precedence 2, this is a bad design because it may need much more memory. To be detailed, the Wi-Fi driver may generate a Block Ack session for each precedence and it needs more memory if the Block Ack session is setup. + + +Wi-Fi AMSDU +------------------------- + +ESP32 supports receiving AMSDU but doesn't support transmitting AMSDU. The transmitting AMSDU is not necessary since ESP32 has transmitting AMPDU. + +Wi-Fi Fragment +------------------------- + +ESP32 supports Wi-Fi receiving fragment, but doesn't support Wi-Fi transmitting fragment. The Wi-Fi transmitting fragment will be supported in future release. + +WPS Enrolle +------------------------- + +ESP32 supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Currently ESP32 supports WPS enrollee type PBC and PIN. + Wi-Fi Buffer Usage -------------------------- @@ -1499,7 +1772,7 @@ In order to get a robust, high-performance system, we need to consider the memor - the available memory in ESP32 is limited. - currently, the default type of buffer in LwIP and Wi-Fi drivers is "dynamic", **which means that both the LwIP and Wi-Fi share memory with the application**. Programmers should always keep this in mind; otherwise, they will face a memory issue, such as "running out of heap memory". - it is very dangerous to run out of heap memory, as this will cause ESP32 an "undefined behavior". Thus, enough heap memory should be reserved for the application, so that it never runs out of it. - - the Wi-Fi throughput heavily depends on memory-related configurations, such as the TCP window size, Wi-Fi RX/TX dynamic buffer number, etc. Refer to <`ESP32 Wi-Fi Throughput`_>. + - the Wi-Fi throughput heavily depends on memory-related configurations, such as the TCP window size, Wi-Fi RX/TX dynamic buffer number, etc. - the peak heap memory that the ESP32 LwIP/Wi-Fi may consume depends on a number of factors, such as the maximum TCP/UDP connections that the application may have, etc. - the total memory that the application requires is also an important factor when considering memory configuration. @@ -1545,9 +1818,6 @@ So, the peak memory that the Wi-Fi driver consumes can be calculated with the fo Generally, we do not need to care about the dynamic tx long buffers and dynamic tx long long buffers, because they are management frames which only have a small impact on the system. - - - Wi-Fi Menuconfig ----------------------- @@ -1571,17 +1841,17 @@ If you are going to modify the default number or type of buffer, it would be hel # labels of diagram nodes APPL_TASK [label="Application\n task", fontsize=12]; - LWIP_TASK [label="LwIP\n task", fontsize=12]; + LwIP_TASK [label="LwIP\n task", fontsize=12]; WIFI_TASK [label="Wi-Fi\n task", fontsize=12]; # labels of description nodes APPL_DESC [label="1> User data", width=120, height=25, shape=note, color=yellow]; - LWIP_DESC [label="2> Pbuf", width=120, height=25, shape=note, color=yellow]; + LwIP_DESC [label="2> Pbuf", width=120, height=25, shape=note, color=yellow]; WIFI_DESC [label="3> Dynamic (Static)\n TX Buffer", width=150, height=40, shape=note, color=yellow]; # node connections - APPL_TASK -> LWIP_TASK -> WIFI_TASK - APPL_DESC -> LWIP_DESC -> WIFI_DESC [style=none] + APPL_TASK -> LwIP_TASK -> WIFI_TASK + APPL_DESC -> LwIP_DESC -> WIFI_DESC [style=none] } @@ -1607,19 +1877,19 @@ The following diagram shows how buffer is allocated/freed in the RX direction: # labels of diagram nodes APPL_TASK [label="Application\n task", fontsize=12]; - LWIP_TASK [label="LwIP\n task", fontsize=12]; + LwIP_TASK [label="LwIP\n task", fontsize=12]; WIFI_TASK [label="Wi-Fi\n task", fontsize=12]; WIFI_INTR [label="Wi-Fi\n interrupt", fontsize=12]; # labels of description nodes APPL_DESC [label="4> User\n Data Buffer", height=40, shape=note, color=yellow]; - LWIP_DESC [label="3> Pbuf", height=40, shape=note, color=yellow]; + LwIP_DESC [label="3> Pbuf", height=40, shape=note, color=yellow]; WIFI_DESC [label="2> Dynamic\n RX Buffer", height=40, shape=note, color=yellow]; INTR_DESC [label="1> Static\n RX Buffer", height=40, shape=note, color=yellow]; # node connections - APPL_TASK <- LWIP_TASK <- WIFI_TASK <- WIFI_INTR - APPL_DESC <- LWIP_DESC <- WIFI_DESC <- INTR_DESC [style=none] + APPL_TASK <- LwIP_TASK <- WIFI_TASK <- WIFI_INTR + APPL_DESC <- LwIP_DESC <- WIFI_DESC <- INTR_DESC [style=none] } Description: @@ -1645,6 +1915,15 @@ The diagram shows the configuration of the Wi-Fi internal buffer. | | | | | 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' | @@ -1667,7 +1946,7 @@ The diagram shows the configuration of the Wi-Fi internal buffer. | | | | | The Dynamic and Static TX Buffers are | | | | | | mutually exclusive. | +------------------+------------+------------+--------------+---------------------------------------+ -| Static TX Buffer | Static | 32 * | Yes | This is a kind of DMA memory. It is | +| Static TX Buffer | Static | 16 * | Yes | This is a kind of DMA memory. It is | | | | 1600Bytes | | initialized in esp_wifi_init() and | | | | | | freed in esp_wifi_deinit(). | | | | | | When the upper-layer (LwIP) sends | @@ -1675,17 +1954,22 @@ The diagram shows the configuration of the Wi-Fi internal buffer. | | | | | 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 | Static | 16 | NO | Wi-Fi driver's internal buffer | +| Management Short | Dynamic | 8 | NO | Wi-Fi driver's internal buffer | | Buffer | | | | | +------------------+------------+------------+--------------+---------------------------------------+ | Management Long | Dynamic | 32 | NO | Wi-Fi driver's internal buffer | | Buffer | | | | | +------------------+------------+------------+--------------+---------------------------------------+ -| Mgmt Long Long | Dynamic | 32 | NO | Wi-Fi driver's internal buffer | -| Buffer | | | | | +| Management Long | Dynamic | 32 | NO | Wi-Fi driver's internal buffer | +| Long Buffer | | | | | +------------------+------------+------------+--------------+---------------------------------------+ @@ -1694,10 +1978,12 @@ Wi-Fi NVS Flash +++++++++++++++++++++ If the Wi-Fi NVS flash is enabled, all Wi-Fi configurations set via the Wi-Fi APIs will be stored into flash, and the Wi-Fi driver will start up with these configurations next time it powers on/reboots. However, the application can choose to disable the Wi-Fi NVS flash if it does not need to store the configurations into persistent memory, or has its own persistent storage, or simply due to debugging reasons, etc. -Wi-Fi AMPDU -+++++++++++++++++++++ -Generally, the AMPDU should be enabled, because it can greatly improve the Wi-Fi throughput. Disabling AMPDU is usually for debugging purposes. It may be removed from future releases. +Wi-Fi AMPDU ++++++++++++++++++++++++++++ +ESP32 supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput. + +Generally, the AMPDU should be enabled. Disabling AMPDU is usually for debugging purposes. Troubleshooting --------------- @@ -1708,4 +1994,4 @@ Please refer to a separate document with :doc:`wireshark-user-guide`. :hidden: wireshark-user-guide - \ No newline at end of file + diff --git a/examples/wifi/iperf/README.md b/examples/wifi/iperf/README.md index 18f94f9a6e..ce7247f051 100644 --- a/examples/wifi/iperf/README.md +++ b/examples/wifi/iperf/README.md @@ -1,9 +1,12 @@ # Iperf Example -## Note about 80Mhz flash frequency -The iperf can get better throughput if the SPI flash frequency is set to 80Mhz, but the system may crash in 80Mhz mode for ESP-WROVER-KIT V3. -Removing R140~R145 from the board can fix this issue. Currently the default SPI frequency is set to 40Mhz, if you want to change the SPI flash -frequency to 80Mhz, please make sure R140~R145 are removed from ESP-WROVER-KIT V3 or use ESP32 DevKitC. +## Note about iperf version +The iperf example doesn't support all features in standard iperf. It's compitable with iperf version 2.x. + +## Note about 80MHz flash frequency +The iperf can get better throughput if the SPI flash frequency is set to 80MHz, but the system may crash in 80MHz mode for ESP-WROVER-KIT. +Removing R140~R145 from the board can fix this issue. Currently the default SPI frequency is set to 40MHz, if you want to change the SPI flash +frequency to 80MHz, please make sure R140~R145 are removed from ESP-WROVER-KIT or use ESP32 DevKitC. ## Introduction This example implements the protocol used by the common performance measurement tool [iPerf](https://iperf.fr/).