DOCSEARCHbyAlgolia
Submit Docs

WiFiManager

repository·master·Indexed 27 days ago

https://github.com/tzapu/wifimanager

An ESP8266 and ESP32 WiFi connection manager that provides a fallback captive web portal for configuring WiFi credentials when a connection cannot be established. It supports custom configuration parameters, static IP setup, portal timeouts, and UI customization via HTML/CSS/JS injection.

Tokens
2.8K
Snippets
6
Records
20
Agent score
43%

What's inside WiFiManager

  1. Switch configuration website languages

    master

    You can change the language of the configuration portal at compile time. By default, it uses LANG_EN. If using PlatformIO, add the desired language code as a build flag in your platformio.ini file.

    Available language codes:

    • LANG_DE (German)
    • LANG_EN (English)
    • LANG_ES (Spanish)
    • LANG_FR (French)
    • LANG_PT (Portuguese)
    • LANG_PT_BR (Portuguese Brazil)

  2. Install WiFiManager via PlatformIO

    master

    You can add WiFiManager to your PlatformIO project by adding it to the lib_deps key in your platformio.ini file. You can use the library name or the GitHub URL.

    [env]
lib_deps =
	WiFiManager

    Or using the GitHub repository:

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

  3. Quick Start: Using WiFiManager in an Arduino sketch

    master

    WiFiManager allows your ESP device to automatically connect to a saved WiFi network or start an Access Point (AP) with a configuration portal if connection fails.

    1. Include the header.
    2. Instantiate the WiFiManager object (ideally in the global scope if using non-blocking mode).
    3. Call autoConnect() in your setup() function.

    When in AP mode, connect to the created Access Point and navigate to the gateway IP (default 192.168.4.1) in a browser to configure credentials.

  4. Install WiFiManager via Arduino Library Manager

    master

    To install WiFiManager in the Arduino IDE:

    1. Go to Sketch > Include Library > Manage Libraries.
    2. Search for WiFiManager.
    3. Click Install.

    Note: Version 0.8+ requires release 2.4.0 or newer of the ESP8266 core for Arduino.

  5. Troubleshoot WiFiManager issues

    master

    Common Issues

    • Compilation Errors: Ensure you are using a recent version of the ESP8266 core for Arduino. If using the latest GitHub version, you may need the latest core version.
    • Portal not appearing: If you connect to the AP but the page doesn't load, manually navigate to 192.168.4.1 in your browser.
    • Endless connection loop: If the device keeps trying to connect and failing, add wifiManager.setConnectTimeout(60); before calling autoConnect() to limit connection attempts to 60 seconds.
    • Stuck in AP mode: If the device stays in AP mode after a power failure, use wifiManager.setConfigPortalTimeout(seconds); to ensure the portal closes after a period of inactivity.

  6. Inject Custom HTML, CSS, or Javascript

    master

    You can customize the look and feel of the configuration portal using three methods:

    1. Custom Head Element: Inject HTML/CSS into the <head> section. Note that <style> elements will overwrite existing CSS rather than appending to it.
    2. Custom HTML Paragraph: Inject a block of HTML into the parameter form using a WiFiManagerParameter object.
    3. Custom HTML Attribute: Add HTML attributes (like readonly) to a specific form element by passing them as the last argument to the WiFiManagerParameter constructor.

  7. Password protect the configuration Access Point

    master

    To secure the configuration Access Point, provide a password as the second argument to the autoConnect method. It is recommended to use a password of at least 8 characters for predictable results.

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

  8. Configure Custom Static IP for AP and Station

    master

    You can manually define IP configurations for both the Access Point (AP) mode and the Station (STA) mode.

    • AP Mode: Use setAPStaticIPConfig(ip, gateway, subnet) to set a specific IP for the captive portal.
    • STA Mode: Use setSTAStaticIPConfig(ip, gateway, subnet) to use a static IP instead of DHCP when connecting to a router.

  10. Apply Theming and UI tweaks

    master

    Use built-in methods to quickly change the UI appearance:

    • setClass("invert"): Applies a dark theme.
    • setScanDispPerc(true): Displays RSSI signal strength as percentages instead of graphs.
    wifiManager.setClass("invert");
wifiManager.setScanDispPerc(true);

  11. Configure Debugging

    master

    Debug output is enabled by default on Serial in non-stable releases.

    • Disable Debug: Call setDebugOutput(false) before autoConnect() or startConfigPortal().
    • Custom Stream: Pass a custom stream (e.g., Serial1) to the WiFiManager constructor.
    • Debug Levels: You can change the verbosity by modifying _debugLevel in the source code. Available levels: DEBUG_ERROR, DEBUG_NOTIFY, DEBUG_VERBOSE, DEBUG_DEV, DEBUG_MAX.

  12. Set Configuration Portal timeout

    master
    To prevent the ESP from hanging indefinitely in configuration mode (e.g., after a power failure), use setConfigPortalTimeout(seconds). This will cause autoConnect() to return after the specified number of seconds, regardless of whether a connection was established.