WiFi DA: Added Dual Antenna to the docs and example created (#6357)

Summary

Added the Dual Antenna documentation.
Added the DA example.

Author: pedrominatel

Diff for: docs/source/api/wifi.rst

@@ -67,6 +67,35 @@ Use static allocation if you want to have more performance and if your applicati
 
 By default, the memory allocation will be set to **dynamic** if this function is not being used.
 
+setDualAntennaConfig
+********************
+
+Configures the Dual antenna functionallity. This function should be used only on the **ESP32-WROOM-DA** module or any other ESP32 with RF switch.
+
+.. code-block:: arduino
+
+    bool setDualAntennaConfig(uint8_t gpio_ant1, uint8_t gpio_ant2, wifi_rx_ant_t rx_mode, wifi_tx_ant_t tx_mode);
+
+
+* ``gpio_ant1`` Configure the GPIO number for the antenna 1 connected to the RF switch (default ``GPIO2`` on ESP32-WROOM-DA)
+* ``gpio_ant2`` Configure the GPIO number for the antenna 2 connected to the RF switch (default ``GPIO25`` on ESP32-WROOM-DA)
+* ``rx_mode`` Set the RX antenna mode. See wifi_rx_ant_t for the options.
+* ``tx_mode`` Set the TX antenna mode. See wifi_tx_ant_t for the options.
+
+Return ``true`` if the configuration was successful.
+
+For the ``rx_mode`` you can use the following configuration:
+
+* ``WIFI_RX_ANT0`` Selects the antenna 1 for all RX activity.
+* ``WIFI_RX_ANT1`` Selects the antenna 2 for all RX activity.
+* ``WIFI_RX_ANT_AUTO``  Selects the antenna for RX automatically.
+
+For the ``tx_mode`` you can use the following configuration:
+
+* ``WIFI_TX_ANT0`` Selects the antenna 1 for all TX activity.
+* ``WIFI_TX_ANT1`` Selects the antenna 2 for all TX activity.
+* ``WIFI_TX_ANT_AUTO`` Selects the antenna for TX automatically.
+
 WiFiAP
 ------
 

Diff for: libraries/WiFi/examples/WiFiScanDualAntenna/README.md

@@ -0,0 +1,70 @@
+# WiFiScan Example
+
+This example demonstrates how to use the WiFi library to scan available WiFi networks and print the results.
+
+This example shows the basic functionality of the dual antenna capability.
+
+# Supported Targets
+
+This example is compatible with the ESP32-WROOM-DA.
+
+## 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 set the `upload_port` option on the `platformio.ini` file.
+
+## Example/Log Output
+
+```
+ets Jul 29 2019 12:21:46
+
+rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
+configsip: 0, SPIWP:0xee
+clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
+mode:DIO, clock div:1
+load:0x3fff0030,len:1412
+load:0x40078000,len:13400
+load:0x40080400,len:3672
+entry 0x400805f8
+Setup done
+scan start
+scan done
+17 networks found
+1: IoTNetwork (-62)*
+2: WiFiSSID (-62)*
+3: B3A7992 (-63)*
+4: WiFi (-63) 
+5: IoTNetwork2 (-64)*
+...
+```
+
+## 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-WROOM-DA Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-wroom-da_datasheet_en.pdf)

Diff for: libraries/WiFi/examples/WiFiScanDualAntenna/WiFiScanDualAntenna.ino

@@ -0,0 +1,74 @@
+/*
+ *  This sketch demonstrates how to scan WiFi networks.
+ *  The API is almost the same as with the WiFi Shield library,
+ *  the most obvious difference being the different file you need to include:
+ */
+#include "WiFi.h"
+
+/* These are the GPIOs connected to the antenna switch on the ESP32-WROOM-DA.
+ * Both GPIOs are not exposed to the module pins and cannot be used except to
+ * control the antnnas switch.
+ * 
+ * For more details, see the datashhet at:
+ * https://www.espressif.com/sites/default/files/documentation/esp32-wroom-da_datasheet_en.pdf
+ */
+
+#define GPIO_ANT1   2   // GPIO for antenna 1
+#define GPIO_ANT2   25  // GPIO for antenna 2 (default)
+
+void setup()
+{
+    bool err = ESP_FAIL;
+    Serial.begin(115200);
+
+    // Set WiFi to station mode and disconnect from an AP if it was previously connected
+    WiFi.mode(WIFI_STA);
+
+    // Set WiFi dual antenna configuration by passing the GPIO and antenna mode for RX ant TX
+    err = WiFi.setDualAntennaConfig(GPIO_ANT1, GPIO_ANT1, WIFI_RX_ANT_AUTO, WIFI_TX_ANT_AUTO);
+
+    /* For more details on how to use this feature, see our docs:
+     * https://docs.espressif.com/projects/arduino-esp32/en/latest/api/wifi.html
+     */
+
+    if(err == ESP_FAIL) {
+        Serial.println("Dual Antenna configuration failed!");
+    } else {
+        Serial.println("Dual Antenna configuration successfuly done!");
+    }
+
+    WiFi.disconnect();
+    delay(100);
+
+    Serial.println("Setup done");
+}
+
+void loop()
+{
+    Serial.println("scan start");
+
+    // WiFi.scanNetworks will return the number of networks found
+    int n = WiFi.scanNetworks();
+    Serial.println("scan done");
+    if (n == 0) {
+        Serial.println("no networks found");
+    } else {
+        Serial.print(n);
+        Serial.println(" networks found");
+        for (int i = 0; i < n; ++i) {
+            // Print SSID and RSSI for each network found
+            Serial.print(i + 1);
+            Serial.print(": ");
+            Serial.print(WiFi.SSID(i));
+            Serial.print(" (");
+            Serial.print(WiFi.RSSI(i));
+            Serial.print(")");
+            Serial.println((WiFi.encryptionType(i) == WIFI_AUTH_OPEN)?" ":"*");
+            delay(10);
+        }
+    }
+    Serial.println("");
+
+    // Wait a bit before scanning again
+    delay(5000);
+}