Skip to content

Latest commit

 

History

History
512 lines (294 loc) · 11 KB

wifi.rst

File metadata and controls

512 lines (294 loc) · 11 KB

Wi-Fi API

About

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 (WPA, WPA2, WEP, 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.

../_static/wifi_esp32_ap.png

This mode can be used for serving a 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.

../_static/wifi_esp32_sta.png

If you need to connect your project to the Internet, this is the mode you are looking for.

API Description

Here is the description about the WiFi API.

WiFiAP

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.

WiFi.softAP(ssid, password);

Please see the full WiFiAP example in: ap example.

AP Configuration

softAP

Use the function softAP to configure the Wi-Fi AP characteristics:

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.

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.

AP Connection

softAPdisconnect

Function used to force the AP disconnection.

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.

uint8_t softAPgetStationNum();

softAPIP

Function to get the AP IPv4 address.

IPAddress softAPIP();

The function will return the AP IP address in IPAddress format.

softAPBroadcastIP

Function to get the AP IPv4 broadcast address.

IPAddress softAPBroadcastIP();

The function will return the AP broadcast address in IPAddress format.

softAPNetworkID

Get the softAP network ID.

IPAddress softAPNetworkID();

The function will return the AP network address in IPAddress format.

softAPSubnetCIDR

Get the softAP subnet CIDR.

uint8_t softAPSubnetCIDR();

softAPenableIpV6

Function used to enable the IPv6 support.

bool softAPenableIpV6();

The function will return true if the configuration is successful.

softAPIPv6

Function to get the IPv6 address.

IPv6Address softAPIPv6();

The function will return the AP IPv6 address in IPv6Address format.

softAPgetHostname

Function to get the AP hostname.

const char * softAPgetHostname();

softAPsetHostname

Function to set the AP hostname.

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.

uint8_t* softAPmacAddress(uint8_t* mac);

Where:

  • mac sets the new MAC address.

Function to get the AP MAC address.

String softAPmacAddress(void);

softAPSSID

Function to get the AP SSID.

String softAPSSID(void) const;

Returns the AP SSID.

WiFiSTA

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.

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:

while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
}

After a successful connection, you can print the IP address given by the network.

Serial.println("IP address: ");
Serial.println(WiFi.localIP());

Please see the full example of the WiFiSTA in: sta example.

STA Configuration

begin

  • Functions begin are used to configure and start the Wi-Fi.
wl_status_t begin(const char* ssid, const char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = 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.
  • connect sets true to connect to the configured network automatically.
wl_status_t begin(char* ssid, char *passphrase = NULL, int32_t channel = 0, const uint8_t* bssid = NULL, bool connect = 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.
  • connect sets true to connect to the configured network automatically.

Function to start the connection after being configured.

wl_status_t begin();

config

Function config is used to configure Wi-Fi. After configuring, you can call function begin to start the Wi-Fi process.

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:

IPAddress(uint8_t first_octet, uint8_t second_octet, uint8_t third_octet, uint8_t fourth_octet);

Example:

IPAddress local_ip(192, 168, 10, 20);

See the WiFiClientStaticIP.ino for more details on how to use this feature.

STA Connection

reconnect

Function used to reconnect the Wi-Fi connection.

bool reconnect();

disconnect

Function to force disconnection.

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.

bool isConnected();

Return the connection state.

setAutoConnect

Function used to set the automatic connection.

bool setAutoConnect(bool autoConnect);

Where:

  • bool autoConnect is set to true to enable this option.

getAutoConnect

Function used to get the automatic connection setting value.

bool getAutoConnect();

The function will return true if the setting is enabled.

setAutoReconnect

Function used to set the automatic reconnection if the connection is lost.

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.

WiFiMulti

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.

bool addAP(const char* ssid, const char *passphrase = NULL);

After adding the AP's, run by the following function.

uint8_t run(uint32_t connectTimeout=5000);

To see how to use the WiFiMulti, take a look at the WiFiMulti.ino example available.

WiFiScan

To perform the Wi-Fi scan for networks, you can use the following functions:

Start scan WiFi networks available.

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.

int16_t scanComplete();

Delete last scan result from RAM.

void scanDelete();

Loads all infos from a scanned wifi in to the ptr parameters.

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 example available.

Examples

Wi-Fi AP Example

.. literalinclude:: ../../../libraries/WiFi/examples/WiFiAccessPoint/WiFiAccessPoint.ino
    :language: arduino

Wi-Fi STA Example

.. literalinclude:: ../../../libraries/WiFi/examples/WiFiClient/WiFiClient.ino
    :language: arduino

References