FAQ

If you can access the AutoConnect root path as http://ESP8266IPADDRESS/_ac from browser, probably the sketch uses ESP8266WebServer::handleClient() without AutoConnect::handleRequest().
For AutoConnect menus to work properly, call AutoConnect::handleRequest() after ESP8266WebServer::handleClient() invoked, or use AutoConnect::handleClient(). AutoConnect::handleClient() is equivalent ESP8266WebServer::handleClient combined AutoConnect::handleRequest().

An esp8266ap as SoftAP was connected but Captive portal does not start.¶

Captive portal detection could not be trapped. It is necessary to disconnect and reset ESP8266 to clear memorized connection data in ESP8266. Also, It may be displayed on the smartphone if the connection information of esp8266ap is wrong. In that case, delete the connection information of esp8266ap memorized by the smartphone once.

Connection lost immediately after establishment with AP¶

A captive portal is disconnected immediately after the connection establishes with the new AP. This is a known problem of ESP32, and it may occur when the following conditions are satisfied at the same time.

SoftAP channel on ESP32 and the connecting AP channel you specified are different. (The default channel of SoftAP is 1.)
NVS had erased by erase_flash causes the connection data lost. The NVS partition has been moved. Never connected to the AP in the past.
There are receivable multiple WiFi signals which are the same SSID with different channels using the WiFi repeater etc. (This condition is loose, it may occur even if there is no WiFi repeater.)
Or the using channel of the AP which established a connection is congested with the radio signal on the same band. (If the channel crowd, connections to known APs may also fail.)

Other possibilities

The above conditions are not absolute. It results from my investigation, and other conditions may exist.

To avoid this problem, try changing the channel.

ESP32 hardware equips only one RF circuitry for WiFi signal. At the AP_STA mode, ESP32 as an AP attempts connect to another AP on another channel while keeping the connection with the station then the channel switching will occur causes the station may be disconnected. But it may not be just a matter of channel switching causes ESP8266 has the same constraints too. It may be a problem with AutoConnect or the arduino core or SDK issue. This problem will persist until a specific solution.

Does not appear esp8266ap in smartphone.¶

Maybe it is successfully connected at the first WiFi.begin. ESP8266 remembers the last SSID successfully connected and will use at the next. It means SoftAP will only start up when the first WiFi.begin() fails.

The saved SSID would be cleared by WiFi.disconnect() with WIFI_STA mode. If you do not want automatic reconnection, you can erase the memorized SSID with the following simple sketch.

#include <ESP8266WiFi.h>

void setup() {
  delay(1000);
  Serial.begin(115200);
  WiFi.mode(WIFI_STA);
  delay(100);
  WiFi.begin();
  if (WiFi.waitForConnectResult() == WL_CONNECTED) {
    WiFi.disconnect();
    while (WiFi.status() == WL_CONNECTED)
      delay(100);
  }
  Serial.println("WiFi disconnected.");
}

void loop() {
  delay(1000);
}

You can interactively check the WiFi state of ESP8266.

Please try ESPShaker. It is ESP8266 interactive serial command processor.

Does not response from /_ac.¶

Probably WiFi.begin failed with the specified SSID. Activating the debug printing will help you to track down the cause.

How change esp8266ap for SSID name in Captive portal?¶

You can change both by using AutoConnectConfig::apid and AutoConnectConfig::psk. Refer to section Change SSID and Password for SoftAP in Advanced usage.

How change HTTP port?¶

HTTP port number is defined as a macro in AutoConnectDefs.h header file. You can change it directly with several editors and must re-compile.

#define AUTOCONNECT_HTTPPORT    80

Hang up after Reset?¶

If ESP8266 hang up after reset by AutoConnect menu, perhaps manual reset is not yet. Especially if it is not manual reset yet after uploading the sketch, the boot mode will stay 'Uart Download'. There is some discussion about this on the Github's ESP8266 core: https://github.com/esp8266/Arduino/issues/1017

If you received the following message, the boot mode is still sketch uploaded. It needs to the manual reset once.

ets Jan  8 2013,rst cause:2, boot mode:(1,6) or (1,7)
ets Jan  8 2013,rst cause:4, boot mode:(1,6) or (1,7)
wdt reset

The correct boot mode for starting the sketch is (3, x).

ESP8266 Boot Messages

It is described by ESP8266 Non-OS SDK API Reference, section A.5.

Messages	Description
rst cause	1: power on 2: external reset 4: hardware watchdog reset
boot mode (the first parameter)	1: ESP8266 is in UART-down mode (and downloads firmware into flash). 3: ESP8266 is in Flash-boot mode (and boots up from flash).

How erase the credentials saved in EEPROM?¶

Make some sketches for erasing the EEPROM area, or some erasing utility is needed. You can prepare the sketch to erase the saved credential with AutoConnectCredential. The AutoConnectCrendential class provides the access method to the saved credential in EEPROM and library source file is including it.

A class description of AutoConnectCredential is follows.

Include header¶

#include <AutoConnectCredential.h>

Constructor¶

AutoConnectCredential();

AutoConnectCredential default constructor. The default offset value is 0. If the offset value is 0, the credential storage area starts from the top of the EEPROM. AutoConnect sometimes overwrites data when using this area with user sketch.

AutoConnectCredential(uint16_t offset);

Specify offset from the top of the EEPROM for the credential storage area together. The offset value is from 0 to the flash sector size.

Public member functions¶

uint8_t entries()
Returns number of entries as contained credentials.
int8_t load(const char* ssid, struct station_config* config)
Load a credential entry specified ssid to config. Returns -1 as unsuccessfully loaded.
bool load(int8_t entry, struct station_config* config)
Load a credential entry to config. The entry parameter specify to index of the entry.
bool save(const struct station_config* config)
Save a credential entry stored in config to EEPROM. Returns the true as succeeded.
bool del(const char* ssid)
Delete a credential entry specified ssid. Returns the true as successfully deleted.

Data structures¶

station_config
A structure is included in the ESP8266 SDK. You can use it in the sketch like as follows.

extern "C" {
#include <user_interface.h>
}

struct station_config {
    uint8 ssid[32];
    uint8 password[64];
    uint8 bssid_set;
    uint8 bssid[6];
};

EEPROM data structure
A data structure of the credential saving area in EEPROM as the below. ¹

Byte offset	Length	Value
0	8	AC_CREDT
8	1	Number of contained entries (uint8_t)
9	2	Container size, excluding size of AC_CREDT and size of the number of entries(width for uint16_t type).
11	variable	SSID terminated by 0x00. Max length is 32 bytes.
variable	variable	Password plain text terminated by 0x00. Max length is 64 bytes.
variable	6	BSSID
variable		Contained the next entries. (Continuation SSID+Password+BSSID)
variable	1	0x00. End of container.

Hint

With the ESPShaker, you can access EEPROM interactively from the serial monitor, and of course you can erase saved credentials.

Link button to AutoConnect menu can be embedded into Sketch's web page. The root path of the menu is /_ac by default and embed the following <a></a> tag in the generating HTML.

<a style="background-color:SteelBlue; display:inline-block; padding:7px 13px; text-decoration:none;" href="/_ac">MENU</a>

How much memory does AutoConnect consume?¶

Sketch size¶

It increases about 53K bytes compared to the case without AutoConnect. A sketch size of the most simple example introduced in the Getting started is about 330K bytes. (270K byte without AutoConnect)

Heap size¶

It consumes about 2K bytes in the static and about 12K bytes are consumed at the moment when menu executed.

Because AutoConnect does not send a login success response to the captive portal requests from the smartphone. The login success response varies iOS, Android and Windows. By analyzing the request URL of different login success inquiries for each OS, the correct behavior can be implemented, but not yet. Please resets ESP8266 from the AutoConnect menu.

I cannot see the custom Web page.¶

If the sketch is correct, a JSON syntax error may have occurred. In this case, activate the AC_DEBUG and rerun. If you take the message of JSON syntax error, the Json Assistant helps syntax checking. This online tool is provided by the author of ArduinoJson and is most consistent for the AutoConnect.

Submit element in a custom Web page does not react.¶

Is there the AutoConnectElements element named SUBMIT in the custom Web page? (case sensitive ignored) AutoConnect does not rely on the input type=submit element for the form submission and uses HTML form element submit function instead. So, the submit function will fail if there is an element named 'submit' in the form. You can not use SUBMIT as the element name of AutoConnectElements in a custom Web page that declares the AutoConnectSubmit element.

Still, not stable with my sketch.¶

If AutoConnect behavior is not stable with your sketch, you can try the following measures.

1. Change WiFi channel¶

Both ESP8266 and ESP32 can only work on one channel at any given moment. This will cause your station to lose connectivity on the channel hosting the captive portal. If the channel of the AP which you want to connect is different from the SoftAP channel, the operation of the captive portal will not respond with the screen of the AutoConnect connection attempt remains displayed. In such a case, please try to configure the channel with AutoConnectConfig to match the access point.

AutoConnect portal;
AutoConnectConfig config;

config.channel = 3;     // Specifies a channel number that matches the AP
portal.config(config);  // Apply channel configurration
portal.begin();         // Start the portal

Channel selection guide

Espressif Systems has released a channel selection guide.

2. Change the arduino core version¶

I recommend change installed an arduino core version to the upstream when your sketch is not stable with AutoConnect on each board.

with ESP8266 arduino core¶

You can select the lwIP variant to contribute for the stable behavior. The lwIP v2 Lower memory option of Arduino IDE for core version 2.4.2 is based on the lwIP-v2. On the other hand, the core version 2.5.0 upstream is based on the lwIP-2.1.2 stable release.

You can select the option from Arduino IDE as Tool menu, if you are using ESP8266 core 2.5.0. It can be select lwIP v2 Lower Memory option. (not lwIP v2 Lower Memory (no features)) It is expected to improve response performance and stability.

with ESP32 arduino core¶

The arduino-esp32 is still under development. It is necessary to judge whether the problem cause of the core or AutoConnect. Trace the log with the esp32 core and the AutoConnect debug option enabled for problem diagnosis and please you check the issue of arduino-esp32. The problem that your sketch possesses may already have been solved.

3. Turn on the debug log options¶

To fully enable for the AutoConnect debug logging options, change the following two files.

AutoConnectDefs.h

#define AC_DEBUG

PageBuilder.h ²

#define PB_DEBUG

4. Reports the issue to AutoConnect Github repository¶

If you can not solve AutoConnect problems please report to Issues. And please make your question comprehensively, not a statement. Include all relevant information to start the problem diagnostics as follows:³

I will make efforts to solve as quickly as possible. But I would like you to know that it is not always possible.

Thank you.

There may be 0xff as an invalid data in the credential saving area. The 0xff area would be reused. ↩
PageBuilder.h exists in the libraries/PageBuilder/src directory under your sketch folder. ↩
Without this information, the reproducibility of the problem is reduced, making diagnosis and analysis difficult. ↩

FAQ

After connected, AutoConnect menu performs but no happens.¶

An esp8266ap as SoftAP was connected but Captive portal does not start.¶

Connection lost immediately after establishment with AP¶

Does not appear esp8266ap in smartphone.¶

Does not response from /_ac.¶

How change esp8266ap for SSID name in Captive portal?¶

How change HTTP port?¶

Hang up after Reset?¶

How erase the credentials saved in EEPROM?¶

Include header¶

Constructor¶

Public member functions¶

Data structures¶

How locate the link button to the AutoConnect menu?¶

How much memory does AutoConnect consume?¶

Sketch size¶

Heap size¶

I cannot see the custom Web page.¶

Submit element in a custom Web page does not react.¶

Still, not stable with my sketch.¶

1. Change WiFi channel¶

2. Change the arduino core version¶

with ESP8266 arduino core¶

with ESP32 arduino core¶

3. Turn on the debug log options¶

4. Reports the issue to AutoConnect Github repository¶

FAQ

After connected, AutoConnect menu performs but no happens.¶

An esp8266ap as SoftAP was connected but Captive portal does not start.¶

Connection lost immediately after establishment with AP¶

Does not appear esp8266ap in smartphone.¶

Does not response from /_ac.¶

How change esp8266ap for SSID name in Captive portal?¶

How change HTTP port?¶

Hang up after Reset?¶

How erase the credentials saved in EEPROM?¶

Include header¶

Constructor¶

Public member functions¶

Data structures¶

How locate the link button to the AutoConnect menu?¶

How much memory does AutoConnect consume?¶

Sketch size¶

Heap size¶

I cannot complete to Wi-Fi login from smartphone.¶

I cannot see the custom Web page.¶

Submit element in a custom Web page does not react.¶

Still, not stable with my sketch.¶

1. Change WiFi channel¶

2. Change the arduino core version¶

with ESP8266 arduino core¶

with ESP32 arduino core¶

3. Turn on the debug log options¶

4. Reports the issue to AutoConnect Github repository¶