ESP8266 / ESP32 WiFi Connection manager using a web configuration portal
| This fork will not be updated as I created a new tool for the same task: puara-module. An usage example can be found at puara-module-template. |
This library if forked from Kentaylor's WiFiManager, but it uses code for 2 other libraries:
. Zhouhan0126's WiFiManager. Tzapu's WiFiManager.
The configuration portal is captive, so it will present the configuration dialogue regardless of the web address selected, excluding https requests.
This is a modification of those existing libraries, and it inherits the characteristics of Ken Taylor's WiFiManager:-
- Portal continues to exist after configuring the ESP device to provide user feedback on success or otherwise.
- Provides guidance to users when they are not connected to the correct network.
- Supports configuration from apps including the ESP Connect Android app.
- Relies on automatic connectivity.
- Configuration portal initiation not automatic when a configured WiFi network is not visible.
- Configuration portal initiated by double pressing the reset button.
- Selectively operates in dual mode
This works with the ESP8266 and the ESP32. Use ESP8266 Arduino platform 2.4.1 or newer / use ESP32 1.0.1 or newer.
- Features
- Portal Continues To Exist After Configuration
- User Guidance At The Same Address Regardless of Network
- Programmatic Configuration
- Relies On Automatic Connectivity
- Configuration Portal Initiation Not Automatic
- Configuration portal initiated by double pressing the reset button
- Selectively Operates In Dual Mode
- How It Works
- Quick Start
- Documentation
- Troubleshooting
- Releases
- Contributors
This version does not close the configuration portal immediately on setting the WiFi values but continues to supply information, including network connectivity or otherwise, until the configuration portal is commanded to close.
The Tzapu version of WiFi Manager appropriates the procedure for connecting the browsing device to a network that requires interaction through a web interface. Connecting the users device to a network is not the same thing as connecting a device which the user is browsing to a network and the Tzapu procedure is not robust in this scenario. It works well in this video which shows an ideal situation but there are problems when the browsing device is different to that in the video or there are issues in connecting to the specified network. In this discussion there is another video that shows a situation where the procedure for connecting the browsing device to a network fails.
It is arguable whether manual or automatic portal closure is better for browser based configuration but manual closure is undoubtedly better for app based configuration.
Feedback is provided at the same web address, wifi.urremote.com, when connected to the internet and when connected to the ESP device network. Any requests to any domain name are redirected to this domain name on the device. The IP address 192.168.1.4 works as well but doesn't exist on the internet. This avoids confusion when the browsing computer is connected to the wrong network which can occur because:-
- Often a user fails to realise they need to change WiFi networks.
- During configuation the device network is temporarily shut down and restarted which often causes the browsing device to swap networks in the background leaving the user unaware of the network change.
Configuration using an app can be easier because WiFi configuration through a web browser is non intuitive due to a requirement to switch back and forward between WiFi networks. URL's /state and /scan are provided that respond with data in JSON format for easy control of the web interface from external applications. The ESP Connect Android app uses this interface.
An ESP8266 stores access point credentials in non volatile memory so these details should only be set once, unless they need to be changed. The ESP8266/ESP32 is set by default to auto connect and will always do it's best to connect to a network when it has an access point name (SSID) configured. If the access point is visible and the password is correct it will connect in a few seconds. If the access point is not visible or goes away it will reestablish the connection automatically when the access point becomes visible. There are no calls to the Espressif ESP8266 library that can connect to a network faster or more reliably.
Older versions of the Espressif library had a bug so that trying to use calls to the Espressif library to connect to a network can sometimes cause the WiFi connectivity to fail until it is rebooted and occasionally can also brick the ESP8266. If you have a device bricked this way it can be recovered.
WiFi networks can be unavailable temporarily and only a human can know whether the solution to failing to connect is to change the WiFi connection data. Therefore a configuration portal is not initiated automatically when the ESP device can not connect to the configured WiFi access point.
The configuration portal is launched if no WiFi configuration data has been stored or a button is pressed. On a Node MCU board the Flash button can be reused as the configuration portal button.
A configuration portal can be launched on every start up for a minute or so, if programmed that way, but the delay in application start up is unacceptible for most use cases.
This method avoids the use of a pin for launching the configuration portal. In the provided example a double press on a button connected to the reset pin can be used to initiate a configuration portal. This works well on development boards that have a reset button like the Wemos.
The ESP8266/ESP32 can simultaneously connect to a Wifi network and run it's own WiFi network in which case it switches the radio channel of it's own network to match the network to which it is attached. When it is searching for a network, the radio channel is changing all the time which makes connecting to it's network flaky.
So if the device is successfully connected to a network the configuration portal will be available on both networks but if it is not already connected to a network it will operate in access point mode and not try to connect until new credential are entered to increase reliability.
While trying to connect to the new network it's own WiFi network will necesarily become flaky and it will shutdown and restart it's own WiFi network on a different channel after it successfully connects. This can cause a browsing device to switch over to a different network.
- The ConfigOnSwitch example shows how it works and should be used as the basis for a sketch that uses this library.
- The concept of ConfigOnSwitch is that a new ESP8266/ESP32 will start a WiFi configuration portal when powered up and save the configuration data in non volatile memory. Thereafter, the configuration portal will only be started again if a button is pushed on the ESP8266/ESP32 module.
- Using any WiFi enabled device with a browser (computer, phone, tablet) connect to the newly created Access Point and type in any http address.
- Because of the Captive Portal and the DNS server you will either get a 'Join to network' type of popup or get any domain you try to access redirected to the configuration portal.
- All http web addresses will be redirected to wifi.urremote.com which will be at IP address 192.168.4.1 . This address is also a valid internet address where the user will see advice that they are connected to the wrong network.
- Choose one of the access points scanned, enter password, click save.
- ESP will try to connect. If successful, the IP address on the new network will be displayed in the configuration portal.
- The configuration portal will now be visible on two networks, these being it's own network and the network to which it has connected. On it's own network it will have two IP addresses, the original 192.168.4.1 and the same IP address it has on the network to which it connected.
- Selecting "close configuration portal" will shutdown the web server, shutdown the ESP8266/ESP32 WiFi network and return control to the following sketch code.
See "Installing Arduino libraries" and use the Importing a .zip Library method or preferably use manual installation as you can checkout the release from github and use that. This makes it easier to keep current with updates. Installing using the Library Manager does not work with this version of the library.
- Include in your sketch
// Define the ESP to use (ESP8266 or ESP32)
// If nothing is defined the library will assume you are using ESP32
#define ESP8266;
//#define ESP32;
#include <WiFi32Manager.h> //https://github.com/edumeneses/WiFi32Manager- When you want open a config portal initialize library, add
WiFiManager wifiManager;then call
wifiManager.startConfigPortal()While in AP mode, connect to it then open a browser to the gateway IP, default 192.168.4.1, configure wifi, save and it should save WiFi connection information in non volatile memory, reboot and connect.
Once WiFi network information is saved in the ESP8266/ESP32, it will try to connect to WiFi every time it is started without requiring any function calls in the sketch.
Also see ConfigOnSwitch example.
You can password protect the configuration access point. Simply add an SSID as the first parameter and the password as a second parameter to startConfigPortal.
A short password seems to have unpredictable results so use one that's around 8 characters or more in length.
The guidelines are that a wifi password must consist of 8 to 63 ASCII-encoded characters in the range of 32 to 126 (decimal)
wifiManager.startConfigPortal( SSID , password )This gets called when custom parameters have been set AND a connection has been established. Use it to set a flag, so when all the configuration finishes, you can save the extra parameters somewhere.
See AutoConnectWithFSParameters Example.
wifiManager.setSaveConfigCallback(saveConfigCallback);saveConfigCallback declaration and example
//flag for saving data
bool shouldSaveConfig = false;
//callback notifying us of the need to save config
void saveConfigCallback () {
Serial.println("Should save config");
shouldSaveConfig = true;
}If you need to set a timeout so the ESP8266 doesn't hang waiting to be configured for ever.
wifiManager.setConfigPortalTimeout(600);which will wait 10 minutes (600 seconds). When the time passes, the startConfigPortal function will return, no matter the outcome and continue the sketch.
Example usage
void loop() {
// is configuration portal requested?
if ( digitalRead(TRIGGER_PIN) == LOW ) {
WiFiManager wifiManager;
wifiManager.startConfigPortal();
Serial.println("connected...yeey :)");
}
}See ConfigOnSwitch example for a more complex version.
Many applications need configuration parameters like MQTT host and port, blynk or emoncms tokens, etc. While it is possible to use WiFiManager to collect additional parameters it is better to read these parameters from a web service once WiFiManager has been used to connect to the internet. This makes WiFiManager simple to code and use, parameters can be edited on a regular web server and can be changed remotely after deployment. A web service that can provide these parameters is at configure.urremote.com.
To capture other parameters with WiFiManager is a lot more involved than all the other features and requires adding custom HTML to your form. If you want to do it with WiFiManager see the example ConfigOnSwitchFS
You can set a custom IP for both AP (access point, config mode) and STA (station mode, client mode, normal project state)
This will set your captive portal to a specific IP should you need/want such a feature. Add the following snippet before startConfigPortal()
//set custom ip for portal
wifiManager.setAPStaticIPConfig(IPAddress(10,0,1,1), IPAddress(10,0,1,1), IPAddress(255,255,255,0));This will use the specified IP configuration instead of using DHCP in station mode.
wifiManager.setSTAStaticIPConfig(IPAddress(192,168,0,99), IPAddress(192,168,0,1), IPAddress(255,255,255,0));There are various ways in which you can inject custom HTML, CSS or Javascript into the configuration portal. The options are:
- inject custom head element
You can use this to any html bit to the head of the configuration portal. If you add a
<style>element, bare in mind it overwrites the included css, not replaces.
wifiManager.setCustomHeadElement("<style>html{filter: invert(100%); -webkit-filter: invert(100%);}</style>");- inject a custom bit of html in the configuration form
WiFiManagerParameter custom_text("<p>This is just a text paragraph</p>");
wifiManager.addParameter(&custom_text);- inject a custom bit of html in a configuration form element Just add the bit you want added as the last parameter to the custom parameter constructor.
WiFiManagerParameter custom_mqtt_server("server", "mqtt server", "iot.eclipse", 40, " readonly");You can filter networks based on signal quality and show/hide duplicate networks.
- If you would like to filter low signal quality networks you can tell WiFiManager to not show networks below an arbitrary quality %;
wifiManager.setMinimumSignalQuality(10);will not show networks under 10% signal quality. If you omit the parameter it defaults to 8%;
- You can also remove or show duplicate networks (default is remove). Use this function to show (or hide) all networks.
wifiManager.setRemoveDuplicateAPs(false);Debug is enabled by default on Serial. To disable add before startConfigPortal()
wifiManager.setDebugOutput(false);If you get compilation errors, more often than not, you may need to install a newer version of the ESP8266/ESP32 core for Arduino.
Tested down to ESP8266 core 2.4.1 and ESP32 core 1.0.1.
If you connect to the created configuration Access Point but the configuration portal does not show up, just open a browser and type in the IP of the web portal, by default 192.168.4.1.
The ESP32 may return null to WiFi.SSID() after restarting. This problem can be solved by copying the following code to the WiFi.SSID() function in WiFiSTA.cpp (WiFi.h related file at ESP32 board library), usually found in /Users/USER/Library/Arduino15/packages/esp32/hardware/esp32/1.0.2/libraries/WiFi/src
String WiFiSTAClass::SSID() const
{
if(WiFiGenericClass::getMode() == WIFI_MODE_NULL){
return String();
}
wifi_ap_record_t info;
if(!esp_wifi_sta_get_ap_info(&info)) {
return String(reinterpret_cast<char*>(info.ssid));
}
else{
wifi_config_t conf;
esp_wifi_get_config(WIFI_IF_STA, &conf);
return String(reinterpret_cast<char*>(conf.sta.ssid));
}
return String();
}
- forked from: kentaylor's WiFiManager.
Uses code from: zhouhan0126's WiFiManager and tzapu's WiFiManager.
Thank you tzapu, kentaylor, zhouhan0126 for the previous work. Also thank you Alex Nieva and Johnty Wang for the contributions.
This WiFi manager version was primarily programmed to use on the wireless T-Sticks. More information at the IDMIL's website and at the instrument's git.