Skip to content

Settings and controls for network and WiFi

AutoConnect allows you to make the static configuration of SoftAP at runtime. Its configuration includes the identification information on the network such as the IP address and the access path of the Web page handled by AutoConnect etc. In addition, the mDNS service allows SoftAP to be accessed by hostname on the local network.
The configuration settings for the network that can be set by AutoConnect is as follows:

404 handler

AutoConnect cannot allow the Sketch registers the "Not-found" handler (404-handler) to the ESP8266WebServer natively. AutoConnect traps Not-found handler of the ESP8266WebServer for its own page processing. If the Sketch overrides the Not-found handler, AutoConnect will miss the opportunity to control the HTTP session and becomes unresponsive to the menu.
Registering the Not-found handler is a different method than for ESP8266WebServer, use AutoConnect::onNotFound. This restriction applies to the WebServer for ESP32 as well.

Assign user sketch's home path

HOME for returning to the user's sketch homepage will display at the bottom of the AutoConnect menu. It could be set using the AutoConnect::home function.

The Sketch HOME path is closely related to the bootUri that specifies the access path on module restart. AutoConnect has the following three parameters concerning control the URIs:

The definition of HOME Behavior Specified by Default value Possible value
ROOT of AutoConnect Default for AC_ONBOOTURI_ROOT #define AUTOCONNECT_URI in AutoConnectDefs.h /_ac URI string
HOME for Application-specific Listed on the menu list as HOME
Also, It may be linked from the menu title and is redundant with the HOME menu item.
eg. Case of bootURI = AC_ONBOOTURI_HOME		 AutoConnectConfig::homeURI / URI string
Which page loads at the boot time, ROOT or HOME Appears after module reboot by RESET button with AutoConnect menu AutoConnectConfig::bootURI AC_ONBOOTURI_ROOT AC_ONBOOTURI_HOME
Which page appears at the captive portal, ROOT or HOME Auto pop-up AutoConnectConfig::bootURI AC_ONBOOTURI_ROOT AC_ONBOOTURI_HOME

Change SSID and Password for SoftAP

An esp8266ap is default SSID name for SoftAP of captive portal and password is 12345678 for ESP8266. Similarly, esp32ap and 12345678 for ESP32. You can change both by setting apid and psk.

AutoConnect portal;
AutoConnectConfig config;

void setup() {
 config.apid = "ap_portal";
  config.psk  = "new_password";
  portal.config(config);
  portal.begin();
}

Also, you can specify the SSID, password for SoftAP with the constructor of the AutoConnectConfig as below.

AutoConnect portal;
AutoConnectConfig config("ap_portal", "new_password");

void setup() {
  portal.config(config);
  portal.begin();
}

You can also assign no password to SoftAP launched as a captive portal. Assigning a null string as String("") to AutoConnectConfig::psk does not require a password when connecting to SoftAP.
But this method is not recommended. The broadcast radio of SSID emitted from SoftAP will leak and reach several tens of meters.

Combination with mDNS

With mDNS library, you can access to ESP8266 by name instead of IP address after connection. The Sketch can start the MDNS responder after AutoConnect::begin.

#include <ESP8266WiFi.h>
#include <ESP8266mDNS.h>
#include <ESP8266WebServer.h>
AutoConnect Portal;
void setup() {
  if (Portal.begin()) {
    if (MDNS.begin("esp8266")) {
      MDNS.addService("http", "tcp", 80);
    }
  }
}

void loop() {
  Portal.handleClient();
}

Make SSID of SoftAP unique

You can change SoftAP's SSID and password programmatically when the captive portal starts up. By using chip specific ID of esp8266/esp32 you can make SSID of SoftAP unique. SSID and password for SoftAP is AutoConnectConfig::apid and AutoConnectConfig::psk.

AutoConnect       portal;
AutoConnectConfig acConfig;

acConfig.apid = "ESP-" + String(ESP.getChipId(), HEX);
aConfig.psk = YOUR_PASSWORD;
portal.config(acConfig);
portal.begin();

Obtaining chip ID for ESP32

acConfig.apid = "ESP-" + String((uint32_t)(ESP.getEfuseMac() >> 32), HEX);

Relocate the AutoConnect home path

A home path of AutoConnect is /_ac by default. You can access from the browser with http://IPADDRESS_OF_ESP_MODULE/_ac. You can change the home path by revising AUTOCONNECT_URI macro in AutoConnectDefs.h header file.

#define AUTOCONNECT_URI         "/_ac"

SoftAP access point IP settings

AutoConnect will activate SoftAP at failed the 1st-WiFi.begin. Its SoftAP settings are stored in AutoConnectConfig as the following parameters. The Sketch could be configured SoftAP using these parameters, refer the AutoConnectConfig API for details.

AutoConnectConfig member Settings for Defined symbol Initial value
apip SoftAP IP address AUTOCONNECT_AP_IP 172.217.28.1
gateway Gateway IP address AUTOCONNECT_AP_GW 172.217.28.1
netmask Subnet mask for the SoftAP AUTOCONNECT_AP_NM 255.255.255.0
channel WiFi channel for the SoftAP AUTOCONNECT_AP_CH 1
hidden Hide the SoftAP false

Static IP assignment as a client

It is possible to assign a static IP Address to ESP8266/ESP32 in STA mode.1 By default DHCP is enabled and it becomes the IP address assigned by the DHCP server with WiFi.begin.

These settings are made via AutoConnectConfig as in the case of SoftAP settings. To assign a static IP to ESP8266/ESP32 with WIFI_STA, the following parameters are required:

AutoConnectConfig member Settings for Initial value
staip Station IP address 0.0.0.0
staGateway Gateway address for the station 0.0.0.0
staNetmask Subnet mask for the the station 0.0.0.0
dns1 Primary DNS server IP address 0.0.0.0
dns2 Secondary DNS server IP address 0.0.0.0

The above parameters must be set using AutoConnect::config prior to AutoConnect::begin call as following:

AutoConnect        portal;
AutoConnectConfig  Config;
Config.staip = IPAddress(192, 168, 1, 10);
Config.staGateway = IPAddress(192, 168, 1, 1);
Config.staNetmask = IPAddress(255, 255, 255, 0);
Config.dns1 = IPAddress(192,168,1,1);
portal.config(Config);
portal.begin();

Static IP preservation

Prioritizing the station IP configuration specified in AutoConnectConfig over the existing configuration must be accompanied by an explicit indication via the AutoConnectConfig::preserveIP. The AutoConnectConfig::preserveIP setting allows AutoConnect to override existing credentials applied at reconnecting with static IP assignments made with the AutoConnectConfig::staip, AutoConnectConfig::staGateway, and AutoConnectConfig::staNetmask settings. The following sketch shows a use case where the preserveIP setting can override an existing static IP configuration.

AutoConnect portal;
AutoConnectConfig config;

void setup() {
  // If the connection to the last established AP fails, attempt to
  // connect to the nearest AP using known credentials.
  config.autoReconnect = true;

  // Apply the following static IP configuration to reconnect.
  config.staip = IPAddress(192, 168, 1, 10);
  config.staGateway = IPAddress(192, 168, 1, 1);
  config.staNetmask = IPAddress(255, 255, 255, 0);
  config.dns1 = IPAddress(192, 168, 1, 1);

  // The above settings take precedence over the IP settings of the
  // stored credentials.
  // If this value is left false, the station IP configuration contained
  // in the stored credentials takes precedence.
  config.preserveIP = true;

  portal.config(config);
  portal.begin();
}

void loop() {
  portal.handleClient();
}

Also, an example sketch with UI for static IP configuration using custom web pages is included in the AutoConnect repository as ConfigIP.ino. This example is useful for overwriting stored IP settings with new IP settings entered from the UI.

Background on the need for preserveIP indication

By default, AutoConnectConfig::autoReconnect restores IP settings along with a credential. So even if the sketch explicitly specifies the static IP settings with AutoConnectConfig, there are cases where they will not be applied upon reconnection.

Station hostname

AutoConnectConfig::hostName assigns a station DHCP hostname to the ESP module. The hostname must satisfy RFC952 compliant and meet the following restrictions:

  • Up to 24 characters
  • Only the alphabet (a-z, A-Z), digits (0-9), minus sign (-)
  • No '-' as last character

  1. Static IP address assignment is available from version 0.9.3. ↩