From 91fc362689234461f8f19fcb257f14bb699da9d7 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Mon, 28 Feb 2022 12:57:20 +0000 Subject: [PATCH] WiFi DA: Added Dual Antenna to the docs and example created --- docs/source/api/wifi.rst | 29 ++++++++ .../examples/WiFiScanDualAntenna/README.md | 70 ++++++++++++++++++ .../WiFiScanDualAntenna.ino | 74 +++++++++++++++++++ 3 files changed, 173 insertions(+) create mode 100644 libraries/WiFi/examples/WiFiScanDualAntenna/README.md create mode 100644 libraries/WiFi/examples/WiFiScanDualAntenna/WiFiScanDualAntenna.ino diff --git a/docs/source/api/wifi.rst b/docs/source/api/wifi.rst index b5214838084..5f1d100493e 100644 --- a/docs/source/api/wifi.rst +++ b/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 --git a/libraries/WiFi/examples/WiFiScanDualAntenna/README.md b/libraries/WiFi/examples/WiFiScanDualAntenna/README.md new file mode 100644 index 00000000000..32131a2b6ac --- /dev/null +++ b/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 --git a/libraries/WiFi/examples/WiFiScanDualAntenna/WiFiScanDualAntenna.ino b/libraries/WiFi/examples/WiFiScanDualAntenna/WiFiScanDualAntenna.ino new file mode 100644 index 00000000000..d628068ccf5 --- /dev/null +++ b/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); +}