WiFiManager

WiFiManager gives ESP8266 and ESP32 firmware a polished, self-hosted Wi-Fi setup experience. It reconnects to saved networks and opens a temporary captive portal when it cannot, so users can configure the device from any phone or browser without a cloud service or companion app.

See it on real hardware

WiFiManager provides a self-hosted setup portal for Wi-Fi and application settings without copying portal HTML into each firmware. See the detailed portal UI guide for supported branding and content APIs.

Start with a working portal

#include <Arduino.h>
#include <WiFiManager.h>

WiFiManager wifi;

void setup() {
    Serial.begin(115200);
    wifi.setConfigPortalTimeout(180);
    wifi.autoConnect("Device Setup", "change-me");
}

void loop() {
    wifi.process();
}

When saved Wi-Fi is unavailable, autoConnect() starts the portal asynchronously. Call process() from every loop() iteration while it may be open. Flash Basic Portal to try this exact flow; its README gives the network name, password, portal address, and expected result after saving Wi-Fi.

Building a Home Assistant device?

WiFiManager remains a standalone provisioning library. If a device also needs persistent configuration, MQTT, Home Assistant discovery, OTA, mDNS, and an optional local web UI, see DeviceFramework, which integrates this portal as part of that larger device lifecycle. A DeviceFramework sketch includes DeviceFramework and calls its setup() and loop() APIs; do not create a second WiFiManager instance alongside it.

Make it yours

const char kTitle[] PROGMEM = "Set up Temperature Monitor";
const char kBrand[] PROGMEM = "Example Devices";
const char kAccent[] PROGMEM = "#347a45";

void setup() {
    WiFiManagerPortalConfig portalUI;

    // Leave fields unset to keep WiFiManager's built-in portal values.
    portalUI.title = WiFiManagerPortalText::progmem(kTitle);
    portalUI.identityText = WiFiManagerPortalText::progmem(kBrand);

    // Theme values customise the built-in styles; they do not replace the portal.
    portalUI.theme.accent = WiFiManagerPortalText::progmem(kAccent);
    portalUI.theme.cornerRadiusPx = 10;

    wifi.setPortalConfig(portalUI);  // Apply before the portal starts.
    wifi.autoConnect("Device Setup");
}

void loop() {
    wifi.process();
}

The Branded Portal example includes a static SVG, accessible identity text, and a small semantic theme. Custom Portal Content shows the supported parameters, information sections, and home cards without replacing the portal shell.

What it provides

Captive Wi-Fi setup: starts an access point only when saved network credentials cannot connect.
Responsive portal: one small portal for Wi-Fi, application fields, information, actions, and firmware update flow.
Structured APIs: C++ configuration and a local JSON protocol for the built-in portal.
Product presentation: title, logo, tagline, and semantic colour tokens without copying the portal HTML.
Primary and fallback networks: an opt-in two-network controller backed by an application-provided store.
ESP8266 and ESP32 support: the package resolves its asynchronous web dependencies for the selected target.

Choose a guide

Goal	Guide
Understand library/application ownership and supported boundaries	Architecture
Get a device online or recover from missing Wi-Fi	Provisioning lifecycle
Brand or constrain the built-in portal	Portal UI and configuration
Add and persist application settings, status, or home cards	Portal content
Configure primary/fallback station profiles	Station profiles
Surface setup, offline, and connection state in firmware	Observability
Configure AP, station, scan, or reconnect behaviour	Network configuration
Look up a supported C++ method and its timing	API reference
Understand the built-in portal's local JSON protocol	Portal API
Follow deployment-oriented integration patterns	Recipes
Build or flash a complete example	Examples
Run documentation and board-free compile checks	Testing
Contribute to this fork or prepare a release	Development

Install

[common]
lib_deps =
    WiFiManager=https://github.com/alexhopeoconnor/WiFiManager.git#v3.2.4

The suffix after # is a Git ref. PlatformIO clones the repository and checks out that release tag; GitHub Release assets are unrelated. Arduino IDE users can install this repository as a library checkout.

See the documentation index, examples, release history, and licence.

5.2 KiB Raw Blame History