diff --git a/README.md b/README.md index 42b193b..2e9cfbc 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ These HTML elements that make up the user-owned screen can be easily loaded from ### Quick and easy to equip the OTA update feature ENHANCED w/ v1.0.0 -You can quickly and easily equip the OTA update feature to your sketch and also you can operate the firmware update process via OTA from AutoConnect menu. +You can quickly and easily equip the [OTA update feature](https://hieromon.github.io/AutoConnect/otaupdate.html) to your sketch and also you can operate the firmware update process via OTA from AutoConnect menu. ## Supported hardware @@ -101,8 +101,9 @@ Full documentation is available on https://Hieromon.github.io/AutoConnect, some ## Change log -### [1.0.0] Aug. 13, 2019 +### [1.0.0] Aug. 29, 2019 - Supports AutoConnectUpdate for the OTA update. +- Supports Preferences for saving credentials with ESP32 core 1.0.3 and later. **In ESP32, the credentials stored past in EEPROM will lose**. ### [0.9.12] Aug. 18, 2019 - Fixed missing captive portal notifications on the newer mobile OS client. As a result of this fix, the SoftAP default IP address and gateway have been changed to **172.217.28.1**. (issue #85) diff --git a/mkdocs.yml b/mkdocs.yml index 588cfb4..b6d0e62 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -37,7 +37,7 @@ nav: - 'Custom Web pages w/o JSON': wojson.md - 'Appendix': - 'Inside AutoConnect::begin': lsbegin.md - - 'Saved credentail access': credit.md + - 'Saved credentails access': credit.md - 'File upload handler': acupload.md - 'Custom colorized': colorized.md - 'FAQ' : faq.md diff --git a/mkdocs/advancedusage.md b/mkdocs/advancedusage.md index 6ccf77a..d7225fb 100644 --- a/mkdocs/advancedusage.md +++ b/mkdocs/advancedusage.md @@ -6,7 +6,11 @@ Registering the "not found" handler is a different way than ESP8266WebServer (We ### Access to saved credentials -AutoConnect stores the established WiFi connection in the EEPROM of the ESP8266/ESP32 module and equips the class to access it from the sketch. You can read, write or erase the credentials using this class individually. It's [AutoConnectCredential](credit.md#autoconnectcredential) class which provides the access method to the saved credentials in EEPROM. Refer to section [Saved credentail access](credit.md) for details. +AutoConnect stores the established WiFi connection in the flash of the ESP8266/ESP32 module and equips the class to access it from the sketch. You can read, write or erase the credentials using this class individually. It's [AutoConnectCredential](credit.md#autoconnectcredential) class which provides the access method to the saved credentials in the flash. Refer to section [Saved credentials access](credit.md) for details. + +!!! note "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](credit.md) for details. + In ESP8266, it is saved in EEPROM as is conventionally done. ### Automatic reconnect @@ -14,7 +18,7 @@ When the captive portal is started, SoftAP starts and the STA is disconnected. T The [*WiFiSTAClass::disconnect*](https://github.com/espressif/arduino-esp32/blob/a0f0bd930cfd2d607bf3d3288f46e2d265dd2e11/libraries/WiFi/src/WiFiSTA.h#L46) function implemented in the arduino-esp32 has extended parameters than the ESP8266's arduino-core. The second parameter of WiFi.disconnect on the arduino-esp32 core that does not exist in the [ESP8266WiFiSTAClass](https://github.com/esp8266/Arduino/blob/7e1bdb225da8ab337373517e6a86a99432921a86/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.cpp#L296) has the effect of deleting the currently connected WiFi configuration and its default value is "false". On the ESP32 platform, even if WiFi.disconnect is executed, WiFi.begin() without the parameters in the next turn will try to connect to that AP. That is, automatic reconnection is implemented in arduino-esp32 already. Although this behavior appears seemingly competent, it is rather a disadvantage in scenes where you want to change the access point each time. When explicitly disconnecting WiFi from the Disconnect menu, AutoConnect will erase the AP connection settings saved by arduino-esp32 core. AutoConnect's automatic reconnection is a mechanism independent from the automatic reconnection of the arduino-esp32 core. -If the [**autoReconnect**](apiconfig.md#autoreconnect) option of the [AutoConnectConfig](apiconfig.md) class is enabled, it automatically attempts to reconnect to the disconnected past access point. When the autoReconnect option is specified, AutoConnect will not start SoftAP immediately if the first WiFi.begin fails. It will scan WiFi signal and the same connection information as the detected BSSID is stored in EEPROM as AutoConnect's credentials, explicitly apply it with WiFi.begin and rerun. +If the [**autoReconnect**](apiconfig.md#autoreconnect) option of the [AutoConnectConfig](apiconfig.md) class is enabled, it automatically attempts to reconnect to the disconnected past access point. When the autoReconnect option is specified, AutoConnect will not start SoftAP immediately if the first WiFi.begin fails. It will scan WiFi signal and the same connection information as the detected BSSID is stored in the flash as AutoConnect's credentials, explicitly apply it with WiFi.begin and rerun. ```cpp hl_lines="3" AutoConnect Portal; @@ -24,14 +28,15 @@ Portal.config(Config); Portal.begin(); ``` -An autoReconnect option is available to *AutoConnect::begin* without SSID and pass passphrase. +An autoReconnect option is available to *AutoConnect::begin* without SSID and pass Passphrase. !!! caution "An autoReconnect will work if SSID detection succeeded" An autoReconnect will not effect if the SSID which stored credential to be connected is a hidden access point. ### Auto save Credential -By default, AutoConnect saves the credentials of the established connection in EEPROM. You can disable it with the [**autoSave**](apiconfig.md#autosave) parameter specified by [AutoConnectConfig](apiconfig.md). +By default, AutoConnect saves the credentials of the established connection to the flash. You can disable it with the [**autoSave**](apiconfig.md#autosave) parameter specified by [AutoConnectConfig](apiconfig.md). +See the [Saved credentials access](credit.md) chapter for details on accessing stored credentials. ```cpp hl_lines="3" AutoConnect Portal; @@ -41,8 +46,30 @@ Portal.config(Config); Portal.begin(); ``` -!!! note "In ESP32, the credentials for AutoConnect are not in NVS" - The credentials used by AutoConnect are not saved in NVS on ESP32 module. ESP-IDF saves the WiFi connection configuration to NVS, but AutoConnect stores it on the EEPROM partition. You can find the partition table for default as [default.csv](https://github.com/espressif/arduino-esp32/blob/master/tools/partitions/default.csv) +!!! note "Credentials storage location" + The location where AutoConnect saves credentials depends on the module type and the AutoConnect library version, also arduino-esp32 core version. + + + + + + + + + + + + + + + + + + + +
AutoConnectArduino core
for ESP8266		Arduino core for ESP32
1.0.2 earlier + 1.0.3 later +
v0.9.12 earlierEEPROMEEPROM (partition)Not supported
v1.0.0 laterPreferences (nvs)

(Can be used EEPROM with turning off AUTOCONNECT_USE_PREFERENCES macro)

Preferences (nvs)
### Captive portal start detection @@ -290,10 +317,13 @@ and > EEPROM library uses one sector of flash located [just after the SPIFFS](http://arduino-esp8266.readthedocs.io/en/latest/libraries.html?highlight=SPIFFS#eeprom). -Also, the placement of the EEPROM area of ESP32 is described in the [partition table](https://github.com/espressif/arduino-esp32/blob/master/tools/partitions/default.csv). 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. +Also, in ESP32 arduino core 1.0.2 earlier, the placement of the EEPROM area of ESP32 is described in the [partition table](https://github.com/espressif/arduino-esp32/blob/master/tools/partitions/default.csv). 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**](apiconfig.md#boundaryoffset) in [AutoConnectConfig](apiconfig.md) specifies the start offset of the credentials storage area. The default value is 0. +!!! info "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 boundaryOffet is ignored with the combination of AutoConnect v1.0.0 or later and the arduino-esp32 1.0.3 or later. + ### On-demand start the captive portal If you do not usually connect to WiFi and need to establish a WiFi connection if necessary, you can combine the [**autoRise**](apiconfig.md#autorise) option with the [**immediateStart**](apiconfig.md#immediatestart) option to achieve on-demand connection. This behavior is similar to the [WiFiManager's startConfigPortal](https://github.com/tzapu/WiFiManager#on-demand-configuration-portal) function. In order to do this, you usually configure only with AutoConnectConfig in *setup()* and [*AutoConnect::begin*](api.md#begin) handles in *loop()*. diff --git a/mkdocs/apiconfig.md b/mkdocs/apiconfig.md index 971110a..f4b93ee 100644 --- a/mkdocs/apiconfig.md +++ b/mkdocs/apiconfig.md @@ -42,7 +42,7 @@ Sets IP address for Soft AP in captive portal. When AutoConnect fails the initia ### 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 EEPROM, even if the connection failed by current SSID. +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**
@@ -104,7 +104,8 @@ Specify the location to be redirected after module reset in the AutoConnect menu ### 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. +The default value is 0. +This option is valid only for ESP8266 or ESP32 arduino core 1.0.2 earlier.
**Type**
uint16_t
diff --git a/mkdocs/changelog.md b/mkdocs/changelog.md index f697c2f..7fa48d0 100644 --- a/mkdocs/changelog.md +++ b/mkdocs/changelog.md @@ -1,5 +1,6 @@ -#### [1.0.0] Aug. 19, 2019 +#### [1.0.0] Aug. 29, 2019 - Supports AutoConnectUpdate for the [OTA update](otaupdate.md). +- Supports Preferences for saving credentials with ESP32 core 1.0.3 and later. #### [0.9.12] Aug. 18, 2019 - Fixed missing captive portal notifications on the newer mobile OS client. As a result of this fix, the SoftAP default IP address and gateway have been changed to **172.217.28.1**. diff --git a/mkdocs/credit.md b/mkdocs/credit.md index 5553fdd..53a4ed3 100644 --- a/mkdocs/credit.md +++ b/mkdocs/credit.md @@ -1,9 +1,43 @@ -## Saved credentials in EEPROM +## Saved credentials in the flash -AutoConnect stores the established WiFi connection in the EEPROM of the ESP8266/ESP32 module and equips the class to access it from the sketch. You can read, write or erase the credentials using this class individually. It's [**AutoConnectCredential**](#autoconnectcredential) class which provides the access method to the saved credentials in EEPROM.[^1] +AutoConnect stores the established WiFi connection in the flash memory of the ESP8266/ESP32 module and equips the class to access the credentials from the sketch. You can read, write or erase the credentials using this class individually. It's [**AutoConnectCredential**](#autoconnectcredential) class which provides the access method to the saved credentials in the flash.[^1] [^1]:An example using AutoConnectCredential is provided as [an example](https://github.com/Hieromon/AutoConnect/blob/master/examples/Credential/Credential.ino) of a library sketch to delete saved credentials. +## Credentials storage location + +The location where AutoConnect saves credentials depends on the module type and the AutoConnect library version, also arduino-esp32 core version. In either case, the location is flash memory, but EEPROM and Preferences (in the nvs[^2]) are used depending on the library versions. + + + + + + + + + + + + + + + + + + + + +
AutoConnectArduino core
for ESP8266		Arduino core for ESP32
1.0.2 earlier + 1.0.3 later +
v0.9.12 earlierEEPROMEEPROM (partition)Not supported
v1.0.0 laterPreferences (nvs)

(Can be used EEPROM with turning off AUTOCONNECT_USE_PREFERENCES macro)

Preferences (nvs)
+ +However, sketches do not need to know where to store credentials using the commonly accessible [AutoConnectCredential](#AutoConnectCredential) API. + +If you are using an Arduino core for ESP32 1.0.2 earlier and need to use credentials in EEPROM for backward compatibility, turns off the **AUTOCONNECT_USE_PREFERENCES**[^3] macro definition in `AutoConnectCredentials.h` file. AutoConnect behaves assuming that credentials are stored in EEPROM if `AUTOCONNECT_USE_PREFERENCES` is not defined. + +[^2]:The namespace for Preferences used by AutoConnect is **AC_CREDT**. +[^3]:Available only for AutoConnect v1.0.0 and later. + ## AutoConnectCredential ### Include header @@ -18,14 +52,14 @@ AutoConnect stores the established WiFi connection in the EEPROM of the ESP8266/ AutoConnectCredential(); ``` -AutoConnectCredential default constructor. The default offset value is 0. If the offset value is 0, the credential area starts from the top of the EEPROM. AutoConnect sometimes overwrites data when using this area with user sketch. +AutoConnectCredential default constructor. The default offset value is 0. In ESP8266 or ESP32 with arduino core 1.0.2 earlier, if the offset value is 0, the credential area starts from the top of the EEPROM. If you use this area in a user sketch, AutoConnect may overwrite that data. ```cpp AutoConnectCredential(uint16_t offset); ```
**Parameter**
-
offsetSpecies offset from the top of the EEPROM for the credential area together. The offset value is from 0 to the flash sector size.
+
offsetSpecies offset from the top of the EEPROM for the credential area together. The offset value is from 0 to the flash sector size. This parameter is ignored for AutoConnect v1.0.0 or later with arduino-esp32 core 1.0.3 or later.
### Public member functions @@ -112,7 +146,7 @@ Delete a credential the specified SSID. uint8_t ent = credential.entries(); while (ent--) { - credential.load((int8_t)0, &config); + credential.load(0, &config); credential.del((const char*)&config.ssid[0]); } } @@ -141,9 +175,9 @@ struct station_config { ### The credential entry -A data structure of the credential saving area in EEPROM as the below. [^2] +A data structure of the credential saving area in EEPROM as the below. [^4] -[^2]: +[^4]: There may be 0xff as an invalid data in the credential saving area. The 0xff area would be reused. | Byte offset | Length | Value | diff --git a/mkdocs/index.md b/mkdocs/index.md index 300a3f7..0e2e6f4 100644 --- a/mkdocs/index.md +++ b/mkdocs/index.md @@ -19,7 +19,7 @@ Easy implementing the Web interface constituting the WLAN for ESP8266/ESP32 WiFi ### Store the established connection -The connection authentication data as credentials are saved automatically in EEPROM of ESP8266/ESP32 and You can select the past SSID from the [AutoConnect menu](menu.md). +The connection authentication data as credentials are saved automatically in the flash of ESP8266/ESP32 and You can select the past SSID from the [AutoConnect menu](menu.md). ### Easy to embed in @@ -88,6 +88,9 @@ Install third-party platform using the *Boards Manager* of Arduino IDE. Package Also, to apply AutoConnect to ESP32, the [arduino-esp32 core](https://github.com/espressif/arduino-esp32) provided by Espressif is needed. Stable 1.0.1 or required and the [latest release](https://github.com/espressif/arduino-esp32/releases/latest) is recommended. Install third-party platform using the *Boards Manager* of Arduino IDE. You can add multiple URLs into *Additional Board Manager URLs* field, separating them with commas. Package URL is https://dl.espressif.com/dl/package_esp32_index.json for ESP32. +!!! info "Arduino core for ESP32 1.0.3 or later" + For ESP32, AutoConnect v1.0.0 later is required for arduino-esp32 1.0.3 or later. + Additional library (Required) The [PageBuilder](https://github.com/Hieromon/PageBuilder) library to build HTML for ESP8266WebServer is needed. diff --git a/mkdocs/menu.md b/mkdocs/menu.md index ed40d93..308665e 100644 --- a/mkdocs/menu.md +++ b/mkdocs/menu.md @@ -15,7 +15,7 @@ The AutoConnect menu appears when you access the **AutoConnect root path**. It i Currently, AutoConnect supports four menus. Undermost menu as "HOME" returns to the home path of its sketch. - **Configure new AP**: Configure SSID and Password for new access point. -- **Open SSIDs**: Opens the past SSID which has been established connection from EEPROM. +- **Open SSIDs**: Opens the past SSID which has been established connection from the flash. - **Disconnect**: Disconnects current connection. - **Reset...**: Rest the ESP8266/ESP32 module. - **HOME**: Return to user home page. @@ -31,7 +31,7 @@ Enter SSID and Passphrase and tap "**apply**" to starts WiFi connection. ## Open SSIDs -Once it was established WiFi connection, its SSID and password will be saved in EEPROM of ESP8266/ESP32 automatically. The **Open SSIDs** menu reads the saved SSID credentials from the EEPROM. The stored credential data are listed by the SSID as shown below. Its label is a clickable button. Tap the SSID button, starts WiFi connection it. +Once it was established WiFi connection, its SSID and password will be saved in the flash of ESP8266/ESP32 automatically. The **Open SSIDs** menu reads the saved SSID credentials from the flash. The stored credential data are listed by the SSID as shown below. Its label is a clickable button. Tap the SSID button, starts WiFi connection it.