# AutoConnectConfig API - AutoConnect for ESP8266/ESP32
ESP8266/ESP32 WLAN configuration at run time with web interface
Author: Hieromon Ikasamo

Skip to content

# AutoConnectConfig API

## 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 SodtAP. 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
  String The 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

### 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 BSSIDs (not the SSID) of the credentials matches the BSSID detected by the network scan.

### 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 1st-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_NEVER The credential no saved.

### 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 1st-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 1st-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.
  AC_MENUITEM_HOME Appends HOME item.
  AC_MENUITEM_DEVINFO Appends the Device info item which links to AutoConnect statistics page.

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:

    AutoConnectConfig config;
    config.menuItems = AC_MENUITEM_OPENSSIDS | AC_MENUITEM_HOME;

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.

### 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.

### 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

### 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 to /_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

## 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