Introduction
In this post we are going to check some additional features of the WiFi Manager library. The tests shown below were performed on a ESP32-E FireBeetle board from DFRobot.
Note that we are only going to cover some of the many features exposed by the library. As such, I also recommend you to explore the documentation of the library and its examples.
This post is the sequence of the previous tutorial where we covered the basics on how to get started with the WiFi Manager library. It is recommended that you take a look at it first to better understand the code sections below.
Resetting saved credentials
In this section we will learn how to reset any saved network credentials, collected in the WiFi Manager portal. There may be multiple reasons to reset existing credentials, but a likely one is for testing purposes, to make sure the portal is launched every time when we call the autoConnect method (the portal is not launched if we call this method and it can successfully connect to a network using existing credentials).
As such, the WiFiManager class exposes a method called resetSettings. This method takes no arguments and erases any saved network credentials.
The usage of this method is shown in the code snippet below. As can be seen, we are calling the resetSettings before the autoConnect method, which will ensure that the WiFi configuration portal will always be launched.
#include <WiFiManager.h>
void setup() {
Serial.begin(115200);
WiFiManager manager;
manager.resetSettings();
bool success = manager.autoConnect("ESP32_AP","password");
if(!success) {
Serial.println("Failed to connect");
}
else {
Serial.println("Connected");
}
}
void loop(){}
Disabling debug output
If you ran the example from the previous tutorial on how to get started with the WiFi Manager library, you probably noticed that it will output a lot of information to the serial port. This happens because debug mode is enabled by default for non-stable releases [1] and, at the time of writing, the latest version available in GitHub is 0.16.0 (non-stable).
We can easily disable the debugging output by calling the setDebugOutput method on the WiFiManager object and passing the Boolean value false, as indicated in the code below.
#include <WiFiManager.h>
void setup() {
Serial.begin(115200);
WiFiManager manager;
manager.setDebugOutput(false);
manager.resetSettings();
bool success = manager.autoConnect("ESP32_AP","password");
if(!success) {
Serial.println("Failed to connect");
}
else {
Serial.println("Connected");
}
}
void loop(){}
After uploading the code to your ESP32, open the Serial Monitor of the Arduino IDE. Debugging content from the WiFi Manager library should no longer be printed to the Serial Monitor.
Setting the configuration portal timeout
Other point that was mentioned on the previous tutorial was that, when we call the autoConnect method, the program execution will block until the user either performs the configuration of a network in the portal or exits (in case there are no previously saved credentials).
Although this is the default behavior of the library, we can set a timeout for this wait with a call to the setConfigPortalTimeout on the WiFiManager object. As input, we need to pass the timeout value, in seconds.
If this timeout is exceeded without any user action, the autoConnect method will return. The code below shows the usage of this method, where we passed a timeout of 10 seconds, a small value used just for testing purposes.
#include <WiFiManager.h>
void setup() {
Serial.begin(115200);
WiFiManager manager;
manager.resetSettings();
manager.setConfigPortalTimeout(10);
manager.autoConnect("ESP32_AP","password");
Serial.println("Wait finished");
}
void loop(){}
To test the code, simply compile it and upload it to your ESP32, and open the Serial Monitor when the procedure finishes. After the portal is setup, wait for 10 seconds and then you should see the “Wait finished” message getting printed in the Serial Monitor.
Collecting custom parameters
Other interesting feature that the WiFi Manager library supports is collecting additional parameters besides the SSID (network name) and password, as can be seen in this section. However, we are responsible for saving those parameters if we need to [2].
To configure the WiFiManager to collect an additional parameter, we first need to create an object of class WiFiManagerParameter. The constructor of this class receives the following values:
- Identifier of the parameter, as a string;
- Label that will be shown above the parameter input textbox, as a string;
- Default parameter value, as a string;
- Maximum length of the parameter, as an integer. We will use a value of 40 for illustration purposes.
WiFiManagerParameter parameter("parameterId", "Parameter Label", "default value", 40);
After that, we need to call the addParameter method on the WiFiManager object, passing as input the address of the WiFiManagerParameter we have just created.
manager.addParameter(¶meter);
We can later access the value of the parameter with a call to the getValue method on the WiFiManagerParameter object, after the autoConnect method returns.
Serial.println("Parameter:");
Serial.println(parameter.getValue());
The complete code can be seen below.
#include <WiFiManager.h>
void setup() {
Serial.begin(115200);
WiFiManager manager;
manager.setDebugOutput(false);
manager.resetSettings();
WiFiManagerParameter parameter("parameterId", "Parameter Label", "default value", 40);
manager.addParameter(¶meter);
manager.autoConnect("ESP32_AP","password");
Serial.println("Parameter:");
Serial.println(parameter.getValue());
}
void loop(){}
To test, as usual, compile the code and upload it to your ESP32. After that, connect a computer to the ESP32 network and access the portal in a web browser of your choice using the URL below:
http://192.168.4.1/
Then, choose the “Configure WiFi” option. You should get a UI simular to figure 1 and, as can be seen below, there’s an extra text input to collect an additional parameter. Both the label and the default value match the ones we configured in our code.
After choosing a WiFi network and saving the credentials, the value you have set on the parameter textbox should get printed on the Arduino IDE Serial Monitor. In my case, I’ve changed the default value to a string “Test value”, as shown in figure 2.
Although our code only covered a single parameter, we can actually configure the WiFiManager to collect more that one parameter, as shown in figure 3.
By default, when we access the WiFi Manager portal, we get the page shown below in image 4. As can be seen, we have not only the entry that directs us to the WiFi configuration page, but also an Info and Exit page.
Nonetheless, we may change this behavior to show, for example, only the Configure WiFi menu entry. To do so, we simply need to create a vector of strings with the menu entries we want to show. In this case, we simply set a single value, called “wifi”, which corresponds to the mentioned menu entry.
std::vector<const char *> menu = {"wifi"};
Then, we simply need to call the setMenu method on our WiFiManager object, passing as input our vector.
manager.setMenu(menu);
The complete code is shown below.
#include <WiFiManager.h>
void setup() {
Serial.begin(115200);
WiFiManager manager;
manager.setDebugOutput(false);
manager.resetSettings();
std::vector<const char *> menu = {"wifi"};
manager.setMenu(menu);
manager.autoConnect("ESP32_AP","password");
}
void loop(){}
After you access the portal root page, you should now see the menu shown in figure 5.
References
[1] https://github.com/tzapu/WiFiManager#debug
[2] https://github.com/tzapu/WiFiManager/tree/2ce0850d80d6c51f36dbbece777bd8a9f41d0927#custom-parameters