AutoConnectConfig API

The AutoConnectConfig class does not present some members regarding custom web page features due to differences in the AutoConnect component used in the sketch.

Sketch allows by including either AutoConnect.h or AutoConnectCore.h header file to use the AutoConnect library. If you include the AutoConnectCore.h with the sketch, AutoConnect will drop the functions involved custom web page facility. And correspondingly, some members that depend on custom web page functions will omit from the AutoConnectConfig class. See the Reducing Binary Size chapter for details.

Constructor¶

AutoConnectConfig¶

AutoConnectConfig()

AutoConnectConfig(const char* ap, const char* password)

AutoConnectConfig(const char* ap, const char* password, const unsigned long timeout)

AutoConnectConfig(const char* ap, const char* password, const unsigned long timeout, const uint8_t channel)

Parameters: apSSID for SoftAP. The length should be up to 31. The default value is esp8266ap for ESP8266, esp32ap for ESP32.; passwordPassword for SoftAP. The length should be from 8 to up to 63. The default value is 12345678.; timeoutThe timeout value of the captive portal in [ms] units. The default value is 0.; channelThe channel number of WIFi when SoftAP starts. The default values is 1.

Public member variables¶

apid¶

SoftAP's SSID.

Type: StringThe default value is esp8266ap for ESP8266, esp32ap for ESP32.

apip¶

Sets IP address for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this.

Type: IPAddressThe default value is 172.217.28.1

auth¶

Apply HTTP authentication with the AutoConnect web page. This This setting allows the Sketch to authenticate with "BASIC" or "DIGEST" scheme. It is given as an enumeration value of AC_AUTH_t that indicates the authentication scheme.
This setting determines the default scheme for HTTP authentication with AutoConnect. When the AutoConnectConfig::authScope is AC_AUTHSCOPE_PARTIAL, each AutoConnectAux authentication scheme has priority.

Type: AC_AUTH_t
Value: AC_AUTH_NONE No authentication. This is the default.; AC_AUTH_DIGEST Use the digest scheme.; AC_AUTH_BASIC Use the basic scheme.

authScope¶

Specifies the authentication scope of AutoConnect Web pages. The Sketch will be able to expand or narrow the range of authentication by this setting, which can be either as AC_AUTHSCOPE_t enumeration value.

Type: AC_AUTHSCOPE_t
Value: AC_AUTHSCOPE_AUX Require authentication to access for all custom Web pages, excepting AutoConnect's pages. This is the Default.; AC_AUTHSCOPE_PARTIAL Authenticate only specific custom Web pages which are specified by AutoConnectAux::authentication function or JSON description.; AC_AUTHSCOPE_PORTAL Require authentication to access for all AutoConnect's pages, including custom Web pages.

This setting is available only when AutoConnectConfig::auth is other than AC_AUTH_NONE. Ignored if it is AC_AUTH_NONE.

Also, the authScope setting has another bit that indicates to allow authentication in the captive portal state. Its enum value cannot be used alone and is always for qualifying the above three enum values.

Value: AC_AUTHSCOPE_WITHCP Allow authentication with the captive portal state. This value cannot be used alone to declare an authentication scope. It indicates to enable authentication in the captive portal by the logical OR operator with one of the AC_AUTHSCOPE_t values above.

autoReconnect¶

Automatically will try to reconnect with the past established access point (BSSID) when the current configured SSID in ESP8266/ESP32 could not be connected. By enabling this option, AutoConnect::begin() function will attempt to reconnect to a known access point using credentials stored in the flash, even if the connection failed by current SSID.
If the connection fails, starts the captive portal in SoftAP+STA mode.

Type: bool
Value: trueReconnect automatically.; falseStarts Captive Portal in SoftAP + STA mode without trying to reconnect. This is the default.

When the autoReconnect option is enabled, an automatic connection will behave if the following conditions are satisfied.

Invokes AutoConnect::begin without user name and password parameter as begin().
If one of the saved credentials matches the BSSID (or SSID) detected by the network scan.

Either BSSID or SSID to aim the access point

Whether or not it points to the target access point is determined by matching the SSID or BSSID. The default key to collate is BSSID.
The BSSID is usually fixed to the MAC address unique to its access point device, but when using some mobile hotspots, the BSSID may change even for the same access point. If you operate inconvenience in aiming at the access point by BSSID, you can change the collation key to SSID by uncomment the below line in AutoConnectDefs.h:

#define AUTOCONNECT_APKEY_SSID

If AUTOCONNECT_APKEY_SSID macro is defined when the library is compiled, the access points are collated by the SSID.

autoReset¶

Reset ESP8266 module automatically after WLAN disconnected.

Type: bool
Value: trueReset after WiFi disconnected automatically.; falseNo reset.

autoRise¶

Captive portal activation switch. False for disabling the captive portal. It prevents starting the captive portal even if the connection at the 1^st-WiFi.begin fails.

Type: bool
Value: trueEnable the captive portal. This is the default.; falseDisable the captive portal.

autoSave¶

The credential saved automatically at the connection establishment.

Type: AC_SAVECREDENTIAL_t
Value: AC_SAVECREDENTIAL_AUTO The credential saved automatically. This is the default.; AC_SAVECREDENTIAL_ALWAYS Save specified SSID and Password always even if a specified credential has been rejected.; AC_SAVECREDENTIAL_NEVER The credential no saved.

beginTimeout¶

Specify the limit time to attempt WiFi connection to the access point. AutoConnect uses this value to abort the connection attempt at WiFi.begin. Its actual value specified in milliseconds unit.
The default value is AUTOCONNECT_TIMEOUT defined in AutoConnectDefs.h and the initial value is 30 seconds.

Type: unsigned long

bootUri¶

Specify the location to be redirected after module reset in the AutoConnect menu. It is given as an enumeration value of AC_ONBOOTURI_t indicating either the AutoConnect root path or the user screen home path.

Type: AC_ONBOOTURI_t
Value: AC_ONBOOTURI_ROOT Resetting the module redirects it to the AutoConnect root path. The root path is assumed to be AUTOCONNECT_URI defined in AutoConnectDefs.h.; AC_ONBOOTURI_HOME It is redirected to the URI specified by AutoConnectConfig::homeUri.

boundaryOffset¶

Sets the offset address of the credential storage area for EEPROM. This value must be between greater than 4 and less than flash sector size. (4096 by SDK)
The default value is 0.
This option is valid only for ESP8266 or ESP32 arduino core 1.0.2 earlier.

Type: uint16_t

It will conflict with user data.

If the Sketch leaves this offset at zero, it will conflict the storage area of credentials with the user sketch owned data. It needs to use the behind of credential area.

channel¶

The channel number of WIFi when SoftAP starts.

Type: uint8_t
Value: 1 ~ 14. The default value is 1.

How do I choose Channel

Espressif Systems had announced the application note about Wi-Fi channel selection.

dns1¶

Set primary DNS server address when using static IP address.

Type: IPAddress

dns2¶

Set secondary DNS server address when using static IP address.

Type: IPAddress

gateway¶

Sets gateway address for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this.

Type: IPAddressThe default value is 172.217.28.1

hidden¶

Sets SoftAP to hidden SSID.

Type: uint8_t
Value: 0SSID will be appeared. This is the default.; 1SSID will be hidden.

homeUri¶

Sets the home path of user sketch. This path would be linked from 'HOME' in the AutoConnect menu. The default for homeUri is "/".

Type: String

hostName¶

Sets the station host name of ESP8266/ESP32.

Type: String

immediateStart¶

Disable the 1^st-WiFi.begin and start the captive portal. If this option is enabled, the module will be in AP_STA mode and the captive portal. The evaluation rank of this parameter is lower than the AutoConnectConfig::autoRise. Even if immediateStart is true, the captive portal will not launch if autoRise is false.

Type: bool
Value: trueStart the captive portal with AutoConnect::begin.; falseEnable the 1^st-WiFi.begin and it will start captive portal when connection failed. This is default.

menuItems¶

Configure applying items of the AutoConnect menu. You can arbitrarily combine valid menus by coordinating the menuItems value.

Type: uint16_tIt provides the combined AC_MENUITEM_t value of the item to apply to the AutoConnect menu.
Specify the value calculated from the logical OR by the AC_MENUITEM_t value of each item applied as a menu. It affects not only disappear the items from the menu also invalidates the URI they have. As a consequence, even if it accesses the URL directly will occur a 404 error.
The default value is logical OR of AC_MENUITEM_CONFIGNEW, AC_MENUITEM_OPENSSIDS, AC_MENUITEM_DISCONNECT, AC_MENUITEM_RESET, AC_MENUITEM_UPDATE and AC_MENUITEM_HOME.
Value: AC_MENUITEM_NONE No assign items except for the AutoConnectAux page item.; AC_MENUITEM_CONFIGNEW Appends Configure new AP item.; AC_MENUITEM_OPENSSIDS Appends Open SSIDs item.; AC_MENUITEM_DISCONNECT Appends Disconnect item.; AC_MENUITEM_RESET Appends Reset... item.; AC_MENUITEM_UPDATE Appends Update item. This value is valid only for AutoConnect; it is not available for AutoConnectCore.; AC_MENUITEM_HOME Appends HOME item.; AC_MENUITEM_DEVINFO Appends the Device info item which links to AutoConnect statistics page.; AC_MENUITEM_DELETESSID Enables the ability to interactively delete credentials on the Open SSIDs menu screen.

How to specify the value of the menu items

An menuItems accepts the logical OR of AC_MENUITEM_t type value. For example, to enable only Open SSIDs and HOME items, specify:

AutoConnect portal;
AutoConnectConfig config;

config.menuItems = AC_MENUITEM_OPENSSIDS | AC_MENUITEM_HOME;
portal.config(config);

Also, to enable the credentials removal feature, follow these settings procedures.

AutoConnect portal;
AutoConnectConfig config;

config.menuItems = config.menuItems | AC_MENUITEM_DELETESSID;
portal.config(config);

However, even if you specify like the above, the AutoConnectAux page items still display on the menu. To remove the AutoConnectAux items, use the AutoConnectAux::menu function.

minRSSI¶

Specify the lower limit of the WiFi signal strength allowed to use as an access point. This value should be greater than -120 as RSSI. Generally, a data link will not be established unless it exceeds -90 dBm. Also, packet transmission is not reliable below -70 dBm to -80 dBm.

Type: int16_tThe default value is -120

netmask¶

Sets subnet mask for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this.

Type: IPAddressThe default value is 255.255.255.0

ota¶

Specifies to import the built-in OTA update class into the Sketch. When this option is enabled, an Update item will appear in the AutoConnect menu, and the OTA update via Web browser will be automatically embedded to the Sketch.

Type: AC_OTA_t
Value: AC_OTA_EXTRA AutoConnect does not import AutoConnectOTA. This is the default.; AC_OTA_BUILTIN Specifies to include AutoConnectOTA in the Sketch.

otaExtraCaption¶

Specifies the caption to be displayed as an extra on the OTA update screen. The extra caption you specified will be displayed in the upper right corner of the OTA update screen. Also, you can only specify the caption string, and you cannot specify the style individually. An extra caption will draw up with the default style of AutoConnect.

Type: const char* An extra caption string pointer.

password¶

Set the password for authentication.

Type: String The default value is same as psk.

portalTimeout¶

Specify the timeout value of the captive portal in [ms] units. It is valid when the station is not connected and does not time out if the station is connected to the ESP module in SoftAP mode (i.e. Attempting WiFi connection with the portal function). If 0, the captive portal will not be timed-out.

Type: unsigned longCaptive portal timeout value. The default value is 0.

preserveAPMode¶

Specifies starting the STA while maintaining the state of the SoftAP mode in the AutoConnect::begin. This setting only applies when the AutoConnectConfig::autoRise is false.

Type: bool
Value: trueAutoConnect::begin keeps AP mode.; falseAutoConnect::begin will stop SoftAP at the beginning of the process.

Note that this option is not for starting the SoftAP forcibly in AutoConnect::begin and only keeps AP mode, SoftAP initiation is left to the Sketch.

preserveIP¶

When using existing credentials to connect WiFi, the station IP configuration specified with the AutoConnectConfig::staip, AutoConnectConfig::staGateway, and AutoConnectConfig::staNetmask are preferred over the IP settings of the stored credentials. If this value is set to true, IP configurations stored with credentials will not be restored.

Type: bool
Value: trueUse IP addresses specified with the AutoConnectConfig::staip, AutoConnectConfig::staGateway, and AutoConnectConfig::staNetmask as the station IP configuration.; falseWhen reconnecting, the station IP configuration specified with AutoConnectConfig is ignored and the saved credential values are used.

principle¶

Specify the connection order will attempt to connect to one of the highest RSSI values among multiple available access points. It is given as an enumeration value of AC_PRINCIPLE_t indicating.

Type: AC_PRINCIPLE_t
Value: AC_PRINCIPLE_RECENT Attempts to connect in the order of the saved credentials entries. The entry order is generally a time series connected in the past.; AC_PRINCIPLE_RSSI Attempts to connect to one of the highest RSSI values among multiple available access points.

psk¶

Sets password for SoftAP. The length should be from 8 to up to 63. The default value is 12345678.

Type: String

reconnectInterval¶

Specifies the number of units for interval time to attempt automatic reconnection when AutoConnectConfig::autoReconnect is enabled. This value is specified by the number of unit times from 0 to 255, and one unit time is macro-defined as AUTOCONNECT_UNITTIME in AutoConnectDefs.h file of library source code, and its initial value is 30[s].

Type: uint8_t

WiFi connection retry is repeated inside AutoConnect::handleClient after the number of seconds that the reconnectInterval value is multiplied by AUTOCONNECT_UNITTIME from the previous attempt. Then, when the connection with one of the saved credentials is established, the automatic reconnection will stop. And while AutoConnectConfig::autoReconnect is enabled, if the WiFi connection is lost, it will start to auto-reconnect again inside AutoConnect::handleClient.

If 0 is specified for the reconnectInterval, background reconnection attempt repeatedly will not be made, and only once at the 1^st-WiFi.begin failure in AutoConnect::begin. (Only when AutoConnectConfig::autoReconnect is enabled) The default value is 0.

AUTOCONNECT_UNITTIME

AUTOCONNECT_UNITTIME as macro defined in AutoConnectDefs.h file of library source code as the below:

// Number of seconds in uint time [s]
#ifndef AUTOCONNECT_UNITTIME
#define AUTOCONNECT_UNITTIME    30
#endif

retainPortal¶

Specify whether to continue the portal function even if the captive portal timed out. If the true, when a timeout occurs, the AutoConnect::begin function is exited with returns false, but the portal facility remains alive. So SoftAP remains alive and you can invoke AutoConnect while continuing sketch execution. The default is false.

Type: bool
Value: trueContinue the portal function even if the captive portal times out. The STA + SoftAP mode of the ESP module continues and accepts the connection request to the AP.; falseWhen the captive portal times out, STA + SoftAP mode of the ESP module is stopped. This is default.

Connection request after timed-out

With the retainPortal, even if AutoConnect::begin in the setup() is timed out, you can execute the Sketch and the portal function as a WiFi connection attempt by calling AutoConnect::handleClient in the loop().

All unresolved addresses redirects /_ac

If you enable the retainPortal option, all unresolved URIs will be redirected to SoftAPIP/_ac. It happens frequently as client devices repeat captive portal probes in particular. To avoid this, you need to exit from the WiFi connection Apps on your device once.

staip¶

Set a static IP address. The IP will behave with STA mode.

Type: IPAddress

staGateway¶

Set the gateway address when using static IP address.

Type: IPAddress

staNetmask¶

Set the subnetmask when using static IP address.

Type: IPAddress

ticker¶

Set flicker signal output according to WiFi connection status during AutoConnect::begin behavior.

Type: bool
Value: trueOutput the flicker signal while AutoConnect::begin operation. The AUTOCONNECT_TICKER_PORT macro in the AutoConnectDefs.h header file assigns pins for signal output. The default pin is arduino valiant's LED_BUILTIN. For boards without the LED_BUILTIN pin, assume pin #2.; falseNo flicker signal output.

tickerPort¶

Specifies the GPIO port number to output the flicker signal of the ticker. The default assumes on the board dependent definition LED_BUILTIN macro redefined by AUTOCONNECT_TICKER_PORT in AutoConnectDefs.h.

Type: uint8_t

tickerOn¶

Specifies the active logic level of the flicker signal. This value indicates the active signal level when driving the ticker.

Type: uint8_t
Value: LOWA flicker signal is an active-high.; HIGHA flicker signal is an active-low.

title¶

Set the menu title.

Type: String

uptime¶

Specifies the waiting time for the module to reboot.

Type: intThe default value is AUTOCONNECT_TIMEOUT/1000.

username¶

Set the username for authentication.

Type: StringThe default value is same as apid.

AutoConnectConfig Initial values¶

Public member	Data type	Initial value definition	Defined symbol ¹
apid	String	`esp8266ap` `esp32ap`	AUTOCONNECT_APID
apip	IPAddress	172.217.28.1	AUTOCONNECT_AP_IP
auth	AC_AUTH_t	AC_AUTH_NONE	AC_AUTH_NONE AC_AUTH_DIGEST AC_AUTH_BASIC
authScope	AC_AUTHSCOPE_t	AC_AUTHSCOPE_AUX	AC_AUTHSCOPE_PARTIAL AC_AUTHSCOPE_AUX AC_AUTHSCOPE_AC AC_AUTHSCOPE_PORTAL AC_AUTHSCOPE_WITHCP
autoReconnect	bool	false
autoReset	bool	true
autoRise	bool	true
autoSave	AC_SAVECREDENTIAL_t	AC_SAVECREDENTIAL_AUTO	AC_SAVECREDENTIAL_AUTO AC_SAVECREDENTIAL_ALWAYS AC_SAVECREDENTIAL_NEVER
beginTimeout	unsinged long	30000UL	AUTOCONNECT_TIMEOUT
bootUri	AC_ONBOOTURI_t	AC_ONBOOTURI_ROOT	AC_ONBOOTURI_ROOT AC_ONBOOTURI_HOME
boundaryOffset	uint16_t	0	AC_IDENTIFIER_OFFSET
channel	uint8_t	1	AUTOCONNECT_AP_CH
dns1	IPAddress	0UL
dns2	IPAddress	0UL
gateway	IPAddress	172.217.28.1	AUTOCONNECT_AP_GW
hidden	uint8_t	0
homeUri	String	`/`	AUTOCONNECT_HOMEURI
hostName	String	NULL
immediateStart	bool	false
menuItems	uint16_t	AC_MENUITEM_CONFIGNEW + AC_MENUITEM_OPENSSIDS + AC_MENUITEM_DISCONNECT + AC_MENUITEM_RESET + AC_MENUITEM_UPDATE + AC_MENUITEM_HOME	AC_MENUITEM_CONFIGNEW AC_MENUITEM_OPENSSIDS AC_MENUITEM_DISCONNECT AC_MENUITEM_RESET AC_MENUITEM_UPDATE AC_MENUITEM_HOME
minRSSI	int16_t	-120	AUTOCONNECT_MIN_RSSI
netmask	IPAddress	172.217.28.1	AUTOCONNECT_AP_NM
ota	AC_OTA_t	AC_OTA_EXTRA	AC_OTA_EXTRA AC_OTA_BUILTIN
otaExtraCaption	const char*	nullptr
password	String	Follow psk
portalTimeout	unsigned long	0UL	AUTOCONNECT_CAPTIVEPORTAL_TIMEOUT
preserveAPMode	bool	false
principle	AC_PRINCIPLE_t	AC_PRINCIPLE_RECENT	AC_PRINCIPLE_RECENT AC_PRINCIPLE_RSSI
psk	String	`12345678`	AUTOCONNECT_PSK
reconnectInterval	uint8_t	0
retainPortal	bool	false
staGateway	IPAddress	0UL
staip	IPAddress	0UL
staNetmask	IPAddress	0UL
ticker	bool	false
tickerOn	uint8_t	LOW	AUTOCONNECT_UPDATE_LEDON
tickerPort	uint8_t	LED_BUILTIN	AUTOCONNECT_TICKER_PORT
title	String	`AutoConnect`	AUTOCONNECT_MENU_TITLE
uptime	int	AUTOCONNECT_TIMEOUT/1000	AUTOCONNECT_STARTUPTIME
username	String	Follow apid

AutoConnectConfig example¶

AutoConnect        Portal;
AutoConnectConfig  Config("", "passpass");    // SoftAp name is determined at runtime
Config.apid = ESP.hostname();                 // Retrieve host name to SotAp identification
Config.apip = IPAddress(192,168,10,101);      // Sets SoftAP IP address
Config.gateway = IPAddress(192,168,10,1);     // Sets WLAN router IP address
Config.netmask = IPAddress(255,255,255,0);    // Sets WLAN scope
Config.autoReconnect = true;                  // Enable auto-reconnect
Config.autoSave = AC_SAVECREDENTIAL_NEVER;    // No save credential
Config.boundaryOffset = 64;                   // Reserve 64 bytes for the user data in EEPROM.
Config.portalTimeout = 60000;                 // Sets timeout value for the captive portal
Config.retainPortal = true;                   // Retains the portal function after timed-out
Config.homeUri = "/index.html";               // Sets home path of Sketch application
Config.title ="My menu";                      // Customize the menu title
Config.staip = IPAddress(192,168,10,10);      // Sets static IP
Config.staGateway = IPAddress(192,168,10,1);  // Sets WiFi router address
Config.staNetmask = IPAddress(255,255,255,0); // Sets WLAN scope
Config.dns1 = IPAddress(192,168,10,1);        // Sets primary DNS address
Portal.config(Config);                        // Configure AutoConnect
Portal.begin();                               // Starts and behaves captive portal

Those symbols are defined in AutoConnectDefs.h. ↩