docs/en/api-guides/wifi-driver/station-scenarios.rst
:link_to_translation:zh_CN:[中文]
.. _wifi-station-general-scenario:
Below is a "big scenario" which describes some small scenarios in station mode:
.. seqdiag:: :caption: Sample Wi-Fi Event Scenarios in Station Mode :align: center
seqdiag sample-scenarios-station-mode {
activation = none;
node_width = 80;
node_height = 60;
edge_length = 140;
span_height = 5;
default_shape = roundedbox;
default_fontsize = 12;
MAIN_TASK [label = "Main\ntask"];
APP_TASK [label = "App\ntask"];
EVENT_TASK [label = "Event\ntask"];
LwIP_TASK [label = "LwIP\ntask"];
WIFI_TASK [label = "Wi-Fi\ntask"];
=== 1. Init Phase ===
MAIN_TASK -> LwIP_TASK [label="1.1> Create / init LwIP"];
MAIN_TASK -> EVENT_TASK [label="1.2> Create / init event"];
MAIN_TASK -> WIFI_TASK [label="1.3> Create / init Wi-Fi"];
MAIN_TASK -> APP_TASK [label="1.4> Create app task"];
=== 2. Configure Phase ===
MAIN_TASK -> WIFI_TASK [label="2> Configure Wi-Fi"];
=== 3. Start Phase ===
MAIN_TASK -> WIFI_TASK [label="3.1> Start Wi-Fi"];
EVENT_TASK <- WIFI_TASK [label="3.2> WIFI_EVENT_STA_START"];
APP_TASK <- EVENT_TASK [label="3.3> WIFI_EVENT_STA_START"];
=== 4. Connect Phase ===
APP_TASK -> WIFI_TASK [label="4.1> Connect Wi-Fi"];
EVENT_TASK <- WIFI_TASK [label="4.2> WIFI_EVENT_STA_CONNECTED"];
APP_TASK <- EVENT_TASK [label="4.3> WIFI_EVENT_STA_CONNECTED"];
=== 5. Got IP Phase ===
EVENT_TASK -> LwIP_TASK [label="5.1> Start DHCP client"];
EVENT_TASK <- LwIP_TASK [label="5.2> IP_EVENT_STA_GOT_IP"];
APP_TASK <- EVENT_TASK [label="5.3> IP_EVENT_STA_GOT_IP"];
APP_TASK -> APP_TASK [label="5.4> socket related init"];
=== 6. Disconnect Phase ===
EVENT_TASK <- WIFI_TASK [label="6.1> WIFI_EVENT_STA_DISCONNECTED"];
APP_TASK <- EVENT_TASK [label="6.2> WIFI_EVENT_STA_DISCONNECTED"];
APP_TASK -> APP_TASK [label="6.3> disconnect handling"];
=== 7. IP Change Phase ===
EVENT_TASK <- LwIP_TASK [label="7.1> IP_EVENT_STA_GOT_IP"];
APP_TASK <- EVENT_TASK [label="7.2> IP_EVENT_STA_GOT_IP"];
APP_TASK -> APP_TASK [label="7.3> Socket error handling"];
=== 8. Deinit Phase ===
APP_TASK -> WIFI_TASK [label="8.1> Disconnect Wi-Fi"];
APP_TASK -> WIFI_TASK [label="8.2> Stop Wi-Fi"];
APP_TASK -> WIFI_TASK [label="8.3> Deinit Wi-Fi"];
}
s1.1: The main task calls :cpp:func:esp_netif_init() to create an LwIP core task and initialize LwIP-related work.
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.
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.
s1.4: The main task calls :cpp:func:esp_wifi_init() to create the Wi-Fi driver task and initialize the Wi-Fi driver.
s1.5: The main task calls OS API to create the application task.
Step 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 initialization 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.
Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is station, so you may need to call :cpp:func:esp_wifi_set_mode (WIFI_MODE_STA) to configure the Wi-Fi mode as station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, the country code, and the bandwidth. Refer to :ref:wifi-configuration.
Generally, the Wi-Fi driver should be configured before the Wi-Fi connection is set up. 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.
If 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.
esp_wifi_start() to start the Wi-Fi driver.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.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 :ref:wifi-event-sta-start arises.s4.1: Once :cpp:func:esp_wifi_connect() is called, the Wi-Fi driver will start the internal scan/connection process.
s4.2: If the internal scan/connection process is successful, the :ref:wifi-event-sta-connected will be generated. In the event task, it starts the DHCP client, which will finally trigger the DHCP process.
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.
In step 4.2, the Wi-Fi connection may fail because, for example, the password is wrong, or the AP is not found. In a case like this, :ref: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.
ip-event-sta-got-ip will arise and the event task will perform common handling.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. A very common mistake is to initialize the socket before :ref:ip-event-sta-got-ip is received. DO NOT start the socket-related work before the IP is received.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.wifi-event-sta-disconnected to the application task. The recommended actions are: 1) call :cpp:func:esp_wifi_connect() to reconnect the Wi-Fi, 2) close all sockets, and 3) re-create them if necessary. For details, please refer to :ref:wifi-event-sta-disconnected.ip-event-sta-got-ip will arise with "ip_change" set to true.esp_wifi_disconnect() to disconnect the Wi-Fi connectivity.esp_wifi_stop() to stop the Wi-Fi driver.esp_wifi_deinit() to unload the Wi-Fi driver... _wifi-scan:
Currently, the :cpp:func:esp_wifi_scan_start() API is supported only in station or station/AP mode.
Scan Type +++++++++++++++++++++++++
.. list-table:: :header-rows: 1 :widths: 15 50
wifi_scan_config_t.wifi_scan_config_t is set to 0, it is an all-channel scan.wifi_scan_config_t set to 1-14, it is a specific-channel scan.The scan modes in above table can be combined arbitrarily, so there are in total 8 different scans:
Scan Configuration +++++++++++++++++++++++++++++++++++++++
The scan type and other per-scan attributes are configured by :cpp:func:esp_wifi_scan_start(). The table below provides a detailed description of :cpp:type:wifi_scan_config_t.
.. list-table:: :header-rows: 1 :widths: 15 50
scan_time
This field is used to control how long the scan dwells on each channel.
For passive scans, scan_time.passive designates the dwell time for each channel.
For active scans, dwell times for each channel are listed in the table below. Here, min is short for scan time.active.min and max is short for scan_time.active.max.
max ms.min ms. If no AP is found during this time frame, the scan switches to the next channel. Otherwise, the scan dwells on the channel for max ms.If you want to improve the performance of the scan, you can try to modify these two parameters.
There are also some global scan attributes which are configured by API :cpp:func:esp_wifi_set_config(), refer to :ref:Station Basic Configuration <station-basic-configuration>.
Scan All APs on All Channels (Foreground) +++++++++++++++++++++++++++++++++++++++++++++
Scenario:
.. seqdiag:: :caption: Foreground Scan of all Wi-Fi Channels :align: center
seqdiag foreground-scan-all-channels {
activation = none;
node_width = 80;
node_height = 60;
edge_length = 160;
span_height = 5;
default_shape = roundedbox;
default_fontsize = 12;
APP_TASK [label = "App\ntask"];
EVENT_TASK [label = "Event\ntask"];
WIFI_TASK [label = "Wi-Fi\ntask"];
APP_TASK -> WIFI_TASK [label="1.1 > Configure country code"];
APP_TASK -> WIFI_TASK [label="1.2 > Scan configuration"];
WIFI_TASK -> WIFI_TASK [label="2.1 > Scan channel 1"];
WIFI_TASK -> WIFI_TASK [label="2.2 > Scan channel 2"];
WIFI_TASK -> WIFI_TASK [label="..."];
WIFI_TASK -> WIFI_TASK [label="2.x > Scan channel N"];
EVENT_TASK <- WIFI_TASK [label="3.1 > WIFI_EVENT_SCAN_DONE"];
APP_TASK <- EVENT_TASK [label="3.2 > WIFI_EVENT_SCAN_DONE"];
}
The scenario above describes an all-channel, foreground scan. The foreground scan can only occur in station mode where the station does not connect to any AP. Whether it is a foreground or background scan is totally determined by the Wi-Fi driver, and cannot be configured by the application.
Detailed scenario description:
Scan Configuration Phase
esp_wifi_set_country() to set the country info if the default country info is not what you want. Refer to :ref:Wi-Fi Country Code <wifi-country-code>.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.Wi-Fi Driver's Internal Scan Phase
Scan-Done Event Handling Phase
wifi-event-scan-done will arise.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.Scan All APs on All Channels (Background) ++++++++++++++++++++++++++++++++++++++++++
Scenario:
.. seqdiag:: :caption: Background Scan of all Wi-Fi Channels :align: center
seqdiag background-scan-all-channels {
activation = none;
node_width = 80;
node_height = 60;
edge_length = 160;
span_height = 5;
default_shape = roundedbox;
default_fontsize = 12;
APP_TASK [label = "App\ntask"];
EVENT_TASK [label = "Event\ntask"];
WIFI_TASK [label = "Wi-Fi\ntask"];
APP_TASK -> WIFI_TASK [label="1.1 > Configure country code"];
APP_TASK -> WIFI_TASK [label="1.2 > Scan configuration"];
WIFI_TASK -> WIFI_TASK [label="2.1 > Scan channel 1"];
WIFI_TASK -> WIFI_TASK [label="2.2 > Back to home channel H"];
WIFI_TASK -> WIFI_TASK [label="2.3 > Scan channel 2"];
WIFI_TASK -> WIFI_TASK [label="2.4 > Back to home channel H"];
WIFI_TASK -> WIFI_TASK [label="..."];
WIFI_TASK -> WIFI_TASK [label="2.x-1 > Scan channel N"];
WIFI_TASK -> WIFI_TASK [label="2.x > Back to home channel H"];
EVENT_TASK <- WIFI_TASK [label="3.1 > WIFI_EVENT_SCAN_DONE"];
APP_TASK <- EVENT_TASK [label="3.2 > WIFI_EVENT_SCAN_DONE"];
}
The 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.
Scan for Specific AP on All Channels +++++++++++++++++++++++++++++++++++++++
Scenario:
.. seqdiag:: :caption: Scan of specific Wi-Fi Channels :align: center
seqdiag scan-specific-channels {
activation = none;
node_width = 80;
node_height = 60;
edge_length = 160;
span_height = 5;
default_shape = roundedbox;
default_fontsize = 12;
APP_TASK [label = "App\ntask"];
EVENT_TASK [label = "Event\ntask"];
WIFI_TASK [label = "Wi-Fi\ntask"];
APP_TASK -> WIFI_TASK [label="1.1 > Configure country code"];
APP_TASK -> WIFI_TASK [label="1.2 > Scan configuration"];
WIFI_TASK -> WIFI_TASK [label="2.1 > Scan channel C1"];
WIFI_TASK -> WIFI_TASK [label="2.2 > Scan channel C2"];
WIFI_TASK -> WIFI_TASK [label="..."];
WIFI_TASK -> WIFI_TASK [label="2.x > Scan channel CN, or the AP is found"];
EVENT_TASK <- WIFI_TASK [label="3.1 > WIFI_EVENT_SCAN_DONE"];
APP_TASK <- EVENT_TASK [label="3.2 > WIFI_EVENT_SCAN_DONE"];
}
This scan is similar to Scan All APs on All Channels (Foreground)_. The differences are:
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.It is a possible situation that there are multiple APs that match the target AP info, e.g., two APs with the SSID of "ap" are scanned. In this case, 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 :ref:Station Basic Configuration <station-basic-configuration>.
You can scan a specific AP, or all of them, in any given channel. These two scenarios are very similar.
.. _scan-in-wifi-connect:
Scan in Wi-Fi Connect +++++++++++++++++++++++++
When :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, :ref:wifi-event-sta-disconnected will be generated. Refer to Scan for Specific AP On All Channels.
Scan in Blocked Mode ++++++++++++++++++++
If 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.
Parallel Scan +++++++++++++
Two 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.
.. _scan-when-wifi-is-connecting:
Scan When Wi-Fi Is Connecting +++++++++++++++++++++++++++++++
The :cpp:func:esp_wifi_scan_start() fails immediately if the Wi-Fi is connecting, because the connecting has higher priority than the scan. If scan fails because of connecting, the recommended strategy is to delay for some time and retry scan again. The scan will succeed once the connecting is completed.
However, the retry/delay strategy may not work all the time. Considering the following scenarios:
wifi-event-sta-disconnected.esp_wifi_connect() to reconnect on receiving the disconnect event.esp_wifi_scan_start() to do scan, the scan always fails immediately because the station keeps connecting.In the above scenarios, the scan will never succeed because the connecting is in process. So if the application supports similar scenario, it needs to implement a better reconnection strategy. For example:
The application can define its own reconnection strategy to avoid the scan starve to death. Refer to :ref:wifi-reconnect.
.. _wifi-station-connecting-scenario:
This scenario depicts the case if only one target AP is found in the scan phase. For scenarios where more than one AP with the same SSID is found, refer to :ref:wifi-station-connecting-when-multiple-aps-are-found.
Generally, the application can ignore the connecting process. Below is a brief introduction to the process for those who are really interested.
Scenario:
.. seqdiag:: :caption: Wi-Fi Station Connecting Process :align: center
seqdiag station-connecting-process {
activation = none;
node_width = 80;
node_height = 60;
edge_length = 160;
span_height = 5;
default_shape = roundedbox;
default_fontsize = 12;
EVENT_TASK [label = "Event\ntask"];
WIFI_TASK [label = "Wi-Fi\ntask"];
AP [label = "AP"];
=== 1. Scan Phase ===
WIFI_TASK -> WIFI_TASK [label="1.1 > Scan"];
EVENT_TASK <- WIFI_TASK [label="1.2 > WIFI_EVENT_STA_DISCONNECTED"];
=== 2. Auth Phase ===
WIFI_TASK -> AP [label="2.1 > Auth request"];
EVENT_TASK <- WIFI_TASK [label="2.2 > WIFI_EVENT_STA_DISCONNECTED"];
WIFI_TASK <- AP [label="2.3 > Auth response"];
EVENT_TASK <- WIFI_TASK [label="2.4 > WIFI_EVENT_STA_DISCONNECTED"];
=== 3. Assoc Phase ===
WIFI_TASK -> AP [label="3.1 > Assoc request"];
EVENT_TASK <- WIFI_TASK [label="3.2 > WIFI_EVENT_STA_DISCONNECTED"];
WIFI_TASK <- AP [label="3.3 > Assoc response"];
EVENT_TASK <- WIFI_TASK [label="3.4 > WIFI_EVENT_STA_DISCONNECTED"];
=== 4. 4-way Handshake Phase ===
EVENT_TASK <- WIFI_TASK [label="4.1 > WIFI_EVENT_STA_DISCONNECTED"];
WIFI_TASK <- AP [label="4.2 > 1/4 EAPOL"];
WIFI_TASK -> AP [label="4.3 > 2/4 EAPOL"];
EVENT_TASK <- WIFI_TASK [label="4.4 > WIFI_EVENT_STA_DISCONNECTED"];
WIFI_TASK <- AP [label="4.5 > 3/4 EAPOL"];
WIFI_TASK -> AP [label="4.6 > 4/4 EAPOL"];
EVENT_TASK <- WIFI_TASK [label="4.7 > WIFI_EVENT_STA_CONNECTED"];
}
Scan Phase +++++++++++++++++++++
scan-in-wifi-connect for more details.wifi-event-sta-disconnected will arise and the reason code could either be WIFI_REASON_NO_AP_FOUND or WIFI_REASON_NO_AP_FOUND_W_COMPATIBLE_SECURITY or WIFI_REASON_NO_AP_FOUND_IN_AUTHMODE_THRESHOLD or WIFI_REASON_NO_AP_FOUND_IN_RSSI_THRESHOLD depending of the Station's configuration. Refer to Wi-Fi Reason Code_.Auth Phase +++++++++++++++++++++
wifi-event-sta-disconnected will arise and the reason code will be WIFI_REASON_AUTH_EXPIRE. Refer to Wi-Fi Reason Code_.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_.Association Phase +++++++++++++++++++++
wifi-event-sta-disconnected will arise and the reason code will be WIFI_REASON_DISASSOC_DUE_TO_INACTIVITY. Refer to Wi-Fi Reason Code_.wifi-event-sta-disconnected arises, while the reason code is the one specified in the association response. Refer to Wi-Fi Reason Code_.Four-way Handshake Phase ++++++++++++++++++++++++++
wifi-event-sta-disconnected will arise and the reason code will be WIFI_REASON_HANDSHAKE_TIMEOUT. Refer to Wi-Fi Reason Code_.wifi-event-sta-disconnected will arise and the reason code will be WIFI_REASON_HANDSHAKE_TIMEOUT. Refer to Wi-Fi Reason Code_.wifi-event-sta-connected... _esp_wifi_reason_code:
Wi-Fi Reason Code +++++++++++++++++++++
The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first column is the macro name defined in :component_file:esp_wifi/include/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. This reason value is same as defined in section 9.4.1.7 of IEEE 802.11-2020. (For more information, refer to the standard mentioned above.) The last column describes the reason. Reason-codes starting from 200 are Espressif defined reason-codes and are not part of IEEE 802.11-2020.\
Also note that REASON_NO_AP_FOUND_XXX codes are mentioned in increasing order of importance. So if a single AP has a combination of the above reasons for failure, the more important one will be reported. Additionally, if there are multiple APs that satisfy the identifying criteria and connecting to all of them fails for different reasons mentioned above, then the reason code reported is for the AP that failed connection due to the least important reason code, as it was the one closest to a successful connection.\
Following reason codes are renamed to their shorter form to wrap the table in page width.
.. list-table:: :header-rows: 1 :widths: 41 10 49 :class: longtable
AUTH_EXPIRE
2
The previous authentication is no longer valid.
For the ESP station, this reason is reported when:
For the ESP AP, this reason is reported when:
esp_wifi_stop().esp_wifi_deauth_sta().AUTH_LEAVE
3
De-authenticated, because the sending station is leaving (or has left).
For the ESP station, this reason is reported when:
DISASSOC_DUE_TO_INACTIVITY
4
Disassociated due to inactivity.
For the ESP station, this reason is reported when:
ASSOC_TOOMANY
5
Disassociated, because the AP is unable to handle all currently associated STAs at the same time.
For the ESP station, this reason is reported when:
For the ESP AP, this reason is reported when:
CLASS2_FRAME_FROM_NONAUTH_STA
6
Class-2 frame received from a non-authenticated STA.
For the ESP station, this reason is reported when:
For the ESP AP, this reason is reported when:
CLASS3_FRAME_FROM_NONASSOC_STA
7
Class-3 frame received from a non-associated STA.
For the ESP station, this reason is reported when:
For the ESP AP, this reason is reported when:
ASSOC_LEAVE
8
Disassociated, because the sending station is leaving (or has left) BSS.
For the ESP station, this reason is reported when:
esp_wifi_disconnect() and other APIs.ASSOC_NOT_AUTHED
9
station requesting (re)association is not authenticated by the responding STA.
For the ESP station, this reason is reported when:
For the ESP AP, this reason is reported when:
DISASSOC_PWRCAP_BAD
10
Disassociated, because the information in the Power Capability element is unacceptable.
For the ESP station, this reason is reported when:
DISASSOC_SUPCHAN_BAD
11
Disassociated, because the information in the Supported Channels element is unacceptable.
For the ESP station, this reason is reported when:
BSS_TRANSITION_DISASSOC
12
AP wants us to move to another AP, sent as a part of BTM procedure. Please note that when station is sending BTM request and moving to another AP, ROAMING reason code will be reported instead of this.
For the ESP station, this reason is reported when:
IE_INVALID
13
Invalid element, i.e., an element whose content does not meet the specifications of the Standard in frame formats clause.
For the ESP station, this reason is reported when:
For the ESP AP, this reason is reported when:
MIC_FAILURE
14
Message integrity code (MIC) failure.
For the ESP station, this reason is reported when:
4WAY_HANDSHAKE_TIMEOUT
15
Four-way handshake times out. For legacy reasons, in ESP this reason code is replaced with WIFI_REASON_HANDSHAKE_TIMEOUT.
For the ESP station, this reason is reported when:
GROUP_KEY_UPDATE_TIMEOUT
16
Group-Key Handshake times out.
For the ESP station, this reason is reported when:
IE_IN_4WAY_DIFFERS
17
The element in the four-way handshake is different from the (Re-)Association Request/Probe and Response/Beacon frame.
For the ESP station, this reason is reported when:
GROUP_CIPHER_INVALID
18
Invalid group cipher.
For the ESP station, this reason is reported when:
PAIRWISE_CIPHER_INVALID
19
Invalid pairwise cipher.
For the ESP station, this reason is reported when:
AKMP_INVALID
20
Invalid AKMP.
For the ESP station, this reason is reported when:
UNSUPP_RSN_IE_VERSION
21
Unsupported RSNE version.
For the ESP station, this reason is reported when:
INVALID_RSN_IE_CAP
22
Invalid RSNE capabilities.
For the ESP station, this reason is reported when:
802_1X_AUTH_FAILED
23
IEEE 802.1X. authentication failed.
For the ESP station, this reason is reported when:
For the ESP AP, this reason is reported when:
CIPHER_SUITE_REJECTED
24
Cipher suite rejected due to security policies.
For the ESP station, this reason is reported when:
NO_AP_FOUND_SECURITY
210
Espressif-specific Wi-Fi reason code: NO_AP_FOUND_W_COMPATIBLE_SECURITY will be reported if an AP that fits identifying criteria (e.g. ssid) is found but the connection is rejected due to incompatible security configuration. These situations could be:
Wi-Fi Reason code related to wrong password ++++++++++++++++++++++++++++++++++++++++++++++
The table below shows the Wi-Fi reason-code may related to wrong password.
.. list-table:: :header-rows: 1 :widths: 5 10 40
NO_AP_FOUND
201
This may related to wrong password in the two scenarios:
Wi-Fi Reason code related to low RSSI ++++++++++++++++++++++++++++++++++++++++++++++
The table below shows the Wi-Fi reason-code may related to low RSSI.
.. list-table:: :header-rows: 1 :widths: 5 10 40
.. _wifi-station-connecting-when-multiple-aps-are-found:
This scenario is similar as :ref:wifi-station-connecting-scenario. The difference is that the station will not raise the event :ref:wifi-event-sta-disconnected unless it fails to connect all of the found APs.
.. _wifi-reconnect:
The station may disconnect due to many reasons, e.g., the connected AP is restarted. It is the application's responsibility to reconnect. The recommended reconnection strategy is to call :cpp:func:esp_wifi_connect() on receiving event :ref:wifi-event-sta-disconnected.
Sometimes the application needs more complex reconnection strategy:
esp_wifi_disconnect() is called, the application may not want to do the reconnection.esp_wifi_scan_start() may be called at anytime, a better reconnection strategy is necessary. Refer to :ref:scan-when-wifi-is-connecting.Another thing that need to be considered is that the reconnection may not connect the same AP if there are more than one APs with the same SSID. The reconnection always select current best APs to connect.
The beacon timeout mechanism is used by {IDF_TARGET_NAME} station to detect whether the AP is alive or not. If the station does not receive the beacon of the connected AP within the inactive time, the beacon timeout happens. The application can set inactive time via API :cpp:func:esp_wifi_set_inactive_time().
After the beacon times out, the station sends 5 probe requests to the AP. If still no probe response or beacon is received from AP, the station disconnects from the AP and raises the event :ref:wifi-event-sta-disconnected.
It should be considered that the timer used for beacon timeout will be reset during the scanning process. It means that the scan process will affect the triggering of the event :ref:wifi-event-sta-beacon-timeout.