docs/en/api/wifi.rst
######### Wi-Fi API #########
The Wi-Fi API provides support for the 802.11b/g/n protocol driver. This API includes:
Station mode (STA mode or Wi-Fi client mode). ESP32 connects to an access point
AP mode (aka Soft-AP mode or Access Point mode). Devices connect to the ESP32
Security modes (WPA2, WPA3 etc.)
Scanning for access points
Working as AP
In this mode, the ESP32 is configured as an Access Point (AP) and it's capable of receiving incoming connections from other devices (stations) by providing a Wi-Fi network.
.. figure:: ../../_static/wifi_esp32_ap.png :align: center :width: 520 :figclass: align-center
This mode can be used for serving an HTTP or HTTPS server inside the ESP32, for example.
Working as STA
The STA mode is used to connect the ESP32 to a Wi-Fi network, provided by an Access Point.
.. figure:: ../../_static/wifi_esp32_sta.png :align: center :width: 520 :figclass: align-center
This is the mode to be used if you want to connect your project to the Internet.
Here is the description of the Wi-Fi API.
Here are the common APIs that are used for both modes, AP and STA.
onEvent (and removeEvent)
Registers a caller-supplied function to be called when Wi-Fi events occur. Several forms are available.
Function pointer callback taking the event ID:
.. code-block:: arduino
typedef void (*WiFiEventCb)(arduino_event_id_t);
wifi_event_id_t onEvent(WiFiEventCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
Function pointer callback taking an event-ID-and-info struct:
.. code-block:: arduino
typedef struct{
arduino_event_id_t event_id;
arduino_event_info_t event_info;
} arduino_event_t;
typedef void (*WiFiEventSysCb)(arduino_event_t *);
wifi_event_id_t onEvent(WiFiEventSysCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
Callback using std::function taking event ID and info separately:
.. code-block:: arduino
typedef std::function<void(arduino_event_id_t, arduino_event_info_t)> WiFiEventFuncCb;
wifi_event_id_t onEvent(WiFiEventFuncCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
A similar set of functions are available to remove callbacks:
.. code-block:: arduino
void removeEvent(WiFiEventCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
void removeEvent(WiFiEventSysCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
void removeEvent(wifi_event_id_t = ARDUINO_EVENT_MAX);
In all cases, the subscribing function accepts an optional event type to
invoke the callback only for that specific event; with the default
ARDUINO_EVENT_MAX, the callback will be invoked for all Wi-Fi events.
Any callback function is given the event type in a parameter.
Some of the possible callback function formats also take an
arduino_event_info_t (or use arduino_event_t which includes both
ID and info) which is a union of structs with additional information
about different event types.
See
WiFiGeneric.h <https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/src/WiFiGeneric.h>_
for the list of event types and "info" substructures, and also see a full
example of event handling: events example_.
.. warning::
Event callback functions are invoked on a separate
`thread <https://en.wikipedia.org/wiki/Thread_(computing)>`_
(`FreeRTOS task <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/freertos_idf.html#tasks>`_)
independent of the main application thread that runs ``setup()`` and
``loop()``. Callback functions must therefore be
`thread-safe <https://en.wikipedia.org/wiki/Thread_safety>`_;
they must not access shared/global variables directly without locking,
and must only call similarly thread-safe functions.
Some core operations like ``Serial.print()`` are thread-safe but many
functions are not. Notably, ``WiFi.onEvent()`` and ``WiFi.removeEvent()``
are not thread-safe and should never be invoked from a callback thread.
setHostname (and getHostname)
Sets the name the DHCP client uses to identify itself. In a typical network setup this will be the name that shows up in the Wi-Fi router's device list. The hostname must be no longer than 32 characters.
.. code-block:: arduino
setHostname(const char *hostname);
If the hostname is never specified, a default one will be assigned based on the chip type and MAC address. The current hostname (default or custom) may be retrieved:
.. code-block:: arduino
const char *getHostname();
.. warning::
The ``setHostname()`` function must be called BEFORE Wi-Fi is started with
``WiFi.begin()``, ``WiFi.softAP()``, ``WiFi.mode()``, or ``WiFi.run()``.
To change the name, reset Wi-Fi with ``WiFi.mode(WIFI_MODE_NULL)``,
then proceed with ``WiFi.setHostname(...)`` and restart WiFi from scratch.
useStaticBuffers
This function is used to set the memory allocation mode for the Wi-Fi buffers.
.. code-block:: arduino
static void useStaticBuffers(bool bufferMode);
true to use the Wi-Fi buffers memory allocation as static.false to set the buffers memory allocation to dynamic.The use of dynamic allocation is recommended to save memory and reduce resources usage. However, the dynamic performs slightly slower than the static allocation. Use static allocation if you want to have more performance and if your application is multi-tasking.
By default, the memory allocation will be set to dynamic if this function is not being used.
setDualAntennaConfig
Configures the Dual antenna functionality. 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.The WiFiAP is used to configure and manage the Wi-Fi as an Access Point. This is where you can find the related functions for the AP.
Basic Usage
To start the Wi-Fi as an Access Point.
.. code-block:: arduino
WiFi.softAP(ssid, password);
Please see the full WiFiAP example in: ap example_.
softAP
Use the function softAP to configure the Wi-Fi AP characteristics:
.. code-block:: arduino
bool softAP(const char* ssid, const char* passphrase = NULL, int channel = 1, int ssid_hidden = 0, int max_connection = 4, bool ftm_responder = false);
Where:
ssid sets the Wi-Fi network SSID.passphrase sets the Wi-Fi network password. If the network is open, set as NULL.channel configures the Wi-Fi channel.ssid_hidden sets the network as hidden.max_connection sets the maximum number of simultaneous connections. The default is 4.ftm_responder sets the Wi-Fi FTM responder feature. Only for ESP32-S2 and ESP32-C3 SoC!Return true if the configuration was successful.
softAPConfig
Function used to configure the IP as static (fixed) as well as the gateway and subnet.
.. code-block:: arduino
bool softAPConfig(IPAddress local_ip, IPAddress gateway, IPAddress subnet);
Where:
local_ip sets the local IP address.gateway sets the gateway IP.subnet sets the subnet mask.The function will return true if the configuration is successful.
softAPdisconnect
Function used to force the AP disconnection.
.. code-block:: arduino
bool softAPdisconnect(bool wifioff = false);
Where:
wifioff sets the Wi-Fi off if true.The function will return true if the configuration is successful.
softAPgetStationNum
This function returns the number of clients connected to the AP.
.. code-block:: arduino
uint8_t softAPgetStationNum();
softAPIP
Function to get the AP IPv4 address.
.. code-block:: arduino
IPAddress softAPIP();
The function will return the AP IP address in IPAddress format.
softAPBroadcastIP
Function to get the AP IPv4 broadcast address.
.. code-block:: arduino
IPAddress softAPBroadcastIP();
The function will return the AP broadcast address in IPAddress format.
softAPNetworkID
Get the softAP network ID.
.. code-block:: arduino
IPAddress softAPNetworkID();
The function will return the AP network address in IPAddress format.
softAPSubnetCIDR
Get the softAP subnet CIDR.
.. code-block:: arduino
uint8_t softAPSubnetCIDR();
softAPSubnetMask
Get the softAP subnet mask.
.. code-block:: arduino
IPAddress softAPSubnetMask();
softAPenableIPv6
Function used to enable the IPv6 support.
.. code-block:: arduino
bool softAPenableIPv6(bool enable=true);
The function will return true if the configuration is successful.
softAPIPv6
Function to get the IPv6 address.
.. code-block:: arduino
IPAddress softAPlinkLocalIPv6();
The function will return the AP IPv6 address in IPAddress format.
softAPgetHostname
Function to get the AP hostname.
.. code-block:: arduino
const char * softAPgetHostname();
softAPsetHostname
Function to set the AP hostname.
.. code-block:: arduino
bool softAPsetHostname(const char * hostname);
Where:
hostname sets the device hostname.The function will return true if the configuration is successful.
softAPmacAddress
Function to define the AP MAC address.
.. code-block:: arduino
uint8_t* softAPmacAddress(uint8_t* mac);
Where:
mac sets the new MAC address.Function to get the AP MAC address.
.. code-block:: arduino
String softAPmacAddress(void);
softAPSSID
Function to get the AP SSID.
.. code-block:: arduino
String softAPSSID(void) const;
Returns the AP SSID.
The WiFiSTA is used to configure and manage the Wi-Fi as Station. The related functions for the STA are here.
Basic Usage
The following code shows the basic usage of the WifiSTA functionality.
.. code-block:: arduino
WiFi.begin(ssid, password);
Where the ssid and password are from the network you want to connect the ESP32.
To check if the connection is successful, you can use:
.. code-block:: arduino
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.print(".");
}
After a successful connection, you can print the IP address given by the network.
.. code-block:: arduino
Serial.println("IP address: ");
Serial.println(WiFi.localIP());
Please see the full example of the WiFiSTA in: sta example_.
begin
begin are used to configure and start the Wi-Fi... code-block:: arduino
wl_status_t begin(const char* ssid, const char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool tryConnect = true);
Where:
ssid sets the AP SSID.passphrase sets the AP password. Set as NULL for open networks.channel sets the Wi-Fi channel.uint8_t* bssid sets the AP BSSID.tryConnect sets true to connect to the configured network automatically... code-block:: arduino
wl_status_t begin(char* ssid, char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool tryConnect = true);
Where:
ssid sets the AP SSID.passphrase sets the AP password. Set as NULL for open networks.channel sets the Wi-Fi channel.bssid sets the AP BSSID.tryConnect sets true to connect to the configured network automatically... note::
The ``begin`` function also accepts ``String`` types for the ``ssid`` and ``passphrase`` parameters, providing convenient overloads for use with Arduino ``String`` objects.
Function to start the connection after being configured.
.. code-block:: arduino
wl_status_t begin();
connect
Function to connect to a Wi-Fi network. This is called internally by begin but can also be used directly for more control.
.. code-block:: arduino
bool connect(const char* ssid, const char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool tryConnect = true);
Where:
ssid sets the AP SSID.passphrase sets the AP password. Set as NULL for open networks.channel sets the Wi-Fi channel.bssid sets the AP BSSID.tryConnect sets true to connect to the configured network automatically... note::
The ``connect`` function also accepts ``String`` types for the ``ssid`` and ``passphrase`` parameters, providing convenient overloads for use with Arduino ``String`` objects.
config
Function config is used to configure Wi-Fi. After configuring, you can call function begin to start the Wi-Fi process.
.. code-block:: arduino
bool config(IPAddress local_ip, IPAddress gateway, IPAddress subnet, IPAddress dns1 = (uint32_t)0x00000000, IPAddress dns2 = (uint32_t)0x00000000);
Where:
local_ip sets the local IP.gateway sets the gateway IP.subnet sets the subnet mask.dns1 sets the DNS.dns2 sets the DNS alternative option.The function will return true if the configuration is successful.
The IPAddress format is defined by 4 bytes as described here:
.. code-block:: arduino
IPAddress(uint8_t first_octet, uint8_t second_octet, uint8_t third_octet, uint8_t fourth_octet);
Example:
.. code-block:: arduino
IPAddress local_ip(192, 168, 10, 20);
See the WiFiClientStaticIP.ino for more details on how to use this feature.
reconnect
Function used to reconnect the Wi-Fi connection.
.. code-block:: arduino
bool reconnect();
disconnect
Function to force disconnection.
.. code-block:: arduino
bool disconnect(bool wifioff = false, bool eraseap = false);
Where:
wifioff use true to turn the Wi-Fi radio off.eraseap use true to erase the AP configuration from the NVS memory.The function will return true if the configuration is successful.
isConnected
Function used to get the connection state.
.. code-block:: arduino
bool isConnected();
Return the connection state.
setAutoConnect
Function is deprecated.
getAutoConnect
Function is deprecated.
setAutoReconnect
Function used to set the automatic reconnection if the connection is lost.
.. code-block:: arduino
bool setAutoReconnect(bool autoReconnect);
Where:
autoConnect is set to true to enable this option.getAutoReconnect
Function used to get the automatic reconnection if the connection is lost.
.. code-block:: arduino
bool getAutoReconnect();
The function will return true if this setting is enabled.
setMinSecurity
Function used to set the minimum security for AP to be considered connectable.
.. code-block:: arduino
bool setMinSecurity(wifi_auth_mode_t minSecurity);
Where:
minSecurity is the minimum security for AP to be considered connectable. Default is WIFI_AUTH_WPA2_PSK.The WiFiMulti allows you to add more than one option for the AP connection while running as a station.
To add the AP, use the following function. You can add multiple AP's and this library will handle the connection.
.. code-block:: arduino
bool addAP(const char *ssid, const char *passphrase = NULL);
Or, if you have WPA2-Enterprise support enabled (CONFIG_ESP_WIFI_ENTERPRISE_SUPPORT):
.. code-block:: arduino
bool addAP(const char *ssid, const char *passphrase = NULL, const char *username = NULL, const char *identity = NULL);
For:
ssid must be set.passphrase must be set.username and passphrase must be set to the username and password required for inner authentication (MSCHAPv2), respectively. identity must be set to the "anonymous identity" used for PEAP, if required by the network, or must be set to an empty string otherwise. Note that WPA2-Enterprise networks using certificate-based authentication (e.g. EAP-TLS) are currently not supported. It is also currently not possible to supply a CA certificate to validate the server certificate for PEAP. Given these limitations, you should consider whether this is secure enough for your needs.After adding the AP's, run by the following function.
.. code-block:: arduino
uint8_t run(uint32_t connectTimeout=5000);
To see how to use the WiFiMulti, take a look at the WiFiMulti.ino, WiFiMultiAdvanced.ino and WiFiMultiEnterprise.ino examples available.
To perform the Wi-Fi scan for networks, you can use the following functions:
Start scan Wi-Fi networks available.
.. code-block:: arduino
int16_t scanNetworks(bool async = false, bool show_hidden = false, bool passive = false, uint32_t max_ms_per_chan = 300, uint8_t channel = 0);
Called to get the scan state in Async mode.
.. code-block:: arduino
int16_t scanComplete();
Delete last scan result from RAM.
.. code-block:: arduino
void scanDelete();
Loads all infos from a scanned Wi-Fi in to the ptr parameters.
.. code-block:: arduino
bool getNetworkInfo(uint8_t networkItem, String &ssid, uint8_t &encryptionType, int32_t &RSSI, uint8_t* &BSSID, int32_t &channel);
To see how to use the WiFiScan, take a look at the WiFiScan.ino or WiFiScanAsync.ino example available.
Complete list of Wi-Fi examples <https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFi/examples>_.
.. _ap example:
Wi-Fi AP Example
.. literalinclude:: ../../../libraries/WiFi/examples/WiFiAccessPoint/WiFiAccessPoint.ino :language: arduino
.. _sta example:
Wi-Fi STA Example
.. literalinclude:: ../../../libraries/WiFi/examples/WiFiClient/WiFiClient.ino :language: arduino
.. _events example:
Wi-Fi Events Example
.. literalinclude:: ../../../libraries/WiFi/examples/WiFiClientEvents/WiFiClientEvents.ino :language: arduino