cpu/esp32: esp_wifi netdev driver

cpu/esp32/Makefile.dep

@@ -28,6 +28,7 @@ endif
 
 ifneq (,$(filter esp_wifi_any,$(USEMODULE)))
     # add additional modules used for any WiFi interface
+    USEMODULE += esp_idf_heap
     USEMODULE += esp_idf_wpa_supplicant_crypto
     USEMODULE += esp_idf_wpa_supplicant_port
     USEMODULE += esp_idf_nvs_flash

cpu/esp32/doc.txt

@@ -46,8 +46,9 @@
     2. [SPIFFS Device](#esp32_spiffs_device)
 8. [Network Interfaces](#esp32_network_interfaces)
     1. [Ethernet MAC Network Interface](#esp32_ethernet_network_interface)
-    2. [ESP-NOW Network Interface](#esp32_esp_now_network_interface)
-    3. [Other Network Devices](#esp32_other_network_devices)
+    2. [WiFi Network Interface](#esp32_wifi_network_interface)
+    3. [ESP-NOW Network Interface](#esp32_esp_now_network_interface)
+    4. [Other Network Devices](#esp32_other_network_devices)
 10. [Application-Specific Configurations](#esp32_application_specific_configurations)
     1. [Make Variable ```CONFIGS```](#esp32_config_make_variable)
     2. [Application-Specific Board Configuration](#esp32_application_specific_board_configuration)
@@ -108,15 +109,16 @@ The following table gives a short reference  in alphabetical order of modules th
 
 Module    | Default  | Short description
 ----------|----------|-------------------
-[esp_can](#esp32_can_interfaces) | not used | enable the ESP32 CAN device
-[esp_eth](#esp32_ethernet_network_interface) | not used | enable the ESP32 EMAC network device
+[esp_can](#esp32_can_interfaces) | not used | enable the CAN device
+[esp_eth](#esp32_ethernet_network_interface) | not used | enable the Ethernet MAC (EMAC) network device
 [esp_gdb](#esp32_debugging) | not used | enable the compilation with debug information for debugging
 [esp_hw_counter](#esp32_timers) | not used | use hardware counters for RIOT timers
 [esp_i2c_hw](#esp32_i2c_interfaces) | not used  | use the i2C hardware implementation
 [esp_idf_heap](#esp32_esp_idf_heap_implementation) | not used | enable ESP-IDF heap implementation
 [esp_now](#esp32_esp_now_network_interface) | not used  | enable the ESP-NOW network device
 [esp_spi_ram](#esp32_spi_ram) | not used |  enable SPI RAM
 [esp_spiffs](#esp32_spiffs_device) | not used  |  enable SPIFFS for on-board flash memory
+[esp_wifi](#esp32_wifi_network_interface) | not used  | enable the Wifi network device
 
 </center>
 
@@ -190,7 +192,6 @@ The RIOT-OS for ESP32 SoCs supports the following features at the moment:
 The implementation of RIOT-OS for ESP32 SOCs has the following limitations at the moment:
 
 - Only <b>one core</b> (the PRO CPU) is used because RIOT does not support running multiple threads  simultaneously.
-- <b>AP-based WiFi</b> is experimental and not stable.
 - RIOT modules <b>crypto</b> and <b>hashes</b> cannot be used together with modules <b>esp_now</b> and <b>esp_wifi</b>
 - <b>Bluetooth</b> cannot be used at the moment.
 - <b>Flash encryption</b> is not yet supported.
@@ -390,14 +391,15 @@ Optional features of ESP32 can be enabled by ```USEMODULE``` definitions in the
 
 Module | Description
 -------|------------
-esp_now | Use the built-in WiFi module with the ESP-NOW protocol as ```netdev``` network device, see section [ESP-NOW Network Interface](#esp32_esp_now_network_interface).
-esp_eth | Use the Ethernet MAC (EMAC) interface as ```netdev``` network device, see section [Ethernet Network Interface](#esp32_ethernet_network_interface).
+esp_can | Enable the CAN device, see section [CAN Interfaces](#esp32_can_interfaces).
+esp_eth | Enable the Ethernet MAC (EMAC) interface as `netdev` network device, see section [Ethernet Network Interface](#esp32_ethernet_network_interface).
 esp_gdb | Enable the compilation with debug information for debugging with [QEMU and GDB](#esp32_qemu_mode_and_gdb) (```QEMU=1```) or via [JTAG interface with OpenOCD](#esp32_jtag_debugging).
 esp_i2c_hw | Use the hardware I2C implementation, see section [I2C Interfaces](#esp32_i2c_interfaces).
 esp_idf_heap | Use the ESP-IDF heap implementation, see section [ESP-IDF Heap Implementation](#esp32_esp_idf_heap_implementation).
+esp_now | Enable the built-in WiFi module with the ESP-NOW protocol as `netdev` network device, see section [ESP-NOW Network Interface](#esp32_esp_now_network_interface).
 esp_spiffs  | Enable the optional SPIFFS drive in on-board flash memory, see section [SPIFFS Device](#esp32_spiffs_device).
 esp_spi_ram | Enable the optional SPI RAM, see section [SPI RAM Modules](#esp32_spi_ram).
-esp_can | Enable the ESP32 CAN device, see section [CAN Interfaces](#esp32_can_interfaces).
+esp_wifi | Enable the built-in WiFi module as `netdev` network device, see section [WiFi Network Interface](#esp32_wifi_network_interface).
 
 </center>
 
@@ -884,7 +886,7 @@ Please refer file ```$RIOTBASE/tests/unittests/test-spiffs/tests-spiffs.c``` for
 ESP32 provides different built-in possibilities to realize network devices:
 
 - <b>EMAC</b>, an Ethernet MAC implementation (requires an external PHY module)
-- <b>ESP WiFi</b>, usual AP-based wireless LAN (not yet supported)
+- <b>ESP WiFi</b>, usual AP-based wireless LAN
 - <b>ESP-NOW</b>, a WiFi based AP-less and connectionless peer to peer communication protocol
 - <b>ESP-MESH</b>, a WiFi based mesh technology (not yet supported)
 
@@ -906,6 +908,50 @@ Otherwise, the application has to add the ```esp_eth``` module in its makefile w
 @note
 The board has to have one of the supported PHY modules to be able to use the Ethernet MAC module.
 
+\anchor esp32_wifi_network_interface
+## <a name="esp32_wifi_network_interface"> WiFi Network Interface </a> &nbsp;[[TOC](#esp32_toc)]
+
+The RIOT port for ESP32 implements in module `esp_wifi` a `netdev` driver for
+the built-in WiFi interface.
+
+@note Due to symbol conflicts with the `crypto` and `hash` modules of RIOT
+in module `esp_idf_wpa_supplicant_crypto`, which is required by module
+`esp_wifi`, `esp_wifi` cannot be used for applications that use these modules.
+Therefore, module `esp_wifi` is not automatically enabled when module
+`netdev_default` is used. Instead, if necessary, the application has to add
+the module `esp_wifi` in the Makefile.
+
+```
+USEMODULE += esp_wifi
+```
+
+Furthermore, the following configuration parameters have to be defined:
+
+<center>
+
+Parameter          | Default                   | Description
+:------------------|:--------------------------|:------------
+ESP_WIFI_SSID      | "RIOT_AP"                 | SSID of the AP to be used.
+ESP_WIFI_PASS      | "ThisistheRIOTporttoESP"  | Passphrase used for the AP as clear text (max. 64 chars).
+ESP_WIFI_STACKSIZE | #THREAD_STACKSIZE_DEFAULT |Stack size used for the WiFi netdev driver thread.
+
+</center>
+
+These configuration parameter definitions, as well as enabling the `esp_wifi`
+module, can be done either in the makefile of the project or at make command
+line, e.g.:
+
+```
+USEMODULE=esp_wifi \
+CFLAGS='-DESP_WIFI_SSID=\"MySSID\" -DESP_WIFI_PASS=\"MyPassphrase\"' \
+make -C examples/gnrc_networking BOARD=...
+```
+
+@note The Wifi network interface (module `esp_wifi`) and the
+[ESP-NOW network interface](#esp32_esp_now_network_interface) (module `esp_now`)
+can be used simultaneously, for example, to realize a border router for
+a mesh network which uses ESP-NOW.
+
 \anchor esp32_esp_now_network_interface
 ## <a name="esp32_esp_now_network_interface"> ESP-NOW Network Interface </a> &nbsp;[[TOC](#esp32_toc)]
 
@@ -927,12 +973,16 @@ The following parameters are defined for ESP-NOW nodes. These parameters can be
 Parameter | Default | Description
 :---------|:--------|:-----------
 ESP_NOW_SCAN_PERIOD | 10000000UL | Defines the period in us at which an node scans for other nodes in its range. The default period is 10 s.
-ESP_NOW_SOFT_AP_PASSPHRASE | ThisistheRIOTporttoESP | Defines the passphrase (max. 64 chars) that is used for the SoftAP interface of an nodes. It has to be same for all nodes in one network.
+ESP_NOW_SOFT_AP_PASS | "ThisistheRIOTporttoESP" | Defines the passphrase as clear text (max. 64 chars) that is used for the SoftAP interface of ESP-NOW nodes. It has to be same for all nodes in one network.
 ESP_NOW_CHANNEL | 6 | Defines the channel that is used as the broadcast medium by all nodes together.
 ESP_NOW_KEY | NULL | Defines a key that is used for encrypted communication between nodes. If it is NULL, encryption is disabled. The key has to be of type ```uint8_t[16]``` and has to be exactly 16 bytes long.
 
 </center>
 
+@note The ESP-NOW network interface (module `esp_now`) and the
+[Wifi network interface](#esp32_wifi_network_interface) (module `esp_wifi`)
+can be used simultaneously, for example, to realize a border router for
+a mesh network which uses ESP-NOW.
 
 ## <a name="esp32_other_network_devices"> Other Network Devices </a> &nbsp;[[TOC](#esp32_toc)]
 

cpu/esp32/esp-wifi/doc.txt

@@ -7,12 +7,46 @@
  */
 
 /**
- * @defgroup        cpu_esp32_esp_wifi ESP WiFi netdev interface
+ * @defgroup        cpu_esp32_esp_wifi ESP32 WiFi netdev interface
  * @ingroup         cpu_esp32
- * @brief           WiFi AP-based network device driver
- *
- * This module realizes a netdev interface using the built-in
- * WiFi module and AP infrastructure.
+ * @brief           Network device driver for the ESP32 WiFi interface
  *
  * @author      Gunar Schorcht <[email protected]>
+
+This module realizes a `netdev` interface for the built-in WiFi interface
+of ESP32. To enable the WiFi interface, module `esp_wifi` has to be used.
+
+@note Due to symbol conflicts with the `crypto` and `hash` modules of RIOT
+in module `esp_idf_wpa_supplicant_crypto`, which is required by module
+`esp_wifi`, `esp_wifi` cannot be used for applications that use these modules.
+Therefore, module `esp_wifi` is not automatically enabled when module
+`netdev_default` is used. Instead, if necessary, the application has to add
+the module `esp_wifi` in the Makefile.
+
+```
+USEMODULE += esp_wifi
+```
+
+Furthermore, the following configuration parameters have to be defined:
+
+Configuration Parameter | Description
+------------------------|------------
+ESP_WIFI_SSID           | SSID of the AP to be used.
+ESP_WIFI_PASS           | Passphrase used for the AP as clear text (max. 64 chars).
+ESP_WIFI_STACKSIZE      | Stack size used for the WiFi netdev driver thread.
+
+These configuration parameter definitions, as well as enabling the `esp_wifi`
+module, can be done either in the makefile of the project or at make command
+line, e.g.:
+
+```
+USEMODULE=esp_wifi \
+CFLAGS='-DESP_WIFI_SSID=\"MySSID\" -DESP_WIFI_PASS=\"MyPassphrase\"' \
+make -C examples/gnrc_networking BOARD=...
+```
+
+@note The Wifi network interface (module `esp_wifi`) and the
+\ref esp32_esp_now_network_interface "ESP-NOW network interface" (module `esp_now`)
+can be used simultaneously, for example, to realize a border router for
+a mesh network which uses ESP-NOW.
  */