ContextQMD
Back to Riot

Doc

cpu/esp_common/esp-wifi/doc.md

2026.07-devel4.1 KB
Original Source
<!-- SPDX-FileCopyrightText: 2019 Gunar Schorcht SPDX-License-Identifier: LGPL-2.1-only -->

@defgroup cpu_esp_common_esp_wifi ESP-WiFi netdev interface @ingroup cpu_esp_common @ingroup cpu_esp32 @ingroup cpu_esp8266 @brief Network device driver for the ESP SoC WiFi interface

@author Gunar Schorcht [email protected]

This module realizes a netdev interface for the built-in WiFi interface of ESP SoCs.

@note On the ESP32 this netdev driver supports both WPA2 Personal Mode and WPA2 Enterprise Mode. On ESP8266, only WPA2 Personal mode is currently supported.

WPA2 Personal Mode

To use the WiFi netdev driver in WPA2 Personal Mode with a preshared key (PSK), module esp_wifi has to be enabled.

USEMODULE += esp_wifi

Furthermore, the following configuration parameters have to be defined:

<center>
ParameterDefaultDescription
WIFI_SSID"RIOT_AP"SSID of the AP to be used.
WIFI_PASS-Passphrase used for the AP as clear text (max. 64 chars).
ESP_WIFI_STACKSIZE#THREAD_STACKSIZE_DEFAULTStack 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, for example:

USEMODULE=esp_wifi \
CFLAGS='-DWIFI_SSID=\"MySSID\" -DWIFI_PASS=\"MyPassphrase\"' \
make -C examples/networking/gnrc/networking BOARD=...

@note

  • Module esp_wifi is not enabled automatically when module netdev_default is used.
  • Leave 'WIFI_PASS' undefined to connect to an open WiFi access point.
  • The Wifi network interface (module esp_wifi) and the 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.

WPA2 Enterprise Mode

To use the WiFi netdev driver in WPA2 Enterprise Mode with IEEE 802.1X/EAP authentication, module esp_wifi_enterprise has to be enabled.

USEMODULE += esp_wifi_enterprise

It supports the following EAP authentication methods:

  • PEAPv0
  • PEAPv1
  • TTLS

As inner (phase 2) EAP authentication method, only MSCHAPv2 is supported.

To use module esp_wifi_enterprise with these authentication methods, the following configuration parameters have to be defined:

<center>
ParameterDefaultDescription
WIFI_SSID"RIOT_AP"SSID of the AP to be used.
WIFI_EAP_IDnoneOptional anonymous identity used in phase 1 (outer) EAP authentication. If it is not defined, the user name defined for phase 2 (inner) EAP authentication is used as identity in phase 1.
WIFI_EAP_USERnoneUser name used in phase 2 (inner) EAP authentication.
WIFI_EAP_PASSnonePassword used in phase 2 (inner) EAP authentication.
ESP_WIFI_STACKSIZE#THREAD_STACKSIZE_DEFAULTStack 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, for example:

USEMODULE=esp_wifi_enterprise \
CFLAGS='-DWIFI_SSID=\"MySSID\" -DWIFI_EAP_ID=\"anonymous\" -DWIFI_EAP_USER=\"MyUserName\" -DWIFI_EAP_PASS=\"MyPassphrase\"' \
make -C examples/networking/gnrc/networking BOARD=...

@note

  • Since there is no possibility to add the CA certificate to the RIOT image, the verification of the AP certificate is not yet supported.
  • Module esp_wifi_enterprise is not enabled automatically when module netdev_default is used.
  • The Wifi network interface (module esp_wifi_enterprise) and the 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. In this case the ESP-NOW interface must use the same channel as the AP of the infrastructure WiFi network. All ESP-NOW nodes must therefore be compiled with the channel of the AP asvalue for the parameter 'ESP_NOW_CHANNEL'.