From f0c5149e53cd8aea1836e1460f2c99b2aea27fcd Mon Sep 17 00:00:00 2001 From: muhaidong Date: Tue, 11 Mar 2025 21:38:17 +0800 Subject: [PATCH] fix(wifi): update auth mode threshold doc --- components/esp_wifi/include/esp_wifi_types.h | 5 +++-- docs/en/api-guides/wifi.rst | 4 ++-- docs/zh_CN/api-guides/wifi.rst | 6 +++--- examples/wifi/antenna/main/antenna_switch_example_main.c | 7 ++++--- .../getting_started/station/main/station_example_main.c | 3 ++- examples/wifi/softap_sta/main/softap_sta.c | 7 ++++--- 6 files changed, 18 insertions(+), 14 deletions(-) diff --git a/components/esp_wifi/include/esp_wifi_types.h b/components/esp_wifi/include/esp_wifi_types.h index 204b98d265e..ee39586abe2 100644 --- a/components/esp_wifi/include/esp_wifi_types.h +++ b/components/esp_wifi/include/esp_wifi_types.h @@ -257,8 +257,9 @@ typedef enum { /** @brief Structure describing parameters for Wi-Fi scan during connection */ 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: Incase 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 authmode 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. */ } wifi_scan_threshold_t; typedef enum { diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index 5f3662fc6a9..a7b505b03f4 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -1308,12 +1308,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.rst b/docs/zh_CN/api-guides/wifi.rst index 95c0e2fa209..15e3d747801 100644 --- a/docs/zh_CN/api-guides/wifi.rst +++ b/docs/zh_CN/api-guides/wifi.rst @@ -1161,7 +1161,7 @@ Wi-Fi 原因代码 * - NO_AP_FOUND - 201 - 保留 - - 乐鑫特有的 Wi-Fi 原因代码： 当 station 未扫描到目标 AP 时，将报告该代码。 + - 乐鑫特有的 Wi-Fi 原因代码： 当 station 未扫描到目标 AP 时，将报告该代码。如果是由于安全性不匹配或 station 配置不匹配导致未扫描到目标 AP，则会报告新的原因代码 NO_AP_FOUND_XXX。 * - AUTH_FAIL - 202 - 保留 @@ -1308,12 +1308,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/examples/wifi/antenna/main/antenna_switch_example_main.c b/examples/wifi/antenna/main/antenna_switch_example_main.c index 502bf40c583..74982be3783 100644 --- a/examples/wifi/antenna/main/antenna_switch_example_main.c +++ b/examples/wifi/antenna/main/antenna_switch_example_main.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Unlicense OR CC0-1.0 */ @@ -116,10 +116,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 (pasword 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 3ed7465daa6..6f2db33ebf7 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 (pasword 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 c6c5b5f688d..2497f18f1ab 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-2024 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Unlicense OR CC0-1.0 */ @@ -148,10 +148,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,