WiFiManager

Espressif ESPx WiFi Connection manager with fallback web configuration portal

:warning: This Documentation is out of date, see notes below

<a name="release"></a>

Member to Member Support / Chat

The configuration portal is of the captive variety, so on various devices it will present the configuration dialogue as soon as you connect to the created access point.

Works with the ESP8266 Arduino and ESP32 Arduino platforms.

Known Issues

• Documentation needs to be updated, see https://github.com/tzapu/WiFiManager/issues/500

---

Contents

• How it works
• Wishlist
• Quick start
  • Installing
    • Arduino - Through Library Manager
    • Arduino - From Github
    • PlatformIO
  • Using
• Documentation
  • Access Point Password
  • Callbacks
  • Configuration Portal Timeout
  • On Demand Configuration
  • Custom Parameters
  • Custom IP Configuration
  • Filter Low Quality Networks
  • Debug Output
• Troubleshooting
• Releases
• Contributors

How It Works

• When your ESP starts up, it sets it up in Station mode and tries to connect to a previously saved Access Point
• if this is unsuccessful (or no previous network saved) it moves the ESP into Access Point mode and spins up a DNS and WebServer (default ip 192.168.4.1)
• using any wifi enabled device with a browser (computer, phone, tablet) connect to the newly created Access Point
• because of the Captive Portal and the DNS server you will either get a 'Join to network' type of popup or get any domain you try to access redirected to the configuration portal
• choose one of the access points scanned, enter password, click save
• ESP will try to connect. If successful, it relinquishes control back to your app. If not, reconnect to AP and reconfigure.
• There are options to change this behavior or manually start the configportal and webportal independantly as well as run them in non blocking mode.

How It Looks

Wishlist

• [x] remove dependency on EEPROM library
• [x] move HTML Strings to PROGMEM
• [x] cleanup and streamline code (although this is ongoing)
• [x] if timeout is set, extend it when a page is fetched in AP mode
• [x] add ability to configure more parameters than ssid/password
• [x] maybe allow setting ip of ESP after reboot
• [x] add to Arduino Library Manager
• [x] add to PlatformIO
• [ ] add multiple sets of network credentials
• [x] allow users to customize CSS
• [ ] rewrite documentation for simplicity, based on scenarios/goals

Development

• [x] ESP32 support
• [x] rely on the SDK's built in auto connect more than forcing a connect
• [x] add non blocking mode
• [x] easy customization of strings
• [x] hostname support
• [x] fix various bugs and workarounds for esp SDK issues
• [x] additional info page items
• [x] last status display / faiilure reason
• [x] customizeable menu
• [x] seperate custom params page
• [x] ondemand webportal
• [x] complete refactor of code to segment functions
• [x] wiif scan icons or percentage display
• [x] invert class for dark mode
• [x] more template tokens
• [x] progmem for all strings
• [ ] new callbacks
• [ ] new callouts / filters
• [ ] shared web server instance
• [x] latest esp idf/sdk support
• [x] wm is now non persistent, will not erase or change stored esp config on esp8266
• [x] tons of debugging output / levels
• [ ] disable captiveportal
• [ ] preload wiifscans, faster page loads
• [ ] softap stability fixes when sta is not connected

Quick Start

Installing

You can either install through the Arduino Library Manager or checkout the latest changes or a release from github

Install through Library Manager

Currently version 0.8+ works with release 2.4.0 or newer of the ESP8266 core for Arduino

• in Arduino IDE got to Sketch/Include Library/Manage Libraries

• search for WiFiManager

• click Install and start using it

Checkout from github

Github version works with release 2.4.0 or newer of the ESP8266 core for Arduino

• Checkout library to your Arduino libraries folder

Using

• Include in your sketch

#include <WiFiManager.h>          //https://github.com/tzapu/WiFiManager WiFi Configuration Magic

• Initialize library, in your setup function add, NOTEif you are using non blocking you will make sure you create this in global scope or handle appropriatly , it will not work if in setup and using non blocking mode.

WiFiManager wifiManager;

• Also in the setup function add

//first parameter is name of access point, second is the password
wifiManager.autoConnect("AP-NAME", "AP-PASSWORD");

if you just want an unsecured access point

wifiManager.autoConnect("AP-NAME");

or if you want to use and auto generated name from 'ESP' and the esp's Chip ID use

wifiManager.autoConnect();

After you write your sketch and start the ESP, it will try to connect to WiFi. If it fails it starts in Access Point mode. While in AP mode, connect to it then open a browser to the gateway IP, default 192.168.4.1, configure wifi, save and it should reboot and connect.

Also see examples.

Install Using PlatformIO

PlatformIO is an emerging ecosystem for IoT development, and is an alternative to using the Arduino IDE. Install WiFiManager using the platformio library manager in your editor, or using the PlatformIO Core CLI, or by adding it to your platformio.ini as shown below (recommended approach).

The simplest way is to open the platformio.ini file at the root of your project, and WifiManager to the common top-level env lib_deps key like so:

[env]
lib_deps =
	WiFiManager

[env]
lib_deps =
	https://github.com/tzapu/WiFiManager.git

Documentation

Switch languages for the configuration website

You can switch the language for configuration website during compile time. Default is LANG_EN for an english setup. Within PlatformIO add the following compile parameter:

[env]
build_flags = -D LANG_EN

Currently the following language codes are available:

LANG_DE
LANG_EN
LANG_ES
LANG_FR
LANG_PT
LANG_PT_BR

Password protect the configuration Access Point

You can and should password protect the configuration access point. Simply add the password as a second parameter to autoConnect. A short password seems to have unpredictable results so use one that's around 8 characters or more in length. The guidelines are that a wifi password must consist of 8 to 63 ASCII-encoded characters in the range of 32 to 126 (decimal)

wifiManager.autoConnect("AutoConnectAP", "password")

Callbacks

Enter Config mode

Use this if you need to do something when your device enters configuration mode on failed WiFi connection attempt. Before autoConnect()

wifiManager.setAPCallback(configModeCallback);

configModeCallback declaration and example

void configModeCallback (WiFiManager *myWiFiManager) {
  Serial.println("Entered config mode");
  Serial.pr