AutoConnect API

Include headers¶

The AutoConnect class is limited in its available APIs by the AutoConnect component it contains. The AutoConnect.h header file makes all AutoConnect features available. On the other hand, the AutoConnectCore.h header file does not include extensions such as custom web pages or OTAs; AutoConnectCore.h reduces memory consumption by limiting functionality to WiFi connectivity utilities only. See the Reducing Binary Size chapter for details.

AutoConnect.h¶

#include <AutoConnect.h>

AutoConnect.h header file provides all AutoConnect features.

AutoConnectCore.h¶

#include <AutoConnectCore.h>

AutoConnectCore.h header file provides the AutoConnect class that excludes Custom Web pages and OTA-related components of the AutoConnect features. When you include this header in your sketch, you cannot use the AutoConnectAux, AutoConnectElements, AutoConnectOTA, and AutoConnectUpdate classes.

Defined macros¶

They contain in AutoConnectDefs.h.

#define AC_USE_SPIFFS                           // Use SPIFFS for the file system on the onboard flash
#define AC_USE_LITTLEFS                         // Use LittleFS for the file system on the onboard fash
#define AC_DEBUG                                // Monitor message output activation
#define AC_DEBUG_PORT           Serial          // Default message output device
#define AUTOCONNECT_AP_IP       0x011CD9AC      // Default SoftAP IP
#define AUTOCONNECT_AP_GW       0x011CD9AC      // Default SoftAP Gateway IP
#define AUTOCONNECT_AP_NM       0x00FFFFFF      // Default subnet mask
#define AUTOCONNECT_DNSPORT     53              // Default DNS port at captive portal
#define AUTOCONNECT_HTTPPORT    80              // Default HTTP
#define AUTOCONNECT_MENU_TITLE  "AutoConnect"   // Default AutoConnect menu title
#define AUTOCONNECT_URI         "/_ac"          // Default AutoConnect root path
#define AUTOCONNECT_TIMEOUT     30000           // Default connection timeout[ms]
#define AUTOCONNECT_CAPTIVEPORTAL_TIMEOUT  0    // Captive portal timeout value
#define AUTOCONNECT_STARTUPTIME 30              // Default waiting time[s] for after reset
#define AUTOCONNECT_USE_JSON                    // Allow AutoConnect elements to be handled by JSON format
#define AUTOCONNECT_USE_UPDATE                  // Indicator of whether to use the AutoConnectUpdate feature.
#define AUTOCONNECT_UPDATE_PORT 8000            // Available HTTP port number for the update
#define AUTOCONNECT_UPDATE_TIMEOUT  8000        // HTTP client timeout limitation for the update [ms]
#define AUTOCONNECT_TICKER_PORT LED_BUILTIN     // Ticker port
#endif

Macros placement moved

Source code placement of the above macros provided for user sketch changed from v0.9.7. The new code is in AutoConnectDefs.h.

Constructors¶

AutoConnect¶

AutoConnect()

AutoConnect default constructor. This entry internally allocates the ESP8266WebServer for ESP8266 or WebServer for ESP32 and is activated internally.

AutoConnect will call the user added handler to respond to the HTTP request using the ESP8266WebServer::on (WebServer::on for ESP32) funtion. This call will be made from during the handleClient of AutoConnect function.
Therefore, in the use case of assigning AutoConnect in this constructor, it is necessary to know the instance of ESP8266WebServer in order to register the request handler. Sketch can use host functions to obtain a reference to an ESP8266WebServer instance that is internally hosted by AutoConnect.

For ESP8266

AutoConnect(ESP8266WebServer& webServer)

For ESP32

AutoConnect(WebServer& webServer)

Run the AutoConnect site using the externally ensured ESP8266WebServer for ESP8266 or WebServer for ESP32.

Parameter: webServerA reference of ESP8266WebServer or WebServer instance.

Public member functions¶

append¶

ESP8266/ESP32 Common

AutoConnectAux* append(const String& uri, const String& title)

For ESP8266

AutoConnectAux* append(const String& uri, const String& title, ESP8266WebServer::THandlerFunction handler)

For ESP32

AutoConnectAux* append(const String& uri, const String& title, WebServer::THandlerFunction handler)

Creates an AutoConnectAux dynamically with the specified URI and integrates it into the menu. Calls with a request handler parameter can use this function as menu registration for a legacy page of ESP8266WebServer/WebServer. If the handler parameter specified, also it will register the request handler for the ESP8266WebServer/WebServer.
AutoConnect manages the menu items using a sequence list, and this function always adds the item to the end of the list. Therefore, the order of the menu items is the additional order.
Returns the pointer to created AutoConnectAux instance, the nullptr if an AutoConnectAux with the same URI already exists.

Parameter: uriA string of the URI.; titleTitle for menu item.; handlerRequest handler function as type of ESP8266WebServer::THandlerFunction/WebServer::THandlerFunction.
Return value: A Pointer to a created AutoConnectAux instance.

An instance of ESP8266WebServer/WebServer is needed

The WebServer must have instantiated for calling with a request handler parameter. AutoConnect can instantiate and host a WebServer internally, but in that case, the point in time to call the append function with a request handler parameter must be after AutoConnect::begin.

aux¶

AutoConnectAux* aux(const String& uri) const

Returns a pointer to AutoConnectAux with the URI specified by uri. If AutoConnectAux with that URI is not bound, it returns nullptr.

Parameter: uriA string of the URI.
Return value: A Pointer of the AutoConnectAux instance.

begin¶

bool begin()

bool begin(const char* ssid, const char* passphrase)

bool begin(const char* ssid, const char* passphrase, unsigned long timeout)

Starts establishing the WiFi connection. The WiFi mode at this time is WIFI_STA.
AutoConnect first invokes WiFi.begin. If the ssid and the passphrase are missing, its WiFi.begin has no SSID and Password. Regardless of the result, ESP8266WebServer/WebServer will start immediately after the first WiFi.begin.
The captive portal will not be started if the connection has been established with first WiFi.begin. If the connection cannot establish, switch to WIFI_AP_STA mode and activate SoftAP. Then DNS server starts.

Parameters: ssidSSID to be connected.; passphrasePassword for connection.; timeoutA time out value in milliseconds for waiting connection.
Return value: trueConnection established, AutoConnect service started with WIFI_STA mode.; falseCould not connected, Captive portal started with WIFI_AP_STA mode.

config¶

bool config(AutoConnectConfig& config)

bool config(const char* ap, const char* password = nullptr)

Set AutoConnect configuration settings.

Parameters: configReference to AutoConnectConfig containing SoftAP's parameters and static IP parameters.; apSSID for SoftAP. The default value is esp8266ap for ESP8266, esp32ap for ESP32.; passwordPassword for SodtAP. The default value is 12345678.
Return value: trueSuccessfully configured.; falseConfiguration parameter is invalid, some values out of range.

detach¶

bool detach(const String& uri)

Detach the AutoConnectAux with the specified URI from the management of AutoConnect. An unmanaged AutoConnectAux will no longer appear in menu items, and its page handler will no longer respond even if the URI is accessed directly.

Parameter: uriURI of AutoConnectAux to be detached.
Return value: trueSuccessfully detached.; falseAn AutoConnectAux with the specified URI does not exist.

If the request handler registered in the detaching AutoConnectAux is for a legacy page of the ESP8266WebServer/WebServer, the URI is still valid after detaching. AutoConnect does not delete the request handler registered to ESP8266WebServer/WebServer with the on function. (It cannot be removed)

Deleting the AutoConnectAux

If the AutoConnectAux to detach was added by AutoConnect::append, it will be automatically removed and freed from memory.

disableMenu¶

void disableMenu(const uint16_t items)

Disable the AutoConnect menu items specified by the items parameter with logical OR value using AC_MENUITEM_t constant.
This function only works for AutoConnect primary menu items. It has no effect on disable for AutoConnectAux items. To disable the items by AutoConnectAux, use the AutoConnectAux::menu function.

Parameter: itemsSpecify the combined value of AC_MENUITEM_t of the items deleting from the AutoConnect menu. It provides the value calculated from the logical OR by the AC_MENUITEM_t value of each item. Refer to the enableMenu about AC_MENUITEM_t.

enableMenu¶

void enableMenu(const uint16_t items)

Enable the AutoConnect menu items specified by the items parameter with logical OR value using AC_MENUITEM_t constant.

This function only works for AutoConnect primary menu items. It has no effect on enable for AutoConnectAux items. To enable the items by AutoConnectAux, use the AutoConnectAux::menu function.

Parameter

itemsSpecify the combined value of AC_MENUITEM_t of the items applying to the AutoConnect menu. It provides the value calculated from the logical OR by the AC_MENUITEM_t value of each item applied as a menu. AC_MENUITEM_t is enumeration type to identify each menu item and it has the below values.

AC_MENUITEM_CONFIGNEW : Configure new AP

AC_MENUITEM_OPENSSIDS : Open SSIDs

AC_MENUITEM_DISCONNECT : Disconnect

AC_MENUITEM_RESET : Reset...

AC_MENUITEM_HOME : HOME

AC_MENUITEM_UPDATE : Update

AC_MENUITEM_DEVINFO : Device statistics as AutoConnect root page

AC_MENUITEM_DELETESSID : Enable to delete credentials on Open SSIDs.

It is added, not replaced.

The initial configuration of the AutoConnect menu items:
AC_MENUITEM_CONFIGNEW | AC_MENUITEM_OPENSSIDS | AC_MENUITEM_DISCONNECT | AC_MENUITEM_RESET | AC_MENUITEM_HOME
The enableMenu function adds an indication of the specified items to the current. Therefore, use the disableMenu to remove the specified item from the initial menu.

end¶

void end(void)

Stops AutoConnect captive portal service. Release ESP8266WebServer/WebServer and DNSServer.

Attention to end

The end function releases the instance of ESP8266WebServer/WebServer and DNSServer. It can not process them after the end function.

getConfig¶

AutoConnectConfig& getConfig(void)

Get the current AutoConnectConfig values held by AutoConnect.

Return value: A reference to an AutoConnectConfig instance retained by AutoConnect. This reference reflects the actual values captured by the AutoConnect::config function, unlike the AutoConnectConfig value declared in the sketch.

getEEPROMUsedSize¶

uint16_t getEEPROMUsedSize(void)

Returns the total amount of memory required to hold the AutoConnect credentials and any custom configuration settings stored in EEPROM. The Sketch that writes its own custom data to the EEPROM must call EEPROM.begin with this value.

Return value: Total amount size of saved AutoConnect credentials and custom data.

The getEEPROMUsedSize is available for only ESP8266 use

It is available for only ESP8266 use and will return 0 when used with ESP32.

handleClient¶

void handleClient(void)

Process the AutoConnect menu interface. The ESP8266WebServer::handleClient¹ function hosted by AutoConnect is also called from within AutoConnect to handle the request handlers contained in Sketch.

Enhanced AutoConnect::handleClient

The handleClient function enhanced since AutoConnect 1.2.0 can start the captive portal according to the WiFi connection status.
By properly specifying AutoConnectConfig::retainPortal and AutoConnectConfig::autoRise, when handleClient detects WiFi disconnection, it shifts WiFi mode to WIFI_AP_STA and starts the DNS server together with SoftAP dynamically. Then trapping for incoming HTTP requests from client devices will be started by AutoConnect. Thus it will open the captive portal behind the execution of the sketch loop() function. The captive portal launched by enhanced handleClient does not interfere with sketch execution except waiting for the result of WiFi.begin.
Also, AutoConnectConfig::autoReconnect has improved. The Sketch can specify the AutoConnectConfig::reconnectInterval to continue retrying the reconnection with enhanced handleClient.

handleRequest¶

void handleRequest(void)

Handling for the AutoConnect menu request.

About used in combination with handleClient

The handleRequest function is not supposed to use with AutoConnect::handleClient. It should be used following ESP8266WebServer::handleClient or WebServer::handleClient.

home¶

void home(String& uri)

Put a user site's home URI. The URI specified by home is linked from "HOME" in the AutoConnect menu.

Parameter: uriA URI string of user site's home path.

host¶

For ESP8266

ESP8266WebServer& host(void)

For ESP32

WebServer& host(void)

Returns the reference of the ESP8266WebServer/WebServer which is allocated in AutoConnect automatically.

Return value: A reference of the ESP8266WebServer/WebServer.

&reference is not a pointer

A reference cannot be re-assigned, and must be assigned at initialization. It's like as bind as alias.

ESP8266WebServer& server = portal.host();
server.handleClient();

or

portal.host().handleClient();

isPortalAvailable¶

bool isPortalAvailable(void)

Returns a boolean value indicating whether a captive portal is available.

Return value: trueCaptive portal is available. It has SoftAP enabled and is spoofing DNS lookup responses by AutoConnect. Usually, in this state, requests from client devices for Internet transparency validation are redirected to the ESP module.; falseAutoConnect is not in captive portal state.

void join(std::vector<std::reference_wrapper<AutoConnectAux>> aux)

join¶

void join(AutoConnectAux& aux)

void join(std::vector<std::reference_wrapper<AutoConnectAux>> aux)

Join the AutoConnectAux object to AutoConnect. AutoConnectAux objects can be joined one by one, or joined altogether. The AutoConnectAux object joined by the join function can be handled from the AutoConnect menu.

Parameter: auxReference to AutoConnectAux. It can be std::vector of std::reference_wrapper of AutoConnectAux with list initialization.

load¶

bool load(const String& aux)

bool load(PGM_P aux)

bool load(const __FlashStringHelper* aux)

bool load(Stream& aux)

Load JSON document of AutoConnectAux which contains AutoConnectElements. If there is a syntax error in the JSON document, false is returned.

Parameter: auxThe input string to be loaded.
Return value: trueThe JSON document as AutoConnectAux successfully loaded.; falseLoading JSON document unsuccessful, probably syntax errors have occurred or insufficient memory. You can diagnose the cause of loading failure using the ArduinoJson Assistant.

locate¶

AutoConnectAux& locate(const String& uri)

Returns a reference to the AutoConnectAux assigned to the uri passed in the argument.

Parameter: uriURI string of the custom web page to be located.
Return value: A reference to the AutoConnectAux that has a specified URI.

AutoConnectAux for the specified uri must exist

If the AutoConnectAux for the uri specified to the locate function does not exist, the function returns a reference to an empty AutoConnectAux. It's just a frame without any AutoConnectElements. No processing can continue using that AutoConnectAux. (causes an exception) A common cause of exceptions for the locate function is syntax errors in the JSON description of a custom web page.

on¶

bool on(const String& uri, const AuxHandlerFunctionT handler, AutoConnectExitOrder_t order = AC_EXIT_AHEAD)

Register the handler function of the AutoConnectAux.

Parameters

uriA string of the URI assigned to the AutoConnectAux page.

handlerA function that behaves when a request to the AutoConnectAux page occurs. AuxHandlerFunctionT type is defined by the following declaration.

String handler(AutoConnectAux&, PageArgument&)

orderSpecifies when the handler is called with the following enumeration value.

AC_EXIT_AHEAD : Called before AutoConnect generates the HTML of the page. You set the value of AutoConnectElements in the handler then its value will be displayed on the page.

AC_EXIT_LATER : Called after AutoConnect generates the HTML of the page. You can append to HTML generated by AutoConnect.

AC_EXIT_BOTH : Called even before generating HTML and after generated.

It is not ESP8266WebServer::on, not WebServer::on for ESP32.

This function effects to AutoConnectAux only. However, it coexists with that of ESP8266WebServer::on or WebServer::on of ESP32.

onConnect¶

void onConnect(ConnectExit_ft fn)

Register the function which will call from AutoConnect at the WiFi connection established.

Parameter: fnA function called at the WiFi connected.

An fn specifies the function called when the WiFi connected. Its prototype declaration is defined as ConnectExit_ft.

typedef std::function<void(IPAddress& localIP)> ConnectExit_ft

Parameter: localIPAn IP address of the ESP module as STA.

onDetect¶

void onDetect(DetectExit_ft fn)

Register the function which will call from AutoConnect at the start of the captive portal.

Parameter: fnA function called at the captive portal start.

An fn specifies the function called when the captive portal starts. Its prototype declaration is defined as DetectExit_ft.

typedef std::function<bool(IPAddress& softapIP)>  DetectExit_ft

Parameter: softapIPAn IP address of SoftAP for the captive portal.
Return value: trueContinues captive portal handling.; falseCancel the captive portal. AutoConnect::begin function will return with a false.

onNotFound¶

For ESP8266

void onNotFound(ESP8266WebServer::THandlerFunction fn)

For ESP32

void onNotFound(WebServer::THandlerFunction fn)

Register the handler function for undefined URL request detected.

Parameter: fnA function of the "not found" handler.

onOTAEnd¶

void onOTAEnd(OTAEndExit_ft fn)

Register the on-end exit routine that is called only once when the OTA is finished.

Parameter: fnA function called when the OTA has been finished.

An fn specifies the function called when the OTA has been finished. Its prototype declaration is defined as OTAEndExit_ft.

typedef std::function<void(void)> OTAEndExit_ft

onOTAError¶

void onOTAError(OTAErrorExit_ft fn)

Register the exit routine that is called when some error occurred.

Parameter: fnA function called when some OTA error occurs.

An fn specifies the function called when the some error occurred. Its prototype declaration is defined as OTAErrorExit_ft.

typedef std::function<void(uint8_t error)> OTAErrorExit_ft

Parameter: errorError code of OTA. It is defined in the Updater class or the Update class of the Arduino core for each platform.

onOTAProgress¶

void onOTAProgress(OTAProgressExit_ft fn)

Register the exit routine that is called during the OTA progress.

Parameter: fnA function called during the OTA progress.

An fn specifies the function called during the OTA progress. Its prototype declaration is defined as OTAProgressExit_ft.

typedef std::function<void(unsigned int amount, unsigned int size)> OTAProgressExit_ft

Parameters: amountTotal amount of bytes received.; sizeBlock size of current send.

onOTAStart¶

void onOTAStart(OTAStartExit_ft fn)

Register the on-start exit routine that is called only once when the OTA has been started.

Parameter: fnA function called at the OTA start.

An fn specifies the function called when the OTA starts. Its prototype declaration is defined as OTAStartExit_ft.

typedef std::function<void(void)> OTAStartExit_ft

portalStatus¶

uint8_t portalStatus(void)

Returns the status of the portal inside AutoConnect::begin and AutoConnect::handleClient.

Return value

A bitwise value that indicates each status and is the logical disjunction of multiple states.

AutoConnect::AC_IDLE: Initial state. AutoConnect is not making any WiFi connection attempts. This state is reached immediately after AutoConnect::begin starts.

AutoConnect::AC_ESTABLISHED: Successfully connected to the WiFi access point.

AutoConnect::AC_AUTORECONNECT: AutoConnectConfig::autoReconnect setting was applied during the WiFi connection attempt process. This flag does not indicate a successful connection. It only shows that a condition that triggers autoReconnect has occurred. Whether the connection was actually successful should be determined by WiFi.status()==WL_CONNECTED.

AutoConnect::AC_TIMEOUT: WiFi connection attempt timed out. Or, the captive portal was shut down by the AutoConnectConfig::portalTimeout setting.

AutoConnect::AC_INTERRUPT: Connection interrupted due to an indication with the exit. The whileConnecting exit routine returned false. or the whileCaptivePortal exit routine returned false. AutoConnect aborted the WiFi connection attempt with those indications.

AutoConnect::AC_CAPTIVEPORTAL: Captive portal is available. It means that SoftAP mode is enabled, and the DNS server is available. The state of this flag is equivalent to the return value of AutoConnect::isPortalAvailable function.

AutoConnect::AC_INPROGRESS: WiFi.begin in progress. AutoConnect is waiting for the connection to succeed or times out; this state will reset when terminating WiFi.begin attempts.

restoreCredential¶

For ESP8266

bool restoreCredential(const char* filename = "/ac_credt", fs::FS& fs = FS)

For ESP32

bool restoreCredential(const char* filename = "/ac_credt", fs::SPIFFSFS& fs = SPIFFS)

bool restoreCredential(const char* filename = "/ac_credt", fs::LittleFSFS& fs = LittleFS)

For using SD

bool restoreCredential<fs::SDFS>(const char* filename, fs::SDFS& fs)

Restore credentials from the file as named filename with specified fs file system. The file containing the credentials of the restore source must have been saved with the AutoConnect::saveCredential function.

Parameter: filenameSpecify the file from which to restore the credentials. The filename must include /, the root directory. If this parameter is not specified, ac_credt is assumed.; fsSpecifies the file system of the source file to be restored. It must be mounted by the begin function of the file system concerned.
Return value: trueCredentials has been restored.; falseFailed to restore the credentials. Current credentials may have been lost.

saveCredential¶

For ESP8266

bool saveCredential(const char* filename = "/ac_credt", fs::FS& fs = FS)

For ESP32

bool saveCredential(const char* filename = "/ac_credt", fs::SPIFFSFS& fs)

bool saveCredential(const char* filename = "/ac_credt", fs::LittleFSFS& fs)

For using SD

bool saveCredential<fs::SDFS>(const char* filename, fs::SDFS& fs)

Saves the current credentials stored by AutoConnect to the specified file. A credential file saved with this function can be treated as input to the AutoConnect::restoreCredential function.

Parameter: filenameSpecify the file from which to save the credentials. The filename must include /, the root directory. If this parameter is not specified, ac_credt is assumed.; fsSpecifies the file system of the destination file to be saved. It must be mounted by the begin function of the file system concerned.
Return value: trueCredentials has been saved.; falseFailed to save the credentials.

where¶

String where(void)

Returns an uri string of the AutoConnectAux uri object of the custom Web page that caused the request to the page.
AutoConnect identifies the URI (ie. the referrer URI) that caused the request each time from the client occurs and will save the URI If the request source is a custom Web page of AutoConnectAux. The where function returns a pointer of AutoConnectAux which is a URI of a least recent request from the custom Web page.
This function is provided to access the fields (ie. the AutoConnectElements) with a custom Web page handler of a page and is available only for request source that is the custom Web pages. It is invalid for HTTP requests from individual pages registered with the on handler of ESP8266WebServer/WebServer for ESP32. In other words, this function only returns the AutoConnecAux page which is a least recently displayed.

Return value: An uri string of the AutoConnectAux that caused the request the page.

The where function usage is described in the section Where to pick up the values.

whileCaptivePortal¶

void whileCaptivePortal(WhileCaptivePortalExit_ft fn)

Register the function which will call from AutoConnect during a stay in the captive portal.

Parameter: fnFunction called at the captive portal start.

An fn specifies the function called while staying in the captive portal. Its prototype declaration is defined as WhileCaptivePortalExit_ft.

typedef std::function<bool(void)>   WhileCaptivePortalExit_ft

Return value: trueContinues captive portal handling.; falseCancel the captive portal. AutoConnect::begin function will return with a false.

whileConnecting¶

void whileConnecting(WhileConnectingExit_ft fn)

Register the function that will call from AutoConnect while waiting for connection after WiFi.begin.

Parameter: fnFunction that will call from AutoConnect while waiting for connection.

An fn specifies the a function called while waiting for a WiFi connection. Its prototype declaration is defined as WhileConnectingExit_ft.

typedef std::function<bool(String&)>    WhileConnectingExit_ft

Parameter: ssidSSID of an access point to which connection is being attempted.
Return value: trueContinue attempts to connect to WiFi.; falseCancel the WiFi connection attempt.

Equivalent to the WebServer::handleClient function on the ESP32 platform. ↩