search

tzapu / WiFiManager

ESP8266 WiFi Connection manager with web captive portal
http://tzapu.com/esp8266-wifi-connection-manager-library-arduino-ide/
MIT License
6.63k stars 1.98k forks source link
arduino captive configuration-portal esp8266 wifimanager

readme

WiFiManager

Espressif ESPx WiFi Connection manager with fallback web configuration portal

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

Release

Build CI Status

Build CI Status Examples

arduino-library-badge

Build with PlatformIO

ESP8266

ESP32 ESP32 ESP32 ESP32

Member to Member Support / Chat

Join the chat at https://gitter.im/tablatronix/WiFiManager

Discord 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

Contents

How It Works

How It Looks

ESP8266 WiFi Captive Portal Homepage ESP8266 WiFi Captive Portal Configuration

Wishlist

Development

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

Checkout from github

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

Using

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

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.println(WiFi.softAPIP());

  Serial.println(myWiFiManager->getConfigPortalSSID());
}
Save settings

This gets called when custom parameters have been set AND a connection has been established. Use it to set a flag, so when all the configuration finishes, you can save the extra parameters somewhere.

IF YOU NEED TO SAVE PARAMETERS EVEN ON WIFI FAIL OR EMPTY, you must set setBreakAfterConfig to true, or else saveConfigCallback will not be called.

//if this is set, it will exit after config, even if connection is unsuccessful.
    void          setBreakAfterConfig(boolean shouldBreak);

See AutoConnectWithFSParameters Example.

wifiManager.setSaveConfigCallback(saveConfigCallback);

saveConfigCallback declaration and example

//flag for saving data
bool shouldSaveConfig = false;

//callback notifying us of the need to save config
void saveConfigCallback () {
  Serial.println("Should save config");
  shouldSaveConfig = true;
}

Configuration Portal Timeout

If you need to set a timeout so the ESP doesn't hang waiting to be configured, for instance after a power failure, you can add

wifiManager.setConfigPortalTimeout(180);

which will wait 3 minutes (180 seconds). When the time passes, the autoConnect function will return, no matter the outcome. Check for connection and if it's still not established do whatever is needed (on some modules I restart them to retry, on others I enter deep sleep)

On Demand Configuration Portal

If you would rather start the configuration portal on demand rather than automatically on a failed connection attempt, then this is for you.

Instead of calling autoConnect() which does all the connecting and failover configuration portal setup for you, you need to use startConfigPortal(). Do not use BOTH.

Example usage

void loop() {
  // is configuration portal requested?
  if ( digitalRead(TRIGGER_PIN) == LOW ) {
    WiFiManager wifiManager;
    wifiManager.startConfigPortal("OnDemandAP");
    Serial.println("connected...yeey :)");
  }
}

See example for a more complex version. OnDemandConfigPortal

Exiting from the Configuration Portal

Normally, once entered, the configuration portal will continue to loop until WiFi credentials have been successfully entered or a timeout is reached. If you'd prefer to exit without joining a WiFi network, say becuase you're going to put the ESP into AP mode, then press the "Exit" button on the main webpage. If started via autoConnect or startConfigPortal then it will return false (portalAbortResult)

Custom Parameters

You can use WiFiManager to collect more parameters than just SSID and password. This could be helpful for configuring stuff like MQTT host and port, blynk or emoncms tokens, just to name a few. You are responsible for saving and loading these custom values. The library just collects and displays the data for you as a convenience. Usage scenario would be:

- if connection to AP fails, configuration portal starts and you can set /change the values (or use on demand configuration portal)
- once configuration is done and connection is established save config callback() is called
- once WiFiManager returns control to your application, read and save the new values using the `WiFiManagerParameter` object.
```cpp
 mqtt_server = custom_mqtt_server.getValue();

This feature is a lot more involved than all the others, so here are some examples to fully show how it is done. You should also take a look at adding custom HTML to your form.

Custom IP Configuration

You can set a custom IP for both AP (access point, config mode) and STA (station mode, client mode, normal project state)

Custom Access Point IP Configuration

This will set your captive portal to a specific IP should you need/want such a feature. Add the following snippet before autoConnect()

//set custom ip for portal
wifiManager.setAPStaticIPConfig(IPAddress(10,0,1,1), IPAddress(10,0,1,1), IPAddress(255,255,255,0));
Custom Station (client) Static IP Configuration

This will make use the specified IP configuration instead of using DHCP in station mode.

wifiManager.setSTAStaticIPConfig(IPAddress(192,168,0,99), IPAddress(192,168,0,1), IPAddress(255,255,255,0)); // optional DNS 4th argument

There are a couple of examples in the examples folder that show you how to set a static IP and even how to configure it through the web configuration portal.

NOTE: You should fill DNS server if you have HTTP requests with hostnames or syncronize time (NTP). It's the same as gateway ip or a popular (Google DNS: 8.8.8.8).

Custom HTML, CSS, Javascript

There are various ways in which you can inject custom HTML, CSS or Javascript into the configuration portal. The options are:

Theming

You can customize certain elements of the default template with some builtin classes

wifiManager.setClass("invert"); // dark theme
wifiManager.setScanDispPerc(true); // display percentages instead of graphs for RSSI

There are additional classes in the css you can use in your custom html , see the example template.

Filter Networks

You can filter networks based on signal quality and show/hide duplicate networks.

Debug

Debug is enabled by default on Serial in non-stable releases. To disable add before autoConnect/startConfigPortal

wifiManager.setDebugOutput(false);

You can pass in a custom stream via constructor 

WiFiManager wifiManager(Serial1);

You can customize the debug level by changing _debugLevel in source options are:

Troubleshooting

If you get compilation errors, more often than not, you may need to install a newer version of the ESP8266 core for Arduino.

Changes added on 0.8 should make the latest trunk work without compilation errors. Tested down to ESP8266 core 2.0.0. Please update to version 0.8

I am trying to keep releases working with release versions of the core, so they can be installed through boards manager, but if you checkout the latest version directly from github, sometimes, the library will only work if you update the ESP8266 core to the latest version because I am using some newly added function.

If you connect to the created configuration Access Point but the configuration portal does not show up, just open a browser and type in the IP of the web portal, by default 192.168.4.1.

If trying to connect ends up in an endless loop, try to add setConnectTimeout(60) before autoConnect();. The parameter is timeout to try connecting in seconds.

I get stuck in ap mode when the power goes out or modem resets, try a setConfigPortalTimeout(seconds). This will cause the configportal to close after no activity, and you can reboot or attempt reconnection in your code.

Releases

1.0.1

Development Overview

Added Public Methods

setConfigPortalBlocking

setShowStaticFields

setCaptivePortalEnable

setRestorePersistent

setCaptivePortalClientCheck

setWebPortalClientCheck

startWebPortal

stopWebPortal

process

disconnect

erase

debugSoftAPConfig

debugPlatformInfo

setScanDispPerc

setHostname

setMenu(menu_page_t[])

setWiFiAutoReconnect

setSTAStaticIPConfig(..,dns)

setShowDnsFields

getLastConxResult

getWLStatusString

getModeString

getWiFiIsSaved

setShowInfoErase

setEnableConfigPortal

setCountry

setClass

htmleEtities

WiFiManagerParameter

WiFiManagerParameter(id,label)

WiFiManagerParameter.setValue(value,length)

getParameters

getParametersCount

Constructors

WiFiManager(Stream& consolePort)

define flags

❗️ Defines cannot be set in user sketches #define WM_MDNS // use MDNS

#define WM_FIXERASECONFIG // use erase flash fix, esp8266 2.4.0

#define WM_ERASE_NVS // esp32 erase(true) will erase NVS

#include <rom/rtc.h> // esp32 info page will show last reset reasons if this file is included

Changes Overview

0.12

0.11
0.10

Contributions and thanks

The support and help I got from the community has been nothing short of phenomenal. I can't thank you guys enough. This is my first real attept in developing open source stuff and I must say, now I understand why people are so dedicated to it, it is because of all the wonderful people involved.

THANK YOU

The esp8266 and esp32 arduino and idf maintainers!

Shawn A aka tablatronix

liebman

Evgeny Dontsov

Chris Marrin

bbx10

kentaylor

Maximiliano Duarte

alltheblinkythings

Niklas Wall

Jakub Piasecki

Peter Allan

John Little

markaswift

franklinvv

Alberto Ricci Bitti

SebiPanther

jonathanendersby

walthercarsten

And countless others

Inspiration