Wi-Fi setup page for your device
Build it step by step
0 of 7 doneUpload the sketch
Open the serial monitor.
Join the hotspot
Connect a phone to Setup-MyDevice.
Open the page
It should appear automatically or at any address.
Choose your network
Pick it from the list and enter the password.
Check it joined
The board restarts and prints its address.
Test a wrong password
Enter one on purpose and see the portal return.
Test the reset
Hold the button at power-up for 10 seconds.
How do you build a wi-Fi setup page for your device?
A new device starts its own hotspot with a setup page, so users can enter their Wi-Fi details without code changes. You need ESP32 DevKit V1, Tactile push button 6 mm and 5 V 2 A USB adapter. It takes 7 steps and about 120 minutes.
- Level
- Intermediate
- Time
- About 120 min
- Parts
- 3
Parts list
- Development BoardsBuyESP32 DevKit V1 × 1
- SwitchesBuy
- PowerBuy
Tick what you already own. It saves to My Garage, so “Build with what I have” knows.
Wiring
| From | To | Why |
|---|---|---|
| Button | ESP32 GPIO4 and GND | Hold 10 s to reset the saved Wi-Fi |
| 5 V adapter | ESP32 USB or VIN | Power |
Code
On first power-up there are no saved details, so the board starts its own hotspot. Joining it opens the setup page on most phones; if it does not, open any web address. The page lists nearby networks, takes the password, saves both in flash memory and restarts. If the saved details fail, it opens the portal again. Hold the button for 10 seconds at power-up to clear them. The setup hotspot is open, so the password crosses the air unprotected for a few seconds; this is a trade-off you should keep in mind, and for a product you would add a per-device setup password printed on the label. Do not write the Wi-Fi password to the serial port or logs. Arduino IDE with the ESP32 boards package, board "ESP32 Dev Module".
Runs on a virtual ESP32 Dev Module in your browser, with sliders for the sensors. Happy with it? Verify and upload to your real board from the same page (Chrome or Edge on a computer).
// Starts a hotspot if no Wi-Fi is saved. Uses WiFi, WebServer, DNSServer and Preferences (all built in).
#include <WiFi.h>
#include <WebServer.h>
#include <DNSServer.h>
#include <Preferences.h>
Preferences prefs;
WebServer server(80);
DNSServer dns;
const byte BTN = 4;
bool portalMode = false;
String page(const String &body) {
return "<html><head><meta name='viewport' content='width=device-width'></head><body style='font-family:sans-serif'>" + body + "</body></html>";
}
void handleRoot() {
int n = WiFi.scanNetworks();
String opts = "";
for (int i = 0; i < n && i < 20; i++) opts += "<option>" + WiFi.SSID(i) + "</option>";
server.send(200, "text/html", page(
"<h3>Set up Wi-Fi</h3><form method='POST' action='/save'>"
"<select name='s'>" + opts + "</select><br><br>"
"<input name='p' type='password' placeholder='Password'><br><br>"
"<input type='submit' value='Save and restart'></form>"));
}
void handleSave() {
prefs.putString("ssid", server.arg("s"));
prefs.putString("pass", server.arg("p")); // never print the password on the serial port
server.send(200, "text/html", page("<p>Saved. The device will restart and join your Wi-Fi.</p>"));
delay(1500);
ESP.restart();
}
void startPortal() {
portalMode = true;
WiFi.mode(WIFI_AP);
WiFi.softAP("Setup-MyDevice"); // open network: use only for the few minutes of setup
dns.start(53, "*", WiFi.softAPIP()); // send every address to our page, a captive portal
server.on("/", handleRoot);
server.on("/save", HTTP_POST, handleSave);
server.onNotFound(handleRoot);
server.begin();
Serial.println("Portal started: join Setup-MyDevice");
}
void setup() {
Serial.begin(115200);
pinMode(BTN, INPUT_PULLUP);
prefs.begin("wifi", false);
unsigned long t = millis(); // holding the button at power-up for 10 s clears the settings
while (digitalRead(BTN) == LOW && millis() - t < 10000) delay(50);
if (millis() - t >= 10000) { prefs.clear(); Serial.println("Settings cleared"); }
String ssid = prefs.getString("ssid", "");
if (ssid == "") { startPortal(); return; }
WiFi.mode(WIFI_STA);
WiFi.begin(ssid.c_str(), prefs.getString("pass", "").c_str());
unsigned long s = millis();
while (WiFi.status() != WL_CONNECTED && millis() - s < 20000) delay(300);
if (WiFi.status() != WL_CONNECTED) { startPortal(); return; } // wrong details: start the portal again
Serial.print("Connected, IP "); Serial.println(WiFi.localIP());
}
void loop() {
if (portalMode) { dns.processNextRequest(); server.handleClient(); }
// your normal code goes here when connected
}What the serial monitor should show
Open the serial monitor at the baud rate in the code. This is what our simulator prints for a virtual ESP32 Dev Module with its sensors at their default values. Your numbers will follow your real readings, but the format should match.
Portal started: join Setup-MyDevice
Test checklist
What you should see at each check. If a reading is far off, stop and use the troubleshooting list.
| Check | Expected |
|---|---|
| First boot | Hotspot appears |
| Correct details | Joins the network after restart |
| Wrong password | Portal starts again |
| Button held 10 s at power-up | Saved details cleared |
If it does not work
Setup page does not appear
Open any address such as 192.168.4.1.
Network not in the list
Move closer and refresh; only 2.4 GHz networks show.
Keeps restarting
Check the saved details and the supply.
Cannot clear settings
Hold the button before and during power-up.
Still stuck? Find the fault step by step with your multimeter →
Common questions
What parts do I need for the wi-Fi setup page for your device?
ESP32 DevKit V1, Tactile push button 6 mm and 5 V 2 A USB adapter.
How long does the wi-Fi setup page for your device take to build?
About 120 minutes for a intermediate maker, in 7 steps.
How do I know the wi-Fi setup page for your device works?
First boot: Hotspot appears. Correct details: Joins the network after restart. Wrong password: Portal starts again.
Setup page does not appear: what should I check?
Open any address such as 192.168.4.1.
Network not in the list: what should I check?
Move closer and refresh; only 2.4 GHz networks show.
Keeps restarting: what should I check?
Check the saved details and the supply.
Cannot clear settings: what should I check?
Hold the button before and during power-up.
