With this library, the developer can create a WiFi ESP32 device which

1. on power on, it provides with the Captive Portal if the WiFi is not configured, where the user can enter the configuration information such as SSID/password, and save to the ESP32 flash filesystem.
2. or boots with the stored WiFi SSID/password and other programmed information if configured already.
3. connects to the WiFi and help run the programmed setup function
4. it will serve as written in the loop function
5. (factory reset) if needed, you can connect the RESET_PIN (default: GPIO0) to ground for more than 5 seconds, then the configuration will be deleted and the device can be reconfigured for the WiFi. The RESET_PIN can be customized for different boards (see Customizing the Reset Pin below).

This is the screenshot of a sample captive portal.

While the examples folder has an example code for this library, there is another example code that uses this ConfigPortal32 with an OLED Display showing the SSID/PW in QR Code.

• https://github.com/iotlab101/ConffigPortal_QRCode

You can create a PlatformIO project with the example directory and modify the src/main.cpp for your purpose and build it.

The following code is the example to use the library.

#include <Arduino.h>
#include <ESPmDNS.h>
#include <ConfigPortal32.h>

char*               ssid_pfix = (char*)"CaptivePortal";
String              user_config_html = "";      
/*
 *  ConfigPortal library to extend and implement the WiFi connected IOT device
 *
 *  Yoonseok Hur
 *
 *  Usage Scenario:
 *  0. copy the example template in the README.md
 *  1. Modify the ssid_pfix to help distinquish your Captive Portal SSID
 *          char   ssid_pfix[];
 *  2. Modify user_config_html to guide and get the user config data through the Captive Portal
 *          String user_config_html;
 *  2. declare the user config variable before setup
 *  3. In the setup(), read the cfg["meta"]["your field"] and assign to your config variable
 *
 */

void setup() {
    Serial.begin(115200);

    loadConfig();
    // *** If no "config" is found or "config" is not "done", run configDevice ***
    if(!cfg.containsKey("config") || strcmp((const char*)cfg["config"], "done")) {
        configDevice();
    }
    WiFi.mode(WIFI_STA);
    WiFi.begin((const char*)cfg["ssid"], (const char*)cfg["w_pw"]);
    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.print(".");
    }
    // main setup
    Serial.printf("\nIP address : "); Serial.println(WiFi.localIP());

    if (MDNS.begin("miniwifi")) {
        Serial.println("MDNS responder started");
    }    
}

void loop() {
}

If additional configuration parameter is needed, you can modify the user_config_html for your variable, and handle the variable as shown below. The custom varialbe here is yourVar in the user_html and handling in setup code as below

In the global section.

String              user_config_html = ""
    "<p><input type='text' name='yourVar' placeholder='Your Variable'>";
char                yourVar[50];

To read and set the configuration parameter to a variable(Refer to the ArduinoJson library for type handling).

    sprintf(yourVar, (const char*)cfg["yourVar"]);

In addition to the Captive Portal configuration capability, it has a feature that enables you to upload the configuration using the LittleFS file upload functions in both of Arduino IDE extension and the VSCode/PlatformIO.

The format of the configuration is as follows, and you place this under the folder named 'data' to upload.

{
   "ssid":"APID",
   "w_pw":"APPassword",
   "yourVar":"sample data",
   "config":"done"
}

Once config.json is ready, you can upload with PIO's 'Upload Filesystem Image' tool. Note: It uses the serial connection, so you need to stop the Serial Monitor if running.

The default RESET_PIN is GPIO0, which works for most ESP32 development boards. However, some boards use a different GPIO for the onboard button. For example, the Xiao Seeed ESP32-C3 has its button connected to GPIO9.

You can customize the RESET_PIN in two ways:

Add a #define before the #include of the library header:

#define RESET_PIN 9
#include <ConfigPortal32.h>

Add the build flag to your platformio.ini:

build_flags = -DRESET_PIN=9

This approach is useful when you want to keep the source code unchanged and manage board-specific settings in the project configuration.

There is one custom user exit call back function pointer and one optional html file postSave.html.

1. If you want/need to provide some intermediate function to run during the configuration stage, you can implement a function and assign it to userConfigLoop function pointer.

    // *** If no "config" is found or "config" is not "done", run configDevice ***
    if(!cfg.containsKey("config") || strcmp((const char*)cfg["config"], "done")) {
        userConfigLoop = &customConfigLoop;
        configDevice();
    }

For example, if you want to update the sensor data on OLED or if you need to provide some information to the browser through the websocket even during the configuration process.

2. If you want/need to show the post configuration information, you can create a html file with name postSave.html and place under data folder, this page will be sent to the browser when the user submit the configuation information. The built-in default page is as follows.

You can override the redirect_html to introduce another configuration step as well.

For example, the io7 IOT Platform's ESP32 Framework, IO7F32(https://github.com/io7lab/IO7F32) uses it to capture the partnering server's CA file to enable the SSL communication.

Unlike the full blown Operating System, Arduino or most of other embedded framework/OS doesn't have all the root CA files, so the target server's CA file needs to be embedded.