Projects / Wi-Fi setup page for your device

Wi-Fi setup page for your device

Intermediate2 hGuided buildReviewed

Build it step by step

0 of 7 done
  1. ESP32

    Upload the sketch

    Open the serial monitor.

  2. ESP32

    Join the hotspot

    Connect a phone to Setup-MyDevice.

  3. ESP32

    Open the page

    It should appear automatically or at any address.

  4. ESP32

    Choose your network

    Pick it from the list and enter the password.

  5. ESP32

    Check it joined

    The board restarts and prints its address.

  6. ESP32

    Test a wrong password

    Enter one on purpose and see the portal return.

  7. ESP32

    Test the reset

    Hold the button at power-up for 10 seconds.

In short

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

Tick what you already own. It saves to My Garage, so “Build with what I have” knows.

Wiring

FromToWhy
ButtonESP32 GPIO4 and GNDHold 10 s to reset the saved Wi-Fi
5 V adapterESP32 USB or VINPower

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.

CheckExpected
First bootHotspot appears
Correct detailsJoins the network after restart
Wrong passwordPortal starts again
Button held 10 s at power-upSaved 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 →

Ask Lark AI

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.