From acbfba84e470cdf79fd618c4d7ca7c1d558c6f03 Mon Sep 17 00:00:00 2001 From: muhaidong Date: Wed, 29 Apr 2026 16:56:18 +0800 Subject: [PATCH 1/6] fix(wifi): fix some wifi bugs 260519 v5.3 1. fix(wifi): fix max connection number issue 2. fix(wifi): fix hidden ap rssi update and owe beacon timeout issue 3. docs: update wifi scan threshold docs --- components/esp_wifi/include/esp_wifi_types_generic.h | 2 +- components/esp_wifi/include/local/esp_wifi_types_native.h | 4 +--- components/esp_wifi/lib | 2 +- 3 files changed, 3 insertions(+), 5 deletions(-) diff --git a/components/esp_wifi/include/esp_wifi_types_generic.h b/components/esp_wifi/include/esp_wifi_types_generic.h index 4f89590e541..f7a7cd16678 100644 --- a/components/esp_wifi/include/esp_wifi_types_generic.h +++ b/components/esp_wifi/include/esp_wifi_types_generic.h @@ -408,7 +408,7 @@ typedef struct { uint8_t channel; /**< Channel of soft-AP. Set to 0 for auto selection (min channel: typically 1 for 2.4G, 36 for 5G). Other invalid values return ESP_ERR_INVALID_ARG. */ wifi_auth_mode_t authmode; /**< Auth mode of soft-AP. Do not support AUTH_WEP, AUTH_WAPI_PSK and AUTH_OWE in soft-AP mode. When the auth mode is set to WPA2_PSK, WPA2_WPA3_PSK or WPA3_PSK, the pairwise cipher will be overwritten with WIFI_CIPHER_TYPE_CCMP by default, unless explicitly set. */ uint8_t ssid_hidden; /**< Broadcast SSID or not, default 0, broadcast the SSID */ - uint8_t max_connection; /**< Max number of stations allowed to connect in */ + uint8_t max_connection; /**< Max number of stations allowed to connect in. Please note that soft-AP and ESP-NOW share the same encryption hardware keys, so the max_connection parameter will be affected by CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM. */ uint16_t beacon_interval; /**< Beacon interval which should be multiples of 100. Unit: TU(time unit, 1 TU = 1024 us). Range: 100 ~ 60000. Default value: 100 */ uint8_t csa_count; /**< Channel Switch Announcement Count. Notify the station that the channel will switch after the csa_count beacon intervals. Default value: 3 */ uint8_t dtim_period; /**< Dtim period of soft-AP. Range: 1 ~ 10. Default value: 1 */ diff --git a/components/esp_wifi/include/local/esp_wifi_types_native.h b/components/esp_wifi/include/local/esp_wifi_types_native.h index 76a45d25b87..bff472e475c 100644 --- a/components/esp_wifi/include/local/esp_wifi_types_native.h +++ b/components/esp_wifi/include/local/esp_wifi_types_native.h @@ -18,10 +18,8 @@ extern "C" { #if CONFIG_IDF_TARGET_ESP32C2 #define ESP_WIFI_MAX_CONN_NUM (4) /**< max number of stations which can connect to ESP32C2 soft-AP */ -#elif CONFIG_IDF_TARGET_ESP32C3 || CONFIG_IDF_TARGET_ESP32C6 || CONFIG_IDF_TARGET_ESP32C5 -#define ESP_WIFI_MAX_CONN_NUM (10) /**< max number of stations which can connect to ESP32C3 soft-AP */ #else -#define ESP_WIFI_MAX_CONN_NUM (15) /**< max number of stations which can connect to ESP32/ESP32S3/ESP32S2 soft-AP */ +#define ESP_WIFI_MAX_CONN_NUM (15) #endif /** @brief List of stations associated with the Soft-AP */ diff --git a/components/esp_wifi/lib b/components/esp_wifi/lib index 6b8485065c9..3cbbdea873c 160000 --- a/components/esp_wifi/lib +++ b/components/esp_wifi/lib @@ -1 +1 @@ -Subproject commit 6b8485065c9e2f6997611a977b65cabbb30611db +Subproject commit 3cbbdea873cfee9972a11374b03ee52bf6e122fe From f4fec5e8b3dc461a4314cc829f9b942e95a766ab Mon Sep 17 00:00:00 2001 From: muhaidong Date: Wed, 6 May 2026 15:49:16 +0800 Subject: [PATCH 2/6] fix(wifi): update rom ld file for fix max connection number issue --- components/esp_rom/esp32c3/ld/esp32c3.rom.ld | 4 ++-- .../esp_rom/esp32c5/mp/esp32c5/ld/esp32c5.rom.net80211.ld | 4 ++-- components/esp_rom/esp32c6/ld/esp32c6.rom.net80211.ld | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/components/esp_rom/esp32c3/ld/esp32c3.rom.ld b/components/esp_rom/esp32c3/ld/esp32c3.rom.ld index 3976b098983..b658e3d5b17 100644 --- a/components/esp_rom/esp32c3/ld/esp32c3.rom.ld +++ b/components/esp_rom/esp32c3/ld/esp32c3.rom.ld @@ -884,8 +884,8 @@ ampdu_dispatch_as_many_as_possible = 0x4000182c; ampdu_dispatch_movement = 0x40001830; ampdu_dispatch_upto = 0x40001834; chm_is_at_home_channel = 0x40001838; -cnx_node_is_existing = 0x4000183c; -cnx_node_search = 0x40001840; +/*cnx_node_is_existing = 0x4000183c;*/ +/*cnx_node_search = 0x40001840;*/ ic_ebuf_recycle_rx = 0x40001844; ic_ebuf_recycle_tx = 0x40001848; ic_reset_rx_ba = 0x4000184c; diff --git a/components/esp_rom/esp32c5/mp/esp32c5/ld/esp32c5.rom.net80211.ld b/components/esp_rom/esp32c5/mp/esp32c5/ld/esp32c5.rom.net80211.ld index d3dd938ddfe..adb0f7ac786 100644 --- a/components/esp_rom/esp32c5/mp/esp32c5/ld/esp32c5.rom.net80211.ld +++ b/components/esp_rom/esp32c5/mp/esp32c5/ld/esp32c5.rom.net80211.ld @@ -26,8 +26,8 @@ ampdu_dispatch_as_many_as_possible = 0x40000b28; ampdu_dispatch_movement = 0x40000b2c; ampdu_dispatch_upto = 0x40000b30; chm_is_at_home_channel = 0x40000b34; -cnx_node_is_existing = 0x40000b38; -cnx_node_search = 0x40000b3c; +/*cnx_node_is_existing = 0x40000b38;*/ +/*cnx_node_search = 0x40000b3c;*/ ic_ebuf_recycle_rx = 0x40000b40; ic_ebuf_recycle_tx = 0x40000b44; ic_reset_rx_ba = 0x40000b48; diff --git a/components/esp_rom/esp32c6/ld/esp32c6.rom.net80211.ld b/components/esp_rom/esp32c6/ld/esp32c6.rom.net80211.ld index 56761322bdc..9de457bf3e6 100644 --- a/components/esp_rom/esp32c6/ld/esp32c6.rom.net80211.ld +++ b/components/esp_rom/esp32c6/ld/esp32c6.rom.net80211.ld @@ -25,8 +25,8 @@ ampdu_dispatch_as_many_as_possible = 0x40000b58; ampdu_dispatch_movement = 0x40000b5c; ampdu_dispatch_upto = 0x40000b60; chm_is_at_home_channel = 0x40000b64; -cnx_node_is_existing = 0x40000b68; -cnx_node_search = 0x40000b6c; +/*cnx_node_is_existing = 0x40000b68;*/ +/*cnx_node_search = 0x40000b6c;*/ ic_ebuf_recycle_rx = 0x40000b70; ic_ebuf_recycle_tx = 0x40000b74; ic_reset_rx_ba = 0x40000b78; From 2c2eee578ed5899209b6a9dc322e792cff471153 Mon Sep 17 00:00:00 2001 From: muhaidong Date: Wed, 29 Apr 2026 17:22:24 +0800 Subject: [PATCH 3/6] fix(wifi): add ESP_WIFI_MAX_CONN_NUM-aligned ranges for soft-AP max STA Kconfig --- examples/network/bridge/main/Kconfig.projbuild | 8 +++++++- examples/network/eth2ap/main/Kconfig.projbuild | 8 +++++++- .../http_server/captive_portal/main/Kconfig.projbuild | 8 +++++++- .../wifi/getting_started/softAP/main/Kconfig.projbuild | 8 +++++++- examples/wifi/softap_sta/main/Kconfig.projbuild | 8 +++++++- .../wifi/wps_softap_registrar/main/Kconfig.projbuild | 10 ++++++++-- 6 files changed, 43 insertions(+), 7 deletions(-) diff --git a/examples/network/bridge/main/Kconfig.projbuild b/examples/network/bridge/main/Kconfig.projbuild index eb3bf58a468..d7abd9d84c2 100644 --- a/examples/network/bridge/main/Kconfig.projbuild +++ b/examples/network/bridge/main/Kconfig.projbuild @@ -40,6 +40,12 @@ menu "Example AP Wifi Configuration" depends on EXAMPLE_BR_WIFI int "Maximal STA connections" default 4 + range 1 4 if IDF_TARGET_ESP32C2 + range 1 15 help - Max number of the STA connects to AP. + Maximum number of STAs allowed to connect to the bridged soft-AP (wifi_config_t.ap.max_connection). + Upper bound matches ESP_WIFI_MAX_CONN_NUM in esp_wifi_types_native.h: + 1-4 on ESP32-C2, 1-15 on other Wi-Fi chips. + Soft-AP and ESP-NOW share encryption keys; see Wi-Fi driver documentation + if ESP-NOW is enabled. endmenu diff --git a/examples/network/eth2ap/main/Kconfig.projbuild b/examples/network/eth2ap/main/Kconfig.projbuild index 885ccf6dbbb..affe95436ee 100644 --- a/examples/network/eth2ap/main/Kconfig.projbuild +++ b/examples/network/eth2ap/main/Kconfig.projbuild @@ -22,7 +22,13 @@ menu "Example Configuration" config EXAMPLE_MAX_STA_CONN int "Maximum STA connections" default 4 + range 1 4 if IDF_TARGET_ESP32C2 + range 1 15 help - Maximum number of the station that allowed to connect to current Wi-Fi hotspot. + Maximum number of STAs allowed to connect to the soft-AP (wifi_config_t.ap.max_connection). + Upper bound matches ESP_WIFI_MAX_CONN_NUM in esp_wifi_types_native.h: + 1-4 on ESP32-C2, 1-15 on other Wi-Fi chips. + Soft-AP and ESP-NOW share encryption keys; see Wi-Fi driver documentation + if ESP-NOW is enabled. endmenu diff --git a/examples/protocols/http_server/captive_portal/main/Kconfig.projbuild b/examples/protocols/http_server/captive_portal/main/Kconfig.projbuild index 959cd4287d5..4bd4b5fb642 100644 --- a/examples/protocols/http_server/captive_portal/main/Kconfig.projbuild +++ b/examples/protocols/http_server/captive_portal/main/Kconfig.projbuild @@ -15,6 +15,12 @@ menu "Example Configuration" config ESP_MAX_STA_CONN int "Maximal STA connections" default 4 + range 1 4 if IDF_TARGET_ESP32C2 + range 1 15 help - Max number of the STA connects to AP. + Maximum number of STAs allowed to connect to the soft-AP (wifi_config_t.ap.max_connection). + Upper bound matches ESP_WIFI_MAX_CONN_NUM in esp_wifi_types_native.h: + 1-4 on ESP32-C2, 1-15 on other Wi-Fi chips. + Soft-AP and ESP-NOW share encryption keys; see Wi-Fi driver documentation + if ESP-NOW is enabled. endmenu diff --git a/examples/wifi/getting_started/softAP/main/Kconfig.projbuild b/examples/wifi/getting_started/softAP/main/Kconfig.projbuild index 19e9f86e011..cf4a0e5cb58 100644 --- a/examples/wifi/getting_started/softAP/main/Kconfig.projbuild +++ b/examples/wifi/getting_started/softAP/main/Kconfig.projbuild @@ -21,6 +21,12 @@ menu "Example Configuration" config ESP_MAX_STA_CONN int "Maximal STA connections" default 4 + range 1 4 if IDF_TARGET_ESP32C2 + range 1 15 help - Max number of the STA connects to AP. + Maximum number of STAs allowed to connect to the soft-AP (wifi_config_t.ap.max_connection). + Upper bound matches ESP_WIFI_MAX_CONN_NUM in esp_wifi_types_native.h: + 1-4 on ESP32-C2, 1-15 on other Wi-Fi chips. + Soft-AP and ESP-NOW share encryption keys; see Wi-Fi driver documentation + if ESP-NOW is enabled. endmenu diff --git a/examples/wifi/softap_sta/main/Kconfig.projbuild b/examples/wifi/softap_sta/main/Kconfig.projbuild index c7af1590148..32e5377d2e7 100644 --- a/examples/wifi/softap_sta/main/Kconfig.projbuild +++ b/examples/wifi/softap_sta/main/Kconfig.projbuild @@ -25,8 +25,14 @@ menu "Example Configuration" config ESP_MAX_STA_CONN_AP int "Maximal STA connections" default 4 + range 1 4 if IDF_TARGET_ESP32C2 + range 1 15 help - Max number of the STA connects to AP. + Maximum number of STAs allowed to connect to the soft-AP (wifi_config_t.ap.max_connection). + Upper bound matches ESP_WIFI_MAX_CONN_NUM in esp_wifi_types_native.h: + 1-4 on ESP32-C2, 1-15 on other Wi-Fi chips. + Soft-AP and ESP-NOW share encryption keys; see Wi-Fi driver documentation + if ESP-NOW is enabled. endmenu menu "STA Configuration" diff --git a/examples/wifi/wps_softap_registrar/main/Kconfig.projbuild b/examples/wifi/wps_softap_registrar/main/Kconfig.projbuild index 4f173a0cabe..a1cb700bddc 100644 --- a/examples/wifi/wps_softap_registrar/main/Kconfig.projbuild +++ b/examples/wifi/wps_softap_registrar/main/Kconfig.projbuild @@ -22,8 +22,14 @@ menu "Example Configuration" config EXAMPLE_MAX_STA_CONN int "Maximal STA connections" default 4 + range 1 4 if IDF_TARGET_ESP32C2 + range 1 15 help - Max number of the STA connects to AP. + Maximum number of STAs allowed to connect to the soft-AP (wifi_config_t.ap.max_connection). + Upper bound matches ESP_WIFI_MAX_CONN_NUM in esp_wifi_types_native.h: + 1-4 on ESP32-C2, 1-15 on other Wi-Fi chips. + Soft-AP and ESP-NOW share encryption keys; see Wi-Fi driver documentation + if ESP-NOW is enabled. choice EXAMPLE_WPS_TYPE prompt "WPS mode" @@ -44,7 +50,7 @@ menu "Example Configuration" int "WPS PIN" default 0 help - WPS PIN to be used for the connection, incase its not give, AP will derive a new one. + WPS PIN to be used for the connection, in case its not give, AP will derive a new one. endif endmenu From 2d01a3e00a853a17f5505b318ede8eeac1b62823 Mon Sep 17 00:00:00 2001 From: muhaidong Date: Tue, 19 May 2026 20:50:25 +0800 Subject: [PATCH 4/6] fix(doc): update the soft-AP max_connection documentation --- docs/en/api-guides/wifi.rst | 76 +++++++++++----------------------- docs/zh_CN/api-guides/wifi.rst | 76 +++++++++++----------------------- 2 files changed, 50 insertions(+), 102 deletions(-) diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index a66571f329d..6f96c4d6cc8 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -3,9 +3,11 @@ Wi-Fi Driver :link_to_translation:`zh_CN:[中文]` -{IDF_TARGET_MAX_CONN_STA_NUM:default="15", esp32c2="4", esp32c3="10", esp32c6="10"} +{IDF_TARGET_MAX_CONN_STA_NUM:default="15", esp32c2="4"} -{IDF_TARGET_SUB_MAX_NUM_FROM_KEYS:default="2", esp32c3="7", esp32c6="7"} +{IDF_TARGET_SUB_MAX_NUM_FROM_KEYS:default="2", esp32c2="0"} + +{IDF_TARGET_SUPPORT_ENCRYPT_NUM:default="17", esp32c2="4"} {IDF_TARGET_NAME} Wi-Fi Feature List ------------------------------------ @@ -1319,56 +1321,28 @@ AP Basic Configuration API :cpp:func:`esp_wifi_set_config()` can be used to configure the AP. And the configuration will be stored in NVS. The table below describes the fields in detail. -.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c6 +.. list-table:: + :header-rows: 1 + :widths: 15 55 - .. list-table:: - :header-rows: 1 - :widths: 15 55 - - * - Field - - Description - * - ssid - - SSID of AP; if the ssid[0] is 0xFF and ssid[1] is 0xFF, the AP defaults the SSID to ``ESP_aabbcc``, where “aabbcc” is the last three bytes of the AP MAC. - * - password - - Password of AP; if the auth mode is ``WIFI_AUTH_OPEN``, this field will be ignored. - * - ssid_len - - Length of SSID; if ssid_len is 0, check the SSID until there is a termination character. If ssid_len > 32, change it to 32; otherwise, set the SSID length according to ssid_len. - * - channel - - Channel of AP; if the channel is out of range, the Wi-Fi driver defaults to channel 1. So, please make sure the channel is within the required range. For more details, refer to `Wi-Fi Country Code`_. - * - authmode - - Auth mode of ESP AP; currently, ESP AP does not support AUTH_WEP. If the authmode is an invalid value, AP defaults the value to ``WIFI_AUTH_OPEN``. - * - ssid_hidden - - If ssid_hidden is 1, AP does not broadcast the SSID; otherwise, it does broadcast the SSID. - * - max_connection - - The max number of stations allowed to connect in, the default value is 10. ESP Wi-Fi supports up to {IDF_TARGET_MAX_CONN_STA_NUM} (``ESP_WIFI_MAX_CONN_NUM``) Wi-Fi connections. Please note that ESP AP and ESP-NOW share the same encryption hardware keys, so the max_connection parameter will be affected by the :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`. The total number of encryption hardware keys is 17, if :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` <= {IDF_TARGET_SUB_MAX_NUM_FROM_KEYS}, the max_connection can be set up to {IDF_TARGET_MAX_CONN_STA_NUM}, otherwise the max_connection can be set up to (17 - :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`). - * - beacon_interval - - Beacon interval; the value is 100 ~ 60000 ms, with default value being 100 ms. If the value is out of range, AP defaults it to 100 ms. - - -.. only:: esp32c2 - - .. list-table:: - :header-rows: 1 - :widths: 15 55 - - * - Field - - Description - * - ssid - - SSID of AP; if the ssid[0] is 0xFF and ssid[1] is 0xFF, the AP defaults the SSID to ``ESP_aabbcc``, where “aabbcc” is the last three bytes of the AP MAC. - * - password - - Password of AP; if the auth mode is ``WIFI_AUTH_OPEN``, this field will be ignored. - * - ssid_len - - Length of SSID; if ssid_len is 0, check the SSID until there is a termination character. If ssid_len > 32, change it to 32; otherwise, set the SSID length according to ssid_len. - * - channel - - Channel of AP; if the channel is out of range, the Wi-Fi driver defaults to channel 1. So, please make sure the channel is within the required range. For more details, refer to `Wi-Fi Country Code`_. - * - authmode - - Auth mode of ESP AP; currently, ESP AP does not support AUTH_WEP. If the authmode is an invalid value, AP defaults the value to ``WIFI_AUTH_OPEN``. - * - ssid_hidden - - If ssid_hidden is 1, AP does not broadcast the SSID; otherwise, it does broadcast the SSID. - * - max_connection - - The max number of stations allowed to connect in, the default value is 2. ESP Wi-Fi supports up to {IDF_TARGET_MAX_CONN_STA_NUM} (``ESP_WIFI_MAX_CONN_NUM``) Wi-Fi connections. Please note that ESP AP and ESP-NOW share the same encryption hardware keys, so the max_connection parameter will be affected by the :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`. The total number of encryption hardware keys is {IDF_TARGET_MAX_CONN_STA_NUM}, the max_connection can be set up to ({IDF_TARGET_MAX_CONN_STA_NUM} - :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`). - * - beacon_interval - - Beacon interval; the value is 100 ~ 60000 ms, with default value being 100 ms. If the value is out of range, AP defaults it to 100 ms. + * - Field + - Description + * - ssid + - SSID of AP; if the ssid[0] is 0xFF and ssid[1] is 0xFF, the AP defaults the SSID to ``ESP_aabbcc``, where “aabbcc” is the last three bytes of the AP MAC. + * - password + - Password of AP; if the auth mode is ``WIFI_AUTH_OPEN``, this field will be ignored. + * - ssid_len + - Length of SSID; if ssid_len is 0, check the SSID until there is a termination character. If ssid_len > 32, change it to 32; otherwise, set the SSID length according to ssid_len. + * - channel + - Channel of AP; set to 0 for auto selection (min channel: typically 1 for 2.4G, 36 for 5G). Other invalid values return ``ESP_ERR_INVALID_ARG``. So, please make sure the channel is within the required range. For more details, refer to `Wi-Fi Country Code`_. + * - authmode + - Auth mode of ESP AP; currently, ESP AP does not support AUTH_WEP. If the authmode is an invalid value, AP defaults the value to ``WIFI_AUTH_OPEN``. + * - ssid_hidden + - If ssid_hidden is 1, AP does not broadcast the SSID; otherwise, it does broadcast the SSID. + * - max_connection + - The max number of stations allowed to connect in. {IDF_TARGET_NAME} supports up to {IDF_TARGET_MAX_CONN_STA_NUM} (``ESP_WIFI_MAX_CONN_NUM``) Wi-Fi connections. Please note that soft-AP and ESP-NOW share the same encryption hardware keys, so the max_connection parameter will be affected by the :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`. The total number of encryption hardware keys is {IDF_TARGET_SUPPORT_ENCRYPT_NUM}, if :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` <= {IDF_TARGET_SUB_MAX_NUM_FROM_KEYS}, the max_connection can be set up to {IDF_TARGET_MAX_CONN_STA_NUM}, otherwise the max_connection can be set up to ({IDF_TARGET_SUPPORT_ENCRYPT_NUM} - :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`). + * - beacon_interval + - Beacon interval; the value is 100 ~ 60000 ms, with default value being 100 ms. If the value is out of range, AP defaults it to 100 ms. Wi-Fi Protocol Mode diff --git a/docs/zh_CN/api-guides/wifi.rst b/docs/zh_CN/api-guides/wifi.rst index fd63d3fb73f..d3dc159dba0 100644 --- a/docs/zh_CN/api-guides/wifi.rst +++ b/docs/zh_CN/api-guides/wifi.rst @@ -3,9 +3,11 @@ Wi-Fi 驱动程序 :link_to_translation:`en:[English]` -{IDF_TARGET_MAX_CONN_STA_NUM:default="15", esp32c2="4", esp32c3="10", esp32c6="10"} +{IDF_TARGET_MAX_CONN_STA_NUM:default="15", esp32c2="4"} -{IDF_TARGET_SUB_MAX_NUM_FROM_KEYS:default="2", esp32c3="7", esp32c6="7"} +{IDF_TARGET_SUB_MAX_NUM_FROM_KEYS:default="2", esp32c2="0"} + +{IDF_TARGET_SUPPORT_ENCRYPT_NUM:default="17", esp32c2="4"} {IDF_TARGET_NAME} Wi-Fi 功能列表 ------------------------------------ @@ -1318,56 +1320,28 @@ AP 基本配置 API :cpp:func:`esp_wifi_set_config()` 可用于配置 AP。配置的参数信息会保存到 NVS 中。下表详细介绍了各个字段。 -.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c6 +.. list-table:: + :header-rows: 1 + :widths: 15 55 - .. list-table:: - :header-rows: 1 - :widths: 15 55 - - * - 字段 - - 描述 - * - ssid - - 指 AP 的 SSID。如果 ssid[0] 和 ssid[1] 均为 0xFF，AP 默认 SSID 为 ``ESP_aabbcc``，”aabbcc” 是 AP MAC 的最后三个字节。 - * - password - - AP 的密码。如果身份验证模式为 ``WIFI_AUTH_OPEN``，此字段将被忽略。 - * - ssid_len - - SSID 的长度。如果 ssid_len 为 0，则检查 SSID 直至出现终止字符。如果 ssid_len 大于 32，请更改为 32，或者根据 ssid_len 设置 SSID 长度。 - * - channel - - AP 的信道。如果信道超出范围，Wi-Fi 驱动程序将默认为信道 1。所以，请确保信道在要求的范围内。有关详细信息，请参阅 `Wi-Fi 国家/地区代码`_。 - * - authmode - - ESP AP 的身份验证模式。目前，ESP AP 不支持 AUTH_WEP。如果 authmode 是一个无效值，AP 默认该值为 ``WIFI_AUTH_OPEN``。 - * - ssid_hidden - - 如果 ssid_hidden 为 1，AP 不广播 SSID。若为其他值，则广播。 - * - max_connection - - 允许连接 station 的最大数目，默认值是 10。ESP Wi-Fi 支持 {IDF_TARGET_MAX_CONN_STA_NUM} (``ESP_WIFI_MAX_CONN_NUM``) 个 Wi-Fi 连接。请注意， ESP AP 和 ESP-NOW 共享同一块加密硬件 keys，因此 max_connection 参数将受到 :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` 的影响。加密硬件 keys 的总数是 17，如果 :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` 小于等于 {IDF_TARGET_SUB_MAX_NUM_FROM_KEYS}，那么 max_connection 最大可以设置为 {IDF_TARGET_MAX_CONN_STA_NUM}，否则 max_connection 最大可以设置为 (17 - :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`)。 - * - beacon_interval - - beacon 间隔。值为 100 ~ 60000 ms，默认值为 100 ms。如果该值不在上述范围，AP 默认取 100 ms。 - - -.. only:: esp32c2 - - .. list-table:: - :header-rows: 1 - :widths: 15 55 - - * - 字段 - - 描述 - * - ssid - - 指 AP 的 SSID。如果 ssid[0] 和 ssid[1] 均为 0xFF，AP 默认 SSID 为 ``ESP_aabbcc``，”aabbcc” 是 AP MAC 的最后三个字节。 - * - password - - AP 的密码。如果身份验证模式为 ``WIFI_AUTH_OPEN``，此字段将被忽略。 - * - ssid_len - - SSID 的长度。如果 ssid_len 为 0，则检查 SSID 直至出现终止字符。如果 ssid_len 大于 32，请更改为 32，或者根据 ssid_len 设置 SSID 长度。 - * - channel - - AP 的信道。如果信道超出范围，Wi-Fi 驱动程序将默认为信道 1。所以，请确保信道在要求的范围内。有关详细信息，请参阅 `Wi-Fi 国家/地区代码`_。 - * - authmode - - ESP AP 的身份验证模式。目前，ESP AP 不支持 AUTH_WEP。如果 authmode 是一个无效值，AP 默认该值为 ``WIFI_AUTH_OPEN``。 - * - ssid_hidden - - 如果 ssid_hidden 为 1，AP 不广播 SSID。若为其他值，则广播。 - * - max_connection - - 允许连接 station 的最大数目，默认值是 2。ESP Wi-Fi 支持 {IDF_TARGET_MAX_CONN_STA_NUM} (``ESP_WIFI_MAX_CONN_NUM``) 个 Wi-Fi 连接。请注意， ESP AP 和 ESP-NOW 共享同一块加密硬件 keys，因此 max_connection 参数将受到 :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` 的影响。加密硬件 keys 的总数是 {IDF_TARGET_MAX_CONN_STA_NUM}， max_connection 最大可以设置为 ({IDF_TARGET_MAX_CONN_STA_NUM} - :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`)。 - * - beacon_interval - - beacon 间隔。值为 100 ~ 60000 ms，默认值为 100 ms。如果该值不在上述范围，AP 默认取 100 ms。 + * - 字段 + - 描述 + * - ssid + - 指 AP 的 SSID。如果 ssid[0] 和 ssid[1] 均为 0xFF，AP 默认 SSID 为 ``ESP_aabbcc``，”aabbcc” 是 AP MAC 的最后三个字节。 + * - password + - AP 的密码。如果身份验证模式为 ``WIFI_AUTH_OPEN``，此字段将被忽略。 + * - ssid_len + - SSID 的长度。如果 ssid_len 为 0，则检查 SSID 直至出现终止字符。如果 ssid_len 大于 32，请更改为 32，或者根据 ssid_len 设置 SSID 长度。 + * - channel + - AP 的信道。设为 0 表示自动选择（最小信道：2.4 GHz 通常为 1，5 GHz 通常为 36）。其它非法值将返回 ``ESP_ERR_INVALID_ARG``。请确保信道在允许范围内。更多说明请参阅 `Wi-Fi 国家/地区代码`_。 + * - authmode + - ESP AP 的身份验证模式。目前，ESP AP 不支持 AUTH_WEP。如果 authmode 是一个无效值，AP 默认该值为 ``WIFI_AUTH_OPEN``。 + * - ssid_hidden + - 如果 ssid_hidden 为 1，AP 不广播 SSID。若为其他值，则广播。 + * - max_connection + - 允许接入的 station 最大数量。{IDF_TARGET_NAME} 最多支持 {IDF_TARGET_MAX_CONN_STA_NUM}（``ESP_WIFI_MAX_CONN_NUM``） 个 Wi-Fi 连接。请注意，soft-AP 与 ESP-NOW 共享同一套加密硬件 keys，因此 max_connection 会受到 :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` 的影响。加密硬件 keys 总数为 {IDF_TARGET_SUPPORT_ENCRYPT_NUM}：若 :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` <= {IDF_TARGET_SUB_MAX_NUM_FROM_KEYS}，则 max_connection 最大可设为 {IDF_TARGET_MAX_CONN_STA_NUM}；否则最大可设为 ({IDF_TARGET_SUPPORT_ENCRYPT_NUM} - :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`)。 + * - beacon_interval + - beacon 间隔。值为 100 ~ 60000 ms，默认值为 100 ms。如果该值不在上述范围，AP 默认取 100 ms。 Wi-Fi 协议模式 From 372de84423b84e32db2fd0d1e83225c9c29a7766 Mon Sep 17 00:00:00 2001 From: muhaidong Date: Tue, 11 Mar 2025 21:24:06 +0800 Subject: [PATCH 5/6] fix(wifi): update wifi scan threshold doc --- components/esp_wifi/include/esp_wifi_types_generic.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/esp_wifi/include/esp_wifi_types_generic.h b/components/esp_wifi/include/esp_wifi_types_generic.h index f7a7cd16678..505b932864b 100644 --- a/components/esp_wifi/include/esp_wifi_types_generic.h +++ b/components/esp_wifi/include/esp_wifi_types_generic.h @@ -333,11 +333,11 @@ 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 + 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_scan_threshold_t; From c349615654a3bc430a469a912399fef23115a8b1 Mon Sep 17 00:00:00 2001 From: muhaidong Date: Tue, 11 Mar 2025 21:38:17 +0800 Subject: [PATCH 6/6] fix(wifi): update auth mode threshold doc --- components/esp_wifi/include/esp_wifi_types_generic.h | 7 ++++--- docs/en/api-guides/wifi.rst | 4 ++-- docs/zh_CN/api-guides/wifi.rst | 6 +++--- examples/phy/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, 19 insertions(+), 15 deletions(-) diff --git a/components/esp_wifi/include/esp_wifi_types_generic.h b/components/esp_wifi/include/esp_wifi_types_generic.h index 505b932864b..67f3ac0ce48 100644 --- a/components/esp_wifi/include/esp_wifi_types_generic.h +++ b/components/esp_wifi/include/esp_wifi_types_generic.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -337,8 +337,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. */ } wifi_scan_threshold_t; /** diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index 6f96c4d6cc8..9390f4a4b05 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -1309,12 +1309,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 d3dc159dba0..d81aff5c5b1 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/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 2d0dba12051..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 (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 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,