WiFiManager: set an ESP32’s WiFi from a phone instead of the sketch
WiFiManager solves the hard-coded password problem. Instead of writing your network name and password into the sketch, you call autoConnect(): if the board has joined a network before, it reconnects with the credentials the ESP core saved in flash; if not, it starts its own access point with a captive portal, and you pick a network and type the password from a phone.
Built in on Mokxi: #include <WiFiManager.h> and it builds, with nothing to install. Free, and no account needed.
What WiFiManager does
While the portal is open the board waits inside autoConnect(), which by default never returns until someone finishes the form. For a device that must keep working without WiFi, set setConfigPortalTimeout() so it gives up after a few minutes and your code carries on.
Custom fields go on the same portal page. A WiFiManagerParameter holds an id, a label, a default value and a length, and after the portal closes getValue() gives what was typed: an MQTT server, an API key, a device name. Saving those for the next boot is your job, usually with Preferences or a file.
| Library Manager name | WiFiManager |
|---|---|
| Author | tzapu |
| Include | #include <WiFiManager.h> |
| Boards | ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, ESP8266 NodeMCU, Raspberry Pi Pico W, Arduino Uno R4 WiFi |
| In the simulator | Builds and runs, and says plainly that the hardware behind it is not simulated. |
Install it
It builds on ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, ESP8266 NodeMCU, Raspberry Pi Pico W, Arduino Uno R4 WiFi.
In Mokxi it is built in: #include <WiFiManager.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "WiFiManager" by tzapu from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add WiFiManager to lib_deps in PlatformIO. Mokxi follows the calls of release 2.0.17, so a sketch written here builds there too.
What to know in the simulator: The setup portal needs access-point mode and saved credentials, which are not simulated, so autoConnect() returns false at once and says why on Serial. WiFi.begin(ssid, password) joins the board’s network.
ESP32-C3 · ESP32-C6 · Seeed XIAO ESP32-C3 · ESP32-C3 SuperMini · Seeed XIAO ESP32-C6 · ESP32 DevKit · ESP32-DevKitC V4 · LOLIN32 Lite · Wemos D1 R32 · Cheap Yellow Display · TTGO T-Display · ESP32-S3-DevKitC-1 · Seeed XIAO ESP32-S3 · Arduino Nano ESP32 · ESP8266 NodeMCU · Raspberry Pi Pico W · Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
WiFiManager wm
Creates the manager. It can be local to setup(), as in the tutorials, since nothing in loop() needs it after the board is connected.
wm.autoConnect("AutoConnectAP", "password")
Joins the saved network, or opens the portal under that access point name and password. Returns true once connected and false if the portal timed out.
if (!wm.autoConnect("AutoConnectAP", "password")) {
Serial.println("Failed to connect");
ESP.restart();
}wm.setConfigPortalTimeout(180)
Closes the portal after 180 seconds with nobody using it, so autoConnect() returns false instead of waiting for ever.
wm.resetSettings()
Erases the saved network so the next autoConnect() opens the portal. Run it once while testing, then take it out, or the board forgets its WiFi on every boot.
WiFiManagerParameter custom_mqtt("server", "MQTT server", "broker.local", 40)
A text field for the portal: id, label, default value and maximum length. Add it with wm.addParameter(&custom_mqtt) before autoConnect().
custom_mqtt.getValue()
The text the field held when the portal closed, as a const char*.
wm.startConfigPortal("Setup")
Opens the portal on demand, for example when a button is held at boot, even if a network is saved.
wm.setSaveConfigCallback(saveConfigCallback)
Calls your function when the portal saves new settings, the cue to store your custom parameters.
Example: WiFiManager, and joining the network directly instead
On the ESP32-C3-DevKitM-1. It runs in the browser exactly as printed.
#include <WiFiManager.h>
WiFiManagerParameter apiKey("key", "API key", "abc123", 16);
void setup() {
Serial.begin(115200);
WiFiManager wm;
wm.addParameter(&apiKey);
if (!wm.autoConnect("AutoConnectAP", "password")) {
Serial.println("Failed to connect, joining directly");
WiFi.begin("Mokxi-Lab", "breadboard");
while (WiFi.status() != WL_CONNECTED) delay(250);
}
Serial.print("connected to ");
Serial.println(wm.getWiFiSSID());
Serial.print("key ");
Serial.println(apiKey.getValue());
}
void loop() {}Common errors and how to fix them
The board opens the portal every time it boots
wm.resetSettings() is still in setup(), so the saved network is erased on each start. Remove it after the first test, or call it only when a reset button is held.
The sketch never reaches loop() when the router is off
With no saved network in range, autoConnect() opens the portal and waits there. Call setConfigPortalTimeout() with a number of seconds so it returns false and the rest of the sketch runs.
autoConnect() returns false at once in Mokxi
Access-point mode and saved credentials are not simulated, so there is no portal to open. Join the simulated network with WiFi.begin(ssid, password) instead, and the rest of the sketch runs as written.
Try WiFiManager without installing anything
Open the example, change the sketch, and keep your version in a free account.