Lines Matching full:-
1 Wi-Fi Driver
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*…
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
20 How To Write a Wi-Fi Application
21 ----------------------------------
25 …-Fi application is to select an example which is similar to your own application, and port the use…
27 Setting Wi-Fi Compile-time Options
29 Refer to `Wi-Fi Menuconfig`_.
31 Init Wi-Fi
33 Refer to `{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_, `{IDF_TARGET_NAME} Wi-Fi AP General S…
35 Start/Connect Wi-Fi
37 Refer to `{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_, `{IDF_TARGET_NAME} Wi-Fi AP General S…
39 Event-Handling
41 …-day" scenarios, such as `WIFI_EVENT_STA_START`_, `WIFI_EVENT_STA_CONNECTED`_ etc. The hard part i…
43 Write Error-Recovery Routines Correctly at All Times
45 …ng of "rainy-day" scenarios, a good error-recovery routine is also fundamental to robust Wi-Fi app…
48 {IDF_TARGET_NAME} Wi-Fi API Error Code
49 --------------------------------------
50 All of the {IDF_TARGET_NAME} Wi-Fi APIs have well-defined return values, namely, the error code. Th…
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.
59 …robust application with Wi-Fi API is to always check the error code and write the error-handling c…
61 …- for recoverable errors, in which case you can write a recoverable-error code. For example, when …
62 …- for non-recoverable, yet non-critical, errors, in which case printing the error code is a good m…
63 …- for non-recoverable, critical errors, in which case "assert" may be a good method for error hand…
65 In esp_err.h, ESP_ERROR_CHECK checks the return values. It is a rather commonplace error-handling c…
66 …he default error-handling code in the application development phase. However, we strongly recommen…
68 {IDF_TARGET_NAME} Wi-Fi API Parameter Initialization
69 ----------------------------------------------------
73 - explicitly set all fields of the parameter
74 - use get API to get current configuration first, then set application specific fields
78 .. _wifi-programming-model:
80 {IDF_TARGET_NAME} Wi-Fi Programming Model
81 -----------------------------------------
82 The {IDF_TARGET_NAME} Wi-Fi programming model is depicted as follows:
85 :caption: Wi-Fi Programming Model
88 blockdiag wifi-programming-model {
102 WIFI_DRV [label="Wi-Fi\n Driver", width = 120, fontsize=12];
106 TCP_STACK -> EVNT_TASK [label=event];
107 EVNT_TASK -> APPL_TASK [label="callback\n or event"];
113 EVNT_TASK <- WIFI_DRV [label=event];
120 APPL_TASK -- KNOT;
122 WIFI_DRV <- KNOT [label="API\n call"];
126 …-Fi driver can be considered a black box that knows nothing about high-layer code, such as the TCP…
128 …-Fi event handling is based on the :doc:`esp_event library <../api-reference/system/esp_event>`. E…
130 {IDF_TARGET_NAME} Wi-Fi Event Description
131 -----------------------------------------
135 The Wi-Fi driver will never generate this event, which, as a result, can be ignored by the applicat…
139 The scan-done event is triggered by :cpp:func:`esp_wifi_scan_start()` and will arise in the followi…
141 …- The scan is completed, e.g., the target AP is found successfully, or all channels have been scan…
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 ov…
145 The scan-done event will not arise in the following scenarios:
147 - It is a blocked scan.
148 - The scan is caused by :cpp:func:`esp_wifi_connect()`.
150 …_wifi_scan_get_ap_records()` to fetch the scanned AP list and trigger the Wi-Fi driver to free the…
151 Refer to `{IDF_TARGET_NAME} Wi-Fi Scan`_ for a more detailed description.
155 If :cpp:func:`esp_wifi_start()` returns ESP_OK and the current Wi-Fi mode is Station or AP+Station,…
159 …-Fi mode is Station or AP+Station, then this event will arise. Upon receiving this event, the even…
163 …-Fi driver is ready for sending and receiving data. This moment is good for beginning the applicat…
169 …- When :cpp:func:`esp_wifi_disconnect()`, or :cpp:func:`esp_wifi_stop()`, or :cpp:func:`esp_wifi_d…
170 …- When :cpp:func:`esp_wifi_connect()` is called, but the Wi-Fi driver fails to set up a connection…
171 …- When the Wi-Fi connection is disrupted because of specific reasons, e.g., the station continuous…
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 socke…
178 …-Fi. However, if the event is raised because :cpp:func:`esp_wifi_disconnect()` is called, the appl…
182 - The application creates a TCP connection to maintain the application-level keep-alive data that i…
183 - Due to certain reasons, the Wi-Fi connection is cut off, and the `WIFI_EVENT_STA_DISCONNECTED`_ i…
184 - Five seconds later, the Wi-Fi connection is restored because :cpp:func:`esp_wifi_connect()` is ca…
185 - Sixty seconds later, when the application sends out data with the keep-alive socket, the socket r…
187 …plication sockets and the network layer should not be affected, since the Wi-Fi connection only fa…
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.
205 This event arises when the IPV6 SLAAC support auto-configures an address for the {IDF_TARGET_NAME},…
211 IP_STA_LOST_IP doesn't arise immediately after the Wi-Fi disconnects, instead it starts an IPV4 add…
231 …- The application calls :cpp:func:`esp_wifi_disconnect()`, or esp_wifi_deauth_sta(), to manually d…
232 …- The Wi-Fi driver kicks off the station, e.g. because the AP has not received any packets in the …
233 - The station kicks off the AP.
243 {IDF_TARGET_NAME} Wi-Fi Station General Scenario
244 ------------------------------------------------
248 :caption: Sample Wi-Fi Event Scenarios in Station Mode
251 seqdiag sample-scenarios-station-mode {
264 WIFI_TASK [label = "Wi-Fi\ntask"];
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"];
272 MAIN_TASK -> WIFI_TASK [label="2> Configure Wi-Fi"];
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"];
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"];
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"];
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"];
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"];
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"];
301 1. Wi-Fi/LwIP Init Phase
303 …- s1.1: The main task calls :cpp:func:`esp_netif_init()` to create an LwIP core task and initializ…
305 …- s1.2: The main task calls :cpp:func:`esp_event_loop_create` to create a system Event task and in…
307 …- s1.3: The main task calls :cpp:func:`esp_netif_create_default_wifi_ap()` or :cpp:func:`esp_netif…
309 …- s1.4: The main task calls :cpp:func:`esp_wifi_init()` to create the Wi-Fi driver task and initia…
311 - s1.5: The main task calls OS API to create the application task.
313 …is a recommended sequence that initializes a Wi-Fi-/LwIP-based application. However, it is **NOT**…
315 2. Wi-Fi Configuration Phase
317 …-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode …
319 …-Fi driver before setting up the Wi-Fi connection, but this is **NOT** mandatory, which means that…
321 …-Fi NVS flash is enabled by menuconfig, all Wi-Fi configuration in this phase, or later phases, wi…
323 3. Wi-Fi Start Phase
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 wil…
327 …- s3.3: The application event callback function relays the `WIFI_EVENT_STA_START`_ to the applicat…
329 4. Wi-Fi Connect Phase
331 …- s4.1: Once :cpp:func:`esp_wifi_connect()` is called, the Wi-Fi driver will start the internal sc…
333 …- s4.2: If the internal scan/connection process is successful, the `WIFI_EVENT_STA_CONNECTED`_ wil…
335 …- s4.3: In the above-mentioned scenario, the application event callback will relay the event to th…
337 …-Fi connection may fail because, for example, the password is wrong, the AP is not found, etc. In …
339 5. Wi-Fi 'Got IP' Phase
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…
344 …- s5.3: In the application event callback, `IP_EVENT_STA_GOT_IP`_ is relayed to the application ta…
346 6. Wi-Fi Disconnect Phase
348 …- s6.1: When the Wi-Fi connection is disrupted, e.g. because the AP is powered off, the RSSI is po…
349 …- s6.2: In the scenario described above, the application event callback function relays `WIFI_EVEN…
351 7. Wi-Fi IP Change Phase
354 …- s7.1: If the IP address is changed, the `IP_EVENT_STA_GOT_IP`_ will arise with "ip_change" set t…
355 …- s7.2: **This event is important to the application. When it occurs, the timing is good for closi…
358 8. Wi-Fi Deinit Phase
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.
366 {IDF_TARGET_NAME} Wi-Fi AP General Scenario
367 ---------------------------------------------
371 :caption: Sample Wi-Fi Event Scenarios in AP Mode
374 seqdiag sample-scenarios-soft-ap-mode {
387 WIFI_TASK [label = "Wi-Fi\ntask"];
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"];
395 MAIN_TASK -> WIFI_TASK [label="2> Configure Wi-Fi"];
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"];
401 EVENT_TASK <- WIFI_TASK [label="4.1> WIFI_EVENT_AP_STACONNECTED"];
402 APP_TASK <- EVENT_TASK [label="4.2> WIFI_EVENT_AP_STACONNECTED"];
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"];
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"];
414 {IDF_TARGET_NAME} Wi-Fi Scan
415 ----------------------------
422 +------------------+--------------------------------------------------------------+
428 +------------------+--------------------------------------------------------------+
434 +------------------+--------------------------------------------------------------+
435 | Foreground Scan | This scan is applicable when there is no Wi-Fi connection |
437 | | controlled by the Wi-Fi driver and cannot be configured by |
439 +------------------+--------------------------------------------------------------+
440 | Background Scan | This scan is applicable when there is a Wi-Fi connection in |
443 | | the Wi-Fi driver and cannot be configured by the application.|
445 +------------------+--------------------------------------------------------------+
446 | All-Channel Scan | It scans all of the channels. |
448 | | to 0, it is an all-channel scan. |
450 +------------------+--------------------------------------------------------------+
453 | | 1, it is a specific-channel scan. |
455 +------------------+--------------------------------------------------------------+
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
471 The scan type and other per-scan attributes are configured by :cpp:func:`esp_wifi_scan_start`. The …
473 +------------------+--------------------------------------------------------------+
479 +------------------+--------------------------------------------------------------+
483 +------------------+--------------------------------------------------------------+
484 | channel | If "channel" is 0, there will be an all-channel scan; |
485 | | otherwise, there will be a specific-channel scan. |
487 +------------------+--------------------------------------------------------------+
491 +------------------+--------------------------------------------------------------+
495 +------------------+--------------------------------------------------------------+
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 |
517 +------------------+--------------------------------------------------------------+
527 :caption: Foreground Scan of all Wi-Fi Channels
530 seqdiag foreground-scan-all-channels {
541 WIFI_TASK [label = "Wi-Fi\ntask"];
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"];
554 …-channel, foreground scan. The foreground scan can only occur in Station mode where the station do…
561 …- s1.1: Call :cpp:func:`esp_wifi_set_country()` to set the country info if the default country inf…
562 …- s1.2: Call :cpp:func:`esp_wifi_scan_start()` to configure the scan. To do so, you can refer to `…
565 Wi-Fi Driver's Internal Scan Phase
568 …- s2.1: The Wi-Fi driver switches to channel 1, in case the scan type is WIFI_SCAN_TYPE_ACTIVE, an…
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…
572 Scan-Done Event Handling Phase
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_S…
583 :caption: Background Scan of all Wi-Fi Channels
586 seqdiag background-scan-all-channels {
597 WIFI_TASK [label = "Wi-Fi\ntask"];
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"];
612 …-channel background scan. Compared to `Scan All APs on All Channels (Foreground)`_ , the differenc…
619 :caption: Scan of specific Wi-Fi Channels
622 seqdiag scan-specific-channels {
633 WIFI_TASK [label = "Wi-Fi\ntask"];
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"];
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 no…
654 Scan in Wi-Fi Connect
657 …-Fi driver will try to scan the configured AP first. The scan in "Wi-Fi Connect" is the same as `S…
662 …s done. The blocked scan is similar to an unblocked one, except that no scan-done event will arise…
666 …-done event. Both scenarios can happen. **However, the Wi-Fi driver does not support multiple conc…
668 Scan When Wi-Fi is Connecting
671 The :cpp:func:`esp_wifi_scan_start()` fails immediately if the Wi-Fi is in connecting process becau…
675 - The station is connecting a non-existed AP or if the station connects the existed AP with a wrong…
676 - The application call :cpp:func:`esp_wifi_connect()` to do reconnection on receiving the disconnec…
677 - Another application task, e.g. the console task, call :cpp:func:`esp_wifi_scan_start()` to do sca…
678 - When scan fails, the application simply delay sometime and retry the scan.
682 - The application can choose to define a maximum continuous reconnect counter, stop reconnect once …
683 - The application can choose to do reconnect immediately in the first N continous reconnect, then g…
685 …define its own reconnect strategy to avoid the scan starve to death. Refer to <`Wi-Fi Reconnect`_>.
687 {IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario
688 ---------------------------------------------------
690 …ore than one AP with the same SSID are found, refer to `{IDF_TARGET_NAME} Wi-Fi Station Connecting…
697 :caption: Wi-Fi Station Connecting Process
700 seqdiag station-connecting-process {
710 WIFI_TASK [label = "Wi-Fi\ntask"];
714 WIFI_TASK -> WIFI_TASK [label="1.1 > Scan"];
715 EVENT_TASK <- WIFI_TASK [label="1.2 > WIFI_EVENT_STA_DISCONNECTED"];
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"];
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"];
740 …- s1.1, The Wi-Fi driver begins scanning in "Wi-Fi Connect". Refer to `Scan in Wi-Fi Connect`_ for…
741 …- s1.2, If the scan fails to find the target AP, `WIFI_EVENT_STA_DISCONNECTED`_ will arise and the…
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 time…
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, w…
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_…
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, …
760 Four-way Handshake Phase
763 …- s4.1, The handshake timer is enabled, the 1/4 EAPOL is not received before the handshake timer e…
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_DISCO…
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`_.
772 Wi-Fi Reason Code
775 …-code defined in {IDF_TARGET_NAME}. The first column is the macro name defined in esp_wifi_types.h…
777 +---------------------------+-------+---------+----------------------------------------------------…
783 +---------------------------+-------+---------+----------------------------------------------------…
788 | | | | - auth is timed out. …
789 | | | | - the reason is received from the AP. …
793 | | | | - the AP has not received any packets from the sta…
795 | | | | - the AP is stopped by calling :cpp:func:`esp_wifi…
796 | | | | - the station is de-authed by calling …
798 +---------------------------+-------+---------+----------------------------------------------------…
799 | AUTH_LEAVE | 3 | 3 | De-authenticated, because the sending STA is …
804 | | | | - it is received from the AP. …
806 +---------------------------+-------+---------+----------------------------------------------------…
811 | | | | - it is received from the AP. …
815 | | | | - the AP has not received any packets from the …
817 | | | | - the AP is stopped by calling :cpp:func:`esp_wifi…
818 | | | | - the station is de-authed by calling …
820 +---------------------------+-------+---------+----------------------------------------------------…
826 | | | | - it is received from the AP. …
830 | | | | - the stations associated with the AP reach the …
833 +---------------------------+-------+---------+----------------------------------------------------…
834 | NOT_AUTHED | 6 | 6 | Class-2 frame received from a non-authenticated STA…
838 | | | | - it is received from the AP. …
842 | | | | - the AP receives a packet with data from a …
843 | | | | non-authenticated station. …
845 +---------------------------+-------+---------+----------------------------------------------------…
846 | NOT_ASSOCED | 7 | 7 | Class-3 frame received from a non-associated STA. …
850 | | | | - it is received from the AP. …
854 | | | | - the AP receives a packet with data from a …
855 | | | | non-associated station. …
857 +---------------------------+-------+---------+----------------------------------------------------…
863 | | | | - it is received from the AP. …
864 | | | | - the station is disconnected by …
867 +---------------------------+-------+---------+----------------------------------------------------…
873 | | | | - it is received from the AP. …
877 | | | | - the AP receives packets with data from an …
880 +---------------------------+-------+---------+----------------------------------------------------…
886 | | | | - it is received from the AP. …
888 +---------------------------+-------+---------+----------------------------------------------------…
894 | | | | - it is received from the AP. …
896 +---------------------------+-------+---------+----------------------------------------------------…
902 | | | | - it is received from the AP. …
906 | | | | - the AP parses a wrong WPA or RSN IE. …
908 +---------------------------+-------+---------+----------------------------------------------------…
913 | | | | - it is received from the AP. …
915 +---------------------------+-------+---------+----------------------------------------------------…
916 | 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, i…
917 | | | | this reason-code is replaced with …
922 | | | | - the handshake times out. …
923 | | | | - it is received from the AP. …
925 +---------------------------+-------+---------+----------------------------------------------------…
926 | GROUP_KEY_UPDATE_TIMEOUT | 16 | 16 | Group-Key Handshake times out. …
930 | | | | - it is received from the AP. …
932 +---------------------------+-------+---------+----------------------------------------------------…
933 | IE_IN_4WAY_DIFFERS | 17 | 17 | The element in the four-way handshake is different …
934 | | | | (Re-)Association Request/Probe and Response/Beacon …
938 | | | | - it is received from the AP. …
939 | | | | - the station finds that the four-way handshake IE…
940 | | | | from the IE in the (Re-)Association Request/Prob…
943 +---------------------------+-------+---------+----------------------------------------------------…
948 | | | | - it is received from the AP. …
950 +---------------------------+-------+---------+----------------------------------------------------…
955 | | | | - it is received from the AP. …
957 +---------------------------+-------+---------+----------------------------------------------------…
962 | | | | - it is received from the AP. …
964 +---------------------------+-------+---------+----------------------------------------------------…
969 | | | | - it is received from the AP. …
971 +---------------------------+-------+---------+----------------------------------------------------…
976 | | | | - it is received from the AP. …
978 +---------------------------+-------+---------+----------------------------------------------------…
983 | | | | - it is received from the AP. …
987 | | | | - 802.1 x authentication fails. …
989 +---------------------------+-------+---------+----------------------------------------------------…
994 | | | | - it is received from the AP. …
996 +---------------------------+-------+---------+----------------------------------------------------…
997 | BEACON_TIMEOUT | 200 |reserved | Espressif-specific Wi-Fi reason-code: when the stat…
1001 +---------------------------+-------+---------+----------------------------------------------------…
1002 | NO_AP_FOUND | 201 |reserved | Espressif-specific Wi-Fi reason-code: when the stat…
1005 +---------------------------+-------+---------+----------------------------------------------------…
1006 | AUTH_FAIL | 202 |reserved | Espressif-specific Wi-Fi reason-code: the …
1009 +---------------------------+-------+---------+----------------------------------------------------…
1010 | ASSOC_FAIL | 203 |reserved | Espressif-specific Wi-Fi reason-code: the associati…
1013 +---------------------------+-------+---------+----------------------------------------------------…
1014 | HANDSHAKE_TIMEOUT | 204 |reserved | Espressif-specific Wi-Fi reason-code: the …
1018 +---------------------------+-------+---------+----------------------------------------------------…
1019 | CONNECTION_FAIL | 205 |reserved | Espressif-specific Wi-Fi reason-code: the …
1022 +---------------------------+-------+---------+----------------------------------------------------…
1024 {IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found
1025 ----------------------------------------------------------------------
1027 This scenario is similar as `{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario`_, the difference …
1030 Wi-Fi Reconnect
1031 ---------------------------
1037 - If the disconnect event is raised because the :cpp:func:`esp_wifi_disconnect()` is called, the ap…
1038 - If the :cpp:func:`esp_wifi_scan_start()` may be called at anytime, a better reconnect strategy is…
1042 Wi-Fi Beacon Timeout
1043 ---------------------------
1049 {IDF_TARGET_NAME} Wi-Fi Configuration
1050 -------------------------------------
1052 …l configurations will be stored into flash when the Wi-Fi NVS is enabled; otherwise, refer to `Wi-…
1054 Wi-Fi Mode
1056 Call :cpp:func:`esp_wifi_set_mode()` to set the Wi-Fi mode.
1058 +------------------+--------------------------------------------------------------+
1064 | | RX/TX Wi-Fi data. Generally, this mode is used for Sniffer, |
1067 | | whole Wi-Fi driver. |
1068 +------------------+--------------------------------------------------------------+
1071 | | is ready for the RX and TX Wi-Fi data. After |
1074 +------------------+--------------------------------------------------------------+
1077 | | for RX/TX Wi-Fi data. Then, the Wi-Fi driver starts broad- |
1080 +------------------+--------------------------------------------------------------+
1081 | WIFI_MODE_APSTA | Station-AP coexistence mode: in this mode, |
1087 +------------------+--------------------------------------------------------------+
1094 +------------------+--------------------------------------------------------------+
1100 +------------------+--------------------------------------------------------------+
1103 +------------------+--------------------------------------------------------------+
1108 +------------------+--------------------------------------------------------------+
1114 +------------------+--------------------------------------------------------------+
1117 +------------------+--------------------------------------------------------------+
1124 +------------------+--------------------------------------------------------------+
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 |
1143 +------------------+--------------------------------------------------------------+
1149 | | RSSI threshold is -127 dBm. If the authmode threshold is set |
1152 +------------------+--------------------------------------------------------------+
1155 …WEP/WPA security modes are deprecated in IEEE 802.11-2016 specifications and are recommended not t…
1162 +------------------+--------------------------------------------------------------+
1169 +------------------+--------------------------------------------------------------+
1173 +------------------+--------------------------------------------------------------+
1178 +------------------+--------------------------------------------------------------+
1179 | channel | Channel of AP; if the channel is out of range, the Wi-Fi |
1182 | | For more details, refer to `Wi-Fi Country Code`_. |
1183 +------------------+--------------------------------------------------------------+
1184 | authmode | Auth mode of ESP AP; currently, ESP Wi-Fi does not |
1188 +------------------+--------------------------------------------------------------+
1192 +------------------+--------------------------------------------------------------+
1193 | max_connection | Currently, ESP Wi-Fi supports up to 10 Wi-Fi connections. |
1196 +------------------+--------------------------------------------------------------+
1200 +------------------+--------------------------------------------------------------+
1202 Wi-Fi Protocol Mode
1207 +--------------------+------------------------------------------------------------+
1211 | | the station/AP to 802.11B-only mode. |
1213 +--------------------+------------------------------------------------------------+
1217 +--------------------+------------------------------------------------------------+
1222 +--------------------+------------------------------------------------------------+
1226 | | Espressif-specific mode. |
1227 +--------------------+------------------------------------------------------------+
1229 | | the station/AP only to the Espressif-specific mode. |
1231 | | **This mode is an Espressif-patented mode which can achieve|
1232 | | a one-kilometer line of sight range. Please, make sure both|
1235 +--------------------+------------------------------------------------------------+
1240 … an Espressif-patented Wi-Fi mode which can achieve a one-kilometer line of sight range. It has be…
1245 …-Fi mode, only {IDF_TARGET_NAME} devices can transmit and receive the LR data. In other words, the…
1247 Following table depicts the Wi-Fi mode negotiation:
1249 +-------+-----+----+---+-------+------+-----+----+
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 +-------+-----+----+---+-------+------+-----+----+
1267 In above table, the row is the Wi-Fi mode of AP and the column is the Wi-Fi mode of station. The "-…
1271 …- For LR enabled in {IDF_TARGET_NAME} AP, it's incompatible with traditional 802.11 mode because t…
1272 …- For LR enabled in {IDF_TARGET_NAME} station and the mode is NOT LR only mode, it's compatible wi…
1273 …- If both station and AP are {IDF_TARGET_NAME} devices and both of them enable LR mode, the negoti…
1275 …-Fi mode supports both traditional 802.11 mode and LR mode, it's the Wi-Fi driver's responsibility…
1277 LR Impacts to Traditional Wi-Fi device
1280 The data transmission in LR rate has no impacts on the traditional Wi-Fi device because:
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.
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.
1306 Wi-Fi Country Code
1312 +------------------+-------------------------------------------------------------------------------…
1318 | | ISO/IEC3166-1. The third octect is one of the following: …
1320 | | - an ASCII space character, if the regulations under which the station/AP is …
1323 | | - an ASCII 'O' character if the regulations under which the station/AP is …
1325 | | - an ASCII 'I' character if the regulations under which the station/AP is …
1327 | | - an ASCII 'X' character if the station/AP is operating under a noncountry …
1330 | | - the binary representation of the Operating Class table number currently in …
1331 | | Refer to Annex E, IEEE Std 802.11-2012. …
1333 +------------------+-------------------------------------------------------------------------------…
1337 +------------------+-------------------------------------------------------------------------------…
1341 +------------------+-------------------------------------------------------------------------------…
1346 +------------------+-------------------------------------------------------------------------------…
1348 … {.cc="CN", .schan=1, .nchan=13, policy=WIFI_COUNTRY_POLICY_AUTO}, if the Wi-Fi Mode is station/AP…
1349 Following table depicts which country info is used in different Wi-Fi Mode and different country po…
1351 +-----------+----------------------------+---------------------------------------------------------…
1360 | | | -If schan+nchan-1 >11 : …
1362 | | | from 12 to schan+nchan-1. …
1364 | | | -If schan+nchan-1 <= 11 : …
1365 | | | Use active scan from schan to schan+nchan-1. …
1374 +-----------+----------------------------+---------------------------------------------------------…
1377 | | | For scan, scans channel "schan" to "schan+nchan-1" with …
1380 +-----------+----------------------------+---------------------------------------------------------…
1383 +-----------+----------------------------+---------------------------------------------------------…
1386 +-----------+----------------------------+---------------------------------------------------------…
1387 |Station/AP-| WIFI_COUNTRY_POLICY_AUTO | If the station doesn't connects to any AP, the AP use th…
1393 +-----------+----------------------------+---------------------------------------------------------…
1398 …efined as the channel of AP which the station is connected to. In Station/AP-coexistence mode, the…
1401 Wi-Fi Vendor IE Configuration
1404 …-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care…
1407 Wi-Fi Easy Connect™ (DPP)
1408 --------------------------
1410 Wi-Fi Easy Connect\ :sup:`TM` (or Device Provisioning Protocol) is a secure and standardized provis…
1411 More information can be found on the API reference page :doc:`esp_dpp <../api-reference/network/esp…
1413 WPA2-Enterprise
1416 WPA2-Enterprise is the secure authentication mechanism for enterprise wireless networks. It uses RA…
1419 …with Counter Mode Cipher Block Chaining Message Authentication protocol (AES-CCM) cipher suite. It…
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 a…
1426 - PAP: Password Authentication Protocol.
1427 - CHAP: Challenge Handshake Authentication Protocol.
1428 - MSCHAP and MSCHAP-V2.
1434 ----------------------------
1436 …luding information related to RF environment. This makes each client network-aware, facilitating o…
1437 - Network assisted Roaming: Enables WLAN to send messages to associated clients, resulting clients …
1442 ---------------------------
1452 Wi-Fi Location
1453 -------------------------------
1455 …-Fi Location will improve the accuracy of a device's location data beyond the Access Point, which …
1460 …sure Wi-Fi Round Trip Time (Wi-Fi RTT) which is the time a Wi-Fi signal takes to travel from a dev…
1461 …-Fi interface hardware at the time of arrival or departure of frames exchanged between a pair of d…
1464 - {IDF_TARGET_NAME} as FTM Initiator in Station mode.
1465 - {IDF_TARGET_NAME} as FTM Responder in SoftAP mode.
1467 …Distance measurement using RTT is not accurate, factors such as RF interference, multi-path travel…
1470 {IDF_TARGET_NAME} Wi-Fi Power-saving Mode
1471 -----------------------------------------
1476 …-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 …
1478 Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station…
1482 …-sleep minimum power save mode or ``esp_wifi_set_ps(WIFI_PS_MAX_MODEM)`` to enable Modem-sleep max…
1484 …-Fi data in real time. When modem sleep is enabled, received Wi-Fi data can be delayed for as long…
1486 The default Modem-sleep mode is WIFI_PS_MIN_MODEM.
1491 Currently {IDF_TARGET_NAME} AP doesn't support all of the power save feature defined in Wi-Fi speci…
1495 {IDF_TARGET_NAME} Wi-Fi Throughput
1496 -----------------------------------
1502 +----------------------+-----------------+-----------------+---------------+--------------+
1503 | Type/Throughput | Air In Lab | Shield-box | Test Tool | IDF Version |
1507 +----------------------+-----------------+-----------------+---------------+--------------+
1509 +----------------------+-----------------+-----------------+---------------+--------------+
1511 +----------------------+-----------------+-----------------+---------------+--------------+
1513 +----------------------+-----------------+-----------------+---------------+--------------+
1515 +----------------------+-----------------+-----------------+---------------+--------------+
1517 +----------------------+-----------------+-----------------+---------------+--------------+
1523 +----------------------+-----------------+-----------------+---------------+--------------+
1524 | Type/Throughput | Air In Lab | Shield-box | Test Tool | IDF Version |
1528 +----------------------+-----------------+-----------------+---------------+--------------+
1530 +----------------------+-----------------+-----------------+---------------+--------------+
1532 +----------------------+-----------------+-----------------+---------------+--------------+
1534 +----------------------+-----------------+-----------------+---------------+--------------+
1536 +----------------------+-----------------+-----------------+---------------+--------------+
1538 +----------------------+-----------------+-----------------+---------------+--------------+
1544 +----------------------+-----------------+-----------------+---------------+--------------+
1545 | Type/Throughput | Air In Lab | Shield-box | Test Tool | IDF Version |
1549 +----------------------+-----------------+-----------------+---------------+--------------+
1551 +----------------------+-----------------+-----------------+---------------+--------------+
1553 +----------------------+-----------------+-----------------+---------------+--------------+
1555 +----------------------+-----------------+-----------------+---------------+--------------+
1557 +----------------------+-----------------+-----------------+---------------+--------------+
1559 +----------------------+-----------------+-----------------+---------------+--------------+
1565 .. list-table::
1566 :header-rows: 1
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
1607 Wi-Fi 80211 Packet Send
1608 ---------------------------
1612 - Send the beacon, probe request, probe response, action frame.
1613 - Send the non-QoS data frame.
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 re…
1622 - The parameters of :cpp:func:`esp_wifi_80211_tx` are hereby correctly provided.
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 dat…
1630 Side-Effects to Avoid in Different Scenarios
1633 …-effects the API imposes on the Wi-Fi driver or other stations/APs, we can send a raw 802.11 packe…
1635 +-----------------------------+---------------------------------------------------+
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 |
1649 | | Side-effect example#1 |
1654 | | "other-AP", whose bssid is mac_x. If this |
1657 | | "other-AP" cannot figure out whether the beacon is|
1658 | | from the "other-AP" or the esp_wifi_80211_tx. |
1660 | | To avoid the above-mentioned side-effects, we |
1663 | | - If esp_wifi_80211_tx is called in Station mode,|
1665 | | exact target-device's MAC, while the second MAC|
1667 | | - If esp_wifi_80211_tx is called in AP mode, |
1669 | | exact target-device's MAC, while the second MAC|
1673 | | side-effects and can be ignored when there are |
1675 +-----------------------------+---------------------------------------------------+
1676 | Have WiFi connection | When the Wi-Fi connection is already set up, and |
1679 | | Wi-Fi connection, as a whole. So, the |
1683 | | The MAC-address recommendations in the |
1699 | | - If the packet type is data and is from the |
1704 | | - If the packet type is data and is from the |
1709 | | - If the packet is from station to AP or |
1711 | | More Data, Re-Transmission bits should be 0, |
1716 +-----------------------------+---------------------------------------------------+
1718 Wi-Fi Sniffer Mode
1719 ---------------------------
1721 The Wi-Fi sniffer mode can be enabled by esp_wifi_set_promiscuous(). If the sniffer mode is enabled…
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.
1730 - 802.11 error frame, such as the frame with a CRC error, etc.
1734 …-Fi sniffer mode can be enabled in the Wi-Fi mode of WIFI_MODE_NULL, or WIFI_MODE_STA, or WIFI_MOD…
1736 …llback wifi_promiscuous_cb_t. The callback will be called directly in the Wi-Fi driver task, so if…
1738 Wi-Fi Multiple Antennas
1739 --------------------------
1740 The Wi-Fi multiple antennas selecting can be depicted as following picture::
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
1753 …nna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3].…
1755 …nnected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpi…
1759 …T_MODE_ANT1, the enabled antenna 1 is selected for RX/TX data. Otherwise, Wi-Fi automatically sele…
1761 …ons are met, e.g. the RX antenna starts to switch if the RSSI is lower than -65 dBm and if another…
1765 …- The TX antenna can be set to WIFI_ANT_MODE_AUTO only if the RX antenna mode is WIFI_ANT_MODE_AUT…
1766 …- Currently Bluetooth® doesn't support the multiple antennas feature, please don't use multiple an…
1770 …- In Wi-Fi mode WIFI_MODE_STA, both RX/TX antenna modes are configured to WIFI_ANT_MODE_AUTO. The …
1771 …- The RX antenna mode is configured to WIFI_ANT_MODE_AUTO. The TX antenna mode is configured to WI…
1772 - Both RX/TX antenna modes are configured to WIFI_ANT_MODE_ANT0 or WIFI_ANT_MODE_ANT1.
1775 Wi-Fi Multiple Antennas Configuration
1780 …- Configure which GPIOs are connected to the antenna_selects, for example, if four antennas are su…
1786 …- Configure which antennas are enabled and how RX/TX use the enabled antennas, for example, if ant…
1796 Wi-Fi Channel State Information
1797 ------------------------------------
1799 …-Fi connection. In {IDF_TARGET_NAME}, this information consists of channel frequency responses of …
1801 …-------------+--------------------+-----------------------------------------+---------------------…
1803 …-------------+--------------------+-------------+---------------------------+----------+----------…
1805 …--------------------+-------------+---------------------------+----------+-----------------+------…
1807 …--------------------+-------------+-------------+-------------+----------+----------+------+------…
1809 …-------------+--------------------+-------------+-------------+-------------+----------+----------…
1810 …-carrier | LLTF | 0~31, -32~-1| 0~31, -32~-1| 0~31, -32~-1| 0~63 | 0~63 | 0~…
1811 …--------------------+-------------+-------------+-------------+----------+----------+------+------…
1812 …-LTF | - | 0~31, -32~-1| 0~31, -32~-1| - | 0~63 | 0~62 | 0~63, -6…
1813 …--------------------+-------------+-------------+-------------+----------+----------+------+------…
1814 …-HT-LTF | - | - | 0~31, -32~-1| - | - | 0~62 | - …
1815 …-------------+--------------------+-------------+-------------+-------------+----------+----------…
1817 …----------------------------------+-------------+-------------+-------------+----------+----------…
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 …
1827 …- If first_word_invalid field of wifi_csi_info_t is true, it means that the first four bytes of CS…
1828 …- More information like RSSI, noise floor of RF, receiving time and antenna is in the rx_ctrl fiel…
1832 …- For STBC packet, CSI is provided for every space-time stream without CSD (cyclic shift delay). A…
1833 …- If LLTF, HT-LTF or STBC-HT-LTF is not enabled by calling API :cpp:func:`esp_wifi_set_csi_config`…
1835 Wi-Fi Channel State Information Configure
1836 -------------------------------------------
1838 To use Wi-Fi CSI, the following steps need to be done.
1840 …- Select Wi-Fi CSI in menuconfig. It is "Menuconfig --> Components config --> Wi-Fi --> WiFi CSI(C…
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`.
1845 The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy operations in the c…
1847 Wi-Fi HT20/40
1848 -------------------------
1850 {IDF_TARGET_NAME} supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. :cpp:f…
1852 …-Fi connection. It is HT40 only if both the station and the connected AP support HT40, otherwise i…
1858 …device is used in some special environment, e.g. there are too many other Wi-Fi devices around the…
1860 Wi-Fi QoS
1861 -------------------------
1863 {IDF_TARGET_NAME} supports all the mandatory features required in WFA Wi-Fi QoS Certification.
1865 …-Fi specification, each AC has a its own priority to access the Wi-Fi channel. Moreover a map rule…
1867 Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in {IDF_TARGET_NAME}, it …
1869 +------------------+------------------------+-----------------+
1870 | IP Precedence | Wi-Fi AC | Support AMPDU? |
1873 +------------------+------------------------+-----------------+
1875 +------------------+------------------------+-----------------+
1877 +------------------+------------------------+-----------------+
1879 +------------------+------------------------+-----------------+
1888 …ity AC, however, it's not always be true, here are some suggestions about how to use the Wi-Fi QoS:
1890 …- For some really important application traffic, can put it into AC_VO queue. Avoid sending big tr…
1891 …- Avoid using more than two different AMPDU supported precedences, e.g. socket A uses precedence 0…
1894 Wi-Fi AMSDU
1895 -------------------------
1899 Wi-Fi Fragment
1900 -------------------------
1904 supports Wi-Fi receiving fragment, but doesn't support Wi-Fi transmitting fragment.
1908 {IDF_TARGET_NAME} supports Wi-Fi receiving and transmitting fragment.
1911 -------------------------
1913 {IDF_TARGET_NAME} supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Cur…
1915 .. _wifi-buffer-usage:
1917 Wi-Fi Buffer Usage
1918 --------------------------
1925 In order to get a , high-performance system, we need to consider the memory usage/configuration ver…
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…
1929 …- it is very dangerous to run out of heap memory, as this will cause {IDF_TARGET_NAME} an "undefin…
1930 …- the Wi-Fi throughput heavily depends on memory-related configurations, such as the TCP window si…
1931 …- the peak heap memory that the {IDF_TARGET_NAME} LwIP/Wi-Fi may consume depends on a number of fa…
1932 …- the total memory that the application requires is also an important factor when considering memo…
1934 Due to these reasons, there is not a good-for-all application configuration. Rather, we have to con…
1939 …-Fi drivers is "dynamic". Most of the time the dynamic buffer can significantly save memory. Howev…
1941 …dynamic. See :ref:`lwIP documentation section about memory use and performance <lwip-performance>`.
1943 Peak Wi-Fi Dynamic Buffer
1946 The Wi-Fi driver supports several types of buffer (refer to `Wi-Fi Buffer Configure`_). However, th…
1947 The peak heap memory that Wi-Fi consumes is the **theoretically-maximum memory** that the Wi-Fi dri…
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
1954 So, the peak memory that the Wi-Fi driver consumes can be calculated with the following formula:
1960 .. _How-to-improve-Wi-Fi-performance:
1962 How to improve Wi-Fi performance
1963 ----------------------------------
1965 The performance of {IDF_TARGET_NAME} Wi-Fi is affected by many parameters, and there are mutual con…
1967 In this section, we will briefly explain the operating mode of the Wi-Fi/LWIP protocol stack and ex…
1972 .. figure:: ../../_static/api-guides-WiFi-driver-how-to-improve-WiFi-performance.png
1977 The {IDF_TARGET_NAME} protocol stack is divided into four layers: Application, LWIP, Wi-Fi, and Har…
1979 …- During receiving, hardware puts the received packet into DMA buffer, and then transfers it into …
1981 …- During sending, the application copies the messages to be sent into the TX buffer of the LWIP la…
1986 Increasing the size or number of the buffers mentioned above properly can improve Wi-Fi performance…
1990 - :ref:`CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM`
1991 …sing this parameter will increase the sender's one-time receiving throughput, thereby improving th…
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 wil…
1996 - :ref:`CONFIG_ESP32_WIFI_RX_BA_WIN`
1999 - :ref:`CONFIG_LWIP_TCP_WND_DEFAULT`
2004 - :ref:`CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM`
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 wil…
2010 - :ref:`CONFIG_LWIP_TCP_SND_BUF_DEFAULT`
2017 - :ref:`CONFIG_ESP32_WIFI_IRAM_OPT`
2018 …If this option is enabled, some Wi-Fi functions are moved to IRAM, improving throughput. This incr…
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 i…
2023 - :ref:`CONFIG_LWIP_IRAM_OPTIMIZATION`
2030 - :ref:`CONFIG_ESP32S2_INSTRUCTION_CACHE_SIZE`
2033 - :ref:`CONFIG_ESP32S2_INSTRUCTION_CACHE_LINE_SIZE`
2040 - :ref:`CONFIG_ESP32S3_INSTRUCTION_CACHE_SIZE`
2043 - :ref:`CONFIG_ESP32S3_INSTRUCTION_CACHE_LINE_SIZE`
2046 - :ref:`CONFIG_ESP32S3_ICACHE_ASSOCIATED_WAYS`
2049 - :ref:`CONFIG_ESP32S3_DATA_CACHE_SIZE`
2052 - :ref:`CONFIG_ESP32S3_DATA_CACHE_LINE_SIZE`
2055 - :ref:`CONFIG_ESP32S3_DCACHE_ASSOCIATED_WAYS`
2072 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2073 …| Rank | Iperf | TX prior | High-performance | RX prior | Default | Memory s…
2076 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2078 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2080 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2082 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2084 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2086 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2088 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2090 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2092 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2094 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2096 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2098 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2100 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2102 …+----------------------------+-------+----------+------------------+----------+---------+---------…
2106 +----------------------------+-------+------------------+---------+---------------+---------+
2107 | Rank | Iperf | High-performance | Default | Memory saving | Minimum |
2110 +----------------------------+-------+------------------+---------+---------------+---------+
2112 +----------------------------+-------+------------------+---------+---------------+---------+
2114 +----------------------------+-------+------------------+---------+---------------+---------+
2116 +----------------------------+-------+------------------+---------+---------------+---------+
2118 +----------------------------+-------+------------------+---------+---------------+---------+
2120 +----------------------------+-------+------------------+---------+---------------+---------+
2122 +----------------------------+-------+------------------+---------+---------------+---------+
2124 +----------------------------+-------+------------------+---------+---------------+---------+
2126 +----------------------------+-------+------------------+---------+---------------+---------+
2128 +----------------------------+-------+------------------+---------+---------------+---------+
2130 +----------------------------+-------+------------------+---------+---------------+---------+
2132 +----------------------------+-------+------------------+---------+---------------+---------+
2134 +----------------------------+-------+------------------+---------+---------------+---------+
2136 +----------------------------+-------+------------------+---------+---------------+---------+
2138 +----------------------------+-------+------------------+---------+---------------+---------+
2140 +----------------------------+-------+------------------+---------+---------------+---------+
2144 +----------------------------+-------+---------+---------+
2148 +----------------------------+-------+---------+---------+
2150 +----------------------------+-------+---------+---------+
2152 +----------------------------+-------+---------+---------+
2154 +----------------------------+-------+---------+---------+
2156 +----------------------------+-------+---------+---------+
2158 +----------------------------+-------+---------+---------+
2160 +----------------------------+-------+---------+---------+
2162 +----------------------------+-------+---------+---------+
2164 +----------------------------+-------+---------+---------+
2166 +----------------------------+-------+---------+---------+
2168 +----------------------------+-------+---------+---------+
2170 +----------------------------+-------+---------+---------+
2174 +----------------------------+-------+---------+---------+
2178 +----------------------------+-------+---------+---------+
2180 +----------------------------+-------+---------+---------+
2182 +----------------------------+-------+---------+---------+
2184 +----------------------------+-------+---------+---------+
2186 +----------------------------+-------+---------+---------+
2188 +----------------------------+-------+---------+---------+
2190 +----------------------------+-------+---------+---------+
2192 +----------------------------+-------+---------+---------+
2194 +----------------------------+-------+---------+---------+
2196 +----------------------------+-------+---------+---------+
2198 +----------------------------+-------+---------+---------+
2200 +----------------------------+-------+---------+---------+
2202 +----------------------------+-------+---------+---------+
2204 +----------------------------+-------+---------+---------+
2206 +----------------------------+-------+---------+---------+
2208 +----------------------------+-------+---------+---------+
2210 +----------------------------+-------+---------+---------+
2215 The test was performed with a single stream in a shielded box using an ASUS RT-N66U router.
2221 The test was performed with a single stream in a shielded box using an ASUS RT-N66U router.
2227 The test was performed with a single stream in a shielded box using an ASUS RT-N66U router.
2234 - **Iperf rank**
2237 - **High-performance rank**
2238 …F_TARGET_NAME}'s high-performance configuration rank, suitable for scenarios that the application …
2240 - **Default rank**
2243 - **Memory saving rank**
2246 - **Minimum rank**
2253 - **Iperf rank**
2256 - **High-performance rank**
2257 …F_TARGET_NAME}'s high-performance configuration rank, suitable for scenarios that the application …
2259 - **Default rank**
2262 - **Memory saving rank**
2265 - **Minimum rank**
2272 - **Iperf rank**
2275 - **Default rank**
2278 - **Minimum rank**
2291 +----------------------------+-------+---------+---------------+---------+
2295 +----------------------------+-------+---------+---------------+---------+
2297 +----------------------------+-------+---------+---------------+---------+
2299 +----------------------------+-------+---------+---------------+---------+
2301 +----------------------------+-------+---------+---------------+---------+
2303 +----------------------------+-------+---------+---------------+---------+
2305 +----------------------------+-------+---------+---------------+---------+
2307 +----------------------------+-------+---------+---------------+---------+
2309 +----------------------------+-------+---------+---------------+---------+
2311 +----------------------------+-------+---------+---------------+---------+
2313 +----------------------------+-------+---------+---------------+---------+
2315 +----------------------------+-------+---------+---------------+---------+
2317 +----------------------------+-------+---------+---------------+---------+
2319 +----------------------------+-------+---------+---------------+---------+
2321 +----------------------------+-------+---------+---------------+---------+
2325 +----------------------------+-------+---------+---------------+---------+
2329 +----------------------------+-------+---------+---------------+---------+
2331 +----------------------------+-------+---------+---------------+---------+
2333 +----------------------------+-------+---------+---------------+---------+
2335 +----------------------------+-------+---------+---------------+---------+
2337 +----------------------------+-------+---------+---------------+---------+
2339 +----------------------------+-------+---------+---------------+---------+
2341 +----------------------------+-------+---------+---------------+---------+
2343 +----------------------------+-------+---------+---------------+---------+
2345 +----------------------------+-------+---------+---------------+---------+
2347 +----------------------------+-------+---------+---------------+---------+
2349 +----------------------------+-------+---------+---------------+---------+
2351 +----------------------------+-------+---------+---------------+---------+
2353 +----------------------------+-------+---------+---------------+---------+
2355 +----------------------------+-------+---------+---------------+---------+
2357 +----------------------------+-------+---------+---------------+---------+
2359 +----------------------------+-------+---------+---------------+---------+
2361 +----------------------------+-------+---------+---------------+---------+
2363 +----------------------------+-------+---------+---------------+---------+
2372 +----------------------------+-------+--------+---------------+----------+
2376 +----------------------------+-------+--------+---------------+----------+
2378 +----------------------------+-------+--------+---------------+----------+
2380 +----------------------------+-------+--------+---------------+----------+
2382 +----------------------------+-------+--------+---------------+----------+
2384 +----------------------------+-------+--------+---------------+----------+
2386 +----------------------------+-------+--------+---------------+----------+
2388 +----------------------------+-------+--------+---------------+----------+
2390 +----------------------------+-------+--------+---------------+----------+
2392 +----------------------------+-------+--------+---------------+----------+
2394 +----------------------------+-------+--------+---------------+----------+
2396 +----------------------------+-------+--------+---------------+----------+
2398 +----------------------------+-------+--------+---------------+----------+
2400 +----------------------------+-------+--------+---------------+----------+
2402 +----------------------------+-------+--------+---------------+----------+
2404 +----------------------------+-------+--------+---------------+----------+
2406 +----------------------------+-------+--------+---------------+----------+
2408 +----------------------------+-------+--------+---------------+----------+
2410 +----------------------------+-------+--------+---------------+----------+
2412 +----------------------------+-------+--------+---------------+----------+
2414 +----------------------------+-------+--------+---------------+----------+
2416 +----------------------------+-------+--------+---------------+----------+
2420 +----------------------------+-------+--------+---------------+----------+
2424 +----------------------------+-------+--------+---------------+----------+
2426 +----------------------------+-------+--------+---------------+----------+
2428 +----------------------------+-------+--------+---------------+----------+
2430 +----------------------------+-------+--------+---------------+----------+
2432 +----------------------------+-------+--------+---------------+----------+
2434 +----------------------------+-------+--------+---------------+----------+
2436 +----------------------------+-------+--------+---------------+----------+
2438 +----------------------------+-------+--------+---------------+----------+
2440 +----------------------------+-------+--------+---------------+----------+
2442 +----------------------------+-------+--------+---------------+----------+
2444 +----------------------------+-------+--------+---------------+----------+
2446 +----------------------------+-------+--------+---------------+----------+
2448 +----------------------------+-------+--------+---------------+----------+
2450 +----------------------------+-------+--------+---------------+----------+
2452 +----------------------------+-------+--------+---------------+----------+
2454 +----------------------------+-------+--------+---------------+----------+
2456 +----------------------------+-------+--------+---------------+----------+
2458 +----------------------------+-------+--------+---------------+----------+
2460 +----------------------------+-------+--------+---------------+----------+
2462 +----------------------------+-------+--------+---------------+----------+
2464 +----------------------------+-------+--------+---------------+----------+
2466 Wi-Fi Menuconfig
2467 -----------------------
2469 Wi-Fi Buffer Configure
2490 WIFI_TASK [label="Wi-Fi\n task", fontsize=12];
2498 APPL_TASK -> LwIP_TASK -> WIFI_TASK
2499 APPL_DESC -> LwIP_DESC -> WIFI_DESC [style=none]
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…
2507 …- When LwIP calls a Wi-Fi API to send the PBUF, the Wi-Fi API will allocate a "Dynamic Tx Buffer" …
2527 WIFI_TASK [label="Wi-Fi\n task", fontsize=12];
2528 WIFI_INTR [label="Wi-Fi\n interrupt", fontsize=12];
2537 APPL_TASK <- LwIP_TASK <- WIFI_TASK <- WIFI_INTR
2538 APPL_DESC <- LwIP_DESC <- WIFI_DESC <- INTR_DESC [style=none]
2543 …- The Wi-Fi hardware receives a packet over the air and puts the packet content to the "Static Rx …
2544 …- The Wi-Fi driver allocates a "Dynamic Rx Buffer", makes a copy of the "Static Rx Buffer", and re…
2545 …- The Wi-Fi driver delivers the packet to the upper-layer (LwIP), and allocates a PBUF for holding…
2546 - The application receives data from LwIP.
2548 The diagram shows the configuration of the Wi-Fi internal buffer.
2550 +------------------+------------+------------+--------------+--------------------------------------…
2561 | | | | | interrupt to the CPU. Then, the Wi-Fi…
2568 | | | | | Wi-Fi, they can reduce this value fro…
2574 +------------------+------------+------------+--------------+--------------------------------------…
2577 | | | | | length. When the Wi-Fi driver receive…
2583 | | | | | total un-freed Dynamic Rx Buffer …
2585 +------------------+------------+------------+--------------+--------------------------------------…
2587 … | | | | allocated to the heap. When the upper-|
2589 | | | | | Wi-Fi driver, it firstly allocates a …
2591 | | | | | of the upper-layer buffer. …
2595 +------------------+------------+------------+--------------+--------------------------------------…
2600 | | | | | the upper-layer (LwIP) sends packets …
2601 | | | | | to the Wi-Fi driver, it firstly …
2603 | | | | | makes a copy of the upper-layer …
2612 +------------------+------------+------------+--------------+--------------------------------------…
2613 | Management Short | Dynamic | 8 | NO | Wi-Fi driver's internal buffer. …
2615 +------------------+------------+------------+--------------+--------------------------------------…
2616 | Management Long | Dynamic | 32 | NO | Wi-Fi driver's internal buffer. …
2618 +------------------+------------+------------+--------------+--------------------------------------…
2619 | Management Long | Dynamic | 32 | NO | Wi-Fi driver's internal buffer. …
2621 +------------------+------------+------------+--------------+--------------------------------------…
2625 Wi-Fi NVS Flash
2627 …-Fi NVS flash is enabled, all Wi-Fi configurations set via the Wi-Fi APIs will be stored into flas…
2629 Wi-Fi AMPDU
2632 …supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput.
2637 ---------------
2639 Please refer to a separate document with :doc:`wireshark-user-guide`.
2644 wireshark-user-guide