Skip to content

# Library APIs

## Include headers

### AutoConnect.h

    #include <AutoConnect.h>

#### Define macros

    #define AC_DEBUG                                // Monitor message output activation
    #define AC_DEBUG_PORT           Serial          // Default message output device
    #define AUTOCONNECT_AP_IP       0x01F4A8C0      // Default SoftAP IP
    #define AUTOCONNECT_AP_GW       0x01F4A8C0      // 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_STARTUPTIME 10              // Default waiting time[s] for after reset
    #define AUTOCONNECT_URI         "/_ac"          // Default AutoConnect root path
    #define AUTOCONNECT_TIMEOUT     30000           // Default connection timeout[ms]

## AutoConnect API

### Constructors

#### AutoConnect

    AutoConnect()

AutoConnect default constructor. This entry activates WebServer internally and the web server is allocated internal.

    AutoConnect(ESP8266WebServer& webServer)

Run the AutoConnect site using the externally ensured ESP 8266 WebServer. User's added URI handler response can be included in handleClient method.

Parameters
  webServerA reference of ESP8266WebServer instance.

### Public member functions

#### begin

    bool begin()

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

    bool begin(const char* ssid, const char* passphraase, unsinged long timeout)

Starts establishing WiFi connection. Before establishing, start the Web server and DNS server for the captive portal. Then begins connection establishment in WIFI_STA mode. If connection can not established with the specified SSID and password, switch to WIFI_AP_STA mode and activate SoftAP.

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)

Sets SoftAP's WiFi configuration.

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

#### end

    void end()

Stops AutoConnect captive portal service. Release ESP8266WebServer and DNSServer.

Attention to end

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

#### handleClient

    void handleClient()

Handling for the AutoConnect web interface. Invoke the handleClient of the parent web server to process client request of the AutoConnect WEB interface. No effects when the web server is not available.

#### handleRequest

    void handleRequest()

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 with ESP8266::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 portal menu.

Parameters
  uri A URI string of user site's home path.

#### host

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

    ESP8266WebServer& host()

Return value
  A reference of the ESP8266WebServer.

&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();

#### onDetect

    void onDetect(DetectExit_ft fn)

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

Parameters
  fnFunction called at the captive portal start.

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

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

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

#### onNotFound

    void onNotFound(ESP8266WebServer::THandlerFunction fn)

Register the handler function for undefined URL request detected.

Parameters
  fnA function of the "not found" handler.

## AutoConnectConfig API

### Constructor

#### AutoConnectConfig

    AutoConnectConfig();

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

Parameters
  apSSID for SoftAP. The length should be up to 31. The default value is esp8266ap.
  passwordPassword for SodtAP. The length should be from 8 to up to 63. The default value is 12345678.

### Public member variables

#### apid

SoftAP's SSID.

Type
  String

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

#### autoReset

Reset ESP8266 module automatically when 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 first 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_AUTOThe credential saved automatically.
  AC_SAVECREDENTIAL_NEVERThe credential no saved.

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

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.

See Application note

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

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

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

Type
  String

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

#### psk

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

Type
  String

### AutoConnectConfig example

    AutoConenct        Portal;
    AutoConenctConfig  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.autoSave = AC_SAVECREDENTIAL_NEVER;    // No save credential
    COnfig.boundaryOffet = 64;                    // Reserve 64 bytes for the user data in EEPROM.
    Config.homeUri = "/index.html"                // Sets home path of the sketch application
    Portal.config(Config);                        // Configure AutoConnect
    Portal.begin();                               // Starts and behaves captive portal

## Something extra

The library presents two PNG icons which can be used to embed a hyperlink to the AutoConnect menu.

- Bar type
- Cog type

To reference the icon, use the AUTOCONNECT_LINK macro in the sketch. It expands into the string literal as an HTML `<a></a>` tag with PNG embedded of the AutoConnect menu hyperlinks. Icon type is specified by the parameter of the macro.

  BAR_32Bars icon, 32x32.
  BAR_48Bars icon, 48x48.
  COG_24Cog icon, 24x24.
  COG_32Cog icon, 32x32.

Usage

    String html = "<html>";
    html += AUTOCONNECT_LINK(BAR_32);
    html += "</html>";
    server.send(200, "text/html", html);