alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-09-21 06:56:11 -04:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

docs(wifi): Add documentation for ESP defined disconnect reasoncodes

Browse Source
This commit is contained in:
Kapil Gupta 2023-11-13 12:45:44 +05:30
parent e8a5fdcff3
commit ffd46a32f7
2 changed files with 65 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
docs/en/api-guides/wifi.rst
View File

@ -797,7 +797,7 @@ Scan Phase
+++++++++++++++++++++
- s1.1: The Wi-Fi driver begins scanning in "Wi-Fi Connect". Refer to `Scan in Wi-Fi Connect`_ for more details.
- s1.2: If the scan fails to find the target AP, `WIFI_EVENT_STA_DISCONNECTED`_ will arise and the reason code will be ``WIFI_REASON_NO_AP_FOUND``. Refer to `Wi-Fi Reason Code`_.
- s1.2: If the scan fails to find the target AP, `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
+++++++++++++++++++++
@ -828,25 +828,33 @@ Four-way Handshake Phase
- s4.7: The station raises `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. The third column is the standard value to which this reason is mapped 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.
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.
- TRANSMISSION_LINK_ESTABLISHMENT_FAILED : TX_LINK_EST_FAILED
- NO_AP_FOUND_W_COMPATIBLE_SECURITY : NO_AP_FOUND_SECURITY
- NO_AP_FOUND_IN_AUTHMODE_THRESHOLD : NO_AP_FOUND_AUTHMODE
- NO_AP_FOUND_IN_RSSI_THRESHOLD : NO_AP_FOUND_RSSI
.. list-table::
:header-rows: 1
:widths: 5 10 12 40
:widths: 5 10 52
* - Reason code
- Value
- Mapped To
- Description
* - UNSPECIFIED
- 1
- 1
- Generally, it means an internal failure, e.g., the memory runs out, the internal TX fails, or the reason is received from the remote side.
* - AUTH_EXPIRE
- 2
- 2
- The previous authentication is no longer valid.
@ -861,7 +869,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- the AP is stopped by calling :cpp:func:`esp_wifi_stop()`.
- the station is de-authed by calling :cpp:func:`esp_wifi_deauth_sta()`.
* - AUTH_LEAVE
- 3
- 3
- De-authenticated, because the sending station is leaving (or has left).
@ -869,7 +876,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- it is received from the AP.
* - ASSOC_EXPIRE
- 4
- 4
- Disassociated due to inactivity.
@ -883,7 +889,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- the AP is stopped by calling :cpp:func:`esp_wifi_stop()`.
- the station is de-authed by calling :cpp:func:`esp_wifi_deauth_sta()`.
* - ASSOC_TOOMANY
- 5
- 5
- Disassociated, because the AP is unable to handle all currently associated STAs at the same time.
@ -895,7 +900,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- the stations associated with the AP reach the maximum number that the AP can support.
* - NOT_AUTHED
- 6
- 6
- Class-2 frame received from a non-authenticated STA.
@ -907,7 +911,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- the AP receives a packet with data from a non-authenticated station.
* - NOT_ASSOCED
- 7
- 7
- Class-3 frame received from a non-associated STA.
@ -919,7 +922,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- the AP receives a packet with data from a non-associated station.
* - ASSOC_LEAVE
- 8
- 8
- Disassociated, because the sending station is leaving (or has left) BSS.
@ -928,7 +930,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- it is received from the AP.
- the station is disconnected by :cpp:func:`esp_wifi_disconnect()` and other APIs.
* - ASSOC_NOT_AUTHED
- 9
- 9
- station requesting (re)association is not authenticated by the responding STA.
@ -940,7 +941,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- the AP receives packets with data from an associated, yet not authenticated, station.
* - DISASSOC_PWRCAP_BAD
- 10
- 10
- Disassociated, because the information in the Power Capability element is unacceptable.
@ -948,15 +948,20 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- it is received from the AP.
* - DISASSOC_SUPCHAN_BAD
- 11
- 11
- Disassociated, because the information in the Supported Channels element is unacceptable.
For the ESP station, this reason is reported when:
- it is received from the AP.
* - 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:
- it is received from the AP.
* - IE_INVALID
- 13
- 13
- Invalid element, i.e., an element whose content does not meet the specifications of the Standard in frame formats clause.
@ -968,7 +973,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- the AP parses a wrong WPA or RSN IE.
* - MIC_FAILURE
- 14
- 14
- Message integrity code (MIC) failure.
@ -976,7 +980,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- it is received from the AP.
* - 4WAY_HANDSHAKE_TIMEOUT
- 15
- 15
- Four-way handshake times out. For legacy reasons, in ESP this reason code is replaced with ``WIFI_REASON_HANDSHAKE_TIMEOUT``.
@ -985,7 +988,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- the handshake times out.
- it is received from the AP.
* - GROUP_KEY_UPDATE_TIMEOUT
- 16
- 16
- Group-Key Handshake times out.
@ -993,7 +995,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- it is received from the AP.
* - IE_IN_4WAY_DIFFERS
- 17
- 17
- The element in the four-way handshake is different from the (Re-)Association Request/Probe and Response/Beacon frame.
@ -1002,7 +1003,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- it is received from the AP.
- the station finds that the four-way handshake IE differs from the IE in the (Re-)Association Request/Probe and Response/Beacon frame.
* - GROUP_CIPHER_INVALID
- 18
- 18
- Invalid group cipher.
@ -1010,7 +1010,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- it is received from the AP.
* - PAIRWISE_CIPHER_INVALID
- 19
- 19
- Invalid pairwise cipher.
@ -1018,14 +1017,12 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- it is received from the AP.
* - AKMP_INVALID
- 20
- 20
- Invalid AKMP.
For the ESP station, this reason is reported when:
- it is received from the AP.
* - UNSUPP_RSN_IE_VERSION
- 21
- 21
- Unsupported RSNE version.
@ -1033,7 +1030,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- it is received from the AP.
* - INVALID_RSN_IE_CAP
- 22
- 22
- Invalid RSNE capabilities.
@ -1041,7 +1037,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- it is received from the AP.
* - 802_1X_AUTH_FAILED
- 23
- 23
- IEEE 802.1X. authentication failed.
@ -1053,7 +1048,6 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- IEEE 802.1X. authentication fails.
* - CIPHER_SUITE_REJECTED
- 24
- 24
- Cipher suite rejected due to security policies.
@ -1061,126 +1055,120 @@ The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first co
- it is received from the AP.
* - TDLS_PEER_UNREACHABLE
- 25
- 25
- TDLS direct-link teardown due to TDLS peer STA unreachable via the TDLS direct link.
* - TDLS_UNSPECIFIED
- 26
- 26
- TDLS direct-link teardown for unspecified reason.
* - SSP_REQUESTED_DISASSOC
- 27
- 27
- Disassociated because session terminated by SSP request.
* - NO_SSP_ROAMING_AGREEMENT
- 28
- 28
- Disassociated because of lack of SSP roaming agreement.
* - BAD_CIPHER_OR_AKM
- 29
- 29
- Requested service rejected because of SSP cipher suite or AKM requirement.
* - NOT_AUTHORIZED_THIS_LOCATION
- 30
- 30
- Requested service not authorized in this location.
* - SERVICE_CHANGE_PRECLUDES_TS
- 31
- 31
- TS deleted because QoS AP lacks sufficient bandwidth for this QoS STA due to a change in BSS service characteristics or operational mode (e.g., an HT BSS change from 40 MHz channel to 20 MHz channel).
* - UNSPECIFIED_QOS
- 32
- 32
- Disassociated for unspecified, QoS-related reason.
* - NOT_ENOUGH_BANDWIDTH
- 33
- 33
- Disassociated because QoS AP lacks sufficient bandwidth for this QoS STA.
* - MISSING_ACKS
- 34
- 34
- Disassociated because excessive number of frames need to be acknowledged, but are not acknowledged due to AP transmissions and/or poor channel conditions.
* - EXCEEDED_TXOP
- 35
- 35
- Disassociated because STA is transmitting outside the limits of its TXOPs.
* - STA_LEAVING
- 36
- 36
- Requesting STA is leaving the BSS (or resetting).
* - END_BA
- 37
- 37
- Requesting STA is no longer using the stream or session.
* - UNKNOWN_BA
- 38
- 38
- Requesting STA received frames using a mechanism for which a setup has not been completed.
* - TIMEOUT
- 39
- 39
- Requested from peer STA due to timeout
* - Reserved
- 40 ~ 45
- 40 ~ 45
-
- Reserved as per IEEE80211-2020 specifications.
* - PEER_INITIATED
- 46
- 46
- In a Disassociation frame: Disassociated because authorized access limit reached.
* - AP_INITIATED
- 47
- 47
- In a Disassociation frame: Disassociated due to external service requirements.
* - INVALID_FT_ACTION_FRAME_COUNT
- 48
- 48
- Invalid FT Action frame count.
* - INVALID_PMKID
- 49
- 49
- Invalid pairwise master key identifier (PMKID).
* - INVALID_MDE
- 50
- 50
- Invalid MDE.
* - INVALID_FTE
- 51
- 51
- Invalid FTE
* - TRANSMISSION_LINK_ESTABLISHMENT_FAILED
* - TX_LINK_EST_FAILED
- 67
- 67
- Transmission link establishment in alternative channel failed.
- TRANSMISSION_LINK_ESTABLISHMENT_FAILED will be reported when Transmission link establishment in alternative channel failed.
* - ALTERATIVE_CHANNEL_OCCUPIED
- 68
- 68
- The alternative channel is occupied.
* - BEACON_TIMEOUT
- 200
- reserved
- Espressif-specific Wi-Fi reason code: when the station loses N beacons continuously, it will disrupt the connection and report this reason.
* - NO_AP_FOUND
- 201
- reserved
- Espressif-specific Wi-Fi reason code: when the station fails to scan the target AP, this reason code will be reported.
- Espressif-specific Wi-Fi reason code: when the station fails to scan the target AP, this reason code will be reported. In case of security mismatch or station's configuration mismatch, new reason codes NO_AP_FOUND_XXX will be reported.
* - AUTH_FAIL
- 202
- reserved
- Espressif-specific Wi-Fi reason code: the authentication fails, but not because of a timeout.
* - ASSOC_FAIL
- 203
- reserved
- Espressif-specific Wi-Fi reason code: the association fails, but not because of ASSOC_EXPIRE or ASSOC_TOOMANY.
* - HANDSHAKE_TIMEOUT
- 204
- reserved
- Espressif-specific Wi-Fi reason code: the handshake fails for the same reason as that in WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT.
* - CONNECTION_FAIL
- 205
- reserved
- Espressif-specific Wi-Fi reason code: the connection to the AP has failed.
* - AP_TSF_RESET
- 206
- Espressif-specific Wi-Fi reason code: the disconnection happened due to AP's TSF reset.
* - ROAMING
- 207
- Espressif-specific Wi-Fi reason code: the station is roaming to another AP, this reason code is just for info, station will automatically move to another AP.
* - ASSOC_COMEBACK_TIME_TOO_LONG
- 208
- Espressif-specific Wi-Fi reason code: This reason code will be reported when Assoc comeback time in association response is too high.
* - SA_QUERY_TIMEOUT
- 209
- Espressif-specific Wi-Fi reason code: This reason code will be reported when AP did not reply of SA query sent by ESP station.
* - 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:
- bss offering WEP, but our password is not WEP compliant
- Encrypted AP bss but we have but no password config set
- AP is Enterprise but we haven't setup enterprise config, and vice versa
* - NO_AP_FOUND_AUTHMODE
- 211
- Espressif-specific Wi-Fi reason code: NO_AP_FOUND_IN_AUTHMODE_THRESHOLD will be reported if an AP that fit identifying criteria (e.g. ssid) is found but the authmode threhsold set in the wifi_config_t is not met.
* - NO_AP_FOUND_RSSI
- 212
- Espressif-specific Wi-Fi reason code: NO_AP_FOUND_IN_RSSI_THRESHOLD will be reported if an AP that fits identifying criteria (e.g. ssid) is found but the RSSI threhsold set in the wifi_config_t is not met.
Wi-Fi Reason code related to wrong password
++++++++++++++++++++++++++++++++++++++++++++++
@ -1196,7 +1184,7 @@ The table below shows the Wi-Fi reason-code may related to wrong password.
- Description
* - 4WAY_HANDSHAKE_TIMEOUT
- 15
- Four-way handshake times out. Setting wrong password when STA connecting to an encrpyted AP.
- Four-way handshake times out. Setting wrong password when STA connecting to an encrypted AP.
* - NO_AP_FOUND
- 201
- This may related to wrong password in the two scenarios:
@ -1219,8 +1207,8 @@ The table below shows the Wi-Fi reason-code may related to low RSSI.
* - Reason code
- Value
- Description
* - NO_AP_FOUND
- 201
* - NO_AP_FOUND_IN_RSSI_THRESHOLD
- 212
- The station fails to scan the target AP due to low RSSI
* - HANDSHAKE_TIMEOUT
- 204

13
docs/en/migration-guides/release-5.x/5.2/wifi.rst
View File

@ -8,3 +8,16 @@ WiFi Enterprise Security
------------------------
APIs defined in `esp_wpa2.h` have been deprecated. Please use newer APIs from `esp_eap_client.h`.
WiFi Disconnect Reason Codes
----------------------------
For the event WIFI_EVENT_STA_DISCONNECTED, the original reason code WIFI_REASON_NO_AP_FOUND has been split as follows:
- REASON_NO_AP_FOUND(original and still used in some scenarios)
- REASON_NO_AP_FOUND_IN_RSSI_THRESHOLD
- REASON_NO_AP_FOUND_IN_AUTHMODE_THRESHOLD
- REASON_NO_AP_FOUND_W_COMPATIBLE_SECURITY
For details, please refer to :ref:`esp_wifi_reason_code`.