Merge branch 'patches/v120' into enhance/v120

.travis.yml

@@ -33,6 +33,7 @@ script:
   - buildExampleSketch ConfigIP
   - buildExampleSketch Credential
   - if [[ "$BOARD" =~ "esp32:esp32:" ]]; then buildExampleSketch CreditMigrate; fi
+  - if [[ "$BOARD" =~ "esp8266:esp8266:" ]]; then buildExampleSketch EEPROM; fi
   - buildExampleSketch Elements
   - buildExampleSketch FileUpload
   - buildExampleSketch FSBrowser

examples/EEPROM/EEPROM.ino

@@ -0,0 +1,164 @@
+/*
+  EEPROM.ino, Example for the AutoConnect library.
+  Copyright (c) 2020, Hieromon Ikasamo
+  https://github.com/Hieromon/AutoConnect
+  This software is released under the MIT License.
+  https://opensource.org/licenses/MIT
+
+  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.
+  This example demonstrates how to use the getEEPROMUsedSize() method to
+  store custom configuration settings in EEPROM without conflicting with
+  AutoConnect's use of that storage. (Note: this applies to the ESP8266
+  only, not the ESP32.)
+*/
+
+#ifndef ARDUINO_ARCH_ESP8266
+#error "EEPROM.ino sketch is available for ESP8266 only."
+#endif
+
+#include <ESP8266WiFi.h>
+#include <ESP8266WebServer.h>
+#include <EEPROM.h>
+#include <AutoConnect.h>
+
+ESP8266WebServer  server;
+AutoConnect       portal(server);
+AutoConnectConfig config;
+
+const char AUX_EEPROM_IO[] PROGMEM = R"(
+[
+  {
+    "title": "EEPROM",
+    "uri": "/",
+    "menu": true,
+    "element": [
+      {
+        "name": "data1",
+        "type": "ACInput",
+        "label": "DATA1",
+        "global": true
+      },
+      {
+        "name": "data2",
+        "type": "ACInput",
+        "label": "DATA2",
+        "global": true
+      },
+      {
+        "name": "data3",
+        "type": "ACInput",
+        "label": "DATA3",
+        "global": true
+      },
+      {
+        "name": "write",
+        "type": "ACSubmit",
+        "value": "WRITE",
+        "uri": "/eeprom",
+        "global": true
+      }
+    ]
+  },
+  {
+    "title": "EEPROM",
+    "uri": "/eeprom",
+    "menu": false,
+    "element": [
+      {
+        "name": "data1",
+        "type": "ACText",
+        "format": "DATA1: %s",
+        "posterior": "br",
+        "global": true
+      },
+      {
+        "name": "data2",
+        "type": "ACText",
+        "format": "DATA2: %s",
+        "posterior": "br",
+        "global": true
+      },
+      {
+        "name": "data3",
+        "type": "ACText",
+        "format": "DATA3: %s",
+        "posterior": "br",
+        "global": true
+      }
+    ]
+  }
+]
+)";
+
+// Defines the custom data should be stored in EEPROM.
+typedef struct {
+  char  data1[8];
+  char  data2[8];
+  char  data3[8];
+} EEPROM_CONFIG_t;
+
+String toString(char* c, uint8_t length) {
+  String  r;
+  while (length-- && *c) {
+    r += (isAlphaNumeric(*c) ? String(*c) : String(*c, HEX));
+    c++;
+  }
+  return r;
+}
+
+// Read from EEPROM
+String onEEPROM(AutoConnectAux& page, PageArgument& args) {
+  EEPROM_CONFIG_t eepromConfig;
+
+  EEPROM.begin(sizeof(eepromConfig));
+  EEPROM.get<EEPROM_CONFIG_t>(0, eepromConfig);
+  EEPROM.end();
+
+  page["data1"].value = toString(eepromConfig.data1, sizeof(EEPROM_CONFIG_t::data1));
+  page["data2"].value = toString(eepromConfig.data2, sizeof(EEPROM_CONFIG_t::data2));
+  page["data3"].value = toString(eepromConfig.data3, sizeof(EEPROM_CONFIG_t::data3));
+  return String();
+}
+
+// Write to EEPROM
+String onEEPROMWrite(AutoConnectAux& page, PageArgument& args) {
+  EEPROM_CONFIG_t eepromConfig;
+
+  strncpy(eepromConfig.data1, page["data1"].value.c_str(), sizeof(EEPROM_CONFIG_t::data1));
+  strncpy(eepromConfig.data2, page["data2"].value.c_str(), sizeof(EEPROM_CONFIG_t::data2));
+  strncpy(eepromConfig.data3, page["data3"].value.c_str(), sizeof(EEPROM_CONFIG_t::data3));
+
+  // The actual area size of the EEPROM region to be given to
+  // EEPROM.begin is the sum of the size of the own custom data and
+  // the size of the currently stored AutoConnect credentials.
+  // eg.
+  //   EEPROM.begin(portal.getEEPROMUsedSize())
+  EEPROM.begin(portal.getEEPROMUsedSize());
+  EEPROM.put<EEPROM_CONFIG_t>(0, eepromConfig);
+  EEPROM.commit();
+  EEPROM.end();
+  return String();
+}
+
+void setup() {
+  delay(1000);
+  Serial.begin(115200);
+  Serial.println();
+
+  portal.load(FPSTR(AUX_EEPROM_IO));
+  portal.on("/", onEEPROM);
+  portal.on("/eeprom", onEEPROMWrite);
+
+  // Specifies to shift the AutoConnect credentials with the custom data region size.
+  config.boundaryOffset = sizeof(EEPROM_CONFIG_t);
+  portal.config(config);
+
+  portal.begin();
+}
+
+void loop() {
+  portal.handleClient();
+}

mkdocs/advancedusage.md

@@ -729,6 +729,38 @@ The [**boundaryOffset**](apiconfig.md#boundaryoffset) in [AutoConnectConfig](api
 !!! 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 [boundaryOffset](apiconfig.md#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*](apiconfig.md#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*](api.md#geteepromusedsize) function to store custom configuration settings in EEPROM without conflicting with  AutoConnect's use of that storage.
+
+```cpp hl_lines="13 21"
+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();
+...
+```
+
 ### <i class="fa fa-caret-right"></i> Relocate the AutoConnect home path
 
 A home path of AutoConnect is **/\_ac** by default. You can access from the browser with http://IPADDRESS/\_ac. You can change the home path by revising [**AUTOCONNECT_URI**](https://github.com/Hieromon/AutoConnect/blob/master/src/AutoConnectDefs.h#L69) macro in the include header file as [AutoConnectDefs.h](https://github.com/Hieromon/AutoConnect/blob/master/src/AutoConnectDefs.h).

mkdocs/api.md

@@ -166,7 +166,6 @@ Stops AutoConnect captive portal service. Release ESP8266WebServer/WebServer and
 !!! warning "Attention to end"
     The end function releases the instance of ESP8266WebServer/WebServer and DNSServer. It can not process them after the end function.
 
-
 ### <i class="fa fa-caret-right"></i> disableMenu
 
 ```cpp
@@ -179,6 +178,21 @@ Disable the [AutoConnect menu](menu.md) items specified by the items parameter w
     <dd><span class="apidef">items</span><span class="apidesc">Specify the combined value of **AC_MENUITEM_t** of the items deleting from the AutoConnect menu. It provides the value calculated from the **logical OR** by the AC_MENUITEM_t value of each item. Refer to the [enableMenu](#enablemenu) about AC_MENUITEM_t.</span></dd>
 </dl>
 
+### <i class="fa fa-caret-right"></i> getEEPROMUsedSize
+
+```cpp
+uint16_t getEEPROMUsedSize(void)
+```
+
+Returns the total amount of memory required to hold the AutoConnect credentials and any custom configuration settings stored in EEPROM. The Sketch that writes its own custom data to the EEPROM must call `EEPROM.begin` with this value. 
+<dl class="apidl">
+    <dt>**Return value**</dt>
+    <dd>Total amount size of saved AutoConnect credentials and custom data.</dd>
+</dl>
+
+!!! note "The getEEPROMUsedSize is available for only ESP8266 use"
+    It is available for only ESP8266 use and will return 0 when used with ESP32.
+    
 ### <i class="fa fa-caret-right"></i> handleClient
 
 ```cpp

src/AutoConnect.cpp

@@ -771,6 +771,21 @@ bool AutoConnect::_loadAvailCredential(const char* ssid, const AC_PRINCIPLE_t pr
   return false;
 }
 
+/**
+ *  Get the total amount of memory required to hold the AutoConnect credentials
+ *  and any custom configuration settings stored in EEPROM.
+ *  This function is available only for ESP8266 use.
+ *  @return  Combined size of AutoConnect credentials and custom settings.
+ */
+uint16_t AutoConnect::getEEPROMUsedSize(void) {
+#if defined(ARDUINO_ARCH_ESP8266)
+  AutoConnectCredential credentials(_apConfig.boundaryOffset);
+  return _apConfig.boundaryOffset + credentials.dataSize();
+#elif defined(ARDUINO_ARCH_ESP32)
+  return 0;
+#endif
+}
+
 /**
  *  Disconnect from the AP and stop the AutoConnect portal.
  *  Stops DNS server and flush tcp sending.

src/AutoConnect.h

@@ -233,6 +233,7 @@ class AutoConnect {
   String where(void) const { return _auxUri; }
   inline void enableMenu(const uint16_t items) { _apConfig.menuItems |= items; }
   inline void disableMenu(const uint16_t items) { _apConfig.menuItems &= (0xffff ^ items); }
+  uint16_t getEEPROMUsedSize(void);
 
   /** For AutoConnectAux described in JSON */
 #ifdef AUTOCONNECT_USE_JSON

src/AutoConnectCredential.h

@@ -2,8 +2,8 @@
  *  Declaration of AutoConnectCredential class.
  *  @file AutoConnectCredential.h
  *  @author hieromon@gmail.com
- *  @version  1.1.0
+ *  @version  1.2.0
- *  @date 2019-10-07
+ *  @date 2020-04-22
  *  @copyright  MIT license.
  */
 
@@ -79,6 +79,7 @@ class AutoConnectCredentialBase {
   explicit AutoConnectCredentialBase() : _entries(0), _containSize(0) {}
   virtual ~AutoConnectCredentialBase() {}
   virtual uint8_t entries(void) { return _entries; }
+  virtual uint16_t dataSize(void) const { return sizeof(AC_IDENTIFIER) - 1 + sizeof(uint8_t) + sizeof(uint16_t) + _containSize; }
   virtual bool    del(const char* ssid) = 0;
   virtual int8_t  load(const char* ssid, station_config_t* config) = 0;
   virtual bool    load(int8_t entry, station_config_t* config) = 0;