Credential accesses

AutoConnect automatically saves the credentials of the established WiFi connection according to the AutoConnectConfig::autoSave settings. The save destination differs depending on the type of ESP module. In the case of ESP8266, it is the EEPROM, and in the case of ESP32, it is the NVS (Non-volatile storage) partition implemented by the Preferences class.
Sketches can access their stored credentials through a class that is independent of AutoConnect.

Access to saved credentials
Autosave Credential
Move the saving area of EEPROM for the credentials
Save and restore credentials

Access to saved credentials¶

AutoConnect stores the credentials of the established WiFi connection in the flash of the ESP8266/ESP32 module and equips the class to access them from the Sketch. The Sketch can read, write, or erase the credentials using this class as the AutoConnectCredential individually. Refer to section Saved credentials access for details.

Where to store credentials in ESP32 with AutoConnect v1.0.0 or later

Since v1.0.0, credentials are stored in nvs of ESP32. AutoConnect v1.0.0 or later accesses the credentials area using the Preferences class with the arduino esp-32 core. So in ESP32, the credentials are not in the EEPROM, it is in the namespace AC_CREDT of the nvs. See Saved credentials access for details.
In ESP8266, it is saved in EEPROM as is conventionally done.

Autosave Credential¶

In the sketch, you can give an indication of when to save the credentials by setting the following three options of AutoConnectConfig::autoSave:

AC_SAVECREDENTIAL_AUTO : AutoConnect will save a credential when the WiFi connection is established with an access point. Its credential contains BSSID which a connection established access point has.
AC_SAVECREDENTIAL_ALWAYS : AutoConnect will save a credential entered via Configure new AP menu even if a connection attempt has failed. BSSID does not exist in the credentials registered with this option. (will be 0x00) If this credential is selected as a connection candidate, the SSID will be adopted for matching attempts with the target access point even if AUTOCONNECT_APKEY_SSID is not enabled.
AC_SAVECREDENTIAL_NEVER : AutoConnect will not store the credentials even if the connection to the access point is successful. However, the core SDK will save it, so it retains the previously established connection unless you disconnect the ESP module from the connected access point.

AutoConnect       Portal;
AutoConnectConfig Config;
Config.autoSave = AC_SAVECREDENTIAL_NEVER;
Portal.config(Config);
Portal.begin();

Credentials storage location

The location where AutoConnect saves credentials depends on the module type and the AutoConnect library version, also arduino-esp32 core version.

AutoConnect	Arduino core for ESP8266	Arduino core for ESP32
AutoConnect	Arduino core for ESP8266	1.0.2 earlier	1.0.3 later
v0.9.12 earlier	EEPROM	EEPROM (partition)	Not supported
v1.0.0 later	EEPROM	Preferences (nvs) (Can be used EEPROM with turning off AUTOCONNECT_USE_PREFERENCES macro)	Preferences (nvs)

Move the saving area of EEPROM for the credentials¶

By default, the credentials saving area is occupied from the beginning of EEPROM area. ESP8266 Arduino core document says that:

The following diagram illustrates flash layout used in Arduino environment:

|--------------|-------|---------------|--|--|--|--|--|
^              ^       ^               ^     ^
Sketch    OTA update   File system   EEPROM  WiFi config (SDK)

and

EEPROM library uses one sector of flash located just after the SPIFFS.

Also, in ESP32 arduino core 1.0.2 earlier, the placement of the EEPROM area of ESP32 is described in the partition table. So in the default state, the credential storage area used by AutoConnect conflicts with data owned by the user sketch. It will be destroyed together saved data in EEPROM by user sketch and AutoConnect each other. But you can move the storage area to avoid this.

The boundaryOffset in AutoConnectConfig specifies the start offset of the credentials storage area. The default value is 0.

The boundaryOffset ignored with AutoConnect v1.0.0 later on ESP32 arduino core 1.0.3 later

For ESP32 arduino core 1.0.3 and later, AutoConnect will store credentials to Preferences in the nvs. Since it is defined as the namespace dedicated to AutoConnect and separated from the area used for user sketches. Therefore, the boundaryOffset is ignored with the combination of AutoConnect v1.0.0 or later and the arduino-esp32 1.0.3 or later.

The AutoConnectConfig::boundaryOffset setting allows AutoConnect to write its data to EEPROM while preserving custom configuration data. Similarly, when a Sketch writes its own data to EEPROM, it must preserve the data written by AutoConnect.
The EEPROM library for ESP8266 erases the entire flash sector when it writes to any part of the sector. Therefore, when writing data to EEPROM with a sketch that handles the custom data, it is necessary to call EEPROM.begin using a total amount of a custom data size and the saved credentials size.
The following code shows how to use the AutoConnect::getEEPROMUsedSize function to store custom configuration settings in EEPROM without conflicting with AutoConnect's use of that storage.

AutoConnect       portal;
AutoConnectConfig config;

// Defines the custom data should be stored in EEPROM.
typedef struct {
  char  data1[8];
  char  data2[8];
  char  data3[8];
} EEPROM_CONFIG_t;
EEPROM_CONFIG_t eepromConfig;
...
// Declares to reserve the EEPROM_CONFIG_t area for a Sketch using.
config.boundaryOffset = sizeof(eepromConfig);
portal.config(config);
...
strcpy(eepromComfig.data1, "data1");
strcpy(eepromComfig.data2, "data2");
strcpy(eepromComfig.data3, "data3");

// Use getEEPROMUsedSize to access the EEPROM with the appropriate region size.
EEPROM.begin(portal.getEEPROMUsedSize());
EEPROM.put<EEPROM_CONFIG_t>(0, eepromConfig);
EEPROM.commit();
EEPROM.end();
...

Save and restore credentials¶

AutoConnect can save stored credentials to various file systems. It is also possible to restore from those file systems. The file system can be SPIFFS, LittleFS, or SDFS. AutoConnect::saveCredential and AutoConnect::restoreCredential functions allow the sketch to save and restore credentials to files.

Use the AutoConnect::saveCredential function to save AutoConnect credentials. This function bulk outputs while preserving AutoConnect's internal credential data structure, so this output file would be used as an input for restoring by the restoreCredential function. The following code snippet is an example of saving AutoConnect credentials to a file on LittleFS with ESP8266. A subsequent snippet that restores credentials saved by saveCredential with restoreCredential is also shown as an example.

#include <FS.h>
#include <LittleFS.h>

...

AutoConnect portal;

void setup() {
  LittleFS.begin(true);

  if (portal.begin()) {
    portal.saveCredential("/cred", LittleFS);
  }
}

#include <FS.h>
#include <LittleFS.h>

...

AutoConnect portal;
AutoConnectConfig config;

void setup() {
  LittleFS.begin();

  config.autoReconnect = true;
  portal.config(config);
  portal.restoreCredential("/cred", LittleFS);

  portal.begin();
}

The credentials file output by AutoConnect::saveCredential is compatible with ESP8266 and ESP32. The credentials file output by saveCredential is compatible with ESP8266 and ESP32, so you can output the AutoConnect credentials on ESP8266 to a portable SD and input it as AutoConnect credentials running on ESP32. To use SD for saving and restoring credentials, use the saveCredential and restoreCredential functions with template arguments as shown in the code snippet below. In this case, the template argument must specify the class name of the SD file system that is compatible with the ESP module. It is usually SDClass for ESP8266 or fs::SDFS for ESP32.

#include <SPI.h>
#include <SD.h>

...

AutoConnect portal;

void setup() {
  SD.begin();

  if (portal.begin()) {
    portal.saveCredential<SDClass>("/cred", SDFS);   // For ESP8266
    // portal.saveCredential<fs::SDFS>("/credentials", SDFS);  // For ESP32
  }
}

#include <SPI.h>
#include <SD.h>

...

AutoConnect portal;
AutoConnectConfig config;

void setup() {
  SD.begin();

  config.autoReconnect = true;
  portal.config(config);
  portal.restoreCredential<SDClass>("/cred", SDFS);  // For ESP8266
  // portal.restoreCredential<fs::SDFS>("/credentials", SDFS);  // For ESP32

  portal.begin();
}