The number of features provided by ESP8266 in the station mode is far more extensive than covered in original
Arduino WiFi library. Therefore, instead of supplementing original documentation, we have decided to write a new one from scratch. Description of station class has been broken down into four parts. First discusses methods to establish connection to an access point. Second provides methods to manage connection like e.g. Start Here begin config Manage Connection reconnect disconnect isConnected setAutoConnect getAutoConnect setAutoReconnect waitForConnectResult Configuration macAddress localIP subnetMask gatewayIP dnsIP hostname status SSID psk BSSID RSSI Connect Different WPS Smart Config Points below provide description and code snippets how to use particular methods. For more code samples please refer to separate section with examples dedicated specifically to the Station Class. Switching the module to Station mode is done with By default, ESP will attempt to reconnect to Wi-Fi network whenever it is disconnected. There is no need to handle this by separate code. A good way to simulate disconnection would be to reset the access point. ESP will report disconnection, and then try to reconnect automatically. begin¶There are several versions (called function
overloads in C++) of The simplest overload of Calling it will enable station mode and connect to the last used access point based on configuration saved in flash memory. Notes:
Below is the syntax of another overload of WiFi.begin(ssid, password, channel, bssid, connect) Meaning of parameters is as follows:
config¶Disable DHCP client (Dynamic Host Configuration Protocol) and set the IP configuration of station interface to user defined arbitrary values. The interface will be a static IP configuration instead of values provided by DHCP. WiFi.config(local_ip, gateway, subnet, dns1, dns2) Function will return The following IP configuration may be provided:
Example code: #include <ESP8266WiFi.h> const char* ssid = "********"; const char* password = "********"; IPAddress staticIP(192,168,1,22); IPAddress gateway(192,168,1,9); IPAddress subnet(255,255,255,0); void setup(void) { Serial.begin(115200); Serial.println(); Serial.printf("Connecting to %s\n", ssid); WiFi.config(staticIP, gateway, subnet); WiFi.begin(ssid, password); while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); } Serial.println(); Serial.print("Connected, IP address: "); Serial.println(WiFi.localIP()); } void loop() {} Example output: Connecting to sensor-net . Connected, IP address: 192.168.1.22 Please note that station with static IP configuration usually connects to the network faster. In the above example it took about 500ms (one dot . displayed). This is because obtaining of IP configuration by DHCP client takes time and in this case this step is skipped. If you pass all three parameter as 0.0.0.0 (local_ip, gateway and subnet), it will re enable DHCP. You need to re-connect the device to get new IPs. Manage Connection¶reconnect¶Reconnect the station. This is done by disconnecting from the access point an then initiating connection back to the same AP. Notes: 1. Station should be already connected to an access point. If this is not the case, then function will return WiFi.reconnect(); while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); } disconnect¶Sets currently configured SSID and password to The isConnected¶Returns setAutoConnect¶Configure module to automatically connect on power on to the last used access point. WiFi.setAutoConnect(autoConnect) The getAutoConnect¶This is “companion”
function to If auto connection functionality is disabled, then function returns setAutoReconnect¶Set whether module will attempt to reconnect to an access point in case it is disconnected. WiFi.setAutoReconnect(autoReconnect) If parameter Note: running waitForConnectResult¶Wait until module connects to the access point. This function is intended for module configured in station or station + soft access point mode. WiFi.waitForConnectResult() Function returns one of the following connection statuses:
Configuration¶macAddress¶Get the MAC address of the ESP station’s interface. Function should be provided with Example code: if (WiFi.status() == WL_CONNECTED) { uint8_t macAddr[6]; WiFi.macAddress(macAddr); Serial.printf("Connected, mac address: %02x:%02x:%02x:%02x:%02x:%02x\n", macAddr[0], macAddr[1], macAddr[2], macAddr[3], macAddr[4], macAddr[5]); } Example output: Mac address: 5C:CF:7F:08:11:17 If you do not feel comfortable with pointers, then there is optional version of this function available. Instead of the pointer, it returns a formatted Example code: if (WiFi.status() == WL_CONNECTED) { Serial.printf("Connected, mac address: %s\n", WiFi.macAddress().c_str()); } localIP¶Function used to obtain IP address of ESP station’s interface. The type of returned value is IPAddress. There is a couple of methods available to display this type of data. They are presented in examples below that cover description
of Example code: if (WiFi.status() == WL_CONNECTED) { Serial.print("Connected, IP address: "); Serial.println(WiFi.localIP()); } Example output: Connected, IP address: 192.168.1.10 subnetMask¶Get the subnet mask of the station’s interface. Module should be connected to the access point to obtain the subnet mask. Example code: Serial.print("Subnet mask: "); Serial.println(WiFi.subnetMask()); Example output: Subnet mask: 255.255.255.0 gatewayIP¶Get the IP address of the gateway. Example code: Serial.printf("Gataway IP: %s\n", WiFi.gatewayIP().toString().c_str()); Example output: dnsIP¶Get the IP addresses of Domain Name Servers (DNS). With the input parameter Example code: Serial.print("DNS #1, #2 IP: "); WiFi.dnsIP().printTo(Serial); Serial.print(", "); WiFi.dnsIP(1).printTo(Serial); Serial.println(); Example output: DNS #1, #2 IP: 62.179.1.60, 62.179.1.61 hostname¶Get the DHCP hostname assigned to ESP station. Function returns The hostname may be changed using the following function: Input
parameter Example code: Serial.printf("Default hostname: %s\n", WiFi.hostname().c_str()); WiFi.hostname("Station_Tester_02"); Serial.printf("New hostname: %s\n", WiFi.hostname().c_str()); Example output: Default hostname: ESP_081117 New hostname: Station_Tester_02 status¶Return the status of Wi-Fi connection. Function returns one of the following connection statuses:
Returned value is type of Example code: #include <ESP8266WiFi.h> void setup(void) { Serial.begin(115200); Serial.printf("Connection status: %d\n", WiFi.status()); Serial.printf("Connecting to %s\n", ssid); WiFi.begin(ssid, password); Serial.printf("Connection status: %d\n", WiFi.status()); while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); } Serial.printf("\nConnection status: %d\n", WiFi.status()); Serial.print("Connected, IP address: "); Serial.println(WiFi.localIP()); } void loop() {} Example output: Connection status: 6 Connecting to sensor-net Connection status: 6 ...... Connection status: 3 Connected, IP address: 192.168.1.10 Particular connection statuses 6 and 3 may be looked up in wl_definitions.h as follows: 3 - WL_CONNECTED 6 - WL_DISCONNECTED Basing on this example, when running above code, module is initially disconnected from the network and returns connection status SSID¶Return the name of Wi-Fi network, formally called Service Set Identification (SSID). Returned value is of the Example code: Serial.printf("SSID: %s\n", WiFi.SSID().c_str()); Example output: psk¶Return current pre shared key (password) associated with the Wi-Fi network. Function returns value of the BSSID¶Return the mac address of the access point to which the ESP module was directed to connect to. This address is formally called Basic Service Set Identification (BSSID). The returned pointer is what the user configured when calling begin() with a bssid argument. It does _not_ necessarily reflect the mac address of the access point to which the ESP module’s station interface is currently connected to. The Below is similar function, but returning BSSID but as a Example code: Serial.printf("BSSID: %s\n", WiFi.BSSIDstr().c_str()); Example output: Connect Different¶ESP8266 SDK provides alternate methods to connect ESP station to an access point. Out of them esp8266 / Arduino core implements WPS and Smart Config as described in more details below. WPS¶The following
Depending on connection result function returns either Example code: #include <ESP8266WiFi.h> void setup(void) { Serial.begin(115200); Serial.println(); Serial.printf("Wi-Fi mode set to WIFI_STA %s\n", WiFi.mode(WIFI_STA) ? "" : "Failed!"); Serial.print("Begin WPS (press WPS button on your router) ... "); Serial.println(WiFi.beginWPSConfig() ? "Success" : "Failed"); while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); } Serial.println(); Serial.print("Connected, IP address: "); Serial.println(WiFi.localIP()); } void loop() {} Example output: Wi-Fi mode set to WIFI_STA Begin WPS (press WPS button on your router) ... Success ......... Connected, IP address: 192.168.1.102 Smart Config¶The Smart Config connection of an ESP module an access point is done by sniffing for special packets that contain SSID and password of desired AP. To do so the mobile device or computer should have functionality of broadcasting of encoded SSID and password. The following three functions are provided to implement Smart Config. Start smart configuration mode by sniffing for special packets that contain SSID and password of desired Access Point. Depending on result either Query Smart Config status, to decide when stop configuration. Function returns either Stop smart config, free the buffer taken by For additional details regarding Smart Config please refer to ESP8266 API User Guide. |