feat(wifi): Allow setting minimum time for wifi scan (#10083)

* feat(wifi): Allow setting minimum time for wifi scan

* ci(pre-commit): Apply automatic fixes

---------
Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>

libraries/WiFi/examples/WiFiScan/README.md

@@ -4,7 +4,7 @@ This example demonstrates how to use the WiFi library to scan available WiFi net
 
 ## Supported Targets
 
-Currently this example supports the following targets.
+Currently, this example supports the following targets.
 
 | Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 | ESP32-C6 |
 | ----------------- | ----- | -------- | -------- | -------- | -------- |
@@ -45,7 +45,7 @@ Nr | SSID            | RSSI | CH | Encryption
 * **Programming Fail:** If the programming/flash procedure fails, try to reduce the serial connection speed.
 * **COM port not detected:** Check the USB cable connection and the USB to Serial driver installation.
 
-If the error persist, you can ask help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
+If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
 
 ## Contribute
 

libraries/WiFi/examples/WiFiScanAsync/README.md

@@ -4,7 +4,7 @@ This example demonstrates how to use the WiFi library to scan available WiFi net
 
 ## Supported Targets
 
-Currently this example supports the following targets.
+Currently, this example supports the following targets.
 
 | Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 | ESP32-C6 |
 | ----------------- | ----- | -------- | -------- | -------- | -------- |
@@ -55,7 +55,7 @@ Nr | SSID            | RSSI | CH | Encryption
 * **Programming Fail:** If the programming/flash procedure fails, try to reduce the serial connection speed.
 * **COM port not detected:** Check the USB cable connection and the USB to Serial driver installation.
 
-If the error persist, you can ask help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
+If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
 
 ## Contribute
 

libraries/WiFi/examples/WiFiScanTime/README.md

+# WiFiScanTime Example
+
+This example demonstrates how to use the WiFi library to scan available WiFi networks with custom scan timing and print the results.
+
+## Supported Targets
+
+Currently, this example supports the following targets.
+
+| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 | ESP32-C6 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- |
+
+## How to Use Example
+
+* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide).
+
+#### Using Arduino IDE
+
+* Before Compile/Verify, select the correct board: `Tools -> Board`.
+* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.
+
+#### Using Platform IO
+
+* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file.
+
+## Example/Log Output
+
+```
+Setup done
+Scan start
+Scan done, elapsed time: 4960 ms
+17 networks found
+Nr | SSID            | RSSI | CH | Encryption
+ 1 | IoTNetwork      |  -62 |  1 | WPA2
+ 2 | WiFiSSID        |  -62 |  1 | WPA2-EAP
+ 3 | B3A7992         |  -63 |  6 | WPA+WPA2
+ 4 | WiFi            |  -63 |  6 | WPA3
+ 5 | IoTNetwork2     |  -64 | 11 | WPA2+WPA3
+...
+```
+
+## Troubleshooting
+
+***Important: Be sure you're using a good quality USB cable and you have enough power source for your project.***
+
+* **Programming Fail:** If the programming/flash procedure fails, try to reduce the serial connection speed.
+* **COM port not detected:** Check the USB cable connection and the USB to Serial driver installation.
+
+If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
+
+## Contribute
+
+To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)
+
+If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome!
+
+Before creating a new issue, be sure to try the Troubleshooting and to check if the same issue was already created by someone else.
+
+## Resources
+
+* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
+* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf)
+* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf)
+* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf)
+* ESP32-C6 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c6_datasheet_en.pdf)
+* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)

libraries/WiFi/examples/WiFiScanTime/WiFiScanTime.ino

+/*
+ *  This sketch demonstrates how to scan WiFi networks with custom scanning time.
+ *  The API is based on the Arduino WiFi Shield library, but has significant changes as newer WiFi functions are supported.
+ *  E.g. the return value of `encryptionType()` different because more modern encryption is supported.
+ */
+
+/*
+ * WiFi scan timing parameters explained:
+ *
+ * min=0, max=0: scan dwells on each channel for 120 ms.
+ * min>0, max=0: scan dwells on each channel for 120 ms.
+ * min=0, max>0: scan dwells on each channel for max ms.
+ * min>0, max>0: the minimum time the scan dwells on each channel is min ms. If no AP is found during this time frame, the scan switches to the next channel. Otherwise, the scan dwells on the channel for max ms.
+ */
+
+#include "WiFi.h"
+
+void wifiScan(uint16_t min_time, uint16_t max_time) {
+  Serial.println("Scan start");
+
+  // Set the minimum time per channel for active scanning.
+  WiFi.setScanActiveMinTime(min_time);
+
+  // Capture the start time of the scan.
+  uint32_t start = millis();
+
+  // WiFi.scanNetworks will return the number of networks found.
+  // Scan networks with those options: Synchrone mode, show hidden networks, active scan, max scan time per channel.
+  int n = WiFi.scanNetworks(false, true, false, max_time);
+  Serial.printf("Scan done, elapsed time: %lu ms\n", millis() - start);
+  if (n == 0) {
+    Serial.println("no networks found");
+  } else {
+    Serial.print(n);
+    Serial.println(" networks found");
+    Serial.println("Nr | SSID                             | RSSI | CH | Encryption");
+    for (int i = 0; i < n; ++i) {
+      // Print SSID and RSSI for each network found
+      Serial.printf("%2d", i + 1);
+      Serial.print(" | ");
+      Serial.printf("%-32.32s", WiFi.SSID(i).c_str());
+      Serial.print(" | ");
+      Serial.printf("%4ld", WiFi.RSSI(i));
+      Serial.print(" | ");
+      Serial.printf("%2ld", WiFi.channel(i));
+      Serial.print(" | ");
+      switch (WiFi.encryptionType(i)) {
+        case WIFI_AUTH_OPEN:            Serial.print("open"); break;
+        case WIFI_AUTH_WEP:             Serial.print("WEP"); break;
+        case WIFI_AUTH_WPA_PSK:         Serial.print("WPA"); break;
+        case WIFI_AUTH_WPA2_PSK:        Serial.print("WPA2"); break;
+        case WIFI_AUTH_WPA_WPA2_PSK:    Serial.print("WPA+WPA2"); break;
+        case WIFI_AUTH_WPA2_ENTERPRISE: Serial.print("WPA2-EAP"); break;
+        case WIFI_AUTH_WPA3_PSK:        Serial.print("WPA3"); break;
+        case WIFI_AUTH_WPA2_WPA3_PSK:   Serial.print("WPA2+WPA3"); break;
+        case WIFI_AUTH_WAPI_PSK:        Serial.print("WAPI"); break;
+        default:                        Serial.print("unknown");
+      }
+      Serial.println();
+      delay(10);
+    }
+  }
+  Serial.println("");
+
+  // Delete the scan result to free memory for code below.
+  WiFi.scanDelete();
+
+  // Wait a bit before scanning again
+  delay(2000);
+}
+
+void setup() {
+  Serial.begin(115200);
+
+  // Set WiFi to station mode and disconnect from an AP if it was previously connected.
+  WiFi.mode(WIFI_STA);
+  WiFi.disconnect();
+  delay(100);
+
+  // Scan WiFi networks with a minimum time of 100 ms per channel and a maximum time of 300 ms per channel (default values).
+  wifiScan(100, 300);
+
+  // Scan WiFi networks with a minimum time of 100 ms per channel and a maximum time of 1500 ms per channel.
+  wifiScan(100, 1500);
+
+  // Scan WiFi networks with a minimum time of 0 ms per channel and a maximum time of 1500 ms per channel.
+  wifiScan(0, 1500);
+}
+
+void loop() {
+  // Nothing to do here
+}

libraries/WiFi/examples/WiFiScanTime/ci.json

+{
+  "targets": {
+    "esp32h2": false
+  }
+}

libraries/WiFi/src/WiFiScan.cpp

@@ -46,12 +46,18 @@ bool WiFiScanClass::_scanAsync = false;
 uint32_t WiFiScanClass::_scanStarted = 0;
 uint32_t WiFiScanClass::_scanTimeout = 60000;
 uint16_t WiFiScanClass::_scanCount = 0;
+uint32_t WiFiScanClass::_scanActiveMinTime = 100;
+
 void *WiFiScanClass::_scanResult = 0;
 
 void WiFiScanClass::setScanTimeout(uint32_t ms) {
   WiFiScanClass::_scanTimeout = ms;
 }
 
+void WiFiScanClass::setScanActiveMinTime(uint32_t ms) {
+  WiFiScanClass::_scanActiveMinTime = ms;
+}
+
 /**
  * Start scan WiFi networks available
  * @param async         run in async mode
@@ -80,7 +86,7 @@ int16_t
     config.scan_time.passive = max_ms_per_chan;
   } else {
     config.scan_type = WIFI_SCAN_TYPE_ACTIVE;
-    config.scan_time.active.min = 100;
+    config.scan_time.active.min = _scanActiveMinTime;
     config.scan_time.active.max = max_ms_per_chan;
   }
   if (esp_wifi_scan_start(&config, false) == ESP_OK) {

libraries/WiFi/src/WiFiScan.h

@@ -32,6 +32,7 @@ class WiFiScanClass {
 
 public:
   void setScanTimeout(uint32_t ms);
+  void setScanActiveMinTime(uint32_t ms);
 
   int16_t scanNetworks(
     bool async = false, bool show_hidden = false, bool passive = false, uint32_t max_ms_per_chan = 300, uint8_t channel = 0, const char *ssid = nullptr,
@@ -62,6 +63,7 @@ protected:
   static uint32_t _scanStarted;
   static uint32_t _scanTimeout;
   static uint16_t _scanCount;
+  static uint32_t _scanActiveMinTime;
 
   static void *_scanResult;