Merge branch 'docs/update_wifi_and_wpa_supplicant_documentation' into…

… 'master'

Docs: Update wifi and wpa_supplicant documentation

See merge request espressif/esp-idf!24029

components/esp_wifi/include/esp_mesh.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2017-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2017-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -1400,7 +1400,7 @@ esp_err_t esp_mesh_set_parent(const wifi_config_t *parent, const mesh_addr_t *pa
  * @return
  *    - ESP_OK
  *    - ESP_ERR_WIFI_NOT_INIT
- *    - ESP_ERR_WIFI_ARG
+ *    - ESP_ERR_INVALID_ARG
  *    - ESP_ERR_WIFI_FAIL
  */
 esp_err_t esp_mesh_scan_get_ap_ie_len(int *len);
@@ -1417,7 +1417,7 @@ esp_err_t esp_mesh_scan_get_ap_ie_len(int *len);
  * @return
  *    - ESP_OK
  *    - ESP_ERR_WIFI_NOT_INIT
- *    - ESP_ERR_WIFI_ARG
+ *    - ESP_ERR_INVALID_ARG
  *    - ESP_ERR_WIFI_FAIL
  */
 esp_err_t esp_mesh_scan_get_ap_record(wifi_ap_record_t *ap_record, void *buffer);
@@ -1506,7 +1506,7 @@ esp_err_t esp_mesh_switch_channel(const uint8_t *new_bssid, int csa_newchan, int
  * @return
  *    - ESP_OK
  *    - ESP_ERR_WIFI_NOT_INIT
- *    - ESP_ERR_WIFI_ARG
+ *    - ESP_ERR_INVALID_ARG
  */
 esp_err_t esp_mesh_get_router_bssid(uint8_t *router_bssid);
 

components/esp_wifi/include/esp_mesh_internal.h

@@ -126,7 +126,7 @@ typedef struct {
  * @return
  *    - ESP_OK
  *    - ESP_FAIL
- *    - ESP_ERR_WIFI_ARG
+ *    - ESP_ERR_INVALID_ARG
  */
 esp_err_t esp_mesh_set_beacon_interval(int interval_ms);
 

components/esp_wifi/include/esp_private/wifi.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -132,7 +132,7 @@ void esp_wifi_internal_free_rx_buffer(void* buffer);
   * @return
   *    - ESP_OK  : Successfully transmit the buffer to wifi driver
   *    - ESP_ERR_NO_MEM: out of memory
-  *    - ESP_ERR_WIFI_ARG: invalid argument
+  *    - ESP_ERR_INVALID_ARG: invalid argument
   *    - ESP_ERR_WIFI_IF : WiFi interface is invalid
   *    - ESP_ERR_WIFI_CONN : WiFi interface is not created, e.g. send the data to STA while WiFi mode is AP mode
   *    - ESP_ERR_WIFI_NOT_STARTED : WiFi is not started
@@ -171,7 +171,7 @@ typedef void (*wifi_netstack_buf_free_cb_t)(void *netstack_buf);
   * @return
   *    - ESP_OK  : Successfully transmit the buffer to wifi driver
   *    - ESP_ERR_NO_MEM: out of memory
-  *    - ESP_ERR_WIFI_ARG: invalid argument
+  *    - ESP_ERR_INVALID_ARG: invalid argument
   *    - ESP_ERR_WIFI_IF : WiFi interface is invalid
   *    - ESP_ERR_WIFI_CONN : WiFi interface is not created, e.g. send the data to STA while WiFi mode is AP mode
   *    - ESP_ERR_WIFI_NOT_STARTED : WiFi is not started
@@ -439,7 +439,7 @@ esp_err_t esp_wifi_internal_set_log_level(wifi_log_level_t level);
   * @return
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
-  *    - ESP_ERR_WIFI_ARG: invalid argument
+  *    - ESP_ERR_INVALID_ARG: invalid argument
   */
 esp_err_t esp_wifi_internal_set_log_mod(wifi_log_module_t module, uint32_t submodule, bool enable);
 

components/esp_wifi/include/esp_wifi.h

@@ -350,9 +350,9 @@ esp_err_t esp_wifi_restore(void);
   * @attention 3. The scanning triggered by esp_wifi_scan_start() will not be effective until connection between device and the AP is established.
   *               If device is scanning and connecting at the same time, it will abort scanning and return a warning message and error
   *               number ESP_ERR_WIFI_STATE.
-  *               If you want to do reconnection after device received disconnect event, remember to add the maximum retry time, otherwise the called
-  *               scan will not work. This is especially true when the AP doesn't exist, and you still try reconnection after device received disconnect
-  *               event with the reason code WIFI_REASON_NO_AP_FOUND.
+  * @attention 4. This API attempts to connect to an Access Point (AP) only once. To enable reconnection in case of a connection failure, please use
+  *               the 'failure_retry_cnt' feature in the 'wifi_sta_config_t'. Users are suggested to implement reconnection logic in their application
+  *               for scenarios where the specified AP does not exist, or reconnection is desired after the device has received a disconnect event.
   *
   * @return
   *    - ESP_OK: succeed
@@ -407,7 +407,10 @@ esp_err_t esp_wifi_deauth_sta(uint16_t aid);
   * @attention The values of maximum active scan time and passive scan time per channel are limited to 1500 milliseconds.
   *            Values above 1500ms may cause station to disconnect from AP and are not recommended.
   *
-  * @param     config  configuration of scanning
+  * @param     config  configuration settings for scanning, if set to NULL default settings will be used
+  *                    of which default values are show_hidden:false, scan_type:active, scan_time.active.min:0,
+  *                    scan_time.active.max:120 miliseconds, scan_time.passive:360 miliseconds
+  *
   * @param     block if block is true, this API will block the caller until the scan is done, otherwise
   *                         it will return immediately
   *
@@ -792,7 +795,7 @@ esp_err_t esp_wifi_set_promiscuous_ctrl_filter(const wifi_promiscuous_filter_t *
   * @return
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
-  *    - ESP_ERR_WIFI_ARG: invalid argument
+  *    - ESP_ERR_INVALID_ARG: invalid argument
   */
 esp_err_t esp_wifi_get_promiscuous_ctrl_filter(wifi_promiscuous_filter_t *filter);
 
@@ -939,7 +942,7 @@ esp_err_t esp_wifi_set_vendor_ie_cb(esp_vendor_ie_cb_t cb, void *ctx);
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
   *    - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start
-  *    - ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is out of range
+  *    - ESP_ERR_INVALID_ARG: invalid argument, e.g. parameter is out of range
   */
 esp_err_t esp_wifi_set_max_tx_power(int8_t power);
 
@@ -952,7 +955,7 @@ esp_err_t esp_wifi_set_max_tx_power(int8_t power);
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
   *    - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start
-  *    - ESP_ERR_WIFI_ARG: invalid argument
+  *    - ESP_ERR_INVALID_ARG: invalid argument
   */
 esp_err_t esp_wifi_get_max_tx_power(int8_t *power);
 
@@ -981,7 +984,7 @@ esp_err_t esp_wifi_set_event_mask(uint32_t mask);
   * @return
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
-  *    - ESP_ERR_WIFI_ARG: invalid argument
+  *    - ESP_ERR_INVALID_ARG: invalid argument
   */
 esp_err_t esp_wifi_get_event_mask(uint32_t *mask);
 
@@ -1001,7 +1004,7 @@ esp_err_t esp_wifi_get_event_mask(uint32_t *mask);
   *            the system sequence number.
   *            Generally, if esp_wifi_80211_tx is called before the Wi-Fi connection has been set up, both
   *            en_sys_seq==true and en_sys_seq==false are fine. However, if the API is called after the Wi-Fi
-  *            connection has been set up, en_sys_seq must be true, otherwise ESP_ERR_WIFI_ARG is returned.
+  *            connection has been set up, en_sys_seq must be true, otherwise ESP_ERR_INVALID_ARG is returned.
   *
   * @return
   *    - ESP_OK: success
@@ -1073,7 +1076,7 @@ esp_err_t esp_wifi_set_csi(bool en);
   * @return
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
-  *    - ESP_ERR_WIFI_ARG: Invalid argument, e.g. parameter is NULL, invalid GPIO number etc
+  *    - ESP_ERR_INVALID_ARG: Invalid argument, e.g. parameter is NULL, invalid GPIO number etc
   */
 esp_err_t esp_wifi_set_ant_gpio(const wifi_ant_gpio_config_t *config);
 
@@ -1085,7 +1088,7 @@ esp_err_t esp_wifi_set_ant_gpio(const wifi_ant_gpio_config_t *config);
   * @return
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
-  *    - ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is NULL
+  *    - ESP_ERR_INVALID_ARG: invalid argument, e.g. parameter is NULL
   */
 esp_err_t esp_wifi_get_ant_gpio(wifi_ant_gpio_config_t *config);
 
@@ -1098,7 +1101,7 @@ esp_err_t esp_wifi_get_ant_gpio(wifi_ant_gpio_config_t *config);
   * @return
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
-  *    - ESP_ERR_WIFI_ARG: Invalid argument, e.g. parameter is NULL, invalid antenna mode or invalid GPIO number
+  *    - ESP_ERR_INVALID_ARG: Invalid argument, e.g. parameter is NULL, invalid antenna mode or invalid GPIO number
   */
 esp_err_t esp_wifi_set_ant(const wifi_ant_config_t *config);
 
@@ -1110,7 +1113,7 @@ esp_err_t esp_wifi_set_ant(const wifi_ant_config_t *config);
   * @return
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
-  *    - ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is NULL
+  *    - ESP_ERR_INVALID_ARG: invalid argument, e.g. parameter is NULL
   */
 esp_err_t esp_wifi_get_ant(wifi_ant_config_t *config);
 
@@ -1143,7 +1146,7 @@ int64_t esp_wifi_get_tsf_time(wifi_interface_t interface);
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
   *    - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start
-  *    - ESP_ERR_WIFI_ARG: invalid argument, For Station, if sec is less than 3. For SoftAP, if sec is less than 10.
+  *    - ESP_ERR_INVALID_ARG: invalid argument, For Station, if sec is less than 3. For SoftAP, if sec is less than 10.
   */
 esp_err_t esp_wifi_set_inactive_time(wifi_interface_t ifx, uint16_t sec);
 
@@ -1157,7 +1160,7 @@ esp_err_t esp_wifi_set_inactive_time(wifi_interface_t ifx, uint16_t sec);
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
   *    - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start
-  *    - ESP_ERR_WIFI_ARG: invalid argument
+  *    - ESP_ERR_INVALID_ARG: invalid argument
   */
 esp_err_t esp_wifi_get_inactive_time(wifi_interface_t ifx, uint16_t *sec);
 
@@ -1173,16 +1176,17 @@ esp_err_t esp_wifi_get_inactive_time(wifi_interface_t ifx, uint16_t *sec);
 esp_err_t esp_wifi_statis_dump(uint32_t modules);
 
 /**
-  * @brief      Set RSSI threshold below which APP will get an event
+  * @brief      Set RSSI threshold, if average rssi gets lower than threshold, WiFi task will post event WIFI_EVENT_STA_BSS_RSSI_LOW.
   *
-  * @attention  This API needs to be called every time after WIFI_EVENT_STA_BSS_RSSI_LOW event is received.
+  * @attention  If the user wants to receive another WIFI_EVENT_STA_BSS_RSSI_LOW event after receiving one, this API needs to be
+  *             called again with an updated/same RSSI threshold.
   *
   * @param      rssi threshold value in dbm between -100 to 0
   *
   * @return
   *    - ESP_OK: succeed
   *    - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init
-  *    - ESP_ERR_WIFI_ARG: invalid argument
+  *    - ESP_ERR_INVALID_ARG: invalid argument
   */
 esp_err_t esp_wifi_set_rssi_threshold(int32_t rssi);
 
@@ -1347,8 +1351,6 @@ esp_err_t esp_wifi_sta_get_aid(uint16_t *aid);
   *
   * @param[out] phymode  store the negotiated phymode.
   *
-  * @attention Operation phy mode, BIT[5]: indicate whether LR enabled, BIT[0-4]: wifi_phy_mode_t
-  *
   * @return
   *    - ESP_OK: succeed
   */

components/esp_wifi/include/esp_wifi_types.h

@@ -308,7 +308,7 @@ typedef struct {
     uint8_t channel;                          /**< channel of target AP. Set to 1~13 to scan starting from the specified channel before connecting to AP. If the channel of AP is unknown, set it to 0.*/
     uint16_t listen_interval;                 /**< Listen interval for ESP32 station to receive beacon when WIFI_PS_MAX_MODEM is set. Units: AP beacon intervals. Defaults to 3 if set to 0. */
     wifi_sort_method_t sort_method;           /**< sort the connect AP in the list by rssi or security mode */
-    wifi_scan_threshold_t  threshold;         /**< When sort_method is set, only APs which have an auth mode that is more secure than the selected auth mode and a signal stronger than the minimum RSSI will be used. */
+    wifi_scan_threshold_t  threshold;         /**< When scan_threshold is set, only APs which have an auth mode that is more secure than the selected auth mode and a signal stronger than the minimum RSSI will be used. */
     wifi_pmf_config_t pmf_cfg;                /**< Configuration for Protected Management Frame. Will be advertised in RSN Capabilities in RSN IE. */
     uint32_t rm_enabled:1;                    /**< Whether Radio Measurements are enabled for the connection */
     uint32_t btm_enabled:1;                   /**< Whether BSS Transition Management is enabled for the connection */

components/wpa_supplicant/esp_supplicant/include/esp_wpa2.h

@@ -33,7 +33,7 @@ extern "C" {
   * @brief  Enable wpa2 enterprise authentication.
   *
   * @attention 1. wpa2 enterprise authentication can only be used when station mode is enabled.
-  * @attention 2. wpa2 enterprise authentication can only support TLS, PEAP-MSCHAPv2 and TTLS-MSCHAPv2 method.
+  * @attention 2. wpa2 enterprise authentication supports EAP-FAST, TLS, PEAP, TTLS(EAP, MSCHAPv2, MSCHAP, PAP, CHAP) methods.
   *
   * @return
   *    - ESP_OK: succeed.
@@ -45,7 +45,7 @@ esp_err_t esp_wifi_sta_wpa2_ent_enable(void);
   * @brief  Disable wpa2 enterprise authentication.
   *
   * @attention 1. wpa2 enterprise authentication can only be used when station mode is enabled.
-  * @attention 2. wpa2 enterprise authentication can only support TLS, PEAP-MSCHAPv2 and TTLS-MSCHAPv2 method.
+  * @attention 2. wpa2 enterprise authentication supports EAP-FAST, TLS, PEAP, TTLS(EAP, MSCHAPv2, MSCHAP, PAP, CHAP) methods.
   *
   * @return
   *    - ESP_OK: succeed.