feat(esp_wifi): Showcase roaming_app capabalities through dedicated e…

…xample

- Shows use of roaming app through dedicated example : roaming_app_example.
- Changes the location of the earlier roaming example by moving it into the roaming_11kvr.
- Please note that this feature is still experimental and still being optimised
and tuned.

examples/wifi/README.md

@@ -15,7 +15,7 @@ The examples are grouped into sub-directories by category. Each category directo
 * `getting_started` contains the basic examples for using Wi-Fi in STA and AP mode.
 * `iperf` shows the common performance measurements for two ESP running this example.
 * `power_save` contains a how to use power save mode of Wi-Fi.
-* `roaming` contains a example using 802.11k and 802.11v APIs.
+* `roaming` contains 2 examples that demonstrate roaming capabilities.
 * `scan` shows how to scan for all the available APs.
 * `smart_config` shows how ESP connects to a target AP with ESPTOUCH.
 * `wifi_eap_fast` shows how ESP connects to AP with Wi-Fi enterprise encryption using the EAP-FAST method.

examples/wifi/roaming/README.md

@@ -1,95 +1,16 @@
 | Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-S2 | ESP32-S3 |
 | ----------------- | ----- | -------- | -------- | -------- | -------- | -------- |
 
-# Roaming Example
+# Wi-Fi Roaming Examples
 
-(See the README.md file in the upper level 'examples' directory for more information about examples.)
+This directory contains 2 example ESP-IDF projects that demonstrate the Wi-Fi Roaming capabilities. These are intended to demonstrate the Wi-Fi roaming functionality, and to provide code that you can copy and use in your own projects.
 
-This example demonstrate a roaming example using 11k and 11v APIs.
+# Example Layout
 
-## How to use example
+* `roaming_11kvr` demonstrates the use of API's that implement IEEE 802.11kvr mechanisms.
+* `roaming_app` implements Espressif's roaming app that optimally combines legacy roaming and 802.11kv based
+   roaming for effective roaming.
 
-Before project configuration and build, be sure to set the correct chip target using `idf.py set-target <chip_name>`.
+# More
 
-### Hardware Required
-
-* A development board with ESP32/ESP32-S2/ESP32-C3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
-* A USB cable for Power supply and programming
-
-### Build and Flash
-
-Build the project and flash it to the board, then run the monitor tool to view the serial output:
-
-Run `idf.py -p PORT flash monitor` to build, flash and monitor the project.
-
-(To exit the serial monitor, type ``Ctrl-]``.)
-
-See the Getting Started Guide for all the steps to configure and use the ESP-IDF to build projects.
-
-* [ESP-IDF Getting Started Guide on ESP32](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html)
-* [ESP-IDF Getting Started Guide on ESP32-S2](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/get-started/index.html)
-* [ESP-IDF Getting Started Guide on ESP32-C3](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/get-started/index.html)
-
-## Example Output
-
-All the logs are taken after debug enabled:
-
-Beacon request:
-```
-I (11125) wpa: scan issued at time=7579442263
-I (11125) wpa: BSS: Add new id 1 BSSID b6:fb:e4:4d:6e:22 SSID 'ESPTest' chan 1
-I (11135) wpa: BSS: Add new id 2 BSSID d6:fb:e4:4d:6e:22 SSID 'ESPDedicated' chan 1
-I (11165) wpa: BSS: Add new id 3 BSSID c6:fb:e4:4d:6e:22 SSID 'ESPGuestNetwork' chan 1
-I (11185) wpa: BSS: Add new id 4 BSSID b4:fb:e4:4d:6e:22 SSID 'ESPIndia' chan 1
-I (11245) wpa: BSS: Add new id 5 BSSID b8:27:eb:3b:4a:59 SSID 'wpa2_enterprise' chan 6
-I (11365) wpa: BSS: Add new id 6 BSSID 38:94:ed:34:07:66 SSID 'Nighthawk' chan 6
-I (11365) wpa: BSS: Add new id 7 BSSID 10:da:43:dc:99:20 SSID 'NETGEAR40' chan 6
-I (12435) wpa: BSS: Add new id 8 BSSID c6:fb:e4:4d:7c:89 SSID 'ESPGuestNetwork' chan 11
-I (12445) wpa: BSS: Add new id 9 BSSID d6:fb:e4:4d:7c:89 SSID 'ESPDedicated' chan 11
-I (12455) wpa: BSS: Add new id 10 BSSID b6:fb:e4:4d:7c:89 SSID 'ESPTest' chan 11
-I (12485) wpa: BSS: Add new id 11 BSSID b4:fb:e4:4d:7c:89 SSID 'ESPIndia' chan 11
-I (12825) wpa: scan done received
-I (12845) wpa: action frame sent
-I (12845) wpa: action frame sent
-```
-
-Sta's moving from one AP to another on BTM request:
-
-```
-I (379479) wpa: WNM: RX action 7 from 50:3e:aa:26:35:42
-I (379479) wpa: WNM: BSS Transition Management Request: dialog_token=1 request_mode=0x1 disassoc_timer=0 validity_interval=1
-I (379489) wpa: WNM: Neighbor report tag 52
-I (379499) wpa: WNM: Subelement id=3 len=1
-I (379499) wpa: WNM: BSS Transition Candidate List
-I (379509) wpa: 0: b4:e6:2d:eb:1d:76 info=0x0 op_class=81 chan=1 phy=7 pref=255
-I (379519) wpa: WNM: Candidate list valid for 102 ms
-I (379519) wpa: WNM: Scan only for a specific BSSID since there is only a single candidate b4:e6:2d:eb:1d:76
-I (379539) wpa: scan issued at time=9979439869
-I (379539) wpa: BSS: Add new id 12 BSSID b4:e6:2d:eb:1d:76 SSID 'roaming_test123' chan 6
-I (381979) wpa: scan done received
-I (381979) wpa: WNM: Process scan results for BSS Transition Management
-I (381979) wpa: WNM: Found an acceptable preferred transition candidate BSS b4:e6:2d:eb:1d:76 (RSSI -7)
-I (381989) wpa: WNM: Transition to BSS b4:e6:2d:eb:1d:76 based on BSS Transition Management Request after_new_scan=1)
-I (381999) wpa: WNM: Sending successful BSS Transition Management Response
-I (382009) wpa: WNM: Send BSS Transition Management Response to 50:3e:aa:26:35:42 dialog_token=1 status=0 reason=0 delay=0
-I (382019) wpa: action frame sent
-I (382029) wpa: WNM: Issuing connect
-I (382029) wifi:state: run -> init (0)
-I (382029) wifi:pm stop, total sleep time: 102136757 us / 109258805 us
-
-I (382039) wifi:new:<6,0>, old:<6,0>, ap:<255,255>, sta:<6,0>, prof:1
-I (382769) wifi:new:<6,1>, old:<6,0>, ap:<255,255>, sta:<6,1>, prof:1
-I (384689) wifi:state: init -> auth (b0)
-I (384699) wifi:state: auth -> assoc (0)
-I (384709) wifi:state: assoc -> run (10)
-I (384729) wifi:connected with roaming_test123, aid = 1, channel 6, 40U, bssid = b4:e6:2d:eb:1d:76
-I (384729) wifi:security: WPA2-PSK, phy: bgn, rssi: -7
-I (384729) wifi:pm start, type: 1
-
-I (384789) wifi:AP's beacon interval = 102400 us, DTIM period = 2
-I (385609) esp_netif_handlers: sta ip: 192.168.4.2, mask: 255.255.255.0, gw: 192.168.4.1
-```
-
-## Troubleshooting
-
-For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.
+See the [README.md](../README.md) file in the upper level [examples](../) directory for more information about examples.

examples/wifi/roaming/roaming_11kvr/README.md

@@ -0,0 +1,95 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-S2 | ESP32-S3 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- |
+
+# Roaming Example
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This example demonstrate a roaming example using 11k and 11v APIs.
+
+## How to use example
+
+Before project configuration and build, be sure to set the correct chip target using `idf.py set-target <chip_name>`.
+
+### Hardware Required
+
+* A development board with ESP32/ESP32-S2/ESP32-C3 SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
+* A USB cable for Power supply and programming
+
+### Build and Flash
+
+Build the project and flash it to the board, then run the monitor tool to view the serial output:
+
+Run `idf.py -p PORT flash monitor` to build, flash and monitor the project.
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for all the steps to configure and use the ESP-IDF to build projects.
+
+* [ESP-IDF Getting Started Guide on ESP32](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html)
+* [ESP-IDF Getting Started Guide on ESP32-S2](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/get-started/index.html)
+* [ESP-IDF Getting Started Guide on ESP32-C3](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/get-started/index.html)
+
+## Example Output
+
+All the logs are taken after debug enabled:
+
+Beacon request:
+```
+I (11125) wpa: scan issued at time=7579442263
+I (11125) wpa: BSS: Add new id 1 BSSID b6:fb:e4:4d:6e:22 SSID 'ESPTest' chan 1
+I (11135) wpa: BSS: Add new id 2 BSSID d6:fb:e4:4d:6e:22 SSID 'ESPDedicated' chan 1
+I (11165) wpa: BSS: Add new id 3 BSSID c6:fb:e4:4d:6e:22 SSID 'ESPGuestNetwork' chan 1
+I (11185) wpa: BSS: Add new id 4 BSSID b4:fb:e4:4d:6e:22 SSID 'ESPIndia' chan 1
+I (11245) wpa: BSS: Add new id 5 BSSID b8:27:eb:3b:4a:59 SSID 'wpa2_enterprise' chan 6
+I (11365) wpa: BSS: Add new id 6 BSSID 38:94:ed:34:07:66 SSID 'Nighthawk' chan 6
+I (11365) wpa: BSS: Add new id 7 BSSID 10:da:43:dc:99:20 SSID 'NETGEAR40' chan 6
+I (12435) wpa: BSS: Add new id 8 BSSID c6:fb:e4:4d:7c:89 SSID 'ESPGuestNetwork' chan 11
+I (12445) wpa: BSS: Add new id 9 BSSID d6:fb:e4:4d:7c:89 SSID 'ESPDedicated' chan 11
+I (12455) wpa: BSS: Add new id 10 BSSID b6:fb:e4:4d:7c:89 SSID 'ESPTest' chan 11
+I (12485) wpa: BSS: Add new id 11 BSSID b4:fb:e4:4d:7c:89 SSID 'ESPIndia' chan 11
+I (12825) wpa: scan done received
+I (12845) wpa: action frame sent
+I (12845) wpa: action frame sent
+```
+
+Sta's moving from one AP to another on BTM request:
+
+```
+I (379479) wpa: WNM: RX action 7 from 50:3e:aa:26:35:42
+I (379479) wpa: WNM: BSS Transition Management Request: dialog_token=1 request_mode=0x1 disassoc_timer=0 validity_interval=1
+I (379489) wpa: WNM: Neighbor report tag 52
+I (379499) wpa: WNM: Subelement id=3 len=1
+I (379499) wpa: WNM: BSS Transition Candidate List
+I (379509) wpa: 0: b4:e6:2d:eb:1d:76 info=0x0 op_class=81 chan=1 phy=7 pref=255
+I (379519) wpa: WNM: Candidate list valid for 102 ms
+I (379519) wpa: WNM: Scan only for a specific BSSID since there is only a single candidate b4:e6:2d:eb:1d:76
+I (379539) wpa: scan issued at time=9979439869
+I (379539) wpa: BSS: Add new id 12 BSSID b4:e6:2d:eb:1d:76 SSID 'roaming_test123' chan 6
+I (381979) wpa: scan done received
+I (381979) wpa: WNM: Process scan results for BSS Transition Management
+I (381979) wpa: WNM: Found an acceptable preferred transition candidate BSS b4:e6:2d:eb:1d:76 (RSSI -7)
+I (381989) wpa: WNM: Transition to BSS b4:e6:2d:eb:1d:76 based on BSS Transition Management Request after_new_scan=1)
+I (381999) wpa: WNM: Sending successful BSS Transition Management Response
+I (382009) wpa: WNM: Send BSS Transition Management Response to 50:3e:aa:26:35:42 dialog_token=1 status=0 reason=0 delay=0
+I (382019) wpa: action frame sent
+I (382029) wpa: WNM: Issuing connect
+I (382029) wifi:state: run -> init (0)
+I (382029) wifi:pm stop, total sleep time: 102136757 us / 109258805 us
+
+I (382039) wifi:new:<6,0>, old:<6,0>, ap:<255,255>, sta:<6,0>, prof:1
+I (382769) wifi:new:<6,1>, old:<6,0>, ap:<255,255>, sta:<6,1>, prof:1
+I (384689) wifi:state: init -> auth (b0)
+I (384699) wifi:state: auth -> assoc (0)
+I (384709) wifi:state: assoc -> run (10)
+I (384729) wifi:connected with roaming_test123, aid = 1, channel 6, 40U, bssid = b4:e6:2d:eb:1d:76
+I (384729) wifi:security: WPA2-PSK, phy: bgn, rssi: -7
+I (384729) wifi:pm start, type: 1
+
+I (384789) wifi:AP's beacon interval = 102400 us, DTIM period = 2
+I (385609) esp_netif_handlers: sta ip: 192.168.4.2, mask: 255.255.255.0, gw: 192.168.4.1
+```
+
+## Troubleshooting
+
+For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.

examples/wifi/roaming/main/roaming_example.c → examples/wifi/roaming/roaming_11kvr/main/roaming_example.c

@@ -1,3 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
 #include <string.h>
 #include <inttypes.h>
 #include <stdlib.h>
@@ -189,7 +194,7 @@ static char * get_btm_neighbor_list(uint8_t *report, size_t report_len)
 			pos += s_len;
 		}
 
-		ESP_LOGI(TAG, "RMM neigbor report bssid=" MACSTR
+		ESP_LOGI(TAG, "RMM neighbor report bssid=" MACSTR
 				" info=0x%" PRIx32 " op_class=%u chan=%u phy_type=%u%s%s%s%s",
 				MAC2STR(nr), WPA_GET_LE32(nr + ETH_ALEN),
 				nr[ETH_ALEN + 4], nr[ETH_ALEN + 5],
@@ -310,11 +315,11 @@ char * get_tmp_neighbor_list(uint8_t *report, size_t report_len)
 static void esp_neighbor_report_recv_handler(void* arg, esp_event_base_t event_base,int32_t event_id, void* event_data)
 {
 	if (!g_neighbor_report_active) {
-		ESP_LOGV(TAG,"Neighbor report recieved but not triggerred by us");
+		ESP_LOGV(TAG,"Neighbor report received but not triggered by us");
 	    return;
     }
     if (!event_data) {
-        ESP_LOGE(TAG, "No event data recieved for neighbor report");
+        ESP_LOGE(TAG, "No event data received for neighbor report");
         return;
     }
     g_neighbor_report_active = false;

examples/wifi/roaming/roaming_app/CMakeLists.txt

@@ -0,0 +1,6 @@
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(wifi_roaming_app)

examples/wifi/roaming/roaming_app/README.md

@@ -0,0 +1,83 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C6 | ESP32-S2 | ESP32-S3 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- |
+
+# Wi-Fi Station Example
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This example shows how to use the Wi-Fi Roaming App  functionality of the Wi-Fi driver of ESP for efficient roaming between compatible APs.
+
+## How to use example
+
+### Configure the project
+
+Open the project configuration menu (`idf.py menuconfig`).
+
+In the `Example Configuration` menu:
+
+* Set the Wi-Fi configuration.
+    * Set `WiFi SSID`.
+    * Set `WiFi Password`.
+
+* To better understand how to configure the app in Components  --> Wi-Fi --> Roaming App settings,
+  please go read the README at components/esp_wifi/wifi_apps/roaming_app/src.
+Optional: If you need, change the other options according to your requirements.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run the monitor tool to view the serial output:
+
+Run `idf.py -p PORT flash monitor` to build, flash and monitor the project.
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for all the steps to configure and use the ESP-IDF to build projects.
+
+* [ESP-IDF Getting Started Guide on ESP32](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html)
+* [ESP-IDF Getting Started Guide on ESP32-S2](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/get-started/index.html)
+* [ESP-IDF Getting Started Guide on ESP32-C3](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/get-started/index.html)
+
+## Example Output
+Note that the output, in particular the order of the output, may vary depending on the environment.
+
+Console output if station roams between APs successfully:
+```
+I (827) wifi roaming app: wifi_init_sta finished.
+I (837) wifi:new:<1,0>, old:<1,0>, ap:<255,255>, sta:<1,0>, prof:5
+I (837) wifi:state: init -> auth (b0)
+I (847) wifi:state: auth -> assoc (0)
+I (857) wifi:Association refused temporarily, comeback time 1000 (TUs)
+I (1877) wifi:state: assoc -> assoc (0)
+I (1917) wifi:state: assoc -> run (10)
+I (2997) wifi:connected with roaming_setup, aid = 1, channel 1, BW20, bssid = de:bd:5b:93:55:99
+I (2997) wifi:security: WPA2-PSK, phy: bgn, rssi: -58
+I (3007) wifi:pm start, type: 1
+
+I (3087) wifi:AP's beacon interval = 102400 us, DTIM period = 2
+I (10467) ROAM: roaming_app_rssi_low_handler:bss rssi is=-61
+I (10467) ROAM: Issued Scan
+I (10857) ROAM: Could not find a better AP with the threshold set to 1
+I (63017) ROAM: Issued Scan
+I (63347) ROAM: Found a better AP 7c:50:79:06:18:46 at channel 9
+I (63347) wifi:state: run -> init (cc0)
+I (63347) wifi:pm stop, total sleep time: 54401305 us / 60339946 us
+
+I (63347) wifi:new:<1,0>, old:<1,0>, ap:<255,255>, sta:<1,0>, prof:5
+E (63357) ROAM: Neighbor report is empty
+I (63357) wifi roaming app: station disconnected during roaming
+I (63377) wifi roaming app: connect to the AP fail
+I (63377) ROAM: Disconnecting and connecting to 7c:50:79:06:18:46 on account of better rssi
+I (63497) wifi:new:<9,0>, old:<1,0>, ap:<255,255>, sta:<9,0>, prof:5
+I (63837) wifi:state: init -> auth (b0)
+I (63847) wifi:state: auth -> assoc (0)
+I (63887) wifi:Association refused temporarily, comeback time 1000 (TUs)
+I (64907) wifi:state: assoc -> assoc (0)
+I (64977) wifi:state: assoc -> run (10)
+I (65007) wifi:connected with roaming_setup, aid = 1, channel 9, BW20, bssid = 7c:50:79:06:18:46
+I (65007) wifi:security: WPA2-PSK, phy: bgn, rssi: -32
+I (65027) wifi:pm start, type: 1
+```
+
+## Troubleshooting
+
+For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.

examples/wifi/roaming/roaming_app/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "roaming_app_example.c"
+                    INCLUDE_DIRS ".")

examples/wifi/roaming/roaming_app/main/Kconfig.projbuild

@@ -0,0 +1,14 @@
+menu "Example Configuration"
+
+    config ESP_WIFI_SSID
+        string "WiFi SSID"
+        default "myssid"
+        help
+            SSID (network name) for the example to connect to.
+
+    config ESP_WIFI_PASSWORD
+        string "WiFi Password"
+        default "mypassword"
+        help
+            WiFi password (WPA or WPA2) for the example to use.
+endmenu