AutoConnect

AutoConnect is an Arduino library designed for ESP8266 and ESP32 modules that enables runtime WLAN configuration via a web interface. Instead of hard-coding SSIDs and passwords into your sketch, users can connect to the device's access point (often via a captive portal) and input credentials through a web UI.

Key features include:

• Dynamic Configuration: Connect to any WLAN at runtime without re-flashing.
• Credential Persistence: Automatically saves connection data to EEPROM so the device can reconnect after a reboot.
• Non-Intrusive Integration: Can work alongside your existing ESP8266WebServer or WebServer (ESP32) instances.
• Custom Web Pages: Supports adding user-defined screens with HTML elements like TEXT, INPUT, BUTTON, CHECKBOX, RADIO, SELECT, and SUBMIT.
• JSON-based UI: User-owned screens can be defined using JSON descriptions stored in PROGMEM, SPIFFS, or SD.
• OTA Support: Easily integrates Over-The-Air firmware updates, manageable via the AutoConnect menu.

AutoConnect can be used in two modes depending on how you declare the AutoConnect object. This determines how the web server is managed and how you access the AutoConnect menu.

1. Reference Mode (With Parameter)

Declaration: AutoConnect VARIABLE(&WEBSERVER); (where WEBSERVER is your ESP8266WebServer or WebServer instance).

• AutoConnect uses your existing server instance to handle the AutoConnect menu.
• You can still use WEBSERVER.on() to register your own custom URL handlers.
• To use the AutoConnect menu: You must call PORTAL.handleClient() OR call WEBSERVER.handleClient() followed by PORTAL.handleRequest().

2. Hosted Mode (No Parameter)

Declaration: AutoConnect VARIABLE;

• AutoConnect internally allocates its own ESP8266WebServer or WebServer instance.
• To use custom URL handlers: You must call PORTAL.begin() first, then use PORTAL.host() to retrieve the internal server instance to register handlers via .on().
• To use the AutoConnect menu: You must call PORTAL.handleClient() OR call WEBSERVER.handleClient() (from the hosted instance) followed by PORTAL.handleRequest().

If you are building a custom update server instead of using the provided Python script, your server must implement the following HTTP sequence to work with the AutoConnectUpdate class:

1. Catalog List Request

The client agent requests a list of available files via a GET request to the /_catalog endpoint with query parameters.

URL Format: [address]/_catalog?op=list&path=[path]

Required Response:

• Content-Type: application/json
• Body: A JSON array of objects, where each object represents a file:

{
  "name" : "FILE_NAME",
  "type" : "bin",
  "date" : "FILE_TIMESTAMP_DATED",
  "time" : "FILE_TIMESTAMP_TIMED",
  "size" : 12345
}

Note: Only files with "type": "bin" are recognized as valid update targets.

2. Binary File Download

When the client selects a file, it issues an HTTP GET request for that file. Your server must respond with the binary data and specific headers for the ESP8266/ESP32 core to process the update.

Required Headers:

• Content-Type: application/octet-stream
• Content-Disposition: attachment; filename="BINARY_SKETCH_FILE_NAME"
• Content-Length: LENGTH_OF_CONTENT
• x-MD5: HEXDIGEST (A 128-bit hexadecimal MD5 checksum of the file)

{
  "name" : FILE_NAME,
  "type" : FILE_TYPE,
  "date" : FILE_TIMESTAMP_DATED,
  "time" : FILE_TIMESTAMP_TIMED,
  "size" : FILE_SIZE
}

The AutoConnect menu provides several built-in functions for managing WiFi and the device state:

• Configure new AP: Scans for nearby access points. Allows entering SSID and Password. You can uncheck "Enable DHCP" to configure a static IP (note: AutoConnect does not validate IP syntax).
• Open SSIDs: Lists previously saved SSID credentials from flash. Clicking an item initiates a connection. If enabled via AutoConnectConfig::menuItems, a trash icon (<i class="fa fa-trash-alt"></i>) appears to allow deleting stored credentials.
• Disconnect: Cuts the current WiFi connection. Note that you will not be able to reach the menu again until you reconfigure the SSID.
• Reset...: Reboots the ESP module using ESP.reset().
• Update: Provides OTA (Over-the-Air) update capabilities. This item only appears if AutoConnectConfig::ota is set to AC_OTA_BUILTIN or AutoConnectUpdate is attached.
• HOME: Returns to the user's defined home path (default is /).

AutoConnect allows you to create custom Web pages that are integrated directly into the AutoConnect menu. These pages can be used to provide user interfaces for configuring parameters (like MQTT broker settings) or triggering actions in your sketch.

Core Abstractions

• AutoConnectAux: A container object that represents a custom Web page. It holds a title (displayed in the menu) and a uri (the web path). It acts as a container for UI elements.
• AutoConnectElement: The building blocks of a page (e.g., text, input boxes, checkboxes, buttons). Specific implementations include ACText, ACSubmit, etc.

Relationship

AutoConnectAux is a container for AutoConnectElement objects. To integrate a custom page into the menu, you must join an AutoConnectAux object to your AutoConnect instance (the portal).

// Conceptual sequence
ACText(header, "Title");
ACSubmit(save, "SAVE", "/save_uri");
AutoConnectAux aux("/page_uri", "Menu Title", true, { header, save });
portal.join({ aux });