diff --git a/components/esp_wifi/include/esp_wifi_types_generic.h b/components/esp_wifi/include/esp_wifi_types_generic.h index 710d7ca06c9..cef75825688 100644 --- a/components/esp_wifi/include/esp_wifi_types_generic.h +++ b/components/esp_wifi/include/esp_wifi_types_generic.h @@ -363,8 +363,9 @@ typedef enum { */ typedef struct { int8_t rssi; /**< The minimum rssi to accept in Wi-Fi scan. Defaults to -127 if set to >= 0 */ - wifi_auth_mode_t authmode; /**< The weakest auth mode to accept in Wi-Fi scan - Note: In case this value is not set and password is set as per WPA2 standards(password len >= 8), it will be defaulted to WPA2 and device won't connect to deprecated WEP/WPA networks. Please set auth mode threshold as WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK to connect to WEP/WPA networks */ + wifi_auth_mode_t authmode; /**< The weakest authentication mode to accept when scanning for Wi-Fi during connection. + Note: In case this value is not set and password is set as per WPA2 standards(password len >= 8), it will be defaulted to WPA2 and device won't connect to deprecated WEP/WPA networks. Please set auth mode threshold as WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK to connect to WEP/WPA networks. + If this is set to a mixed mode (for example, WPA_WPA2 or WPA2_WPA3), the minimum mode becomes the stronger of the two. For example, WPA_WPA2 becomes WPA2, and WPA2_WPA3 becomes WPA3. See `wifi_auth_mode_t` for details on relative strengths. */ uint8_t rssi_5g_adjustment; /**< The RSSI value of the 5G AP is within the rssi_5g_adjustment range compared to the 2G AP, the 5G AP will be given priority for connection. */ } wifi_scan_threshold_t; diff --git a/components/esp_wifi/remote/include/injected/esp_wifi_types_generic.h b/components/esp_wifi/remote/include/injected/esp_wifi_types_generic.h index be9a81a0070..44a24d329fb 100644 --- a/components/esp_wifi/remote/include/injected/esp_wifi_types_generic.h +++ b/components/esp_wifi/remote/include/injected/esp_wifi_types_generic.h @@ -359,12 +359,13 @@ typedef enum { } wifi_sort_method_t; /** - * @brief Structure describing parameters for a Wi-Fi fast scan + * @brief Structure describing parameters for Wi-Fi scan during connection */ typedef struct { - int8_t rssi; /**< The minimum rssi to accept in the fast scan mode. Defaults to -127 if set to >= 0 */ - wifi_auth_mode_t authmode; /**< The weakest auth mode to accept in the fast scan mode - Note: In case this value is not set and password is set as per WPA2 standards(password len >= 8), it will be defaulted to WPA2 and device won't connect to deprecated WEP/WPA networks. Please set auth mode threshold as WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK to connect to WEP/WPA networks */ + int8_t rssi; /**< The minimum rssi to accept in Wi-Fi scan. Defaults to -127 if set to >= 0 */ + wifi_auth_mode_t authmode; /**< The weakest authentication mode to accept when scanning for Wi-Fi during connection. + Note: In case this value is not set and password is set as per WPA2 standards(password len >= 8), it will be defaulted to WPA2 and device won't connect to deprecated WEP/WPA networks. Please set auth mode threshold as WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK to connect to WEP/WPA networks. + If this is set to a mixed mode (for example, WPA_WPA2 or WPA2_WPA3), the minimum mode becomes the stronger of the two. For example, WPA_WPA2 becomes WPA2, and WPA2_WPA3 becomes WPA3. See `wifi_auth_mode_t` for details on relative strengths. */ uint8_t rssi_5g_adjustment; /**< The RSSI value of the 5G AP is within the rssi_5g_adjustment range compared to the 2G AP, the 5G AP will be given priority for connection. */ } wifi_scan_threshold_t; diff --git a/docs/en/api-guides/wifi-driver/overview.rst b/docs/en/api-guides/wifi-driver/overview.rst index bde7f8d228e..cad38e96e86 100644 --- a/docs/en/api-guides/wifi-driver/overview.rst +++ b/docs/en/api-guides/wifi-driver/overview.rst @@ -515,12 +515,12 @@ API :cpp:func:`esp_wifi_set_config()` can be used to configure the station. And * - threshold - The threshold is used to filter the found AP. If the RSSI or security mode is less than the configured threshold, the AP will be discarded. - If the RSSI is set to 0, it means the default threshold is used, and the default RSSI threshold is -127 dBm. If the authmode threshold is set to 0, it means the default threshold is used, and the default authmode threshold is open. + If the RSSI is set to 0, it means the default threshold is used, and the default RSSI threshold is -127 dBm. If the authmode threshold is set to 0, it means the default threshold is used, and the default authmode threshold is ``WIFI_AUTH_OPEN``. .. attention:: - WEP/WPA security modes are deprecated in IEEE 802.11-2016 specifications and are recommended not to be used. These modes can be rejected using authmode threshold by setting threshold as WPA2 by threshold.authmode as ``WIFI_AUTH_WPA2_PSK``. + WEP and TKIP are deprecated in IEEE 802.11-2016 and should not be used. To make the station connect only to APs with WPA2 or higher security, set ``wifi_config_t.sta.threshold.authmode`` to ``WIFI_AUTH_WPA2_PSK``. APs below this threshold, such as OPEN, WEP, and WPA-PSK, will be ignored during connection filtering. AP Basic Configuration +++++++++++++++++++++++++++++++++++++ diff --git a/docs/zh_CN/api-guides/wifi-driver/overview.rst b/docs/zh_CN/api-guides/wifi-driver/overview.rst index bad98dd0c4d..3a6a87dc2a9 100644 --- a/docs/zh_CN/api-guides/wifi-driver/overview.rst +++ b/docs/zh_CN/api-guides/wifi-driver/overview.rst @@ -515,12 +515,12 @@ API :cpp:func:`esp_wifi_set_config()` 可用于配置 station。配置的参数 * - threshold - 该字段用来筛选找到的 AP，如果 AP 的 RSSI 或安全模式小于配置的阈值，则不会被连接。 - 如果 RSSI 设置为 0，则表示默认阈值，默认 RSSI 阈值为 -127 dBm。如果 authmode 阈值设置为 0，则表示默认阈值，默认 authmode 阈值为开放模式。 + 如果 RSSI 设置为 0，则表示默认阈值，默认 RSSI 阈值为 -127 dBm。如果 authmode 阈值设置为 0，则表示默认阈值，默认 authmode 阈值为 ``WIFI_AUTH_OPEN``。 .. attention:: - WEP/WPA 安全模式在 IEEE802.11-2016 协议中已弃用，建议不要使用。可使用 authmode 阈值代替，通过将 threshold.authmode 设置为 ``WIFI_AUTH_WPA2_PSK`` 使用 WPA2 模式。 + IEEE 802.11-2016 已废弃 WEP 和 TKIP，不建议继续使用 WEP 或基于 TKIP 的 WPA 网络。若希望 station 只连接 WPA2 及以上安全级别的 AP，可将 ``wifi_config_t.sta.threshold.authmode`` 设置为 ``WIFI_AUTH_WPA2_PSK``；低于该阈值的 AP（如 OPEN、WEP、WPA-PSK）将在连接筛选时被忽略。 AP 基本配置 +++++++++++++++++++++++++++++++++++++ diff --git a/docs/zh_CN/api-guides/wifi-driver/station-scenarios.rst b/docs/zh_CN/api-guides/wifi-driver/station-scenarios.rst index a4735cfd1f7..8ac88ea3217 100644 --- a/docs/zh_CN/api-guides/wifi-driver/station-scenarios.rst +++ b/docs/zh_CN/api-guides/wifi-driver/station-scenarios.rst @@ -772,7 +772,7 @@ Wi-Fi 原因代码 - 乐鑫特有的 Wi-Fi 原因代码： 当 station 连续失去 N 个 beacon，将中断连接并报告该代码。 * - NO_AP_FOUND - 201 - - 乐鑫特有的 Wi-Fi 原因代码： 当 station 未扫描到目标 AP 时，将报告该代码。 + - 乐鑫特有的 Wi-Fi 原因代码： 当 station 未扫描到目标 AP 时，将报告该代码。如果是由于安全性不匹配或 station 配置不匹配导致未扫描到目标 AP，则会报告新的原因代码NO_AP_FOUND_XXX。 * - AUTH_FAIL - 202 - 乐鑫特有的 Wi-Fi 原因代码： authentication 失败，但并非由超时而引发。 diff --git a/examples/phy/antenna/main/antenna_switch_example_main.c b/examples/phy/antenna/main/antenna_switch_example_main.c index c81a07458e5..3d8cb05534c 100644 --- a/examples/phy/antenna/main/antenna_switch_example_main.c +++ b/examples/phy/antenna/main/antenna_switch_example_main.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Unlicense OR CC0-1.0 */ @@ -117,10 +117,11 @@ void wifi_init_sta(void) .sta = { .ssid = EXAMPLE_ESP_WIFI_SSID, .password = EXAMPLE_ESP_WIFI_PASS, - /* Authmode threshold resets to WPA2 as default if password matches WPA2 standards (password len => 8). + /* Authmode threshold resets to WPA2 as default if auth mode threshold equals WIFI_AUTH_OPEN + * and password matches WPA2 standards (password len => 8). * If you want to connect the device to deprecated WEP/WPA networks, Please set the threshold value * to WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK and set the password with length and format matching to - * WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK standards. + * WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK standards. */ .threshold.authmode = ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD, .sae_pwe_h2e = WPA3_SAE_PWE_BOTH, diff --git a/examples/wifi/getting_started/station/main/station_example_main.c b/examples/wifi/getting_started/station/main/station_example_main.c index 1cc82b0b834..e929c6eb176 100644 --- a/examples/wifi/getting_started/station/main/station_example_main.c +++ b/examples/wifi/getting_started/station/main/station_example_main.c @@ -121,7 +121,8 @@ void wifi_init_sta(void) .sta = { .ssid = EXAMPLE_ESP_WIFI_SSID, .password = EXAMPLE_ESP_WIFI_PASS, - /* Authmode threshold resets to WPA2 as default if password matches WPA2 standards (password len => 8). + /* Authmode threshold resets to WPA2 as default if auth mode threshold equals WIFI_AUTH_OPEN + * and password matches WPA2 standards (password len => 8). * If you want to connect the device to deprecated WEP/WPA networks, Please set the threshold value * to WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK and set the password with length and format matching to * WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK standards. diff --git a/examples/wifi/softap_sta/main/softap_sta.c b/examples/wifi/softap_sta/main/softap_sta.c index d942fd230bd..0f496e55939 100644 --- a/examples/wifi/softap_sta/main/softap_sta.c +++ b/examples/wifi/softap_sta/main/softap_sta.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Unlicense OR CC0-1.0 */ @@ -152,10 +152,11 @@ esp_netif_t *wifi_init_sta(void) .password = EXAMPLE_ESP_WIFI_STA_PASSWD, .scan_method = WIFI_ALL_CHANNEL_SCAN, .failure_retry_cnt = EXAMPLE_ESP_MAXIMUM_RETRY, - /* Authmode threshold resets to WPA2 as default if password matches WPA2 standards (password len => 8). + /* Authmode threshold resets to WPA2 as default if auth mode threshold equals WIFI_AUTH_OPEN + * and password matches WPA2 standards (password len => 8). * If you want to connect the device to deprecated WEP/WPA networks, Please set the threshold value * to WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK and set the password with length and format matching to - * WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK standards. + * WIFI_AUTH_WEP/WIFI_AUTH_WPA_PSK standards. */ .threshold.authmode = ESP_WIFI_SCAN_AUTH_MODE_THRESHOLD, .sae_pwe_h2e = WPA3_SAE_PWE_BOTH,