1Wi-Fi Driver 2============= 3:link_to_translation:`zh_CN:[中文]` 4 5 6{IDF_TARGET_NAME} Wi-Fi Feature List 7------------------------------------ 8- Support Station-only mode, AP-only mode, Station/AP-coexistence mode 9- Support IEEE 802.11B, IEEE 802.11G, IEEE 802.11N and APIs to configure the protocol mode 10- Support WPA/WPA2/WPA3/WPA2-Enterprise and WPS 11- Support AMPDU, HT40, QoS and other key features 12- Support Modem-sleep 13- Support the Espressif-specific ESP-NOW protocol and Long Range mode, which supports up to **1 km** of data traffic 14- Up to 20 MBit/s TCP throughput and 30 MBit/s UDP throughput over the air 15- Support Sniffer 16- Support both fast scan and all-channel scan 17- Support multiple antennas 18- Support channel state information 19 20How To Write a Wi-Fi Application 21---------------------------------- 22 23Preparation 24+++++++++++ 25Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend you to select an :example:`example <wifi>`. 26 27Setting Wi-Fi Compile-time Options 28++++++++++++++++++++++++++++++++++++ 29Refer to `Wi-Fi Menuconfig`_. 30 31Init Wi-Fi 32+++++++++++ 33Refer to `{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_, `{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_. 34 35Start/Connect Wi-Fi 36++++++++++++++++++++ 37Refer to `{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_, `{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_. 38 39Event-Handling 40++++++++++++++ 41Generally, it is easy to write code in "sunny-day" scenarios, such as `WIFI_EVENT_STA_START`_, `WIFI_EVENT_STA_CONNECTED`_ etc. The hard part is to write routines in "rainy-day" scenarios, such as `WIFI_EVENT_STA_DISCONNECTED`_ etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to `{IDF_TARGET_NAME} Wi-Fi Event Description`_, `{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_, `{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_. See also :doc:`an overview of event handling in ESP-IDF<event-handling>`. 42 43Write Error-Recovery Routines Correctly at All Times 44++++++++++++++++++++++++++++++++++++++++++++++++++++ 45Just like the handling of "rainy-day" scenarios, a good error-recovery routine is also fundamental to robust Wi-Fi applications. Refer to `{IDF_TARGET_NAME} Wi-Fi API Error Code`_. 46 47 48{IDF_TARGET_NAME} Wi-Fi API Error Code 49-------------------------------------- 50All of the {IDF_TARGET_NAME} Wi-Fi APIs have well-defined return values, namely, the error code. The error code can be categorized into: 51 52 - No errors, e.g. ESP_OK means that the API returns successfully. 53 - Recoverable errors, such as ESP_ERR_NO_MEM, etc. 54 - Non-recoverable, non-critical errors. 55 - Non-recoverable, critical errors. 56 57Whether the error is critical or not depends on the API and the application scenario, and it is defined by the API user. 58 59**The primary principle to write a robust application with Wi-Fi API is to always check the error code and write the error-handling code.** Generally, the error-handling code can be used: 60 61 - for recoverable errors, in which case you can write a recoverable-error code. For example, when :cpp:func:`esp_wifi_start` returns ESP_ERR_NO_MEM, the recoverable-error code vTaskDelay can be called, in order to get a microseconds' delay for another try. 62 - for non-recoverable, yet non-critical, errors, in which case printing the error code is a good method for error handling. 63 - for non-recoverable, critical errors, in which case "assert" may be a good method for error handling. For example, if :cpp:func:`esp_wifi_set_mode` returns ESP_ERR_WIFI_NOT_INIT, it means that the Wi-Fi driver is not initialized by :cpp:func:`esp_wifi_init` successfully. You can detect this kind of error very quickly in the application development phase. 64 65In esp_err.h, ESP_ERROR_CHECK checks the return values. It is a rather commonplace error-handling code and can be used 66as the default error-handling code in the application development phase. However, we strongly recommend that API users write their own error-handling code. 67 68{IDF_TARGET_NAME} Wi-Fi API Parameter Initialization 69---------------------------------------------------- 70 71When initializing struct parameters for the API, one of two approaches should be followed: 72 73- explicitly set all fields of the parameter 74- use get API to get current configuration first, then set application specific fields 75 76Initializing 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. 77 78.. _wifi-programming-model: 79 80{IDF_TARGET_NAME} Wi-Fi Programming Model 81----------------------------------------- 82The {IDF_TARGET_NAME} Wi-Fi programming model is depicted as follows: 83 84.. blockdiag:: 85 :caption: Wi-Fi Programming Model 86 :align: center 87 88 blockdiag wifi-programming-model { 89 90 # global attributes 91 node_height = 60; 92 node_width = 100; 93 span_width = 100; 94 span_height = 60; 95 default_shape = roundedbox; 96 default_group_color = none; 97 98 # node labels 99 TCP_STACK [label="TCP\n stack", fontsize=12]; 100 EVNT_TASK [label="Event\n task", fontsize=12]; 101 APPL_TASK [label="Application\n task", width = 120, fontsize=12]; 102 WIFI_DRV [label="Wi-Fi\n Driver", width = 120, fontsize=12]; 103 KNOT [shape=none]; 104 105 # node connections + labels 106 TCP_STACK -> EVNT_TASK [label=event]; 107 EVNT_TASK -> APPL_TASK [label="callback\n or event"]; 108 109 # arrange nodes vertically 110 group { 111 label = "default handler"; 112 orientation = portrait; 113 EVNT_TASK <- WIFI_DRV [label=event]; 114 } 115 116 # intermediate node 117 group { 118 label = "user handler"; 119 orientation = portrait; 120 APPL_TASK -- KNOT; 121 } 122 WIFI_DRV <- KNOT [label="API\n call"]; 123 } 124 125 126The Wi-Fi driver can be considered a black box that knows nothing about high-layer code, such as the TCP/IP stack, application task, event task, etc. The application task (code) generally calls :doc:`Wi-Fi driver APIs <../api-reference/network/esp_wifi>` to initialize Wi-Fi and handles Wi-Fi events when necessary. Wi-Fi driver receives API calls, handles them, and post events to the application. 127 128Wi-Fi event handling is based on the :doc:`esp_event library <../api-reference/system/esp_event>`. Events are sent by the Wi-Fi driver to the :ref:`default event loop <esp-event-default-loops>`. Application may handle these events in callbacks registered using :cpp:func:`esp_event_handler_register`. Wi-Fi events are also handled by :doc:`esp_netif component <../api-reference/network/esp_netif>` to provide a set of default behaviors. For example, when Wi-Fi station connects to an AP, esp_netif will automatically start the DHCP client (by default). 129 130{IDF_TARGET_NAME} Wi-Fi Event Description 131----------------------------------------- 132 133WIFI_EVENT_WIFI_READY 134++++++++++++++++++++++++++++++++++++ 135The Wi-Fi driver will never generate this event, which, as a result, can be ignored by the application event callback. This event may be removed in future releases. 136 137WIFI_EVENT_SCAN_DONE 138++++++++++++++++++++++++++++++++++++ 139The scan-done event is triggered by :cpp:func:`esp_wifi_scan_start()` and will arise in the following scenarios: 140 141 - The scan is completed, e.g., the target AP is found successfully, or all channels have been scanned. 142 - The scan is stopped by :cpp:func:`esp_wifi_scan_stop()`. 143 - The :cpp:func:`esp_wifi_scan_start()` is called before the scan is completed. A new scan will override the current scan and a scan-done event will be generated. 144 145The scan-done event will not arise in the following scenarios: 146 147 - It is a blocked scan. 148 - The scan is caused by :cpp:func:`esp_wifi_connect()`. 149 150Upon receiving this event, the event task does nothing. The application event callback needs to call :cpp:func:`esp_wifi_scan_get_ap_num()` and :cpp:func:`esp_wifi_scan_get_ap_records()` to fetch the scanned AP list and trigger the Wi-Fi driver to free the internal memory which is allocated during the scan **(do not forget to do this!)**. 151Refer to `{IDF_TARGET_NAME} Wi-Fi Scan`_ for a more detailed description. 152 153WIFI_EVENT_STA_START 154++++++++++++++++++++++++++++++++++++ 155If :cpp:func:`esp_wifi_start()` returns ESP_OK and the current Wi-Fi mode is Station or AP+Station, then this event will arise. Upon receiving this event, the event task will initialize the LwIP network interface (netif). Generally, the application event callback needs to call :cpp:func:`esp_wifi_connect()` to connect to the configured AP. 156 157WIFI_EVENT_STA_STOP 158++++++++++++++++++++++++++++++++++++ 159If :cpp:func:`esp_wifi_stop()` returns ESP_OK and the current Wi-Fi mode is Station or AP+Station, then this event will arise. Upon receiving this event, the event task will release the station's IP address, stop the DHCP client, remove TCP/UDP-related connections and clear the LwIP station netif, etc. The application event callback generally does not need to do anything. 160 161WIFI_EVENT_STA_CONNECTED 162++++++++++++++++++++++++++++++++++++ 163If :cpp:func:`esp_wifi_connect()` returns ESP_OK and the station successfully connects to the target AP, the connection event will arise. Upon receiving this event, the event task starts the DHCP client and begins the DHCP process of getting the IP address. Then, the Wi-Fi driver is ready for sending and receiving data. This moment is good for beginning the application work, provided that the application does not depend on LwIP, namely the IP address. However, if the application is LwIP-based, then you need to wait until the *got ip* event comes in. 164 165WIFI_EVENT_STA_DISCONNECTED 166++++++++++++++++++++++++++++++++++++ 167This event can be generated in the following scenarios: 168 169 - When :cpp:func:`esp_wifi_disconnect()`, or :cpp:func:`esp_wifi_stop()`, or :cpp:func:`esp_wifi_deinit()` is called and the station is already connected to the AP. 170 - When :cpp:func:`esp_wifi_connect()` is called, but the Wi-Fi driver fails to set up a connection with the AP due to certain reasons, e.g. the scan fails to find the target AP, authentication times out, etc. If there are more than one AP with the same SSID, the disconnected event is raised after the station fails to connect all of the found APs. 171 - 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. 172 173Upon receiving this event, the default behavior of the event task is: 174 175- Shuts down the station's LwIP netif. 176- 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. 177 178The most common event handle code for this event in application is to call :cpp:func:`esp_wifi_connect()` to reconnect the Wi-Fi. However, if the event is raised because :cpp:func:`esp_wifi_disconnect()` is called, the application should not call :cpp:func:`esp_wifi_connect()` to reconnect. It's application's responsibility to distinguish whether the event is caused by :cpp:func:`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`_. 179 180Another 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: 181 182- The application creates a TCP connection to maintain the application-level keep-alive data that is sent out every 60 seconds. 183- Due to certain reasons, the Wi-Fi connection is cut off, and the `WIFI_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. 184- Five seconds later, the Wi-Fi connection is restored because :cpp:func:`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**. 185- 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. 186 187In above scenarios, 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. 188 189IP_EVENT_STA_GOT_IP 190++++++++++++++++++++++++++++++++++++ 191This 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). 192 193The IPV4 may be changed because of the following reasons: 194 195 - The DHCP client fails to renew/rebind the IPV4 address, and the station's IPV4 is reset to 0. 196 - The DHCP client rebinds to a different address. 197 - The static-configured IPV4 address is changed. 198 199Whether the IPV4 address is changed or NOT is indicated by field ``ip_change`` of ``ip_event_got_ip_t``. 200 201The 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. 202 203IP_EVENT_GOT_IP6 204++++++++++++++++++++++++++++++++++++ 205This event arises when the IPV6 SLAAC support auto-configures an address for the {IDF_TARGET_NAME}, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets). 206 207IP_STA_LOST_IP 208++++++++++++++++++++++++++++++++++++ 209This event arises when the IPV4 address become invalid. 210 211IP_STA_LOST_IP doesn't arise immediately after the Wi-Fi disconnects, instead it starts an IPV4 address lost timer, if the IPV4 address is got before ip lost timer expires, IP_EVENT_STA_LOST_IP doesn't happen. Otherwise, the event arises when IPV4 address lost timer expires. 212 213Generally 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. 214 215WIFI_EVENT_AP_START 216++++++++++++++++++++++++++++++++++++ 217Similar to `WIFI_EVENT_STA_START`_. 218 219WIFI_EVENT_AP_STOP 220++++++++++++++++++++++++++++++++++++ 221Similar to `WIFI_EVENT_STA_STOP`_. 222 223WIFI_EVENT_AP_STACONNECTED 224++++++++++++++++++++++++++++++++++++ 225Every time a station is connected to {IDF_TARGET_NAME} AP, the `WIFI_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. 226 227WIFI_EVENT_AP_STADISCONNECTED 228++++++++++++++++++++++++++++++++++++ 229This event can happen in the following scenarios: 230 231 - The application calls :cpp:func:`esp_wifi_disconnect()`, or esp_wifi_deauth_sta(), to manually disconnect the station. 232 - 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 time can be modified by :cpp:func:`esp_wifi_set_inactive_time`. 233 - The station kicks off the AP. 234 235When 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. 236 237WIFI_EVENT_AP_PROBEREQRECVED 238++++++++++++++++++++++++++++++++++++ 239 240This event is disabled by default. The application can enable it via API :cpp:func:`esp_wifi_set_event_mask()`. 241When this event is enabled, it will be raised each time the AP receives a probe request. 242 243{IDF_TARGET_NAME} Wi-Fi Station General Scenario 244------------------------------------------------ 245Below is a "big scenario" which describes some small scenarios in Station mode: 246 247.. seqdiag:: 248 :caption: Sample Wi-Fi Event Scenarios in Station Mode 249 :align: center 250 251 seqdiag sample-scenarios-station-mode { 252 activation = none; 253 node_width = 80; 254 node_height = 60; 255 edge_length = 140; 256 span_height = 5; 257 default_shape = roundedbox; 258 default_fontsize = 12; 259 260 MAIN_TASK [label = "Main\ntask"]; 261 APP_TASK [label = "App\ntask"]; 262 EVENT_TASK [label = "Event\ntask"]; 263 LwIP_TASK [label = "LwIP\ntask"]; 264 WIFI_TASK [label = "Wi-Fi\ntask"]; 265 266 === 1. Init Phase === 267 MAIN_TASK -> LwIP_TASK [label="1.1> Create / init LwIP"]; 268 MAIN_TASK -> EVENT_TASK [label="1.2> Create / init event"]; 269 MAIN_TASK -> WIFI_TASK [label="1.3> Create / init Wi-Fi"]; 270 MAIN_TASK -> APP_TASK [label="1.4> Create app task"]; 271 === 2. Configure Phase === 272 MAIN_TASK -> WIFI_TASK [label="2> Configure Wi-Fi"]; 273 === 3. Start Phase === 274 MAIN_TASK -> WIFI_TASK [label="3.1> Start Wi-Fi"]; 275 EVENT_TASK <- WIFI_TASK [label="3.2> WIFI_EVENT_STA_START"]; 276 APP_TASK <- EVENT_TASK [label="3.3> WIFI_EVENT_STA_START"]; 277 === 4. Connect Phase === 278 APP_TASK -> WIFI_TASK [label="4.1> Connect Wi-Fi"]; 279 EVENT_TASK <- WIFI_TASK [label="4.2> WIFI_EVENT_STA_CONNECTED"]; 280 APP_TASK <- EVENT_TASK [label="4.3> WIFI_EVENT_STA_CONNECTED"]; 281 === 5. Got IP Phase === 282 EVENT_TASK -> LwIP_TASK [label="5.1> Start DHCP client"]; 283 EVENT_TASK <- LwIP_TASK [label="5.2> IP_EVENT_STA_GOT_IP"]; 284 APP_TASK <- EVENT_TASK [label="5.3> IP_EVENT_STA_GOT_IP"]; 285 APP_TASK -> APP_TASK [label="5.4> socket related init"]; 286 === 6. Disconnect Phase === 287 EVENT_TASK <- WIFI_TASK [label="6.1> WIFI_EVENT_STA_DISCONNECTED"]; 288 APP_TASK <- EVENT_TASK [label="6.2> WIFI_EVENT_STA_DISCONNECTED"]; 289 APP_TASK -> APP_TASK [label="6.3> disconnect handling"]; 290 === 7. IP Change Phase === 291 EVENT_TASK <- LwIP_TASK [label="7.1> IP_EVENT_STA_GOT_IP"]; 292 APP_TASK <- EVENT_TASK [label="7.2> IP_EVENT_STA_GOT_IP"]; 293 APP_TASK -> APP_TASK [label="7.3> Socket error handling"]; 294 === 8. Deinit Phase === 295 APP_TASK -> WIFI_TASK [label="8.1> Disconnect Wi-Fi"]; 296 APP_TASK -> WIFI_TASK [label="8.2> Stop Wi-Fi"]; 297 APP_TASK -> WIFI_TASK [label="8.3> Deinit Wi-Fi"]; 298 } 299 300 3011. Wi-Fi/LwIP Init Phase 302++++++++++++++++++++++++++++++ 303 - s1.1: The main task calls :cpp:func:`esp_netif_init()` to create an LwIP core task and initialize LwIP-related work. 304 305 - s1.2: The main task calls :cpp:func:`esp_event_loop_create` to create a system Event task and initialize an application event's callback function. In the scenario above, the application event's callback function does nothing but relaying the event to the application task. 306 307 - s1.3: The main task calls :cpp:func:`esp_netif_create_default_wifi_ap()` or :cpp:func:`esp_netif_create_default_wifi_sta()` to create default network interface instance binding station or AP with TCP/IP stack. 308 309 - s1.4: The main task calls :cpp:func:`esp_wifi_init()` to create the Wi-Fi driver task and initialize the Wi-Fi driver. 310 311 - s1.5: The main task calls OS API to create the application task. 312 313Step 1.1 ~ 1.5 is a recommended sequence that initializes a Wi-Fi-/LwIP-based application. However, it is **NOT** a must-follow sequence, which means that you can create the application task in step 1.1 and put all other initializations in the application task. Moreover, you may not want to create the application task in the initialization phase if the application task depends on the sockets. Rather, you can defer the task creation until the IP is obtained. 314 3152. Wi-Fi Configuration Phase 316+++++++++++++++++++++++++++++++ 317Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is Station, so you may need to call :cpp:func:`esp_wifi_set_mode` (WIFI_MODE_STA) to configure the Wi-Fi mode as Station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to `{IDF_TARGET_NAME} Wi-Fi Configuration`_. 318 319Generally, we configure the Wi-Fi driver before setting up the Wi-Fi connection, but this is **NOT** mandatory, which means that you can configure the Wi-Fi connection anytime, provided that the Wi-Fi driver is initialized successfully. However, if the configuration does not need to change after the Wi-Fi connection is set up, you should configure the Wi-Fi driver at this stage, because the configuration APIs (such as :cpp:func:`esp_wifi_set_protocol`) will cause the Wi-Fi to reconnect, which may not be desirable. 320 321If the Wi-Fi NVS flash is enabled by menuconfig, all Wi-Fi configuration in this phase, or later phases, will be stored into flash. When the board powers on/reboots, you do not need to configure the Wi-Fi driver from scratch. You only need to call esp_wifi_get_xxx APIs to fetch the configuration stored in flash previously. You can also configure the Wi-Fi driver if the previous configuration is not what you want. 322 3233. Wi-Fi Start Phase 324++++++++++++++++++++++++++++++++ 325 - s3.1: Call :cpp:func:`esp_wifi_start()` to start the Wi-Fi driver. 326 - s3.2: The Wi-Fi driver posts `WIFI_EVENT_STA_START`_ to the event task; then, the event task will do some common things and will call the application event callback function. 327 - s3.3: The application event callback function relays the `WIFI_EVENT_STA_START`_ to the application task. We recommend that you call :cpp:func:`esp_wifi_connect()`. However, you can also call :cpp:func:`esp_wifi_connect()` in other phrases after the `WIFI_EVENT_STA_START`_ arises. 328 3294. Wi-Fi Connect Phase 330+++++++++++++++++++++++++++++++++ 331 - s4.1: Once :cpp:func:`esp_wifi_connect()` is called, the Wi-Fi driver will start the internal scan/connection process. 332 333 - s4.2: If the internal scan/connection process is successful, the `WIFI_EVENT_STA_CONNECTED`_ will be generated. In the event task, it starts the DHCP client, which will finally trigger the DHCP process. 334 335 - s4.3: In the above-mentioned scenario, the application event callback will relay the event to the application task. Generally, the application needs to do nothing, and you can do whatever you want, e.g., print a log, etc. 336 337In step 4.2, the Wi-Fi connection may fail because, for example, the password is wrong, the AP is not found, etc. In a case like this, `WIFI_EVENT_STA_DISCONNECTED`_ will arise and the reason for such a failure will be provided. For handling events that disrupt Wi-Fi connection, please refer to phase 6. 338 3395. Wi-Fi 'Got IP' Phase 340+++++++++++++++++++++++++++++++++ 341 342 - s5.1: Once the DHCP client is initialized in step 4.2, the *got IP* phase will begin. 343 - s5.2: If the IP address is successfully received from the DHCP server, then `IP_EVENT_STA_GOT_IP`_ will arise and the event task will perform common handling. 344 - s5.3: In the application event callback, `IP_EVENT_STA_GOT_IP`_ is relayed to the application task. For LwIP-based applications, this event is very special and means that everything is ready for the application to begin its tasks, e.g. creating the TCP/UDP socket, etc. A very common mistake is to initialize the socket before `IP_EVENT_STA_GOT_IP`_ is received. **DO NOT start the socket-related work before the IP is received.** 345 3466. Wi-Fi Disconnect Phase 347+++++++++++++++++++++++++++++++++ 348 - s6.1: When the Wi-Fi connection is disrupted, e.g. because the AP is powered off, the RSSI is poor, etc., `WIFI_EVENT_STA_DISCONNECTED`_ will arise. This event may also arise in phase 3. Here, the event task will notify the LwIP task to clear/remove all UDP/TCP connections. Then, all application sockets will be in a wrong status. In other words, no socket can work properly when this event happens. 349 - s6.2: In the scenario described above, the application event callback function relays `WIFI_EVENT_STA_DISCONNECTED`_ to the application task. We recommend that :cpp:func:`esp_wifi_connect()` be called to reconnect the Wi-Fi, close all sockets and re-create them if necessary. Refer to `WIFI_EVENT_STA_DISCONNECTED`_. 350 3517. Wi-Fi IP Change Phase 352++++++++++++++++++++++++++++++++++ 353 354 - s7.1: If the IP address is changed, the `IP_EVENT_STA_GOT_IP`_ will arise with "ip_change" set to true. 355 - s7.2: **This event is important to the application. When it occurs, the timing is good for closing all created sockets and recreating them.** 356 357 3588. Wi-Fi Deinit Phase 359++++++++++++++++++++++++++++ 360 361 - s8.1: Call :cpp:func:`esp_wifi_disconnect()` to disconnect the Wi-Fi connectivity. 362 - s8.2: Call :cpp:func:`esp_wifi_stop()` to stop the Wi-Fi driver. 363 - s8.3: Call :cpp:func:`esp_wifi_deinit()` to unload the Wi-Fi driver. 364 365 366{IDF_TARGET_NAME} Wi-Fi AP General Scenario 367--------------------------------------------- 368Below is a "big scenario" which describes some small scenarios in AP mode: 369 370 .. seqdiag:: 371 :caption: Sample Wi-Fi Event Scenarios in AP Mode 372 :align: center 373 374 seqdiag sample-scenarios-soft-ap-mode { 375 activation = none; 376 node_width = 80; 377 node_height = 60; 378 edge_length = 140; 379 span_height = 5; 380 default_shape = roundedbox; 381 default_fontsize = 12; 382 383 MAIN_TASK [label = "Main\ntask"]; 384 APP_TASK [label = "App\ntask"]; 385 EVENT_TASK [label = "Event\ntask"]; 386 LwIP_TASK [label = "LwIP\ntask"]; 387 WIFI_TASK [label = "Wi-Fi\ntask"]; 388 389 === 1. Init Phase === 390 MAIN_TASK -> LwIP_TASK [label="1.1> Create / init LwIP"]; 391 MAIN_TASK -> EVENT_TASK [label="1.2> Create / init event"]; 392 MAIN_TASK -> WIFI_TASK [label="1.3> Create / init Wi-Fi"]; 393 MAIN_TASK -> APP_TASK [label="1.4> Create app task"]; 394 === 2. Configure Phase === 395 MAIN_TASK -> WIFI_TASK [label="2> Configure Wi-Fi"]; 396 === 3. Start Phase === 397 MAIN_TASK -> WIFI_TASK [label="3.1> Start Wi-Fi"]; 398 EVENT_TASK <- WIFI_TASK [label="3.2> WIFI_EVENT_AP_START"]; 399 APP_TASK <- EVENT_TASK [label="3.3> WIFI_EVENT_AP_START"]; 400 === 4. Connect Phase === 401 EVENT_TASK <- WIFI_TASK [label="4.1> WIFI_EVENT_AP_STACONNECTED"]; 402 APP_TASK <- EVENT_TASK [label="4.2> WIFI_EVENT_AP_STACONNECTED"]; 403 === 5. Disconnect Phase === 404 EVENT_TASK <- WIFI_TASK [label="5.1> WIFI_EVENT_AP_STADISCONNECTED"]; 405 APP_TASK <- EVENT_TASK [label="5.2> WIFI_EVENT_AP_STADISCONNECTED"]; 406 APP_TASK -> APP_TASK [label="5.3> disconnect handling"]; 407 === 6. Deinit Phase === 408 APP_TASK -> WIFI_TASK [label="6.1> Disconnect Wi-Fi"]; 409 APP_TASK -> WIFI_TASK [label="6.2> Stop Wi-Fi"]; 410 APP_TASK -> WIFI_TASK [label="6.3> Deinit Wi-Fi"]; 411 } 412 413 414{IDF_TARGET_NAME} Wi-Fi Scan 415---------------------------- 416 417Currently, the :cpp:func:`esp_wifi_scan_start()` API is supported only in Station or Station+AP mode. 418 419Scan Type 420+++++++++++++++++++++++++ 421 422+------------------+--------------------------------------------------------------+ 423| Mode | Description | 424+==================+==============================================================+ 425| Active Scan | Scan by sending a probe request. | 426| | The default scan is an active scan. | 427| | | 428+------------------+--------------------------------------------------------------+ 429| Passive Scan | No probe request is sent out. Just switch to the specific | 430| | channel and wait for a beacon. | 431| | Application can enable it via the scan_type field of | 432| | wifi_scan_config_t. | 433| | | 434+------------------+--------------------------------------------------------------+ 435| Foreground Scan | This scan is applicable when there is no Wi-Fi connection | 436| | in Station mode. Foreground or background scanning is | 437| | controlled by the Wi-Fi driver and cannot be configured by | 438| | the application. | 439+------------------+--------------------------------------------------------------+ 440| Background Scan | This scan is applicable when there is a Wi-Fi connection in | 441| | Station mode or in Station+AP mode. | 442| | Whether it is a foreground scan or background scan depends on| 443| | the Wi-Fi driver and cannot be configured by the application.| 444| | | 445+------------------+--------------------------------------------------------------+ 446| All-Channel Scan | It scans all of the channels. | 447| | If the channel field of wifi_scan_config_t is set | 448| | to 0, it is an all-channel scan. | 449| | | 450+------------------+--------------------------------------------------------------+ 451| Specific Channel | It scans specific channels only. | 452| Scan | If the channel field of wifi_scan_config_t set to | 453| | 1, it is a specific-channel scan. | 454| | | 455+------------------+--------------------------------------------------------------+ 456 457The scan modes in above table can be combined arbitrarily, so we totally have 8 different scans: 458 459 - All-Channel Background Active Scan 460 - All-Channel Background Passive Scan 461 - All-Channel Foreground Active Scan 462 - All-Channel Foreground Passive Scan 463 - Specific-Channel Background Active Scan 464 - Specific-Channel Background Passive Scan 465 - Specific-Channel Foreground Active Scan 466 - Specific-Channel Foreground Passive Scan 467 468Scan Configuration 469+++++++++++++++++++++++++++++++++++++++ 470 471The scan type and other per-scan attributes are configured by :cpp:func:`esp_wifi_scan_start`. The table below provides a detailed description of wifi_scan_config_t. 472 473+------------------+--------------------------------------------------------------+ 474| Field | Description | 475+==================+==============================================================+ 476| ssid | If the SSID is not NULL, it is only the AP with the same | 477| | SSID that can be scanned. | 478| | | 479+------------------+--------------------------------------------------------------+ 480| bssid | If the BSSID is not NULL, it is only the AP with the same | 481| | BSSID that can be scanned. | 482| | | 483+------------------+--------------------------------------------------------------+ 484| channel | If "channel" is 0, there will be an all-channel scan; | 485| | otherwise, there will be a specific-channel scan. | 486| | | 487+------------------+--------------------------------------------------------------+ 488| show_hidden | If "show_hidden" is 0, the scan ignores the AP with a hidden | 489| | SSID; otherwise, the scan considers the hidden AP a normal | 490| | one. | 491+------------------+--------------------------------------------------------------+ 492| scan_type | If "scan_type" is WIFI_SCAN_TYPE_ACTIVE, the scan is | 493| | "active"; otherwise, it is a "passive" one. | 494| | | 495+------------------+--------------------------------------------------------------+ 496| scan_time | This field is used to control how long the scan dwells on | 497| | each channel. | 498| | | 499| | For passive scans, scan_time.passive designates the dwell | 500| | time for each channel. | 501| | | 502| | For active scans, dwell times for each channel are listed | 503| | in the table below. Here, min is short for scan | 504| | time.active.min and max is short for scan_time.active.max. | 505| | | 506| | - min=0, max=0: scan dwells on each channel for 120 ms. | 507| | - min>0, max=0: scan dwells on each channel for 120 ms. | 508| | - min=0, max>0: scan dwells on each channel for ``max`` ms. | 509| | - min>0, max>0: the minimum time the scan dwells on each | 510| | channel is ``min`` ms. If no AP is found during this time | 511| | frame, the scan switches to the next channel. Otherwise, | 512| | the scan dwells on the channel for ``max`` ms. | 513| | | 514| | If you want to improve the performance of the | 515| | the scan, you can try to modify these two parameters. | 516| | | 517+------------------+--------------------------------------------------------------+ 518 519There are also some global scan attributes which are configured by API :cpp:func:`esp_wifi_set_config`, refer to `Station Basic Configuration`_ 520 521Scan All APs on All Channels (Foreground) 522+++++++++++++++++++++++++++++++++++++++++++++ 523 524Scenario: 525 526.. seqdiag:: 527 :caption: Foreground Scan of all Wi-Fi Channels 528 :align: center 529 530 seqdiag foreground-scan-all-channels { 531 activation = none; 532 node_width = 80; 533 node_height = 60; 534 edge_length = 160; 535 span_height = 5; 536 default_shape = roundedbox; 537 default_fontsize = 12; 538 539 APP_TASK [label = "App\ntask"]; 540 EVENT_TASK [label = "Event\ntask"]; 541 WIFI_TASK [label = "Wi-Fi\ntask"]; 542 543 APP_TASK -> WIFI_TASK [label="1.1 > Configure country code"]; 544 APP_TASK -> WIFI_TASK [label="1.2 > Scan configuration"]; 545 WIFI_TASK -> WIFI_TASK [label="2.1 > Scan channel 1"]; 546 WIFI_TASK -> WIFI_TASK [label="2.2 > Scan channel 2"]; 547 WIFI_TASK -> WIFI_TASK [label="..."]; 548 WIFI_TASK -> WIFI_TASK [label="2.x > Scan channel N"]; 549 EVENT_TASK <- WIFI_TASK [label="3.1 > WIFI_EVENT_SCAN_DONE"]; 550 APP_TASK <- EVENT_TASK [label="3.2 > WIFI_EVENT_SCAN_DONE"]; 551 } 552 553 554The scenario above describes an all-channel, foreground scan. The foreground scan can only occur in Station mode where the station does not connect to any AP. Whether it is a foreground or background scan is totally determined by the Wi-Fi driver, and cannot be configured by the application. 555 556Detailed scenario description: 557 558Scan Configuration Phase 559************************** 560 561 - s1.1: Call :cpp:func:`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`_. 562 - s1.2: Call :cpp:func:`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. 563 564 565Wi-Fi Driver's Internal Scan Phase 566************************************** 567 568 - s2.1: The Wi-Fi driver switches to channel 1, in case the scan type is WIFI_SCAN_TYPE_ACTIVE, and broadcasts a probe request. Otherwise, the Wi-Fi will wait for a beacon from the APs. The Wi-Fi driver will stay in channel 1 for some time. The dwell time is configured in min/max time, with default value being 120 ms. 569 - s2.2: The Wi-Fi driver switches to channel 2 and performs the same operation as in step 2.1. 570 - s2.3: The Wi-Fi driver scans the last channel N, where N is determined by the country code which is configured in step 1.1. 571 572Scan-Done Event Handling Phase 573********************************* 574 575 - s3.1: When all channels are scanned, `WIFI_EVENT_SCAN_DONE`_ will arise. 576 - s3.2: The application's event callback function notifies the application task that `WIFI_EVENT_SCAN_DONE`_ is received. :cpp:func:`esp_wifi_scan_get_ap_num()` is called to get the number of APs that have been found in this scan. Then, it allocates enough entries and calls :cpp:func:`esp_wifi_scan_get_ap_records()` to get the AP records. Please note that the AP records in the Wi-Fi driver will be freed, once :cpp:func:`esp_wifi_scan_get_ap_records()` is called. Do not call :cpp:func:`esp_wifi_scan_get_ap_records()` twice for a single scan-done event. If :cpp:func:`esp_wifi_scan_get_ap_records()` is not called when the scan-done event occurs, the AP records allocated by the Wi-Fi driver will not be freed. So, make sure you call :cpp:func:`esp_wifi_scan_get_ap_records()`, yet only once. 577 578Scan All APs on All Channels (Background) 579++++++++++++++++++++++++++++++++++++++++++ 580Scenario: 581 582.. seqdiag:: 583 :caption: Background Scan of all Wi-Fi Channels 584 :align: center 585 586 seqdiag background-scan-all-channels { 587 activation = none; 588 node_width = 80; 589 node_height = 60; 590 edge_length = 160; 591 span_height = 5; 592 default_shape = roundedbox; 593 default_fontsize = 12; 594 595 APP_TASK [label = "App\ntask"]; 596 EVENT_TASK [label = "Event\ntask"]; 597 WIFI_TASK [label = "Wi-Fi\ntask"]; 598 599 APP_TASK -> WIFI_TASK [label="1.1 > Configure country code"]; 600 APP_TASK -> WIFI_TASK [label="1.2 > Scan configuration"]; 601 WIFI_TASK -> WIFI_TASK [label="2.1 > Scan channel 1"]; 602 WIFI_TASK -> WIFI_TASK [label="2.2 > Back to home channel H"]; 603 WIFI_TASK -> WIFI_TASK [label="2.3 > Scan channel 2"]; 604 WIFI_TASK -> WIFI_TASK [label="2.4 > Back to home channel H"]; 605 WIFI_TASK -> WIFI_TASK [label="..."]; 606 WIFI_TASK -> WIFI_TASK [label="2.x-1 > Scan channel N"]; 607 WIFI_TASK -> WIFI_TASK [label="2.x > Back to home channel H"]; 608 EVENT_TASK <- WIFI_TASK [label="3.1 > WIFI_EVENT_SCAN_DONE"]; 609 APP_TASK <- EVENT_TASK [label="3.2 > WIFI_EVENT_SCAN_DONE"]; 610 } 611 612The scenario above is an all-channel background scan. Compared to `Scan All APs on All Channels (Foreground)`_ , the difference in the all-channel background scan is that the Wi-Fi driver will scan the back-to-home channel for 30 ms before it switches to the next channel to give the Wi-Fi connection a chance to transmit/receive data. 613 614Scan for Specific AP on All Channels 615+++++++++++++++++++++++++++++++++++++++ 616Scenario: 617 618.. seqdiag:: 619 :caption: Scan of specific Wi-Fi Channels 620 :align: center 621 622 seqdiag scan-specific-channels { 623 activation = none; 624 node_width = 80; 625 node_height = 60; 626 edge_length = 160; 627 span_height = 5; 628 default_shape = roundedbox; 629 default_fontsize = 12; 630 631 APP_TASK [label = "App\ntask"]; 632 EVENT_TASK [label = "Event\ntask"]; 633 WIFI_TASK [label = "Wi-Fi\ntask"]; 634 635 APP_TASK -> WIFI_TASK [label="1.1 > Configure country code"]; 636 APP_TASK -> WIFI_TASK [label="1.2 > Scan configuration"]; 637 WIFI_TASK -> WIFI_TASK [label="2.1 > Scan channel C1"]; 638 WIFI_TASK -> WIFI_TASK [label="2.2 > Scan channel C2"]; 639 WIFI_TASK -> WIFI_TASK [label="..."]; 640 WIFI_TASK -> WIFI_TASK [label="2.x > Scan channel CN, or the AP is found"]; 641 EVENT_TASK <- WIFI_TASK [label="3.1 > WIFI_EVENT_SCAN_DONE"]; 642 APP_TASK <- EVENT_TASK [label="3.2 > WIFI_EVENT_SCAN_DONE"]; 643 } 644 645This scan is similar to `Scan All APs on All Channels (Foreground)`_. The differences are: 646 647 - s1.1: In step 1.2, the target AP will be configured to SSID/BSSID. 648 - 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. 649 650If 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`_. 651 652You can scan a specific AP, or all of them, in any given channel. These two scenarios are very similar. 653 654Scan in Wi-Fi Connect 655+++++++++++++++++++++++++ 656 657When :cpp:func:`esp_wifi_connect()` is called, the Wi-Fi driver will try to scan the configured AP first. The scan in "Wi-Fi Connect" is the same as `Scan for Specific AP On All Channels`_, except that no scan-done event will be generated when the scan is completed. If the target AP is found, the Wi-Fi driver will start the Wi-Fi connection; otherwise, `WIFI_EVENT_STA_DISCONNECTED`_ will be generated. Refer to `Scan for Specific AP On All Channels`_. 658 659Scan In Blocked Mode 660++++++++++++++++++++ 661 662If the block parameter of :cpp:func:`esp_wifi_scan_start()` is true, then the scan is a blocked one, and the application task will be blocked until the scan is done. The blocked scan is similar to an unblocked one, except that no scan-done event will arise when the blocked scan is completed. 663 664Parallel Scan 665+++++++++++++ 666Two application tasks may call :cpp:func:`esp_wifi_scan_start()` at the same time, or the same application task calls :cpp:func:`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 {IDF_TARGET_NAME}'s Wi-Fi functionality improves continuously. 667 668Scan When Wi-Fi is Connecting 669+++++++++++++++++++++++++++++++ 670 671The :cpp:func:`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. 672 673However, the retry/delay strategy may not work all the time. Considering following scenario: 674 675- 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 `WIFI_EVENT_STA_DISCONNECTED`_. 676- The application call :cpp:func:`esp_wifi_connect()` to do reconnection on receiving the disconnect event. 677- Another application task, e.g. the console task, call :cpp:func:`esp_wifi_scan_start()` to do scan, the scan always fails immediately because the station is keeping connecting. 678- When scan fails, the application simply delay sometime and retry the scan. 679 680In 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. 681 682- The application can choose to define a maximum continuous reconnect counter, stop reconnect once the reconnect reaches the max counter. 683- The application can choose to do reconnect immediately in the first N continous reconnect, then give a delay sometime and reconnect again. 684 685The application can define its own reconnect strategy to avoid the scan starve to death. Refer to <`Wi-Fi Reconnect`_>. 686 687{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario 688--------------------------------------------------- 689 690This 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 `{IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found`_. 691 692Generally, 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. 693 694Scenario: 695 696.. seqdiag:: 697 :caption: Wi-Fi Station Connecting Process 698 :align: center 699 700 seqdiag station-connecting-process { 701 activation = none; 702 node_width = 80; 703 node_height = 60; 704 edge_length = 160; 705 span_height = 5; 706 default_shape = roundedbox; 707 default_fontsize = 12; 708 709 EVENT_TASK [label = "Event\ntask"]; 710 WIFI_TASK [label = "Wi-Fi\ntask"]; 711 AP [label = "AP"]; 712 713 === 1. Scan Phase === 714 WIFI_TASK -> WIFI_TASK [label="1.1 > Scan"]; 715 EVENT_TASK <- WIFI_TASK [label="1.2 > WIFI_EVENT_STA_DISCONNECTED"]; 716 === 2. Auth Phase === 717 WIFI_TASK -> AP [label="2.1 > Auth request"]; 718 EVENT_TASK <- WIFI_TASK [label="2.2 > WIFI_EVENT_STA_DISCONNECTED"]; 719 WIFI_TASK <- AP [label="2.3 > Auth response"]; 720 EVENT_TASK <- WIFI_TASK [label="2.4 > WIFI_EVENT_STA_DISCONNECTED"]; 721 === 3. Assoc Phase === 722 WIFI_TASK -> AP [label="3.1 > Assoc request"]; 723 EVENT_TASK <- WIFI_TASK [label="3.2 > WIFI_EVENT_STA_DISCONNECTED"]; 724 WIFI_TASK <- AP [label="3.3 > Assoc response"]; 725 EVENT_TASK <- WIFI_TASK [label="3.4 > WIFI_EVENT_STA_DISCONNECTED"]; 726 === 4. 4-way Handshake Phase === 727 EVENT_TASK <- WIFI_TASK [label="4.1 > WIFI_EVENT_STA_DISCONNECTED"]; 728 WIFI_TASK <- AP [label="4.2 > 1/4 EAPOL"]; 729 WIFI_TASK -> AP [label="4.3 > 2/4 EAPOL"]; 730 EVENT_TASK <- WIFI_TASK [label="4.4 > WIFI_EVENT_STA_DISCONNECTED"]; 731 WIFI_TASK <- AP [label="4.5 > 3/4 EAPOL"]; 732 WIFI_TASK -> AP [label="4.6 > 4/4 EAPOL"]; 733 EVENT_TASK <- WIFI_TASK [label="4.7 > WIFI_EVENT_STA_CONNECTED"]; 734 } 735 736 737Scan Phase 738+++++++++++++++++++++ 739 740 - s1.1, The Wi-Fi driver begins scanning in "Wi-Fi Connect". Refer to `Scan in Wi-Fi Connect`_ for more details. 741 - s1.2, If the scan fails to find the target AP, `WIFI_EVENT_STA_DISCONNECTED`_ will arise and the reason-code will be WIFI_REASON_NO_AP_FOUND. Refer to `Wi-Fi Reason Code`_. 742 743Auth Phase 744+++++++++++++++++++++ 745 746 - s2.1, The authentication request packet is sent and the auth timer is enabled. 747 - s2.2, If the authentication response packet is not received before the authentication timer times out, `WIFI_EVENT_STA_DISCONNECTED`_ will arise and the reason-code will be WIFI_REASON_AUTH_EXPIRE. Refer to `Wi-Fi Reason Code`_. 748 - s2.3, The auth-response packet is received and the auth-timer is stopped. 749 - s2.4, The AP rejects authentication in the response and `WIFI_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`_. 750 751Association Phase 752+++++++++++++++++++++ 753 754 - s3.1, The association request is sent and the association timer is enabled. 755 - s3.2, If the association response is not received before the association timer times out, `WIFI_EVENT_STA_DISCONNECTED`_ will arise and the reason-code will be WIFI_REASON_ASSOC_EXPIRE. Refer to `Wi-Fi Reason Code`_. 756 - s3.3, The association response is received and the association timer is stopped. 757 - s3.4, The AP rejects the association in the response and `WIFI_EVENT_STA_DISCONNECTED`_ arises, while the reason-code is the one specified in the association response. Refer to `Wi-Fi Reason Code`_. 758 759 760Four-way Handshake Phase 761++++++++++++++++++++++++++ 762 763 - s4.1, The handshake timer is enabled, the 1/4 EAPOL is not received before the handshake timer expires, `WIFI_EVENT_STA_DISCONNECTED`_ will arise and the reason-code will be WIFI_REASON_HANDSHAKE_TIMEOUT. Refer to `Wi-Fi Reason Code`_. 764 - s4.2, The 1/4 EAPOL is received. 765 - s4.3, The STA replies 2/4 EAPOL. 766 - s4.4, If the 3/4 EAPOL is not received before the handshake timer expires, `WIFI_EVENT_STA_DISCONNECTED`_ will arise and the reason-code will be WIFI_REASON_HANDSHAKE_TIMEOUT. Refer to `Wi-Fi Reason Code`_. 767 - s4.5, The 3/4 EAPOL is received. 768 - s4.6, The STA replies 4/4 EAPOL. 769 - s4.7, The STA raises `WIFI_EVENT_STA_CONNECTED`_. 770 771 772Wi-Fi Reason Code 773+++++++++++++++++++++ 774 775The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first column is the macro name defined in esp_wifi_types.h. The common prefix *WIFI_REASON* is removed, which means that *UNSPECIFIED* actually stands for *WIFI_REASON_UNSPECIFIED* and so on. The second column is the value of the reason. The third column is the standard value to which this reason is mapped in section 8.4.1.7 of IEEE 802.11-2012. (For more information, refer to the standard mentioned above.) The last column is a description of the reason. 776 777+---------------------------+-------+---------+-------------------------------------------------------------+ 778| Reason code | Value |Mapped To| Description | 779+===========================+=======+=========+=============================================================+ 780| UNSPECIFIED | 1 | 1 | Generally, it means an internal failure, e.g., the memory | 781| | | | runs out, the internal TX fails, or the reason is received | 782| | | | from the remote side, etc. | 783+---------------------------+-------+---------+-------------------------------------------------------------+ 784| AUTH_EXPIRE | 2 | 2 | The previous authentication is no longer valid. | 785| | | | | 786| | | | For the ESP Station, this reason is reported when: | 787| | | | | 788| | | | - auth is timed out. | 789| | | | - the reason is received from the AP. | 790| | | | | 791| | | | For the ESP AP, this reason is reported when: | 792| | | | | 793| | | | - the AP has not received any packets from the station | 794| | | | in the past five minutes. | 795| | | | - the AP is stopped by calling :cpp:func:`esp_wifi_stop()`.| 796| | | | - the station is de-authed by calling | 797| | | | :cpp:func:`esp_wifi_deauth_sta()`. | 798+---------------------------+-------+---------+-------------------------------------------------------------+ 799| AUTH_LEAVE | 3 | 3 | De-authenticated, because the sending STA is | 800| | | | leaving (or has left). | 801| | | | | 802| | | | For the ESP Station, this reason is reported when: | 803| | | | | 804| | | | - it is received from the AP. | 805| | | | | 806+---------------------------+-------+---------+-------------------------------------------------------------+ 807| ASSOC_EXPIRE | 4 | 4 | Disassociated due to inactivity. | 808| | | | | 809| | | | For the ESP Station, this reason is reported when: | 810| | | | | 811| | | | - it is received from the AP. | 812| | | | | 813| | | | For the ESP AP, this reason is reported when: | 814| | | | | 815| | | | - the AP has not received any packets from the | 816| | | | station in the past five minutes. | 817| | | | - the AP is stopped by calling :cpp:func:`esp_wifi_stop()` | 818| | | | - the station is de-authed by calling | 819| | | | :cpp:func:`esp_wifi_deauth_sta()` | 820+---------------------------+-------+---------+-------------------------------------------------------------+ 821| ASSOC_TOOMANY | 5 | 5 | Disassociated, because the AP is unable to handle | 822| | | | all currently associated STAs at the same time. | 823| | | | | 824| | | | For the ESP Station, this reason is reported when: | 825| | | | | 826| | | | - it is received from the AP. | 827| | | | | 828| | | | For the ESP AP, this reason is reported when: | 829| | | | | 830| | | | - the stations associated with the AP reach the | 831| | | | maximum number that the AP can support. | 832| | | | | 833+---------------------------+-------+---------+-------------------------------------------------------------+ 834| NOT_AUTHED | 6 | 6 | Class-2 frame received from a non-authenticated STA. | 835| | | | | 836| | | | For the ESP Station, this reason is reported when: | 837| | | | | 838| | | | - it is received from the AP. | 839| | | | | 840| | | | For the ESP AP, this reason is reported when: | 841| | | | | 842| | | | - the AP receives a packet with data from a | 843| | | | non-authenticated station. | 844| | | | | 845+---------------------------+-------+---------+-------------------------------------------------------------+ 846| NOT_ASSOCED | 7 | 7 | Class-3 frame received from a non-associated STA. | 847| | | | | 848| | | | For the ESP Station, this reason is reported when: | 849| | | | | 850| | | | - it is received from the AP. | 851| | | | | 852| | | | For the ESP AP, this reason is reported when: | 853| | | | | 854| | | | - the AP receives a packet with data from a | 855| | | | non-associated station. | 856| | | | | 857+---------------------------+-------+---------+-------------------------------------------------------------+ 858| ASSOC_LEAVE | 8 | 8 | Disassociated, because the sending STA is leaving (or has | 859| | | | left) BSS. | 860| | | | | 861| | | | For the ESP Station, this reason is reported when: | 862| | | | | 863| | | | - it is received from the AP. | 864| | | | - the station is disconnected by | 865| | | | :cpp:func:`esp_wifi_disconnect()` and other APIs. | 866| | | | | 867+---------------------------+-------+---------+-------------------------------------------------------------+ 868| ASSOC_NOT_AUTHED | 9 | 9 | STA requesting (re)association is not authenticated by the | 869| | | | responding STA. | 870| | | | | 871| | | | For the ESP Station, this reason is reported when: | 872| | | | | 873| | | | - it is received from the AP. | 874| | | | | 875| | | | For the ESP AP, this reason is reported when: | 876| | | | | 877| | | | - the AP receives packets with data from an | 878| | | | associated, yet not authenticated, station. | 879| | | | | 880+---------------------------+-------+---------+-------------------------------------------------------------+ 881| DISASSOC_PWRCAP_BAD | 10 | 10 | Disassociated, because the information in the Power | 882| | | | Capability element is unacceptable. | 883| | | | | 884| | | | For the ESP Station, this reason is reported when: | 885| | | | | 886| | | | - it is received from the AP. | 887| | | | | 888+---------------------------+-------+---------+-------------------------------------------------------------+ 889| DISASSOC_SUPCHAN_BAD | 11 | 11 | Disassociated, because the information in the Supported | 890| | | | Channels element is unacceptable. | 891| | | | | 892| | | | For the ESP Station, this reason is reported when: | 893| | | | | 894| | | | - it is received from the AP. | 895| | | | | 896+---------------------------+-------+---------+-------------------------------------------------------------+ 897| IE_INVALID | 13 | 13 | Invalid element, i.e. an element whose content does not meet| 898| | | | the specifications of the Standard in frame formats clause. | 899| | | | | 900| | | | For the ESP Station, this reason is reported when: | 901| | | | | 902| | | | - it is received from the AP. | 903| | | | | 904| | | | For the ESP AP, this reason is reported when: | 905| | | | | 906| | | | - the AP parses a wrong WPA or RSN IE. | 907| | | | | 908+---------------------------+-------+---------+-------------------------------------------------------------+ 909| MIC_FAILURE | 14 | 14 | Message integrity code (MIC) failure. | 910| | | | | 911| | | | For the ESP Station, this reason is reported when: | 912| | | | | 913| | | | - it is received from the AP. | 914| | | | | 915+---------------------------+-------+---------+-------------------------------------------------------------+ 916| 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, in ESP | 917| | | | this reason-code is replaced with | 918| | | | WIFI_REASON_HANDSHAKE_TIMEOUT. | 919| | | | | 920| | | | For the ESP Station, this reason is reported when: | 921| | | | | 922| | | | - the handshake times out. | 923| | | | - it is received from the AP. | 924| | | | | 925+---------------------------+-------+---------+-------------------------------------------------------------+ 926| GROUP_KEY_UPDATE_TIMEOUT | 16 | 16 | Group-Key Handshake times out. | 927| | | | | 928| | | | For the ESP station, this reason is reported when: | 929| | | | | 930| | | | - it is received from the AP. | 931| | | | | 932+---------------------------+-------+---------+-------------------------------------------------------------+ 933| IE_IN_4WAY_DIFFERS | 17 | 17 | The element in the four-way handshake is different from the | 934| | | | (Re-)Association Request/Probe and Response/Beacon frame. | 935| | | | | 936| | | | For the ESP station, this reason is reported when: | 937| | | | | 938| | | | - it is received from the AP. | 939| | | | - the station finds that the four-way handshake IE differs | 940| | | | from the IE in the (Re-)Association Request/Probe and | 941| | | | Response/Beacon frame. | 942| | | | | 943+---------------------------+-------+---------+-------------------------------------------------------------+ 944| GROUP_CIPHER_INVALID | 18 | 18 | Invalid group cipher. | 945| | | | | 946| | | | For the ESP Station, this reason is reported when: | 947| | | | | 948| | | | - it is received from the AP. | 949| | | | | 950+---------------------------+-------+---------+-------------------------------------------------------------+ 951| PAIRWISE_CIPHER_INVALID | 19 | 19 | Invalid pairwise cipher. | 952| | | | | 953| | | | For the ESP Station, this reason is reported when: | 954| | | | | 955| | | | - it is received from the AP. | 956| | | | | 957+---------------------------+-------+---------+-------------------------------------------------------------+ 958| AKMP_INVALID | 20 | 20 | Invalid AKMP. | 959| | | | | 960| | | | For the ESP Station, this reason is reported when: | 961| | | | | 962| | | | - it is received from the AP. | 963| | | | | 964+---------------------------+-------+---------+-------------------------------------------------------------+ 965| UNSUPP_RSN_IE_VERSION | 21 | 21 | Unsupported RSNE version. | 966| | | | | 967| | | | For the ESP Station, this reason is reported when: | 968| | | | | 969| | | | - it is received from the AP. | 970| | | | | 971+---------------------------+-------+---------+-------------------------------------------------------------+ 972| INVALID_RSN_IE_CAP | 22 | 22 | Invalid RSNE capabilities. | 973| | | | | 974| | | | For the ESP Station, this reason is reported when: | 975| | | | | 976| | | | - it is received from the AP. | 977| | | | | 978+---------------------------+-------+---------+-------------------------------------------------------------+ 979| 802_1X_AUTH_FAILED | 23 | 23 | IEEE 802.1X. authentication failed. | 980| | | | | 981| | | | For the ESP Station, this reason is reported when: | 982| | | | | 983| | | | - it is received from the AP. | 984| | | | | 985| | | | For the ESP AP, this reason is reported when: | 986| | | | | 987| | | | - 802.1 x authentication fails. | 988| | | | | 989+---------------------------+-------+---------+-------------------------------------------------------------+ 990| CIPHER_SUITE_REJECTED | 24 | 24 | Cipher suite rejected due to security policies. | 991| | | | | 992| | | | For the ESP Station, this reason is reported when: | 993| | | | | 994| | | | - it is received from the AP. | 995| | | | | 996+---------------------------+-------+---------+-------------------------------------------------------------+ 997| BEACON_TIMEOUT | 200 |reserved | Espressif-specific Wi-Fi reason-code: when the station | 998| | | | loses N beacons continuously, it will disrupt the connection| 999| | | | and report this reason. | 1000| | | | | 1001+---------------------------+-------+---------+-------------------------------------------------------------+ 1002| NO_AP_FOUND | 201 |reserved | Espressif-specific Wi-Fi reason-code: when the station | 1003| | | | fails to scan the target AP, this reason code will be | 1004| | | | reported. | 1005+---------------------------+-------+---------+-------------------------------------------------------------+ 1006| AUTH_FAIL | 202 |reserved | Espressif-specific Wi-Fi reason-code: the | 1007| | | | authentication fails, but not because of a timeout. | 1008| | | | | 1009+---------------------------+-------+---------+-------------------------------------------------------------+ 1010| ASSOC_FAIL | 203 |reserved | Espressif-specific Wi-Fi reason-code: the association | 1011| | | | fails, but not because of ASSOC_EXPIRE or ASSOC_TOOMANY. | 1012| | | | | 1013+---------------------------+-------+---------+-------------------------------------------------------------+ 1014| HANDSHAKE_TIMEOUT | 204 |reserved | Espressif-specific Wi-Fi reason-code: the | 1015| | | | handshake fails for the same reason as that in | 1016| | | | WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT. | 1017| | | | | 1018+---------------------------+-------+---------+-------------------------------------------------------------+ 1019| CONNECTION_FAIL | 205 |reserved | Espressif-specific Wi-Fi reason-code: the | 1020| | | | connection to the AP has failed. | 1021| | | | | 1022+---------------------------+-------+---------+-------------------------------------------------------------+ 1023 1024{IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found 1025---------------------------------------------------------------------- 1026 1027This scenario is similar as `{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario`_, the difference is the station will not raise the event `WIFI_EVENT_STA_DISCONNECTED`_ unless it fails to connect all of the found APs. 1028 1029 1030Wi-Fi Reconnect 1031--------------------------- 1032 1033The 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 :cpp:func:`esp_wifi_connect()` on receiving event `WIFI_EVENT_STA_DISCONNECTED`_. 1034 1035Sometimes the application needs more complex reconnect strategy: 1036 1037- If the disconnect event is raised because the :cpp:func:`esp_wifi_disconnect()` is called, the application may not want to do reconnect. 1038- If the :cpp:func:`esp_wifi_scan_start()` may be called at anytime, a better reconnect strategy is necessary, refer to `Scan When Wi-Fi is Connecting`_. 1039 1040Another 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. 1041 1042Wi-Fi Beacon Timeout 1043--------------------------- 1044 1045The beacon timeout mechanism is used by {IDF_TARGET_NAME} 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. 1046 1047After the beacon timeout happens, the station sends 5 probe requests to AP, it disconnects the AP and raises the event `WIFI_EVENT_STA_DISCONNECTED`_ if still no probe response or beacon is received from AP. 1048 1049{IDF_TARGET_NAME} Wi-Fi Configuration 1050------------------------------------- 1051 1052All configurations will be stored into flash when the Wi-Fi NVS is enabled; otherwise, refer to `Wi-Fi NVS Flash`_. 1053 1054Wi-Fi Mode 1055+++++++++++++++++++++++++ 1056Call :cpp:func:`esp_wifi_set_mode()` to set the Wi-Fi mode. 1057 1058+------------------+--------------------------------------------------------------+ 1059| Mode | Description | 1060+==================+==============================================================+ 1061| WIFI_MODE_NULL | NULL mode: in this mode, the internal data struct is not | 1062| | allocated to the station and the AP, while both the | 1063| | station and AP interfaces are not initialized for | 1064| | RX/TX Wi-Fi data. Generally, this mode is used for Sniffer, | 1065| | or when you only want to stop both the STA and the AP | 1066| | without calling :cpp:func:`esp_wifi_deinit()` to unload the | 1067| | whole Wi-Fi driver. | 1068+------------------+--------------------------------------------------------------+ 1069| WIFI_MODE_STA | Station mode: in this mode, :cpp:func:`esp_wifi_start()` will| 1070| | init the internal station data, while the station's interface| 1071| | is ready for the RX and TX Wi-Fi data. After | 1072| | :cpp:func:`esp_wifi_connect()` is called, the STA will | 1073| | connect to the target target AP. | 1074+------------------+--------------------------------------------------------------+ 1075| WIFI_MODE_AP | AP mode: in this mode, :cpp:func:`esp_wifi_start()` will init| 1076| | the internal AP data, while the AP's interface is ready | 1077| | for RX/TX Wi-Fi data. Then, the Wi-Fi driver starts broad- | 1078| | casting beacons, and the AP is ready to get connected | 1079| | to other stations. | 1080+------------------+--------------------------------------------------------------+ 1081| WIFI_MODE_APSTA | Station-AP coexistence mode: in this mode, | 1082| | :cpp:func:`esp_wifi_start()` will simultaneously init both | 1083| | the station and the AP.This is done in station mode and AP | 1084| | mode. Please note that the channel of the external AP, which | 1085| | the ESP Station is connected to, has higher priority over the| 1086| | ESP AP channel. | 1087+------------------+--------------------------------------------------------------+ 1088 1089Station Basic Configuration 1090+++++++++++++++++++++++++++++++++++++ 1091 1092API esp_wifi_set_config() can be used to configure the station. The table below describes the fields in detail. 1093 1094+------------------+--------------------------------------------------------------+ 1095| Field | Description | 1096+==================+==============================================================+ 1097| ssid | This is the SSID of the target AP, to which the station wants| 1098| | to connect to. | 1099| | | 1100+------------------+--------------------------------------------------------------+ 1101| password | Password of the target AP. | 1102| | | 1103+------------------+--------------------------------------------------------------+ 1104| scan_method | For WIFI_FAST_SCAN scan, the scan ends when the first matched| 1105| | AP is found, for WIFI_ALL_CHANNEL_SCAN, the scan finds all | 1106| | matched APs on all channels. | 1107| | The default scan is WIFI_FAST_SCAN. | 1108+------------------+--------------------------------------------------------------+ 1109| bssid_set | If bssid_set is 0, the station connects to the AP whose SSID | 1110| | is the same as the field "ssid", while the field "bssid" | 1111| | is ignored. In all other cases, the station connects to | 1112| | the AP whose SSID is the same as the "ssid" field, while its | 1113| | BSSID is the same the "bssid" field . | 1114+------------------+--------------------------------------------------------------+ 1115| bssid | This is valid only when bssid_set is 1; see field | 1116| | "bssid_set". | 1117+------------------+--------------------------------------------------------------+ 1118| channel | If the channel is 0, the station scans the channel 1 ~ N to | 1119| | search for the target AP; otherwise, the station starts by | 1120| | scanning the channel whose value is the same as that of the | 1121| | "channel" field, and then scans others to find the target AP.| 1122| | If you do not know which channel the target AP is running on,| 1123| | set it to 0. | 1124+------------------+--------------------------------------------------------------+ 1125| sort_method | This field is only for WIFI_ALL_CHANNEL_SCAN | 1126| | | 1127| | If the sort_method is WIFI_CONNECT_AP_BY_SIGNAL, all matched | 1128| | APs are sorted by signal, for AP with best signal will be | 1129| | connected firstly. E.g. if the station want to connect AP | 1130| | whose ssid is "apxx", the scan finds two AP whose ssid equals| 1131| | to "apxx", the first AP's signal is -90 dBm, the second AP's | 1132| | signal is -30 dBm, the station connects the second AP | 1133| | firstly, it doesn't connect the first one unless it fails to | 1134| | connect the second one. | 1135| | | 1136| | If the sort_method is WIFI_CONNECT_AP_BY_SECURITY, all | 1137| | matched APs are sorted by security. E.g. if the station wants| 1138| | to connect AP whose ssid is "apxx", the scan finds two AP | 1139| | whose ssid is "apxx", the security of the first found AP is | 1140| | open while the second one is WPA2, the stations connects to | 1141| | the second AP firstly, it doesn't connect the second one | 1142| | unless it fails to connect the first one. | 1143+------------------+--------------------------------------------------------------+ 1144| threshold | The threshold is used to filter the found AP, if the RSSI or | 1145| | security mode is less than the configured threshold, the AP | 1146| | will be discard. | 1147| | | 1148| | If the RSSI set to 0, it means default threshold, the default| 1149| | RSSI threshold is -127 dBm. If the authmode threshold is set | 1150| | to 0, it means default threshold, the default authmode | 1151| | threshold is open. | 1152+------------------+--------------------------------------------------------------+ 1153 1154.. attention:: 1155 WEP/WPA security modes are deprecated in IEEE 802.11-2016 specifications and are recommended not to be used. These modes can be rejected using authmode threshold by setting threshold as WPA2 by threshold.authmode as WIFI_AUTH_WPA2_PSK. 1156 1157AP Basic Configuration 1158+++++++++++++++++++++++++++++++++++++ 1159 1160API esp_wifi_set_config() can be used to configure the AP. The table below describes the fields in detail. 1161 1162+------------------+--------------------------------------------------------------+ 1163| Field | Description | 1164+==================+==============================================================+ 1165| ssid | SSID of AP; if the ssid[0] is 0xFF and ssid[1] is 0xFF, | 1166| | the AP defaults the SSID to ESP_aabbcc, where "aabbcc" | 1167| | is the last three bytes of the AP MAC. | 1168| | | 1169+------------------+--------------------------------------------------------------+ 1170| password | Password of AP; if the auth mode is WIFI_AUTH_OPEN, | 1171| | this field will be ignored. | 1172| | | 1173+------------------+--------------------------------------------------------------+ 1174| ssid_len | Length of SSID; if ssid_len is 0, check the SSID until there | 1175| | is a termination character. If ssid_len > 32, change it to | 1176| | 32; otherwise, set the SSID length according to ssid_len. | 1177| | | 1178+------------------+--------------------------------------------------------------+ 1179| channel | Channel of AP; if the channel is out of range, the Wi-Fi | 1180| | driver defaults the channel to channel 1. So, please make | 1181| | sure the channel is within the required range. | 1182| | For more details, refer to `Wi-Fi Country Code`_. | 1183+------------------+--------------------------------------------------------------+ 1184| authmode | Auth mode of ESP AP; currently, ESP Wi-Fi does not | 1185| | support AUTH_WEP. If the authmode is an invalid value, | 1186| | AP defaults the value to WIFI_AUTH_OPEN. | 1187| | | 1188+------------------+--------------------------------------------------------------+ 1189| ssid_hidden | If ssid_hidden is 1, AP does not broadcast the SSID; | 1190| | otherwise, it does broadcast the SSID. | 1191| | | 1192+------------------+--------------------------------------------------------------+ 1193| max_connection | Currently, ESP Wi-Fi supports up to 10 Wi-Fi connections. | 1194| | If max_connection > 10, AP defaults the value to 10. | 1195| | | 1196+------------------+--------------------------------------------------------------+ 1197| beacon_interval | Beacon interval; the value is 100 ~ 60000 ms, with default | 1198| | value being 100 ms. If the value is out of range, | 1199| | AP defaults it to 100 ms. | 1200+------------------+--------------------------------------------------------------+ 1201 1202Wi-Fi Protocol Mode 1203+++++++++++++++++++++++++ 1204 1205Currently, the IDF supports the following protocol modes: 1206 1207+--------------------+------------------------------------------------------------+ 1208| Protocol Mode | Description | 1209+====================+============================================================+ 1210| 802.11 B | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B) to set | 1211| | the station/AP to 802.11B-only mode. | 1212| | | 1213+--------------------+------------------------------------------------------------+ 1214| 802.11 BG | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_ | 1215| | PROTOCOL_11G) to set the station/AP to 802.11BG mode. | 1216| | | 1217+--------------------+------------------------------------------------------------+ 1218| 802.11 BGN | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| | 1219| | WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) to set the station/ | 1220| | AP to BGN mode. | 1221| | | 1222+--------------------+------------------------------------------------------------+ 1223| 802.11 BGNLR | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| | 1224| | WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR) | 1225| | to set the station/AP to BGN and the | 1226| | Espressif-specific mode. | 1227+--------------------+------------------------------------------------------------+ 1228| 802.11 LR | Call esp_wifi_set_protocol (ifx, WIFI_PROTOCOL_LR) to set | 1229| | the station/AP only to the Espressif-specific mode. | 1230| | | 1231| | **This mode is an Espressif-patented mode which can achieve| 1232| | a one-kilometer line of sight range. Please, make sure both| 1233| | the station and the AP are connected to an | 1234| | ESP device** | 1235+--------------------+------------------------------------------------------------+ 1236 1237Long Range (LR) 1238+++++++++++++++++++++++++ 1239 1240Long 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. 1241 1242LR Compatibility 1243************************* 1244 1245Since LR is Espressif unique Wi-Fi mode, only {IDF_TARGET_NAME} devices can transmit and receive the LR data. In other words, the {IDF_TARGET_NAME} device should NOT transmit the data in LR data rate if the connected device doesn't support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the {IDF_TARGET_NAME} may transmit data in LR rate, otherwise, {IDF_TARGET_NAME} will transmit all data in traditional Wi-Fi data rate. 1246 1247Following table depicts the Wi-Fi mode negotiation: 1248 1249+-------+-----+----+---+-------+------+-----+----+ 1250|AP\STA | BGN | BG | B | BGNLR | BGLR | BLR | LR | 1251+=======+=====+====+===+=======+======+=====+====+ 1252| BGN | BGN | BG | B | BGN | BG | B | - | 1253+-------+-----+----+---+-------+------+-----+----+ 1254| BG | BG | BG | B | BG | BG | B | - | 1255+-------+-----+----+---+-------+------+-----+----+ 1256| B | B | B | B | B | B | B | - | 1257+-------+-----+----+---+-------+------+-----+----+ 1258| BGNLR | - | - | - | BGNLR | BGLR | BLR | LR | 1259+-------+-----+----+---+-------+------+-----+----+ 1260| BGLR | - | - | - | BGLR | BGLR | BLR | LR | 1261+-------+-----+----+---+-------+------+-----+----+ 1262| BLR | - | - | - | BLR | BLR | BLR | LR | 1263+-------+-----+----+---+-------+------+-----+----+ 1264| LR | - | - | - | LR | LR | LR | LR | 1265+-------+-----+----+---+-------+------+-----+----+ 1266 1267In 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. 1268 1269According to the table, we can conclude that: 1270 1271 - For LR enabled in {IDF_TARGET_NAME} AP, it's incompatible with traditional 802.11 mode because the beacon is sent in LR mode. 1272 - For LR enabled in {IDF_TARGET_NAME} station and the mode is NOT LR only mode, it's compatible with traditional 802.11 mode. 1273 - If both station and AP are {IDF_TARGET_NAME} devices and both of them enable LR mode, the negotiated mode supports LR. 1274 1275If the negotiated Wi-Fi mode supports both traditional 802.11 mode and LR mode, it's the Wi-Fi 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. 1276 1277LR Impacts to Traditional Wi-Fi device 1278*************************************** 1279 1280The data transmission in LR rate has no impacts on the traditional Wi-Fi device because: 1281 1282 - The CCA and backoff process in LR mode are consistent with 802.11 specification. 1283 - The traditional Wi-Fi device can detect the LR signal via CCA and do backoff. 1284 1285In other words, the impact transmission in LR mode is similar as the impact in 802.11B mode. 1286 1287LR Transmission Distance 1288************************* 1289 1290The reception sensitivity of LR has about 4 dB gain than the traditional 802.11B mode, theoretically the transmission distance is about 2 to 2.5 times the distance of 11B. 1291 1292LR Throughput 1293************************* 1294 1295The LR rate has very limited throughput because the raw PHY data rate LR is 1/2 Mbits and 1/4 Mbits. 1296 1297When to Use LR 1298************************* 1299 1300The general conditions for using LR are: 1301 1302 - Both the AP and station are devices. 1303 - Long distance Wi-Fi connection and data transmission is required. 1304 - Data throughput requirements are very small, such as remote device control, etc. 1305 1306Wi-Fi Country Code 1307+++++++++++++++++++++++++ 1308 1309Call :cpp:func:`esp_wifi_set_country()` to set the country info. 1310The table below describes the fields in detail, please consult local 2.4 GHz RF operating regulations before configuring these fields. 1311 1312+------------------+-----------------------------------------------------------------------------------+ 1313| Field | Description | 1314+==================+===================================================================================+ 1315| cc[3] | Country code string, this attributes identify the country or noncountry entity | 1316| | in which the station/AP is operating. If it's a country, the first two | 1317| | octets of this string is the two character country info as described in document | 1318| | ISO/IEC3166-1. The third octect is one of the following: | 1319| | | 1320| | - an ASCII space character, if the regulations under which the station/AP is | 1321| | operating encompass all environments for the current frequency band in the | 1322| | country. | 1323| | - an ASCII 'O' character if the regulations under which the station/AP is | 1324| | operating are for an outdoor environment only. | 1325| | - an ASCII 'I' character if the regulations under which the station/AP is | 1326| | operating are for an indoor environment only. | 1327| | - an ASCII 'X' character if the station/AP is operating under a noncountry | 1328| | entity. The first two octets of the noncountry entity is two ASCII 'XX' | 1329| | characters. | 1330| | - the binary representation of the Operating Class table number currently in use.| 1331| | Refer to Annex E, IEEE Std 802.11-2012. | 1332| | | 1333+------------------+-----------------------------------------------------------------------------------+ 1334| schan | Start channel, it's the minimum channel number of the regulations under which the | 1335| | station/AP can operate. | 1336| | | 1337+------------------+-----------------------------------------------------------------------------------+ 1338| nchan | Total number of channels as per the regulations, e.g. if the schan=1, nchan=13, | 1339| | it means the station/AP can send data from channel 1 to 13. | 1340| | | 1341+------------------+-----------------------------------------------------------------------------------+ 1342| policy | Country policy, this field control which country info will be used if the | 1343| | configured country info is conflict with the connected AP's. More description | 1344| | about policy is provided in following section. | 1345| | | 1346+------------------+-----------------------------------------------------------------------------------+ 1347 1348The default country info is {.cc="CN", .schan=1, .nchan=13, policy=WIFI_COUNTRY_POLICY_AUTO}, if the Wi-Fi Mode is station/AP coexist mode, they share the same configured country info. Sometimes, the country info of AP, to which the station is connected, is different from the country info of configured. For example, the configured station has country info {.cc="JP", .schan=1, .nchan=14, policy=WIFI_COUNTRY_POLICY_AUTO}, but the connected AP has country info {.cc="CN", .schan=1, .nchan=13}, then country info of connected AP's is used. 1349Following table depicts which country info is used in different Wi-Fi Mode and different country policy, also describe the impact to active scan. 1350 1351+-----------+----------------------------+----------------------------------------------------------------+ 1352| WiFi Mode | Policy | Description | 1353+===========+============================+================================================================+ 1354| Station | WIFI_COUNTRY_POLICY_AUTO | If the connected AP has country IE in its beacon, the country | 1355| | | info equals to the country info in beacon, otherwise, use | 1356| | | default country info. | 1357| | | | 1358| | | For scan: | 1359| | | | 1360| | | -If schan+nchan-1 >11 : | 1361| | | Use active scan from schan to 11 and use passive scan | 1362| | | from 12 to schan+nchan-1. | 1363| | | | 1364| | | -If schan+nchan-1 <= 11 : | 1365| | | Use active scan from schan to schan+nchan-1. | 1366| | | | 1367| | | Always keep in mind that if an AP with hidden SSID | 1368| | | is set to a passive scan channel, the passive scan will not | 1369| | | find it. In other words, if the application hopes to find the | 1370| | | AP with hidden SSID in every channel, the policy of | 1371| | | country info should be configured to | 1372| | | WIFI_COUNTRY_POLICY_MANUAL. | 1373| | | | 1374+-----------+----------------------------+----------------------------------------------------------------+ 1375| Station | WIFI_COUNTRY_POLICY_MANUAL | Always use the configured country info. | 1376| | | | 1377| | | For scan, scans channel "schan" to "schan+nchan-1" with active | 1378| | | scan. | 1379| | | | 1380+-----------+----------------------------+----------------------------------------------------------------+ 1381| AP | WIFI_COUNTRY_POLICY_AUTO | Always use the configured country info. | 1382| | | | 1383+-----------+----------------------------+----------------------------------------------------------------+ 1384| AP | WIFI_COUNTRY_POLICY_MANUAL | Always use the configured country info. | 1385| | | | 1386+-----------+----------------------------+----------------------------------------------------------------+ 1387|Station/AP-| WIFI_COUNTRY_POLICY_AUTO | If the station doesn't connects to any AP, the AP use the | 1388| | | configured country info. | 1389|coexistence| | If the station connects to an AP, the AP has the same | 1390| | | country info as the station. | 1391| | | | 1392| | | Same as station mode with policy WIFI_COUNTRY_POLICY_AUTO. | 1393+-----------+----------------------------+----------------------------------------------------------------+ 1394 1395Home Channel 1396************************* 1397 1398In AP mode, the home channel is defined as the AP channel. In Station mode, home channel is defined as the channel of AP which the station is connected to. In Station/AP-coexistence mode, the home channel of AP and station must be the same, if they are different, the station's home channel is always in priority. Take the following as an example: the AP is on channel 6, and the station connects to an AP whose channel is 9. Since the station's home channel has higher priority, the AP needs to switch its channel from 6 to make sure that it has the same home channel as the station. While switching channel, the {IDF_TARGET_NAME} in SoftAP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Station that supports channel switching will transit without disconnecting and reconnecting to the SoftAP. 1399 1400 1401Wi-Fi Vendor IE Configuration 1402+++++++++++++++++++++++++++++++++++ 1403 1404By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care about them. Some applications, however, may have to handle the beacon, probe request, probe response and other management frames. For example, if you insert some vendor-specific IE into the management frames, it is only the management frames which contain this vendor-specific IE that will be processed. In {IDF_TARGET_NAME}, :cpp:func:`esp_wifi_set_vendor_ie()` and :cpp:func:`esp_wifi_set_vendor_ie_cb()` are responsible for this kind of tasks. 1405 1406 1407Wi-Fi Easy Connect™ (DPP) 1408-------------------------- 1409 1410Wi-Fi Easy Connect\ :sup:`TM` (or Device Provisioning Protocol) is a secure and standardized provisioning protocol for configuration of Wi-Fi Devices. 1411More information can be found on the API reference page :doc:`esp_dpp <../api-reference/network/esp_dpp>`. 1412 1413WPA2-Enterprise 1414+++++++++++++++++++++++++++++++++ 1415 1416WPA2-Enterprise is the secure authentication mechanism for enterprise wireless networks. It uses RADIUS server for authentication of network users before connecting to the Access Point. The authentication process is based on 802.1X policy and comes with different Extended Authentication Protocol (EAP) methods like TLS, TTLS, PEAP etc. RADIUS server authenticates the users based on their credentials (username and password), digital certificates or both. When {IDF_TARGET_NAME} in Station mode tries to connect to an AP in enterprise mode, it sends authentication request to AP which is sent to RADIUS server by AP for authenticating the Station. Based on different EAP methods, the parameters can be set in configuration which can be opened using ``idf.py menuconfig``. WPA2_Enterprise is supported by {IDF_TARGET_NAME} only in Station mode. 1417 1418 1419For establishing a secure connection, AP and Station negotiate and agree on the best possible cipher suite to be used. {IDF_TARGET_NAME} supports 802.1X/EAP (WPA) method of AKM and Advanced encryption standard with Counter Mode Cipher Block Chaining Message Authentication protocol (AES-CCM) cipher suite. It also supports the cipher suites supported by mbedtls if `USE_MBEDTLS_CRYPTO` flag is set. 1420 1421 1422{IDF_TARGET_NAME} currently supports the following EAP methods: 1423 - EAP-TLS: This is certificate based method and only requires SSID and EAP-IDF. 1424 - PEAP: This is Protected EAP method. Username and Password are mandatory. 1425 - EAP-TTLS: This is credentials based method. Only server authentication is mandatory while user authentication is optional. Username and Password are mandatory. It supports different Phase2 methods like, 1426 - PAP: Password Authentication Protocol. 1427 - CHAP: Challenge Handshake Authentication Protocol. 1428 - MSCHAP and MSCHAP-V2. 1429 1430 1431Detailed information on creating certificates and how to run wpa2_enterprise example on {IDF_TARGET_NAME} can be found in :example:`wifi/wifi_enterprise`. 1432 1433Wireless Network Management 1434---------------------------- 1435 1436Wireless Network Management allows client devices to exchange information about the network topology, including information related to RF environment. This makes each client network-aware, facilitating overall improvement in the performace of the wireless network. It is part of 802.11v specification. It also enables client to support Network assisted Roaming. 1437- Network assisted Roaming: Enables WLAN to send messages to associated clients, resulting clients to associate with APs with better link metrics. This is useful for both load balancing and in directing poorly connected clients. 1438 1439Current implementation of 802.11v includes support for BSS transition management frames. 1440 1441Radio Resource Measurement 1442--------------------------- 1443 1444Radio Resource Measurement (802.11k) is intended to improve the way traffic is distributed within a network. In a wireless LAN, each device normally connects to the access point (AP) that provides the strongest signal. Depending on the number and geographic locations of the subscribers, this arrangement can sometimes lead to excessive demand on one AP and underutilization of others, resulting in degradation of overall network performance. In a network conforming to 802.11k, if the AP having the strongest signal is loaded to its full capacity, a wireless device can be moved to one of the underutilized APs. Even though the signal may be weaker, the overall throughput is greater because more efficient use is made of the network resources. 1445 1446Current implementation of 802.11k includes support for beacon measurement report, link measurement report and neighbor request. 1447 1448Refer IDF example :idf_file:`examples/wifi/roaming/README.md` to set up and use these APIs. Example code only demonstrates how these APIs can be used, the application should define its own algorithm and cases as required. 1449 1450.. only:: esp32s2 or esp32c3 1451 1452 Wi-Fi Location 1453 ------------------------------- 1454 1455 Wi-Fi Location will improve the accuracy of a device's location data beyond the Access Point, which will enable creation of new, feature-rich applications and services such as geo-fencing, network management, navigation and others. One of the protocols used to determine the device location with respect to the Access Point is Fine Timing Measurement which calculates Time-of-Flight of a WiFi frame. 1456 1457 Fine Timing Measurement (FTM) 1458 +++++++++++++++++++++++++++++ 1459 1460 FTM is used to measure Wi-Fi Round Trip Time (Wi-Fi RTT) which is the time a Wi-Fi signal takes to travel from a device to another device and back again. Using Wi-Fi RTT the distance between the devices can be calculated with a simple formula of `RTT * c / 2`, where c is the speed of light. 1461 FTM uses timestamps given by Wi-Fi interface hardware at the time of arrival or departure of frames exchanged between a pair of devices. One entity called FTM Initiator (mostly a Station device) discovers the FTM Responder (can be a Station or an Access Point) and negotiates to start an FTM procedure. The procedure uses multiple Action frames sent in bursts and its ACK's to gather the timestamps data. FTM Initiator gathers the data in the end to calculate an average Round-Trip-Time. 1462 {IDF_TARGET_NAME} supports FTM in below configuration: 1463 1464 - {IDF_TARGET_NAME} as FTM Initiator in Station mode. 1465 - {IDF_TARGET_NAME} as FTM Responder in SoftAP mode. 1466 1467 Distance measurement using RTT is not accurate, factors such as RF interference, multi-path travel, antenna orientation and lack of calibration increase these inaccuracies. For better results it is suggested to perform FTM between two {IDF_TARGET_NAME} devices as Station and SoftAP. 1468 Refer to IDF example :idf_file:`examples/wifi/ftm/README.md` for steps on how to setup and perform FTM. 1469 1470{IDF_TARGET_NAME} Wi-Fi Power-saving Mode 1471----------------------------------------- 1472 1473Station Sleep 1474++++++++++++++++++++++ 1475 1476Currently, {IDF_TARGET_NAME} Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode. 1477 1478Modem-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. 1479 1480In 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. 1481 1482Call ``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. 1483 1484Call ``esp_wifi_set_ps(WIFI_PS_NONE)`` 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). Disabling modem sleep entirely is not possible for Wi-Fi and Bluetooth coexist mode. 1485 1486The default Modem-sleep mode is WIFI_PS_MIN_MODEM. 1487 1488AP Sleep 1489+++++++++++++++++++++++++++++++ 1490 1491Currently {IDF_TARGET_NAME} 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 {IDF_TARGET_NAME} AP are power save enabled, they may experience multicast packet loss. 1492 1493In the future, all power save features will be supported on {IDF_TARGET_NAME} AP. 1494 1495{IDF_TARGET_NAME} Wi-Fi Throughput 1496----------------------------------- 1497 1498The table below shows the best throughput results we got in Espressif's lab and in a shield box. 1499 1500.. only:: esp32 1501 1502 +----------------------+-----------------+-----------------+---------------+--------------+ 1503 | Type/Throughput | Air In Lab | Shield-box | Test Tool | IDF Version | 1504 | | | | | (commit ID) | 1505 +======================+=================+=================+===============+==============+ 1506 | Raw 802.11 Packet RX | N/A | **130 MBit/s** | Internal tool | NA | 1507 +----------------------+-----------------+-----------------+---------------+--------------+ 1508 | Raw 802.11 Packet TX | N/A | **130 MBit/s** | Internal tool | NA | 1509 +----------------------+-----------------+-----------------+---------------+--------------+ 1510 | UDP RX | 30 MBit/s | 85 MBit/s | iperf example | 15575346 | 1511 +----------------------+-----------------+-----------------+---------------+--------------+ 1512 | UDP TX | 30 MBit/s | 75 MBit/s | iperf example | 15575346 | 1513 +----------------------+-----------------+-----------------+---------------+--------------+ 1514 | TCP RX | 20 MBit/s | 65 MBit/s | iperf example | 15575346 | 1515 +----------------------+-----------------+-----------------+---------------+--------------+ 1516 | TCP TX | 20 MBit/s | 75 MBit/s | iperf example | 15575346 | 1517 +----------------------+-----------------+-----------------+---------------+--------------+ 1518 1519 When the throughput is tested by iperf example, the sdkconfig is :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32`. 1520 1521.. only:: esp32s2 1522 1523 +----------------------+-----------------+-----------------+---------------+--------------+ 1524 | Type/Throughput | Air In Lab | Shield-box | Test Tool | IDF Version | 1525 | | | | | (commit ID) | 1526 +======================+=================+=================+===============+==============+ 1527 | Raw 802.11 Packet RX | N/A | **130 MBit/s** | Internal tool | NA | 1528 +----------------------+-----------------+-----------------+---------------+--------------+ 1529 | Raw 802.11 Packet TX | N/A | **130 MBit/s** | Internal tool | NA | 1530 +----------------------+-----------------+-----------------+---------------+--------------+ 1531 | UDP RX | 30 MBit/s | 70 MBit/s | iperf example | 15575346 | 1532 +----------------------+-----------------+-----------------+---------------+--------------+ 1533 | UDP TX | 30 MBit/s | 50 MBit/s | iperf example | 15575346 | 1534 +----------------------+-----------------+-----------------+---------------+--------------+ 1535 | TCP RX | 20 MBit/s | 32 MBit/s | iperf example | 15575346 | 1536 +----------------------+-----------------+-----------------+---------------+--------------+ 1537 | TCP TX | 20 MBit/s | 37 MBit/s | iperf example | 15575346 | 1538 +----------------------+-----------------+-----------------+---------------+--------------+ 1539 1540 When the throughput is tested by iperf example, the sdkconfig is :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32s2`. 1541 1542.. only:: esp32c3 1543 1544 +----------------------+-----------------+-----------------+---------------+--------------+ 1545 | Type/Throughput | Air In Lab | Shield-box | Test Tool | IDF Version | 1546 | | | | | (commit ID) | 1547 +======================+=================+=================+===============+==============+ 1548 | Raw 802.11 Packet RX | N/A | **130 MBit/s** | Internal tool | NA | 1549 +----------------------+-----------------+-----------------+---------------+--------------+ 1550 | Raw 802.11 Packet TX | N/A | **130 MBit/s** | Internal tool | NA | 1551 +----------------------+-----------------+-----------------+---------------+--------------+ 1552 | UDP RX | 30 MBit/s | 50 MBit/s | iperf example | 15575346 | 1553 +----------------------+-----------------+-----------------+---------------+--------------+ 1554 | UDP TX | 30 MBit/s | 40 MBit/s | iperf example | 15575346 | 1555 +----------------------+-----------------+-----------------+---------------+--------------+ 1556 | TCP RX | 20 MBit/s | 35 MBit/s | iperf example | 15575346 | 1557 +----------------------+-----------------+-----------------+---------------+--------------+ 1558 | TCP TX | 20 MBit/s | 37 MBit/s | iperf example | 15575346 | 1559 +----------------------+-----------------+-----------------+---------------+--------------+ 1560 1561 When the throughput is tested by iperf example, the sdkconfig is :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32c3`. 1562 1563.. only:: esp32s3 1564 1565 .. list-table:: 1566 :header-rows: 1 1567 :widths: 10 10 10 15 20 1568 1569 * - Type/Throughput 1570 - Air In Lab 1571 - Shield-box 1572 - Test Tool 1573 - IDF Version (commit ID) 1574 * - Raw 802.11 Packet RX 1575 - N/A 1576 - **130 MBit/s** 1577 - Internal tool 1578 - NA 1579 * - Raw 802.11 Packet TX 1580 - N/A 1581 - **130 MBit/s** 1582 - Internal tool 1583 - NA 1584 * - UDP RX 1585 - 30 MBit/s 1586 - 88 MBit/s 1587 - iperf example 1588 - 15575346 1589 * - UDP TX 1590 - 30 MBit/s 1591 - 98 MBit/s 1592 - iperf example 1593 - 15575346 1594 * - TCP RX 1595 - 20 MBit/s 1596 - 73 MBit/s 1597 - iperf example 1598 - 15575346 1599 * - TCP TX 1600 - 20 MBit/s 1601 - 83 MBit/s 1602 - iperf example 1603 - 15575346 1604 1605 When the throughput is tested by iperf example, the sdkconfig is :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32s3`. 1606 1607Wi-Fi 80211 Packet Send 1608--------------------------- 1609 1610The :cpp:func:`esp_wifi_80211_tx` API can be used to: 1611 1612 - Send the beacon, probe request, probe response, action frame. 1613 - Send the non-QoS data frame. 1614 1615It cannot be used for sending encrypted or QoS frames. 1616 1617Preconditions of Using :cpp:func:`esp_wifi_80211_tx` 1618++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1619 1620 - The Wi-Fi mode is Station, or AP, or Station+AP. 1621 - Either esp_wifi_set_promiscuous(true), or :cpp:func:`esp_wifi_start()`, or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before :cpp:func:`esp_wifi_80211_tx` is called. In {IDF_TARGET_NAME}, both esp_wifi_set_promiscuous(true) and :cpp:func:`esp_wifi_start()` can trigger the initialization of Wi-Fi hardware. 1622 - The parameters of :cpp:func:`esp_wifi_80211_tx` are hereby correctly provided. 1623 1624Data rate 1625+++++++++++++++++++++++++++++++++++++++++++++++ 1626 1627 - If there is no Wi-Fi connection, the data rate is 1 Mbps. 1628 - If there is Wi-Fi connection and the packet is from station to AP or from AP to station, the data rate is same as the Wi-Fi connection. Otherwise the data rate is 1 Mbps. 1629 1630Side-Effects to Avoid in Different Scenarios 1631+++++++++++++++++++++++++++++++++++++++++++++++++++++ 1632 1633Theoretically, if we do not consider the side-effects the API imposes on the Wi-Fi driver or other stations/APs, we can send a raw 802.11 packet over the air, with any destination MAC, any source MAC, any BSSID, or any other type of packet. However,robust/useful applications should avoid such side-effects. The table below provides some tips/recommendations on how to avoid the side-effects of :cpp:func:`esp_wifi_80211_tx` in different scenarios. 1634 1635+-----------------------------+---------------------------------------------------+ 1636| Scenario | Description | 1637+=============================+===================================================+ 1638| No WiFi connection | In this scenario, no Wi-Fi connection is set up, | 1639| | so there are no side-effects on the Wi-Fi driver. | 1640| | If en_sys_seq==true, the Wi-Fi driver is | 1641| | responsible for the sequence control. If | 1642| | en_sys_seq==false, the application needs to ensure| 1643| | that the buffer has the correct sequence. | 1644| | | 1645| | Theoretically, the MAC address can be any address.| 1646| | However, this may impact other stations/APs | 1647| | with the same MAC/BSSID. | 1648| | | 1649| | Side-effect example#1 | 1650| | The application calls esp_wifi_80211_tx to send | 1651| | a beacon with BSSID == mac_x in AP mode, but | 1652| | the mac_x is not the MAC of the AP interface. | 1653| | Moreover, there is another AP, say | 1654| | "other-AP", whose bssid is mac_x. If this | 1655| | happens, an "unexpected behavior" may occur, | 1656| | because the stations which connect to the | 1657| | "other-AP" cannot figure out whether the beacon is| 1658| | from the "other-AP" or the esp_wifi_80211_tx. | 1659| | | 1660| | To avoid the above-mentioned side-effects, we | 1661| | recommend that: | 1662| | | 1663| | - If esp_wifi_80211_tx is called in Station mode,| 1664| | the first MAC should be a multicast MAC or the | 1665| | exact target-device's MAC, while the second MAC| 1666| | should be that of the station interface. | 1667| | - If esp_wifi_80211_tx is called in AP mode, | 1668| | the first MAC should be a multicast MAC or the | 1669| | exact target-device's MAC, while the second MAC| 1670| | should be that of the AP interface. | 1671| | | 1672| | The recommendations above are only for avoiding | 1673| | side-effects and can be ignored when there are | 1674| | good reasons for doing this. | 1675+-----------------------------+---------------------------------------------------+ 1676| Have WiFi connection | When the Wi-Fi connection is already set up, and | 1677| | the sequence is controlled by the application, the| 1678| | latter may impact the sequence control of the | 1679| | Wi-Fi connection, as a whole. So, the | 1680| | en_sys_seq need to be true, otherwise | 1681| | ESP_ERR_WIFI_ARG is returned. | 1682| | | 1683| | The MAC-address recommendations in the | 1684| | "No WiFi connection" scenario also apply to this | 1685| | scenario. | 1686| | | 1687| | If the WiFi mode is station mode and the MAC | 1688| | address1 is the MAC of AP to which the station is | 1689| | connected, the MAC address2 is the MAC of station | 1690| | interface, we say the packets is from the station | 1691| | to AP. On the other hand, if the WiFi mode is | 1692| | AP mode and the MAC address1 is the MAC of | 1693| | the station who connects to this AP, the MAC | 1694| | address2 is the MAC of AP interface, we say | 1695| | the packet is from the AP to station. | 1696| | To avoid conflicting with WiFi connections, the | 1697| | following checks are applied: | 1698| | | 1699| | - If the packet type is data and is from the | 1700| | station to AP, the ToDS bit in IEEE 80211 | 1701| | frame control should be 1, the FromDS bit | 1702| | should be 0, otherwise the packet will be | 1703| | discarded by WiFi driver. | 1704| | - If the packet type is data and is from the | 1705| | AP to station, the ToDS bit in IEEE 80211 | 1706| | frame control should be 0, the FromDS bit | 1707| | should be 1, otherwise the packet will be | 1708| | discarded by WiFi driver. | 1709| | - If the packet is from station to AP or | 1710| | from AP to station, the Power Management, | 1711| | More Data, Re-Transmission bits should be 0, | 1712| | otherwise the packet will be discarded by WiFi | 1713| | driver. | 1714| | | 1715| | ESP_ERR_WIFI_ARG is returned if any check fails. | 1716+-----------------------------+---------------------------------------------------+ 1717 1718Wi-Fi Sniffer Mode 1719--------------------------- 1720 1721The Wi-Fi sniffer mode can be enabled by esp_wifi_set_promiscuous(). If the sniffer mode is enabled, the following packets **can** be dumped to the application: 1722 1723 - 802.11 Management frame. 1724 - 802.11 Data frame, including MPDU, AMPDU, AMSDU, etc. 1725 - 802.11 MIMO frame, for MIMO frame, the sniffer only dumps the length of the frame. 1726 - 802.11 Control frame. 1727 1728The following packets will **NOT** be dumped to the application: 1729 1730 - 802.11 error frame, such as the frame with a CRC error, etc. 1731 1732For frames that the sniffer **can** dump, the application can additionally decide which specific type of packets can be filtered to the application by using :cpp:func:`esp_wifi_set_promiscuous_filter()` and :cpp:func:`esp_wifi_set_promiscuous_ctrl_filter()`. By default, it will filter all 802.11 data and management frames to the application. 1733 1734The 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. 1735 1736Another 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. 1737 1738Wi-Fi Multiple Antennas 1739-------------------------- 1740The Wi-Fi multiple antennas selecting can be depicted as following picture:: 1741 1742 __________ 1743 |Enabled | 1744 ___|Antenna 0 |\\ _________ 1745 |__________| \\ GPIO[0] <----> antenna_select[0] ---| | --- antenna 0 1746 RX/TX ___ \\____\ GPIO[1] <----> antenna_select[1] ---| Antenna | --- antenna 1 1747 \ __________ // / GPIO[2] <----> antenna_select[2] ---| Switch | ... ... 1748 \ ___|Enabled | // GPIO[3] <----> antenna_select[3] ---|_________| --- antenna 15 1749 \ |Antenna 1 |// 1750 |__________| 1751 1752 1753{IDF_TARGET_NAME} supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. E.g. the value '0b1011' means the antenna 11 is selected. The default value of antenna_select[3:0] is '0b0000', it means the antenna 0 is selected by default. 1754 1755Up to four GPIOs are connected to the four active high antenna_select pins. {IDF_TARGET_NAME} can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided. 1756 1757Although up to sixteen anteenas are supported, only one or two antennas can be simultaneously enabled for RX/TX. The API :cpp:func:`esp_wifi_set_ant()` is used to configure which antennas are enabled. 1758 1759The enabled antennas selecting algorithm is also configured by :cpp:func:`esp_wifi_set_ant()`. The RX/TX antenna mode can be WIFI_ANT_MODE_ANT0, WIFI_ANT_MODE_ANT1 or WIFI_ANT_MODE_AUTO. If the antenna mode is WIFI_ANT_MODE_ANT0, the enabled antenna 0 is selected for RX/TX data. If the antenna mode is WIFI_ANT_MODE_ANT1, the enabled antenna 1 is selected for RX/TX data. Otherwise, Wi-Fi automatically selects the antenna that has better signal from the enabled antennas. 1760 1761If the RX antenna mode is WIFI_ANT_MODE_AUTO, the default antenna mode also needs to be set. Because the RX antenna switching only happens when some conditions are met, e.g. the RX antenna starts to switch if the RSSI is lower than -65 dBm and if another antenna has better signal etc, RX uses the default antenna if the conditions are not met. If the default antenna mode is WIFI_ANT_MODE_ANT1, the enabled antenna 1 is used as the default RX antenna, otherwise the enabled antenna 0 is used as the default RX antenna. 1762 1763Some limitations need to be considered: 1764 1765 - The TX antenna can be set to WIFI_ANT_MODE_AUTO only if the RX antenna mode is WIFI_ANT_MODE_AUTO because TX antenna selecting algorithm is based on RX antenna in WIFI_ANT_MODE_AUTO type. 1766 - Currently Bluetooth® doesn't support the multiple antennas feature, please don't use multiple antennas related APIs. 1767 1768Following is the recommended scenarios to use the multiple antennas: 1769 1770 - In Wi-Fi mode WIFI_MODE_STA, both RX/TX antenna modes are configured to WIFI_ANT_MODE_AUTO. The Wi-Fi driver selects the better RX/TX antenna automatically. 1771 - The RX antenna mode is configured to WIFI_ANT_MODE_AUTO. The TX antenna mode is configured to WIFI_ANT_MODE_ANT0 or WIFI_ANT_MODE_ANT1. The applications can choose to always select a specified antenna for TX, or implement their own TX antenna selecting algorithm, e.g. selecting the TX antenna mode based on the channel switch information etc. 1772 - Both RX/TX antenna modes are configured to WIFI_ANT_MODE_ANT0 or WIFI_ANT_MODE_ANT1. 1773 1774 1775Wi-Fi Multiple Antennas Configuration 1776+++++++++++++++++++++++++++++++++++++ 1777 1778Generally, following steps can be taken to configure the multiple antennas: 1779 1780 - Configure which GPIOs are connected to the antenna_selects, for example, if four antennas are supported and GPIO20/GPIO21 are connected to antenna_select[0]/antenna_select[1], the configurations look like:: 1781 1782 wifi_ant_gpio_config_t config = { 1783 { .gpio_select = 1, .gpio_num = 20 }, 1784 { .gpio_select = 1, .gpio_num = 21 } 1785 }; 1786 - Configure which antennas are enabled and how RX/TX use the enabled antennas, for example, if antenna1 and antenna3 are enabled, the RX needs to select the better antenna automatically and uses antenna1 as its default antenna, the TX always selects the antenna3. The configuration looks like:: 1787 1788 wifi_ant_config_t config = { 1789 .rx_ant_mode = WIFI_ANT_MODE_AUTO, 1790 .rx_ant_default = WIFI_ANT_ANT0, 1791 .tx_ant_mode = WIFI_ANT_MODE_ANT1, 1792 .enabled_ant0 = 1, 1793 .enabled_ant1 = 3 1794 }; 1795 1796Wi-Fi Channel State Information 1797------------------------------------ 1798 1799Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In {IDF_TARGET_NAME}, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF) and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI is shown in the following table. 1800 1801+-------------+--------------------+-----------------------------------------+--------------------------------------------------------+----------------------------------------------------------+ 1802| channel | secondary channel | none | below | above | 1803+-------------+--------------------+-------------+---------------------------+----------+---------------------------------------------+----------+-----------------------------------------------+ 1804| packet | signal mode | non HT | HT | non HT | HT | non HT | HT | 1805+ +--------------------+-------------+---------------------------+----------+-----------------+---------------------------+----------+-------------------+---------------------------+ 1806| information | channel bandwidth | 20 MHz | 20 MHz | 20 MHz | 20 MHz | 40 MHz | 20 MHz | 20 MHz | 40 MHz | 1807+ +--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+ 1808| | STBC | non STBC | non STBC | STBC | non STBC | non STBC | STBC | non STBC | STBC | non STBC | non STBC | STBC | non STBC | STBC | 1809+-------------+--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+ 1810| sub-carrier | LLTF | 0~31, -32~-1| 0~31, -32~-1| 0~31, -32~-1| 0~63 | 0~63 | 0~63 | 0~63 | 0~63 | -64~-1 | -64~-1 | -64~-1 | -64~-1 | -64~-1 | 1811+ +--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+ 1812| index | HT-LTF | - | 0~31, -32~-1| 0~31, -32~-1| - | 0~63 | 0~62 | 0~63, -64~-1| 0~60, -60~-1| - | -64~-1 | -62~-1 | 0~63, -64~-1| 0~60, -60~-1| 1813+ +--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+ 1814| | STBC-HT-LTF | - | - | 0~31, -32~-1| - | - | 0~62 | - | 0~60, -60~-1| - | - | -62~-1 | - | 0~60, -60~-1| 1815+-------------+--------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+ 1816| total bytes | 128 | 256 | 384 | 128 | 256 | 380 | 384 | 612 | 128 | 256 | 376 | 384 | 612 | 1817+----------------------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+ 1818 1819All of the information in the table can be found in the structure wifi_csi_info_t. 1820 1821 - Secondary channel refers to secondary_channel field of rx_ctrl field. 1822 - Signal mode of packet refers to sig_mode field of rx_ctrl field. 1823 - Channel bandwidth refers to cwb field of rx_ctrl field. 1824 - STBC refers to stbc field of rx_ctrl field. 1825 - Total bytes refers to len field. 1826 - The CSI data corresponding to each Long Training Field(LTF) type is stored in a buffer starting from the buf field. Each item is stored as two bytes: imaginary part followed by real part. The order of each item is the same as the sub-carrier in the table. The order of LTF is: LLTF, HT-LTF, STBC-HT-LTF. However all 3 LTFs may not be present, depending on the channel and packet information (see above). 1827 - If first_word_invalid field of wifi_csi_info_t is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in {IDF_TARGET_NAME}. 1828 - More information like RSSI, noise floor of RF, receiving time and antenna is in the rx_ctrl field. 1829 1830.. note:: 1831 1832 - For STBC packet, CSI is provided for every space-time stream without CSD (cyclic shift delay). As each cyclic shift on the additional chains shall be -200 ns, only the CSD angle of first space-time stream is recorded in sub-carrier 0 of HT-LTF and STBC-HT-LTF for there is no channel frequency response in sub-carrier 0. CSD[10:0] is 11 bits, ranging from -pi to pi. 1833 - If LLTF, HT-LTF or STBC-HT-LTF is not enabled by calling API :cpp:func:`esp_wifi_set_csi_config`, the total bytes of CSI data will be fewer than that in the table. For example, if LLTF and HT-LTF is not enabled and STBC-HT-LTF is enabled, when a packet is received with the condition above/HT/40MHz/STBC, the total bytes of CSI data is 244 ((61 + 60) * 2 + 2 = 244, the result is aligned to four bytes and the last two bytes is invalid). 1834 1835Wi-Fi Channel State Information Configure 1836------------------------------------------- 1837 1838To use Wi-Fi CSI, the following steps need to be done. 1839 1840 - Select Wi-Fi CSI in menuconfig. It is "Menuconfig --> Components config --> Wi-Fi --> WiFi CSI(Channel State Information)". 1841 - Set CSI receiving callback function by calling API :cpp:func:`esp_wifi_set_csi_rx_cb`. 1842 - Configure CSI by calling API :cpp:func:`esp_wifi_set_csi_config`. 1843 - Enable CSI by calling API :cpp:func:`esp_wifi_set_csi`. 1844 1845The 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`. 1846 1847Wi-Fi HT20/40 1848------------------------- 1849 1850{IDF_TARGET_NAME} supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. :cpp:func:`esp_wifi_set_bandwidth` can be used to change the default bandwidth of station or AP. The default bandwidth for {IDF_TARGET_NAME} station and AP is HT40. 1851 1852In 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. 1853 1854Similarly, in AP mode, the actual bandwidth is negotiated between AP and the stations that connect to the AP. It's HT40 if the AP and one of the stations support HT40, otherwise it's HT20. 1855 1856In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in {IDF_TARGET_NAME}. 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. 1857 1858Theoretically 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 {IDF_TARGET_NAME} 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. 1859 1860Wi-Fi QoS 1861------------------------- 1862 1863{IDF_TARGET_NAME} supports all the mandatory features required in WFA Wi-Fi QoS Certification. 1864 1865Four 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. 1866 1867Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in {IDF_TARGET_NAME}, it also indicates whether the AMPDU is supported for this AC. The table is sorted with priority descending order, namely, the AC_VO has highest priority. 1868 1869+------------------+------------------------+-----------------+ 1870| IP Precedence | Wi-Fi AC | Support AMPDU? | 1871+==================+========================+=================+ 1872| 6, 7 | AC_VO (Voice) | No | 1873+------------------+------------------------+-----------------+ 1874| 4, 5 | AC_VI (Video) | Yes | 1875+------------------+------------------------+-----------------+ 1876| 3, 0 | AC_BE (Best Effort) | Yes | 1877+------------------+------------------------+-----------------+ 1878| 1, 2 | AC_BK (Background) | Yes | 1879+------------------+------------------------+-----------------+ 1880 1881The 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:: 1882 1883 const int ip_precedence_vi = 4; 1884 const int ip_precedence_offset = 5; 1885 int priority = (ip_precedence_vi << ip_precedence_offset); 1886 setsockopt(socket_id, IPPROTO_IP, IP_TOS, &priority, sizeof(priority)); 1887 1888Theoretically 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: 1889 1890 - 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. 1891 - 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. 1892 1893 1894Wi-Fi AMSDU 1895------------------------- 1896 1897{IDF_TARGET_NAME} supports receiving and transmitting AMSDU. 1898 1899Wi-Fi Fragment 1900------------------------- 1901 1902.. only:: esp32 or esp32s2 1903 1904 supports Wi-Fi receiving fragment, but doesn't support Wi-Fi transmitting fragment. 1905 1906.. only:: esp32c3 or esp32s3 1907 1908 {IDF_TARGET_NAME} supports Wi-Fi receiving and transmitting fragment. 1909 1910WPS Enrollee 1911------------------------- 1912 1913{IDF_TARGET_NAME} supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Currently {IDF_TARGET_NAME} supports WPS enrollee type PBC and PIN. 1914 1915.. _wifi-buffer-usage: 1916 1917Wi-Fi Buffer Usage 1918-------------------------- 1919 1920This section is only about the dynamic buffer configuration. 1921 1922Why Buffer Configuration Is Important 1923+++++++++++++++++++++++++++++++++++++++ 1924 1925In order to get a , high-performance system, we need to consider the memory usage/configuration very carefully, because: 1926 1927 - the available memory in {IDF_TARGET_NAME} is limited. 1928 - 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". 1929 - it is very dangerous to run out of heap memory, as this will cause {IDF_TARGET_NAME} an "undefined behavior". Thus, enough heap memory should be reserved for the application, so that it never runs out of it. 1930 - the Wi-Fi throughput heavily depends on memory-related configurations, such as the TCP window size, Wi-Fi RX/TX dynamic buffer number, etc. 1931 - the peak heap memory that the {IDF_TARGET_NAME} LwIP/Wi-Fi may consume depends on a number of factors, such as the maximum TCP/UDP connections that the application may have, etc. 1932 - the total memory that the application requires is also an important factor when considering memory configuration. 1933 1934Due to these reasons, there is not a good-for-all application configuration. Rather, we have to consider memory configurations separately for every different application. 1935 1936Dynamic vs. Static Buffer 1937++++++++++++++++++++++++++++++ 1938 1939The default type of buffer in Wi-Fi drivers is "dynamic". Most of the time the dynamic buffer can significantly save memory. However, it makes the application programming a little more difficult, because in this case the application needs to consider memory usage in Wi-Fi. 1940 1941lwIP also allocates buffers at the TCP/IP layer, and this buffer allocation is also dynamic. See :ref:`lwIP documentation section about memory use and performance <lwip-performance>`. 1942 1943Peak Wi-Fi Dynamic Buffer 1944++++++++++++++++++++++++++++++ 1945 1946The Wi-Fi driver supports several types of buffer (refer to `Wi-Fi Buffer Configure`_). However, this section is about the usage of the dynamic Wi-Fi buffer only. 1947The peak heap memory that Wi-Fi consumes is the **theoretically-maximum memory** that the Wi-Fi driver consumes. Generally, the peak memory depends on: 1948 1949 - the number of dynamic rx buffers that are configured: wifi_rx_dynamic_buf_num 1950 - the number of dynamic tx buffers that are configured: wifi_tx_dynamic_buf_num 1951 - the maximum packet size that the Wi-Fi driver can receive: wifi_rx_pkt_size_max 1952 - the maximum packet size that the Wi-Fi driver can send: wifi_tx_pkt_size_max 1953 1954So, the peak memory that the Wi-Fi driver consumes can be calculated with the following formula: 1955 1956 wifi_dynamic_peek_memory = (wifi_rx_dynamic_buf_num * wifi_rx_pkt_size_max) + (wifi_tx_dynamic_buf_num * wifi_tx_pkt_size_max) 1957 1958Generally, 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. 1959 1960.. _How-to-improve-Wi-Fi-performance: 1961 1962How to improve Wi-Fi performance 1963---------------------------------- 1964 1965The performance of {IDF_TARGET_NAME} Wi-Fi is affected by many parameters, and there are mutual constraints between each parameter. A proper configuration can not only improve performance but also increase available memory for applications and improve stability. 1966 1967In this section, we will briefly explain the operating mode of the Wi-Fi/LWIP protocol stack and explain the role of each parameter. We will give several recommended configuration ranks, user can choose the appropriate rank according to the usage scenario. 1968 1969Protocol stack operation mode 1970++++++++++++++++++++++++++++++++++ 1971 1972.. figure:: ../../_static/api-guides-WiFi-driver-how-to-improve-WiFi-performance.png 1973 :align: center 1974 1975 {IDF_TARGET_NAME} datapath 1976 1977The {IDF_TARGET_NAME} protocol stack is divided into four layers: Application, LWIP, Wi-Fi, and Hardware. 1978 1979 - During receiving, hardware puts the received packet into DMA buffer, and then transfers it into the RX buffer of Wi-Fi, LWIP in turn for related protocol processing, and finally to the application layer. The Wi-Fi RX buffer and the LWIP RX buffer shares the same buffer by default. In other words, the Wi-Fi forwards the packet to LWIP by reference by default. 1980 1981 - During sending, the application copies the messages to be sent into the TX buffer of the LWIP layer for TCP/IP encapsulation. The messages will then be passed to the TX buffer of the Wi-Fi layer for MAC encapsulation and wait to be sent. 1982 1983Parameters 1984++++++++++++++ 1985 1986Increasing the size or number of the buffers mentioned above properly can improve Wi-Fi performance. Meanwhile, it will reduce available memory to the application. The following is an introduction to the parameters that users need to configure: 1987 1988**RX direction:** 1989 1990 - :ref:`CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM` 1991 This parameter indicates the number of DMA buffer at the hardware layer. Increasing this parameter will increase the sender's one-time receiving throughput, thereby improving the Wi-Fi protocol stack ability to handle burst traffic. 1992 1993 - :ref:`CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM` 1994 This parameter indicates the number of RX buffer in the Wi-Fi layer. Increasing this parameter will improve the performance of packet reception. This parameter needs to match the RX buffer size of the LWIP layer. 1995 1996 - :ref:`CONFIG_ESP32_WIFI_RX_BA_WIN` 1997 This parameter indicates the size of the AMPDU BA Window at the receiving end. This parameter should be configured to the smaller value between twice of :ref:`CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM` and :ref:`CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM`. 1998 1999 - :ref:`CONFIG_LWIP_TCP_WND_DEFAULT` 2000 This parameter represents the RX buffer size of the LWIP layer for each TCP stream. Its value should be configured to the value of WIFI_DYNAMIC_RX_BUFFER_NUM(KB) to reach a high and stable performance. Meanwhile, in case of multiple streams, this value needs to be reduced proportionally. 2001 2002**TX direction:** 2003 2004 - :ref:`CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM` 2005 This parameter indicates the type of TX buffer, it is recommended to configure it as a dynamic buffer, which can make full use of memory. 2006 2007 - :ref:`CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM` 2008 This parameter indicates the number of TX buffer on the Wi-Fi layer. Increasing this parameter will improve the performance of packet sending. The parameter value needs to match the TX buffer size of the LWIP layer. 2009 2010 - :ref:`CONFIG_LWIP_TCP_SND_BUF_DEFAULT` 2011 This parameter represents the TX buffer size of the LWIP layer for each TCP stream. Its value should be configured to the value of WIFI_DYNAMIC_TX_BUFFER_NUM(KB) to reach a high and stable performance. In case of multiple streams, this value needs to be reduced proportionally. 2012 2013**Throughput optimization by placing code in IRAM:** 2014 2015.. only:: esp32 or esp32s2 2016 2017 - :ref:`CONFIG_ESP32_WIFI_IRAM_OPT` 2018 If this option is enabled, some Wi-Fi functions are moved to IRAM, improving throughput. This increases IRAM usage by 15 kB. 2019 2020 - :ref:`CONFIG_ESP32_WIFI_RX_IRAM_OPT` 2021 If this option is enabled, some Wi-Fi RX functions are moved to IRAM, improving throughput. This increases IRAM usage by 16 kB. 2022 2023 - :ref:`CONFIG_LWIP_IRAM_OPTIMIZATION` 2024 If this option is enabled, some LWIP functions are moved to IRAM, improving throughput. This increases IRAM usage by 13 kB. 2025 2026.. only:: esp32s2 2027 2028 **CACHE:** 2029 2030 - :ref:`CONFIG_ESP32S2_INSTRUCTION_CACHE_SIZE` 2031 Configure the size of the instruction Cache. 2032 2033 - :ref:`CONFIG_ESP32S2_INSTRUCTION_CACHE_LINE_SIZE` 2034 Configure the width of the instruction Cache bus. 2035 2036.. only:: esp32s3 2037 2038 **CACHE:** 2039 2040 - :ref:`CONFIG_ESP32S3_INSTRUCTION_CACHE_SIZE` 2041 Configure the size of the instruction Cache. 2042 2043 - :ref:`CONFIG_ESP32S3_INSTRUCTION_CACHE_LINE_SIZE` 2044 Configure the size of the instruction Cache bus. 2045 2046 - :ref:`CONFIG_ESP32S3_ICACHE_ASSOCIATED_WAYS` 2047 Configure the associated ways of the instruction Cache. 2048 2049 - :ref:`CONFIG_ESP32S3_DATA_CACHE_SIZE` 2050 Configure the size of the Data Cache. 2051 2052 - :ref:`CONFIG_ESP32S3_DATA_CACHE_LINE_SIZE` 2053 Configure the line size of the Data Cache. 2054 2055 - :ref:`CONFIG_ESP32S3_DCACHE_ASSOCIATED_WAYS` 2056 Configure the associated ways of the Data Cache. 2057 2058.. note:: 2059 The buffer size mentioned above is fixed as 1.6 KB. 2060 2061How to configure parameters 2062++++++++++++++++++++++++++++ 2063 2064{IDF_TARGET_NAME}'s memory is shared by protocol stack and applications. 2065 2066Here, we have given several configuration ranks. In most cases, the user should select a suitable rank for parameter configuration according to the size of the memory occupied by the application. 2067 2068The parameters not mentioned in the following table should be set to the default. 2069 2070.. only:: esp32 2071 2072 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2073 | Rank | Iperf | TX prior | High-performance | RX prior | Default | Memory saving | Minimum | 2074 +============================+=======+==========+==================+==========+=========+===============+=========+ 2075 | Available memory(KB) | 37.1 | 113.8 | 123.3 | 145.5 | 144.5 | 170.2 | 185.2 | 2076 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2077 | WIFI_STATIC_RX_BUFFER_NUM | 16 | 6 | 6 | 6 | 6 | 6 | 4 | 2078 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2079 | WIFI_DYNAMIC_RX_BUFFER_NUM | 64 | 16 | 24 | 34 | 20 | 12 | 8 | 2080 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2081 | WIFI_DYNAMIC_TX_BUFFER_NUM | 64 | 28 | 24 | 18 | 20 | 12 | 8 | 2082 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2083 | WIFI_RX_BA_WIN | 32 | 8 | 12 | 12 | 10 | 6 | Disable | 2084 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2085 | TCP_SND_BUF_DEFAULT(KB) | 65 | 28 | 24 | 18 | 20 | 12 | 8 | 2086 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2087 | TCP_WND_DEFAULT(KB) | 65 | 16 | 24 | 34 | 20 | 12 | 8 | 2088 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2089 | WIFI_IRAM_OPT | 15 | 15 | 15 | 15 | 15 | 15 | 15 | 2090 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2091 | WIFI_RX_IRAM_OPT | 16 | 16 | 16 | 16 | 16 | 16 | 16 | 2092 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2093 | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 13 | 13 | 13 | 13 | 13 | 2094 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2095 | TCP TX throughput (Mbit/s) | 74.6 | 50.8 | 46.5 | 39.9 | 44.2 | 33.8 | 25.6 | 2096 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2097 | TCP RX throughput (Mbit/s) | 63.6 | 35.5 | 42.3 | 48.5 | 40.5 | 30.1 | 27.8 | 2098 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2099 | UDP TX throughput (Mbit/s) | 76.2 | 75.1 | 74.1 | 72.4 | 69.6 | 64.1 | 36.5 | 2100 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2101 | UDP RX throughput (Mbit/s) | 83.1 | 66.3 | 75.1 | 75.6 | 73.1 | 65.3 | 54.7 | 2102 +----------------------------+-------+----------+------------------+----------+---------+---------------+---------+ 2103 2104.. only:: esp32s2 2105 2106 +----------------------------+-------+------------------+---------+---------------+---------+ 2107 | Rank | Iperf | High-performance | Default | Memory saving | Minimum | 2108 +============================+=======+==================+=========+===============+=========+ 2109 | Available memory (KB) | 4.1 | 24.2 | 78.4 | 86.5 | 116.4 | 2110 +----------------------------+-------+------------------+---------+---------------+---------+ 2111 | WIFI_STATIC_RX_BUFFER_NUM | 8 |6 | 6 | 4 | 3 | 2112 +----------------------------+-------+------------------+---------+---------------+---------+ 2113 | WIFI_DYNAMIC_RX_BUFFER_NUM | 24 | 18 | 12 | 8 | 6 | 2114 +----------------------------+-------+------------------+---------+---------------+---------+ 2115 | WIFI_DYNAMIC_TX_BUFFER_NUM | 24 | 18 | 12 | 8 | 6 | 2116 +----------------------------+-------+------------------+---------+---------------+---------+ 2117 | WIFI_RX_BA_WIN | 12 | 9 | 6 | 4 | 3 | 2118 +----------------------------+-------+------------------+---------+---------------+---------+ 2119 | TCP_SND_BUF_DEFAULT (KB) | 24 | 18 | 12 | 8 | 6 | 2120 +----------------------------+-------+------------------+---------+---------------+---------+ 2121 | TCP_WND_DEFAULT(KB) | 24 | 18 | 12 | 8 | 6 | 2122 +----------------------------+-------+------------------+---------+---------------+---------+ 2123 | WIFI_IRAM_OPT | 15 | 15 | 15 | 15 | 0 | 2124 +----------------------------+-------+------------------+---------+---------------+---------+ 2125 | WIFI_RX_IRAM_OPT | 16 | 16 | 16 | 0 | 0 | 2126 +----------------------------+-------+------------------+---------+---------------+---------+ 2127 | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 0 | 0 | 0 | 2128 +----------------------------+-------+------------------+---------+---------------+---------+ 2129 | INSTRUCTION_CACHE | 16 | 16 | 16 | 16 | 8 | 2130 +----------------------------+-------+------------------+---------+---------------+---------+ 2131 | INSTRUCTION_CACHE_LINE | 16 | 16 | 16 | 16 | 16 | 2132 +----------------------------+-------+------------------+---------+---------------+---------+ 2133 | TCP TX throughput (Mbit/s) | 37.6 | 33.1 | 22.5 | 12.2 | 5.5 | 2134 +----------------------------+-------+------------------+---------+---------------+---------+ 2135 | TCP RX throughput (Mbit/s) | 31.5 | 28.1 | 20.1 | 13.1 | 7.2 | 2136 +----------------------------+-------+------------------+---------+---------------+---------+ 2137 | UDP TX throughput (Mbit/s) | 58.1 | 57.3 | 28.1 | 22.6 | 8.7 | 2138 +----------------------------+-------+------------------+---------+---------------+---------+ 2139 | UDP RX throughput (Mbit/s) | 78.1 | 66.7 | 65.3 | 53.8 | 28.5 | 2140 +----------------------------+-------+------------------+---------+---------------+---------+ 2141 2142.. only:: esp32c3 2143 2144 +----------------------------+-------+---------+---------+ 2145 | Rank | Iperf | Default | Minimum | 2146 +============================+=======+=========+=========+ 2147 | Available memory(KB) | 59 | 160 | 180 | 2148 +----------------------------+-------+---------+---------+ 2149 | WIFI_STATIC_RX_BUFFER_NUM | 20 | 8 | 3 | 2150 +----------------------------+-------+---------+---------+ 2151 | WIFI_DYNAMIC_RX_BUFFER_NUM | 40 | 16 | 6 | 2152 +----------------------------+-------+---------+---------+ 2153 | WIFI_DYNAMIC_TX_BUFFER_NUM | 40 | 16 | 6 | 2154 +----------------------------+-------+---------+---------+ 2155 | WIFI_RX_BA_WIN | 32 | 16 | 6 | 2156 +----------------------------+-------+---------+---------+ 2157 | TCP_SND_BUF_DEFAULT(KB) | 40 | 16 | 6 | 2158 +----------------------------+-------+---------+---------+ 2159 | TCP_WND_DEFAULT(KB) | 40 | 16 | 6 | 2160 +----------------------------+-------+---------+---------+ 2161 | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 0 | 2162 +----------------------------+-------+---------+---------+ 2163 | TCP TX throughput (Mbit/s) | 38.1 | 27.2 | 20.4 | 2164 +----------------------------+-------+---------+---------+ 2165 | TCP RX throughput (Mbit/s) | 35.3 | 24.2 | 17.4 | 2166 +----------------------------+-------+---------+---------+ 2167 | UDP TX throughput (Mbit/s) | 40.6 | 38.9 | 34.1 | 2168 +----------------------------+-------+---------+---------+ 2169 | UDP RX throughput (Mbit/s) | 52.4 | 44.5 | 44.2 | 2170 +----------------------------+-------+---------+---------+ 2171 2172.. only:: esp32s3 2173 2174 +----------------------------+-------+---------+---------+ 2175 | Rank | Iperf | Default | Minimum | 2176 +============================+=======+=========+=========+ 2177 | Available memory(KB) | 133.9 | 183.9 | 273.6 | 2178 +----------------------------+-------+---------+---------+ 2179 | WIFI_STATIC_RX_BUFFER_NUM | 24 | 8 | 3 | 2180 +----------------------------+-------+---------+---------+ 2181 | WIFI_DYNAMIC_RX_BUFFER_NUM | 64 | 32 | 6 | 2182 +----------------------------+-------+---------+---------+ 2183 | WIFI_DYNAMIC_TX_BUFFER_NUM | 64 | 32 | 6 | 2184 +----------------------------+-------+---------+---------+ 2185 | WIFI_RX_BA_WIN | 32 | 16 | 6 | 2186 +----------------------------+-------+---------+---------+ 2187 | TCP_SND_BUF_DEFAULT (KB) | 64 | 32 | 6 | 2188 +----------------------------+-------+---------+---------+ 2189 | TCP_WND_DEFAULT (KB) | 64 | 32 | 6 | 2190 +----------------------------+-------+---------+---------+ 2191 | WIFI_IRAM_OPT | 15 | 15 | 15 | 2192 +----------------------------+-------+---------+---------+ 2193 | WIFI_RX_IRAM_OPT | 16 | 16 | 16 | 2194 +----------------------------+-------+---------+---------+ 2195 | LWIP_IRAM_OPTIMIZATION | 13 | 13 | 0 | 2196 +----------------------------+-------+---------+---------+ 2197 | INSTRUCTION_CACHE | 32 | 32 | 16 | 2198 +----------------------------+-------+---------+---------+ 2199 | INSTRUCTION_CACHE_LINE | 32 | 32 | 32 | 2200 +----------------------------+-------+---------+---------+ 2201 | INSTRUCTION_CACHE_WAYS | 8 | 8 | 4 | 2202 +----------------------------+-------+---------+---------+ 2203 | TCP TX throughput (Mbit/s) | 83.93 | 64.28 | 23.17 | 2204 +----------------------------+-------+---------+---------+ 2205 | TCP RX throughput (Mbit/s) | 73.98 | 60.39 | 18.11 | 2206 +----------------------------+-------+---------+---------+ 2207 | UDP TX throughput (Mbit/s) | 98.69 | 96.28 | 48.78 | 2208 +----------------------------+-------+---------+---------+ 2209 | UDP RX throughput (Mbit/s) | 88.58 | 86.57 | 59.45 | 2210 +----------------------------+-------+---------+---------+ 2211 2212.. only:: esp32 or esp32s3 2213 2214 .. note:: 2215 The test was performed with a single stream in a shielded box using an ASUS RT-N66U router. 2216 {IDF_TARGET_NAME}'s CPU is dual core with 240 MHz, {IDF_TARGET_NAME}'s flash is in QIO mode with 80 MHz. 2217 2218.. only:: esp32s2 2219 2220 .. note:: 2221 The test was performed with a single stream in a shielded box using an ASUS RT-N66U router. 2222 {IDF_TARGET_NAME}'s CPU is single core with 240 MHz, {IDF_TARGET_NAME}'s flash is in QIO mode with 80 MHz. 2223 2224.. only:: esp32c3 2225 2226 .. note:: 2227 The test was performed with a single stream in a shielded box using an ASUS RT-N66U router. 2228 {IDF_TARGET_NAME}'s CPU is single core with 160 MHz, {IDF_TARGET_NAME}'s flash is in QIO mode with 80 MHz. 2229 2230.. only:: esp32 2231 2232 **Ranks:** 2233 2234 - **Iperf rank** 2235 {IDF_TARGET_NAME} extreme performance rank used to test extreme performance. 2236 2237 - **High-performance rank** 2238 The {IDF_TARGET_NAME}'s high-performance configuration rank, suitable for scenarios that the application occupies less memory and has high-performance requirements. In this rank, users can choose to use the RX prior rank or the TX prior rank according to the usage scenario. 2239 2240 - **Default rank** 2241 {IDF_TARGET_NAME}'s default configuration rank, the available memory, and performance are in balance. 2242 2243 - **Memory saving rank** 2244 This rank is suitable for scenarios where the application requires a large amount of memory, and the transceiver performance will be reduced in this rank. 2245 2246 - **Minimum rank** 2247 This is the minimum configuration rank of {IDF_TARGET_NAME}. The protocol stack only uses the necessary memory for running. It is suitable for scenarios that have no requirement for performance and the application requires lots of space. 2248 2249.. only:: esp32s2 2250 2251 **Ranks:** 2252 2253 - **Iperf rank** 2254 {IDF_TARGET_NAME} extreme performance rank used to test extreme performance. 2255 2256 - **High-performance rank** 2257 The {IDF_TARGET_NAME}'s high-performance configuration rank, suitable for scenarios that the application occupies less memory and has high-performance requirements. 2258 2259 - **Default rank** 2260 {IDF_TARGET_NAME}'s default configuration rank, the available memory, and performance are in balance. 2261 2262 - **Memory saving rank** 2263 This rank is suitable for scenarios where the application requires a large amount of memory, and the transceiver performance will be reduced in this rank. 2264 2265 - **Minimum rank** 2266 This is the minimum configuration rank of {IDF_TARGET_NAME}. The protocol stack only uses the necessary memory for running. It is suitable for scenarios that have no requirement for performance and the application requires lots of space. 2267 2268.. only:: esp32c3 or esp32s3 2269 2270 **Ranks:** 2271 2272 - **Iperf rank** 2273 {IDF_TARGET_NAME} extreme performance rank used to test extreme performance. 2274 2275 - **Default rank** 2276 {IDF_TARGET_NAME}'s default configuration rank, the available memory, and performance are in balance. 2277 2278 - **Minimum rank** 2279 This is the minimum configuration rank of {IDF_TARGET_NAME}. The protocol stack only uses the necessary memory for running. It is suitable for scenarios that have no requirement for performance and the application requires lots of space. 2280 2281.. only:: esp32 or esp32s2 or esp32s3 2282 2283 Using PSRAM 2284 ++++++++++++++++++++++++++++ 2285 2286 PSRAM is generally used when the application takes up a lot of memory. In this mode, the :ref:`CONFIG_ESP32_WIFI_TX_BUFFER` is forced to be static. :ref:`CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM` indicates the number of DMA buffers at the hardware layer, increase this parameter can improve performance. 2287 The following are the recommended ranks for using PSRAM: 2288 2289 .. only:: esp32 2290 2291 +----------------------------+-------+---------+---------------+---------+ 2292 | Rank | Iperf | Default | Memory saving | Minimum | 2293 +============================+=======+=========+===============+=========+ 2294 | Available memory (KB) | 113.8 | 152.4 | 181.2 | 202.6 | 2295 +----------------------------+-------+---------+---------------+---------+ 2296 | WIFI_STATIC_RX_BUFFER_NUM | 16 | 8 | 4 | 2 | 2297 +----------------------------+-------+---------+---------------+---------+ 2298 | WIFI_DYNAMIC_RX_BUFFER_NUM | 128 | 128 | 128 | 128 | 2299 +----------------------------+-------+---------+---------------+---------+ 2300 | WIFI_STATIC_TX_BUFFER_NUM | 16 | 8 | 4 | 2 | 2301 +----------------------------+-------+---------+---------------+---------+ 2302 | WIFI_RX_BA_WIN | 16 | 16 | 8 | Disable | 2303 +----------------------------+-------+---------+---------------+---------+ 2304 | TCP_SND_BUF_DEFAULT (KB) | 65 | 65 | 65 | 65 | 2305 +----------------------------+-------+---------+---------------+---------+ 2306 | TCP_WND_DEFAULT (KB) | 65 | 65 | 65 | 65 | 2307 +----------------------------+-------+---------+---------------+---------+ 2308 | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | 2309 +----------------------------+-------+---------+---------------+---------+ 2310 | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | 2311 +----------------------------+-------+---------+---------------+---------+ 2312 | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | 2313 +----------------------------+-------+---------+---------------+---------+ 2314 | TCP TX throughput (Mbit/s) | 37.5 | 31.7 | 21.7 | 14.6 | 2315 +----------------------------+-------+---------+---------------+---------+ 2316 | TCP RX throughput (Mbit/s) | 31.5 | 29.8 | 26.5 | 21.1 | 2317 +----------------------------+-------+---------+---------------+---------+ 2318 | UDP TX throughput (Mbit/s) | 69.1 | 31.5 | 27.1 | 24.1 | 2319 +----------------------------+-------+---------+---------------+---------+ 2320 | UDP RX throughput (Mbit/s) | 40.1 | 38.5 | 37.5 | 36.9 | 2321 +----------------------------+-------+---------+---------------+---------+ 2322 2323 .. only:: esp32s2 2324 2325 +----------------------------+-------+---------+---------------+---------+ 2326 | Rank | Iperf | Default | Memory saving | Minimum | 2327 +============================+=======+=========+===============+=========+ 2328 | Available memory (KB) | 70.6 | 96.4 | 118.8 | 148.2 | 2329 +----------------------------+-------+---------+---------------+---------+ 2330 | WIFI_STATIC_RX_BUFFER_NUM | 8 | 8 | 6 | 4 | 2331 +----------------------------+-------+---------+---------------+---------+ 2332 | WIFI_DYNAMIC_RX_BUFFER_NUM | 64 | 64 | 64 | 64 | 2333 +----------------------------+-------+---------+---------------+---------+ 2334 | WIFI_STATIC_TX_BUFFER_NUM | 16 | 8 | 6 | 4 | 2335 +----------------------------+-------+---------+---------------+---------+ 2336 | WIFI_RX_BA_WIN | 16 | 6 | 6 | Disable | 2337 +----------------------------+-------+---------+---------------+---------+ 2338 | TCP_SND_BUF_DEFAULT (KB) | 32 | 32 | 32 | 32 | 2339 +----------------------------+-------+---------+---------------+---------+ 2340 | TCP_WND_DEFAULT (KB) | 32 | 32 | 32 | 32 | 2341 +----------------------------+-------+---------+---------------+---------+ 2342 | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | 2343 +----------------------------+-------+---------+---------------+---------+ 2344 | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | 2345 +----------------------------+-------+---------+---------------+---------+ 2346 | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | 2347 +----------------------------+-------+---------+---------------+---------+ 2348 | INSTRUCTION_CACHE | 16 | 16 | 16 | 8 | 2349 +----------------------------+-------+---------+---------------+---------+ 2350 | INSTRUCTION_CACHE_LINE | 16 | 16 | 16 | 16 | 2351 +----------------------------+-------+---------+---------------+---------+ 2352 | DATA_CACHE | 8 | 8 | 8 | 8 | 2353 +----------------------------+-------+---------+---------------+---------+ 2354 | DATA_CACHE_LINE | 32 | 32 | 32 | 32 | 2355 +----------------------------+-------+---------+---------------+---------+ 2356 | TCP TX throughput (Mbit/s) | 40.1 | 29.2 | 20.1 | 8.9 | 2357 +----------------------------+-------+---------+---------------+---------+ 2358 | TCP RX throughput (Mbit/s) | 21.9 | 16.8 | 14.8 | 9.6 | 2359 +----------------------------+-------+---------+---------------+---------+ 2360 | UDP TX throughput (Mbit/s) | 50.1 | 25.7 | 22.4 | 10.2 | 2361 +----------------------------+-------+---------+---------------+---------+ 2362 | UDP RX throughput (Mbit/s) | 45.3 | 43.1 | 28.5 | 15.1 | 2363 +----------------------------+-------+---------+---------------+---------+ 2364 2365 .. note:: 2366 Reaching peak performance may cause task watchdog. It is a normal phenomenon considering the CPU may have no time for lower priority tasks. 2367 2368 .. only:: esp32s3 2369 2370 **PSRAM with 4 lines:** 2371 2372 +----------------------------+-------+--------+---------------+----------+ 2373 | Rank | Iperf | Default| Memory saving | Minimum | 2374 +============================+=======+========+===============+==========+ 2375 | Available memory (KB) | 50.3 | 158.7 | 198.2 | 228.9 | 2376 +----------------------------+-------+--------+---------------+----------+ 2377 | WIFI_STATIC_RX_BUFFER_NUM | 24 | 8 | 6 | 4 | 2378 +----------------------------+-------+--------+---------------+----------+ 2379 | WIFI_DYNAMIC_RX_BUFFER_NUM | 85 | 64 | 32 | 32 | 2380 +----------------------------+-------+--------+---------------+----------+ 2381 | WIFI_STATIC_TX_BUFFER_NUM | 32 | 32 | 6 | 4 | 2382 +----------------------------+-------+--------+---------------+----------+ 2383 | WIFI_RX_BA_WIN | 32 | 16 | 12 | Disable | 2384 +----------------------------+-------+--------+---------------+----------+ 2385 | TCP_SND_BUF_DEFAULT (KB) | 85 | 32 | 32 | 32 | 2386 +----------------------------+-------+--------+---------------+----------+ 2387 | TCP_WND_DEFAULT (KB) | 85 | 32 | 32 | 32 | 2388 +----------------------------+-------+--------+---------------+----------+ 2389 | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | 2390 +----------------------------+-------+--------+---------------+----------+ 2391 | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | 2392 +----------------------------+-------+--------+---------------+----------+ 2393 | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | 2394 +----------------------------+-------+--------+---------------+----------+ 2395 | LWIP_UDP_RECVMBOX_SIZE | 16 | 16 | 16 | 16 | 2396 +----------------------------+-------+--------+---------------+----------+ 2397 | INSTRUCTION_CACHE | 32 | 16 | 16 | 16 | 2398 +----------------------------+-------+--------+---------------+----------+ 2399 | INSTRUCTION_CACHE_LINE | 32 | 16 | 16 | 16 | 2400 +----------------------------+-------+--------+---------------+----------+ 2401 | INSTRUCTION_CACHE_WAYS | 8 | 8 | 8 | 8 | 2402 +----------------------------+-------+--------+---------------+----------+ 2403 | DATA_CACHE | 64 | 16 | 16 | 16 | 2404 +----------------------------+-------+--------+---------------+----------+ 2405 | DATA_CACHE_LINE | 32 | 32 | 32 | 32 | 2406 +----------------------------+-------+--------+---------------+----------+ 2407 | DATA_CACHE_WAYS | 8 | 8 | 8 | 8 | 2408 +----------------------------+-------+--------+---------------+----------+ 2409 | TCP TX throughput (Mbit/s) | 93.1 | 62.5 | 41.3 | 42.7 | 2410 +----------------------------+-------+--------+---------------+----------+ 2411 | TCP RX throughput (Mbit/s) | 88.9 | 46.5 | 46.2 | 37.9 | 2412 +----------------------------+-------+--------+---------------+----------+ 2413 | UDP TX throughput (Mbit/s) | 106.4 | 106.2 | 60.7 | 50.0 | 2414 +----------------------------+-------+--------+---------------+----------+ 2415 | UDP RX throughput (Mbit/s) | 99.8 | 92.6 | 94.3 | 53.3 | 2416 +----------------------------+-------+--------+---------------+----------+ 2417 2418 **PSRAM with 8 lines:** 2419 2420 +----------------------------+-------+--------+---------------+----------+ 2421 | Rank | Iperf | Default| Memory saving | Minimum | 2422 +============================+=======+========+===============+==========+ 2423 | Available memory (KB) | 49.1 | 151.3 | 215.3 | 243.6 | 2424 +----------------------------+-------+--------+---------------+----------+ 2425 | WIFI_STATIC_RX_BUFFER_NUM | 24 | 8 | 6 | 4 | 2426 +----------------------------+-------+--------+---------------+----------+ 2427 | WIFI_DYNAMIC_RX_BUFFER_NUM | 85 | 64 | 32 | 32 | 2428 +----------------------------+-------+--------+---------------+----------+ 2429 | WIFI_STATIC_TX_BUFFER_NUM | 32 | 32 | 6 | 4 | 2430 +----------------------------+-------+--------+---------------+----------+ 2431 | WIFI_RX_BA_WIN | 32 | 16 | 12 | Disable | 2432 +----------------------------+-------+--------+---------------+----------+ 2433 | TCP_SND_BUF_DEFAULT (KB) | 85 | 32 | 32 | 32 | 2434 +----------------------------+-------+--------+---------------+----------+ 2435 | TCP_WND_DEFAULT (KB) | 85 | 32 | 32 | 32 | 2436 +----------------------------+-------+--------+---------------+----------+ 2437 | WIFI_IRAM_OPT | 15 | 15 | 15 | 0 | 2438 +----------------------------+-------+--------+---------------+----------+ 2439 | WIFI_RX_IRAM_OPT | 16 | 16 | 0 | 0 | 2440 +----------------------------+-------+--------+---------------+----------+ 2441 | LWIP_IRAM_OPTIMIZATION | 13 | 0 | 0 | 0 | 2442 +----------------------------+-------+--------+---------------+----------+ 2443 | LWIP_UDP_RECVMBOX_SIZE | 16 | 16 | 16 | 16 | 2444 +----------------------------+-------+--------+---------------+----------+ 2445 | INSTRUCTION_CACHE | 32 | 16 | 16 | 16 | 2446 +----------------------------+-------+--------+---------------+----------+ 2447 | INSTRUCTION_CACHE_LINE | 32 | 16 | 16 | 16 | 2448 +----------------------------+-------+--------+---------------+----------+ 2449 | INSTRUCTION_CACHE_WAYS | 8 | 8 | 8 | 8 | 2450 +----------------------------+-------+--------+---------------+----------+ 2451 | DATA_CACHE | 64 | 16 | 16 | 16 | 2452 +----------------------------+-------+--------+---------------+----------+ 2453 | DATA_CACHE_LINE | 32 | 32 | 32 | 32 | 2454 +----------------------------+-------+--------+---------------+----------+ 2455 | DATA_CACHE_WAYS | 8 | 8 | 8 | 8 | 2456 +----------------------------+-------+--------+---------------+----------+ 2457 | TCP TX throughput (Mbit/s) | 93.3 | 58.4 | 37.1 | 35.6 | 2458 +----------------------------+-------+--------+---------------+----------+ 2459 | TCP RX throughput (Mbit/s) | 86.1 | 43.6 | 42.5 | 35.0 | 2460 +----------------------------+-------+--------+---------------+----------+ 2461 | UDP TX throughput (Mbit/s) | 104.7 | 82.2 | 60.4 | 47.9 | 2462 +----------------------------+-------+--------+---------------+----------+ 2463 | UDP RX throughput (Mbit/s) | 104.6 |104.8 | 104.0 | 55.7 | 2464 +----------------------------+-------+--------+---------------+----------+ 2465 2466Wi-Fi Menuconfig 2467----------------------- 2468 2469Wi-Fi Buffer Configure 2470+++++++++++++++++++++++ 2471 2472If you are going to modify the default number or type of buffer, it would be helpful to also have an overview of how the buffer is allocated/freed in the data path. The following diagram shows this process in the TX direction: 2473 2474.. blockdiag:: 2475 :caption: TX Buffer Allocation 2476 :align: center 2477 2478 blockdiag buffer_allocation_tx { 2479 2480 # global attributes 2481 node_height = 60; 2482 node_width = 100; 2483 span_width = 50; 2484 span_height = 20; 2485 default_shape = roundedbox; 2486 2487 # labels of diagram nodes 2488 APPL_TASK [label="Application\n task", fontsize=12]; 2489 LwIP_TASK [label="LwIP\n task", fontsize=12]; 2490 WIFI_TASK [label="Wi-Fi\n task", fontsize=12]; 2491 2492 # labels of description nodes 2493 APPL_DESC [label="1> User data", width=120, height=25, shape=note, color=yellow]; 2494 LwIP_DESC [label="2> Pbuf", width=120, height=25, shape=note, color=yellow]; 2495 WIFI_DESC [label="3> Dynamic (Static)\n TX Buffer", width=150, height=40, shape=note, color=yellow]; 2496 2497 # node connections 2498 APPL_TASK -> LwIP_TASK -> WIFI_TASK 2499 APPL_DESC -> LwIP_DESC -> WIFI_DESC [style=none] 2500 } 2501 2502 2503Description: 2504 2505 - The application allocates the data which needs to be sent out. 2506 - The application calls TCPIP-/Socket-related APIs to send the user data. These APIs will allocate a PBUF used in LwIP, and make a copy of the user data. 2507 - When LwIP calls a Wi-Fi API to send the PBUF, the Wi-Fi API will allocate a "Dynamic Tx Buffer" or "Static Tx Buffer", make a copy of the LwIP PBUF, and finally send the data. 2508 2509The following diagram shows how buffer is allocated/freed in the RX direction: 2510 2511.. blockdiag:: 2512 :caption: RX Buffer Allocation 2513 :align: center 2514 2515 blockdiag buffer_allocation_rx { 2516 2517 # global attributes 2518 node_height = 60; 2519 node_width = 100; 2520 span_width = 40; 2521 span_height = 20; 2522 default_shape = roundedbox; 2523 2524 # labels of diagram nodes 2525 APPL_TASK [label="Application\n task", fontsize=12]; 2526 LwIP_TASK [label="LwIP\n task", fontsize=12]; 2527 WIFI_TASK [label="Wi-Fi\n task", fontsize=12]; 2528 WIFI_INTR [label="Wi-Fi\n interrupt", fontsize=12]; 2529 2530 # labels of description nodes 2531 APPL_DESC [label="4> User\n Data Buffer", height=40, shape=note, color=yellow]; 2532 LwIP_DESC [label="3> Pbuf", height=40, shape=note, color=yellow]; 2533 WIFI_DESC [label="2> Dynamic\n RX Buffer", height=40, shape=note, color=yellow]; 2534 INTR_DESC [label="1> Static\n RX Buffer", height=40, shape=note, color=yellow]; 2535 2536 # node connections 2537 APPL_TASK <- LwIP_TASK <- WIFI_TASK <- WIFI_INTR 2538 APPL_DESC <- LwIP_DESC <- WIFI_DESC <- INTR_DESC [style=none] 2539 } 2540 2541Description: 2542 2543 - The Wi-Fi hardware receives a packet over the air and puts the packet content to the "Static Rx Buffer", which is also called "RX DMA Buffer". 2544 - The Wi-Fi driver allocates a "Dynamic Rx Buffer", makes a copy of the "Static Rx Buffer", and returns the "Static Rx Buffer" to hardware. 2545 - The Wi-Fi driver delivers the packet to the upper-layer (LwIP), and allocates a PBUF for holding the "Dynamic Rx Buffer". 2546 - The application receives data from LwIP. 2547 2548The diagram shows the configuration of the Wi-Fi internal buffer. 2549 2550+------------------+------------+------------+--------------+---------------------------------------+ 2551| Buffer Type | Alloc Type | Default | Configurable | Description | 2552+==================+============+============+==============+=======================================+ 2553| Static RX Buffer | Static | 10 * | Yes | This is a kind of DMA memory. It is | 2554| (Hardware RX | | 1600 Bytes | | initialized in | 2555| Buffer) | | | | :cpp:func:`esp_wifi_init()` and freed | 2556| | | | | in :cpp:func:`esp_wifi_deinit()`. The | 2557| | | | | 'Static Rx Buffer' forms the hardware | 2558| | | | | receiving list. Upon receiving a frame| 2559| | | | | over the air, hardware writes the | 2560| | | | | frame into the buffer and raises an | 2561| | | | | interrupt to the CPU. Then, the Wi-Fi | 2562| | | | | driver reads the content from the | 2563| | | | | buffer and returns the buffer back to | 2564| | | | | the list. | 2565| | | | | | 2566| | | | | If the application want to reduce the | 2567| | | | | the memory statically allocated by | 2568| | | | | Wi-Fi, they can reduce this value from| 2569| | | | | 10 to 6 to save 6400 Bytes memory. | 2570| | | | | It's not recommended to reduce the | 2571| | | | | configuration to a value less than 6 | 2572| | | | | unless the AMPDU feature is disabled. | 2573| | | | | | 2574+------------------+------------+------------+--------------+---------------------------------------+ 2575| Dynamic RX Buffer| Dynamic | 32 | Yes | The buffer length is variable and it | 2576| | | | | depends on the received frames' | 2577| | | | | length. When the Wi-Fi driver receives| 2578| | | | | a frame from the 'Hardware Rx Buffer',| 2579| | | | | the 'Dynamic Rx Buffer' needs to be | 2580| | | | | allocated from the heap. The number of| 2581| | | | | the Dynamic Rx Buffer, configured in | 2582| | | | | the menuconfig, is used to limit the | 2583| | | | | total un-freed Dynamic Rx Buffer | 2584| | | | | number. | 2585+------------------+------------+------------+--------------+---------------------------------------+ 2586| Dynamic TX Buffer| Dynamic | 32 | Yes | This is a kind of DMA memory. It is | 2587| | | | | allocated to the heap. When the upper-| 2588| | | | | layer (LwIP) sends packets to the | 2589| | | | | Wi-Fi driver, it firstly allocates a | 2590| | | | | 'Dynamic TX Buffer' and makes a copy | 2591| | | | | of the upper-layer buffer. | 2592| | | | | | 2593| | | | | The Dynamic and Static TX Buffers are | 2594| | | | | mutually exclusive. | 2595+------------------+------------+------------+--------------+---------------------------------------+ 2596| Static TX Buffer | Static | 16 * | Yes | This is a kind of DMA memory. It is | 2597| | | 1600Bytes | | initialized in | 2598| | | | | :cpp:func:`esp_wifi_init()` and freed | 2599| | | | | in :cpp:func:`esp_wifi_deinit()`. When| 2600| | | | | the upper-layer (LwIP) sends packets | 2601| | | | | to the Wi-Fi driver, it firstly | 2602| | | | | allocates a 'Static TX Buffer' and | 2603| | | | | makes a copy of the upper-layer | 2604| | | | | buffer. | 2605| | | | | | 2606| | | | | The Dynamic and Static TX Buffer are | 2607| | | | | mutually exclusive. | 2608| | | | | | 2609| | | | | Since the TX buffer must be DMA | 2610| | | | | buffer, so when PSRAM is enabled, the | 2611| | | | | TX buffer must be static. | 2612+------------------+------------+------------+--------------+---------------------------------------+ 2613| Management Short | Dynamic | 8 | NO | Wi-Fi driver's internal buffer. | 2614| Buffer | | | | | 2615+------------------+------------+------------+--------------+---------------------------------------+ 2616| Management Long | Dynamic | 32 | NO | Wi-Fi driver's internal buffer. | 2617| Buffer | | | | | 2618+------------------+------------+------------+--------------+---------------------------------------+ 2619| Management Long | Dynamic | 32 | NO | Wi-Fi driver's internal buffer. | 2620| Long Buffer | | | | | 2621+------------------+------------+------------+--------------+---------------------------------------+ 2622 2623 2624 2625Wi-Fi NVS Flash 2626+++++++++++++++++++++ 2627If 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. 2628 2629Wi-Fi AMPDU 2630+++++++++++++++++++++++++++ 2631 2632{IDF_TARGET_NAME} supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput. 2633 2634Generally, the AMPDU should be enabled. Disabling AMPDU is usually for debugging purposes. 2635 2636Troubleshooting 2637--------------- 2638 2639Please refer to a separate document with :doc:`wireshark-user-guide`. 2640 2641.. toctree:: 2642 :hidden: 2643 2644 wireshark-user-guide 2645
