WiFiThermostat/libraries/PersWiFiManager-api-reference.md

PersWiFiManager API Reference

constructor

PersWiFiManager::PersWiFiManager

functions

PersWiFiManager::attemptConnection

PersWiFiManager::begin

PersWiFiManager::getApSsid

PersWiFiManager::handleWiFi

PersWiFiManager::onAp

PersWiFiManager::onConnect

PersWiFiManager::setApCredentials

PersWiFiManager::setConnectNonBlock

PersWiFiManager::setupWiFiHandlers

PersWiFiManager::startApMode

---

PersWiFiManager

Creates a new PersWiFiManager object

Signatures

PersWiFiManager(ESP8266WebServer& s, DNSServer& d)

Args

ESP8266WebServer& s An existing instance of the ESP8266WebServer class that will be used throughout the program
DNSServer& d An existing instance of the DNSServer class that will be used throughout the program

Notes

Declare the object globally, or at least in the same scope as your ESP8266WebServer and DNSServer

attemptConnection

Attempts to auto-connect to last WiFi network used (or other if specified). Falls back to AP mode if unsuccessful.

Signatures

bool attemptConnection()
bool attemptConnection(const String& ssid)
bool attemptConnection(const String& ssid, const String& pass)

Args

const String& ssid (Optional) SSID to connect to. This overrides the default behavior of connecting to the last network used.
const String& pass (Optional) password for the specified SSID. Length must be >= 8 characters

Returns

true if successfully autoconnected, false if switched to AP mode

Notes

This function is already called inside begin, or when WiFi settings are changed, but this can be used for manual operation.

begin

Begins automatic WiFi Configuration

Signatures

bool begin()
bool begin(const String& ssid)
bool begin(const String& ssid, const String& pass)

Args

const String& ssid (Optional) SSID to connect to. This overrides the default behavior of connecting to the last network used.
const String& pass (Optional) password for the specified SSID. Length must be >= 8 characters

Returns

true if successfully autoconnected

Notes

This sets up the server handlers for WiFi actions, then attempts to autoconnect. If no SSID is specified, it automatically attempts to connect to the last network used.

getApSsid

API Reference / PersWiFiManager::getApSsid Gets the AP mode SSID

Signatures

String getApSsid()

Returns

String containing the AP mode SSID

Notes

The AP mode SSID is automatically set by the library, unless overridden by setApCredentials

handleWiFi

Handles WiFi connecting/disconnecting in non-blocking mode

Signatures

void handleWiFi()

Notes

This function does not need to be called in normal mode.

If the PersWiFiManager is set to non-blocking mode with setConnectNonBlock, this must be called in the main loop.

onAp

Attach a handler function that runs every time AP mode is started

Signatures

void onAp(WiFiChangeHandlerFunction fn)

Args

WiFiChangeHandlerFunction fn A generic function pointer to an AP mode handler function

Notes

This will run the handler function every time AP mode is started, when WiFi fails to connect or AP mode is manually triggered.

For successful connection handler, see onConnect

Example Code

void setup(){
...

//uses a lambda function as the argument
persWM.onAp([]() {
    //this code runs every time AP mode is started
    DEBUG_PRINT("AP MODE");
    DEBUG_PRINT(persWM.getApSsid());
});

onConnect

Attach a handler function that runs every time WiFi connects

Signatures

void onConnect(WiFiChangeHandlerFunction fn)

Args

WiFiChangeHandlerFunction fn A generic function pointer to a wifi connection handler function

Notes

This will run the handler function every time the WiFi settings are changed and then a successful connection is made.

For unsuccessful / AP mode connection handler, see onAp

Example Code

void setup(){
...

//uses a lambda function as the argument
persWM.onConnect([]() {
    //this code runs every time wifi is connected
    DEBUG_PRINT("wifi connected");
    DEBUG_PRINT(WiFi.localIP());
    EasySSDP::begin(server);
});

setApCredentials

Sets the SSID (and password) to be used for AP mode

Signatures

void setApCredentials(const String& apSsid)
void setApCredentials(const String& apSsid, const String& apPass)

Args

const String& apSsid SSID to be used for AP mode.
const String& apPass (Optional) Password to be used for AP mode.

Notes

Passwords less than 8 characters long will be ignored.

setConnectNonBlock

Sets the PersWiFiManager connecting actions to non-blocking mode

Signatures

void setConnectNonBlock(bool b)

Args

bool b use true for non-blocking mode, false for regular mode

Notes

In non-blocking mode, handleWiFi must be called in the main loop

setupWiFiHandlers

Attaches WiFi settings and captive DNS handlers to web server and DNS Server

Signatures

void setupWiFiHandlers()

Notes

This function is already called inside begin() and doesn’t normally need to be used, but is available for manual operation.

startApMode

Allows manual starting of AP mode

Signatures

void startApMode()

Notes

WiFi settings are controlled by the user via the web-interface, but this allows a manual program-induced switch to AP mode.