DS_CAP_WIFIMANAGER - denis-stepanov/esp-ds-system GitHub Wiki

This capability adds support for Wi-Fi configuration at runtime. Instead of hardcoding network credentials, a Wi-Fi configuration page could be called, which would allow selecting network and entering its password.

The following methods are available:

void System::configureNetwork();                 // Configure network (blocking)
bool System::needsNetworkConfiguration();        // Return true if network needs configuration
void System::requestNetworkConfiguration();      // Request network configuration
String System::getNetworkConfigPassword();       // Return Wi-Fi configuration password

configureNetwork() will enter Wi-Fi manager, implemented by Wi-FiManager library. By design of that library, this is a blocking call, but it will keep the background tasks, such as network, running. As soon as Wi-Fi manager is activated, it will start a temporary Wi-Fi access point, with the SSID defined by System::hostname field (see network) and password given by the getNetworkConfigPassword() function. The configureNetwork() call exits once the network credentials are entered by the user.

The temporary access point is protected by a password which is always 8 chars long and is built on a basis of System::hostname. The SSID (hostname) and this password could be marked on a device to inform end user about network credentials needed to configure Wi-Fi.

The way configureNetwork() is invoked depends on a sketch logic. Functions requestNetworkConfiguration() and needsNetworkConfiguration() provide some assistance with that. requestNetworkConfiguration() will set up a flag that Wi-Fi configuration has been requested, and needsNetworkConfiguration() can be used to check that flag. For instance, if Wi-Fi manager needs to be activated by a button long press, the algorithm could look as follows:

1. configure button callback to call requestNetworkConfiguration() on long press;
2. in loop(), check needsNetworkConfiguration() and call configureNetwork() if needed. The flag gets reset on exit from configureNetwork().

If on-board button is active, this sequence will be automatically enabled, with a long-press delay of 1 s. See complete example in the Usage below.

For another common pattern of entering Wi-Fi manager if button is pressed on boot, setup() could read a momentary button value and call configureNetwork() directly, without using other functions.

• DS_CAP_SYS_NETWORK — network capability
• Wi-Fi Manager — Wi-Fi manager implementation

• DS_CAP_SYS_NETWORK — network connection routine on startup will use hardcoded network credentials in absence of Wi-Fi manager, and will rely on credentials stored in flash memory in presence of Wi-FI manager. If network name in flash memory turns out to be empty, no connection attempt will be made; user will have to configure network credentials in order to proceed;
• DS_CAP_SYS_LOG — if syslog is enabled, Wi-Fi manager entry and exit will be logged;
• DS_CAP_APP_LOG — if application log is enabled, network reconfiguration by user will be logged;
• DS_CAP_SYS_LED — if system LED is enabled, it will be lit steadily while Wi-Fi manager is running;
• DS_CAP_BUTTON — if system button is enabled, long press will activate Wi-Fi manager;
• DS_CAP_WEBSERVER — if web server is enabled, its "System Information" page will include "Wi-Fi Config AP" line with information on SSID and password to use in order to configure Wi-Fi. Also, since Wi-Fi manager brings its own web server, the existing web server will shut down for the time that the manager is active, in order to avoid conflict.

None.

(assuming on-board button is present)

MySystem.h:

#define DS_CAP_SYS_NETWORK  // Enable network
#define DS_CAP_WIFIMANAGER  // Enable Wi-Fi Manager
#define DS_CAP_SYS_LOG_HW   // Enable syslog on hardware serial line

#include "System.h"         // System global definitions

sketch.ino:

#include "MySystem.h"

using namespace ds;

void setup() {
    System::begin();
    System::log->println("Long press button to enter Wi-Fi Manager");
    System::log->printf("Once active, connect to configuration network '%s', password '%s',"
        " and follow instructions\n",
        System::hostname, System::getNetworkConfigPassword().c_str());
}

void loop() {
    System::update();
}

• wifimanager
• wifimanager_button

None.

Version 1.0 or later.

None.