From f21f57d4b909a4540bea06655aef9b88e5d1b992 Mon Sep 17 00:00:00 2001 From: Hieromon Ikasamo Date: Wed, 22 Feb 2023 18:55:00 +0900 Subject: [PATCH] Deploy for #581 --- docs/api.html | 22 ++++++++++ docs/apiaux.html | 5 +++ docs/images/menu_ondemand.png | Bin 0 -> 88449 bytes docs/menu.html | 78 +++++++++++++++++++++++++++++++-- docs/search/search_index.json | 2 +- docs/sitemap.xml | 80 +++++++++++++++++----------------- docs/sitemap.xml.gz | Bin 484 -> 483 bytes 7 files changed, 142 insertions(+), 45 deletions(-) create mode 100644 docs/images/menu_ondemand.png diff --git a/docs/api.html b/docs/api.html index de19bf23..fb047ae8 100644 --- a/docs/api.html +++ b/docs/api.html @@ -810,6 +810,13 @@ end + + +
  • + + getConfig + +
  • @@ -1458,6 +1465,13 @@ end +
    • + +
  • + + getConfig + +
  • @@ -1890,6 +1904,14 @@

    endAttention to end

    The end function releases the instance of ESP8266WebServer/WebServer and DNSServer. It can not process them after the end function.

    +

    getConfig

    +

    + +
    AutoConnectConfig& getConfig(void)
+
    +

    Get the current AutoConnectConfig values held by AutoConnect.

    +
    Return value
    +
    A reference to an AutoConnectConfig instance retained by AutoConnect. This reference reflects the actual values captured by the AutoConnect::config function, unlike the AutoConnectConfig value declared in the sketch.

    getEEPROMUsedSize

    diff --git a/docs/apiaux.html b/docs/apiaux.html index b2045dcd..3e990b8f 100644 --- a/docs/apiaux.html +++ b/docs/apiaux.html @@ -1619,6 +1619,11 @@

    on

    void on(const AuxHandlerFunctionT handler, const AutoConnectExitOrder_t order = AC_EXIT_AHEAD)
    diff --git a/docs/images/menu_ondemand.png b/docs/images/menu_ondemand.png new file mode 100644 index 0000000000000000000000000000000000000000..b08e41997c190f70a7d1fc4e1d84ab23e9efe5f0 GIT binary patch literal 88449 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 z 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 literal 0 HcmV?d00001 diff --git a/docs/menu.html b/docs/menu.html index 4b7e142a..72320afb 100644 --- a/docs/menu.html +++ b/docs/menu.html @@ -359,6 +359,19 @@ Applying the active menu items + +
  • @@ -1201,6 +1214,19 @@ Applying the active menu items + +
  • @@ -1278,7 +1304,7 @@

    Reset...state of GPIO0 is important. Since this depends on the circuit implementation for each module, not every module will be rebooted normally. See also FAQ.

    Custom menu items

    -

    If the Sketch has custom Web pages, the AutoConnect menu lines them up with the AutoConnect's items. Details for Custom Web pages in AutoConnect menu.

    +

    If the Sketch has custom Web pages, the AutoConnect menu lines them up with the AutoConnect's items. Details for Custom Web pages in AutoConnect menu.

    Update

    If you specify AutoConnectConfig::ota to import the OTA update feature into Sketch, an item will appear in the menu list as Update.

    @@ -1301,7 +1327,7 @@

    Applying the portal.config(config); }

    -

    The next is another way to achieve the same effect.

    +

    Following code snippet is another way to achieve the same effect.

    AutoConnect portal;
 
 void setup() {
@@ -1309,9 +1335,50 @@ 
     Applying the
   portal.config(config);
 }
    -

    The result of executing the above Sketch is as below:

    +

    Here is the result of running the above sketch:

    -

    Details for AutoConnectConfig::menuItems.

    +

    AutoConnectConfig::menuItems section has more details.

    +

    AutoConnect shows and hides menu items when AutoConnect::begin is executed and when AutoConnect::handleClient is executed in a loop function. You can dynamically change the available menu items during the loop() by setting the show/hide items before executing those functions with AutoConnect::enableMenu and AutoConnect::disableMenu.

    +

    The current menu item settings held by AutoConnectConfig can be retrieved with the AutoConnect::getConfig function, and the code snippet to reconfigure menu items based on the getConfig return value is as follows:

    +

    Enable OTA menu on demand using an external switch connected to a GPIO.

    +

    +
    const int externalSwitch = 5;  // Assign the OTA activation switch to D1 (GPIO5).
+AutoConnect portal;
+AutoConnectConfig config;
+
+void setup() {
+  // The logic level of the external switch assumes active LOW.
+  // Note: A said switch is an alternate and must retain its state.
+  pinMode(externalSwitch, INPUT_PULLUP);
+
+  // Set up OTA, but hide the Update item from the menu list until an external
+  // switch is pressed.
+  config.ota = AC_OTA_BUILTIN;
+  portal.config(config);
+  portal.disableMenu(AC_MENUITEM_UPDATE);
+  portal.begin(); 
+}
+
+void loop() {
+  // Use AutoConnect::getConfig to obtain the current AutoConnectConfig values
+  // and indicate the display state of an Update item.
+  bool  menuUpdate = portal.getConfig().menuItems & AC_MENUITEM_UPDATE;
+
+  // Hides the Update item from the menu list depending on the state of the switch.
+  if (digitalRead(externalSwitch) == LOW && !(menuUpdate)) {
+    portal.enableMenu(AC_MENUITEM_UPDATE);
+  }
+  else {
+    portal.disableMenu(AC_MENUITEM_UPDATE);
+  }
+
+  portal.handleClient();
+}
+
    +
    +

    enableMenu/disableMenu has no effect for custom web page items

    +

    AutoConnect::enableMenu and disableMenu functions are not enabled to show/hide menu items for custom web pages. They only work on AutoConnect's built-in pages2. Use the AutoConnectAux::menu and AutoConnectAux::isMenu functions to show/hide menu items for custom web pages. For more information, see Custom Web pages in AutoConnect menu section.

    +

    Attaching to AutoConnect menu

    The AutoConnect menu can contain your sketch's web pages as extra items as a custom. It works for HTML pages implemented by the ESP8266WebServer::on handler or the WebServer::on handler for ESP32. That is, you can make them invoke the legacy web pages from the AutoConnect menu. The below screen-shot is the result of adding an example sketch for the ESP8266WebServer library known as FSBrowser to the AutoConnect menu item. It can add Edit and List items with little modification to the legacy sketch code.

    @@ -1323,6 +1390,9 @@

    Attaching to A

  • AutoConnect does not check the syntax and validity of the entered IP address. If the entered static IPs are incorrect, it cannot connect to the access point. ↩

    • +
  • +

    AutoConnect built-in pages are predefined by the AC_MENUITEM_t enum value. ↩

    +
    • diff --git a/docs/search/search_index.json b/docs/search/search_index.json index e3e08038..c13dc2bf 100644 --- a/docs/search/search_index.json +++ b/docs/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"index.html","title":"AutoConnect for ESP8266/ESP32","text":"

    An Arduino library for ESP8266/ESP32 WLAN configuration at run time with web interface.

    "},{"location":"index.html#overview","title":"Overview","text":"

    To the dynamic configuration for joining to WLAN with SSID and PSK accordingly. It an Arduino library united with ESP8266WebServer class for ESP8266 or WebServer class for ESP32. Easy implementing the Web interface constituting the WLAN for ESP8266/ESP32 WiFi connection. With this library to make a Sketch easily which connects from ESP8266/ESP32 to the access point at runtime by the web interface without hard-coded SSID and password.

    "},{"location":"index.html#no-need-pre-coded-ssid-password","title":"No need pre-coded SSID & password","text":"

    It is no needed hard-coding in advance the SSID and Password into the Sketch to connect between ESP8266/ESP32 and WLAN. You can input SSID & Password from a smartphone via the web interface at runtime.

    "},{"location":"index.html#simple-usage","title":"Simple usage","text":"

    AutoConnect control screen will be displayed automatically for establishing new connections. It aids by the captive portal when vested the connection cannot be detected.By using the AutoConnect menu, to manage the connections convenient.

    "},{"location":"index.html#store-the-established-connection","title":"Store the established connection","text":"

    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.

    "},{"location":"index.html#easy-to-embed-in","title":"Easy to embed in","text":"

    AutoConnect can be placed easily in your Sketch. It's \"begin\" and \"handleClient\" only.

    "},{"location":"index.html#lives-with-your-sketches","title":"Lives with your Sketches","text":"

    The Sketches which provide the web page using ESP8266WebServer there is, AutoConnect will not disturb it. AutoConnect can use an already instantiated ESP8266WebServer object, or itself can assign it. This effect also applies to ESP32. The corresponding class for ESP32 will be the WebServer.

    "},{"location":"index.html#easy-to-add-the-custom-web-pages-enhanced-wv097","title":"Easy to add the custom Web pages ENHANCED w/v0.9.7","text":"

    You can easily add your owned web pages that can consist of representative HTML elements and invoke them from the menu. Further it possible importing the custom Web pages declarations described with JSON which stored in PROGMEM, SPIFFS, or SD.

    "},{"location":"index.html#quick-and-easy-to-equip-the-ota-update-feature-updated-wv115","title":"Quick and easy to equip the OTA update feature UPDATED w/v1.1.5","text":"

    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.

    "},{"location":"index.html#installation","title":"Installation","text":""},{"location":"index.html#requirements","title":"Requirements","text":""},{"location":"index.html#supported-hardware","title":"Supported hardware","text":"
    • Generic ESP8266 modules (applying the ESP8266 Community's Arduino core)
    • Adafruit HUZZAH ESP8266 (ESP-12)
    • ESP-WROOM-02
    • Heltec WiFi Kit 8
    • NodeMCU 0.9 (ESP-12) / NodeMCU 1.0 (ESP-12E)
    • Olimex MOD-WIFI-ESP8266
    • SparkFun Thing
    • SweetPea ESP-210
    • ESP32Dev Board (applying the Espressif's arduino-esp32 core)
    • SparkFun ESP32 Thing
    • WEMOS LOLIN D32
    • Ai-Thinker NodeMCU-32S
    • Heltec WiFi Kit 32
    • M5Stack
    • And other ESP8266/ESP32 modules supported by the Additional Board Manager URLs of the Arduino-IDE.

    About flash size on the module

    The AutoConnect Sketch size is relatively large. Large flash capacity is necessary. 512Kbyte (4Mbits) flash inclusion module such as ESP-01 is not recommended.

    "},{"location":"index.html#required-libraries","title":"Required libraries","text":"

    AutoConnect requires the following environment and libraries.

    Arduino IDE

    The current upstream at the 1.8 level or later is needed. Please install from the official Arduino IDE download page. This step is not required if you already have a modern version.

    ESP8266 Arduino core

    AutoConnect targets Sketches made on the assumption of ESP8266 Community's Arduino core. Stable 2.4.0 or higher required and the latest release is recommended. Install third-party platform using the Boards Manager of Arduino IDE. Package URL is http://arduino.esp8266.com/stable/package_esp8266com_index.json

    ESP32 Arduino core

    Also, to apply AutoConnect to ESP32, the arduino-esp32 core provided by Espressif is needed. Stable 1.0.1 or required and the latest release 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.

    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 library to build HTML for ESP8266WebServer is needed. To install the PageBuilder library into your Arduino IDE, you can use the Library Manager. Select the board of ESP8266 series in the Arduino IDE, open the library manager and search keyword 'PageBuilder' with the topic 'Communication', then you can see the PageBuilder. The latest version is required 1.4.2 later.1

    Additional library (Optional)

    By adding the ArduinoJson library, AutoConnect will be able to handle the custom Web pages described with JSON. Since AutoConnect v0.9.7 you can insert user-owned web pages that can consist of representative HTML elements as styled TEXT, INPUT, BUTTON, CHECKBOX, SELECT, SUBMIT and invoke them from the AutoConnect menu. These HTML elements can be added by Sketches using the AutoConnect API. Further it possible importing the custom Web pages declarations described with JSON which stored in PROGMEM, SPIFFS, or SD. ArduinoJson is required to use this feature.2 AutoConnect can work with ArduinoJson both version 5 and version 6.

    "},{"location":"index.html#install-the-autoconnect","title":"Install the AutoConnect","text":"

    Clone or download from the AutoConnect GitHub repository.

    When you select Download, you can import it to Arduino IDE immediately. After downloaded, the AutoConnect-master.zip file will be saved in your download folder. Then in the Arduino IDE, navigate to \"Sketch > Include Library\". At the top of the drop down list, select the option to \"Add .ZIP Library...\". Details for Arduino official page.

    Supported by Library manager.

    AutoConnect was added to the Arduino IDE library manager. It can be used with the PlatformIO library also.

    1. Since AutoConnect v1.2.3, PageBuilder v1.5.0 later is required.\u00a0\u21a9

    2. Using the AutoConnect API natively allows you to Sketch custom Web pages without JSON.\u00a0\u21a9

    "},{"location":"acelements.html","title":"AutoConnectElements","text":""},{"location":"acelements.html#the-elements-for-the-custom-web-pages","title":"The elements for the custom Web pages","text":"

    Representative HTML elements for making the custom Web page are provided as AutoConnectElements.

    • AutoConnectButton: Labeled action button
    • AutoConnectCheckbox: Labeled checkbox
    • AutoConnectElement: General tag
    • AutoConnectFile: File uploader
    • AutoConnectInput: Labeled text input box
    • AutoConnectRadio: Labeled radio button
    • AutoConnectRange: Labeled range slider
    • AutoConnectSelect: Selection list
    • AutoConnectStyle: Custom CSS code
    • AutoConnectSubmit: Submit button
    • AutoConnectText: Style attributed text
    "},{"location":"acelements.html#layout-on-a-custom-web-page","title":"Layout on a custom Web page","text":"

    AutoConnect will not actively be involved in the layout of custom Web pages generated from AutoConnectElements. However, each element has an attribute to arrange placement on a custom web page by horizontally or vertically.

    "},{"location":"acelements.html#custom-css-for-a-custom-web-page","title":"Custom CSS for a custom Web page","text":"

    All custom Web page styles are limited to the built-in unique CSS embedded in the library code. Direct modification of the CSS affects AutoConnect behavior. You can use dedicated elements to relatively safely modify the style of your custom Web page. The AutoConnectStyle will insert the raw CSS code into the style block in HTML of the custom Web page.

    "},{"location":"acelements.html#form-and-autoconnectelements","title":"Form and AutoConnectElements","text":"

    All AutoConnectElements placed on custom web pages will be contained into one form. Its form is fixed and created by AutoConnect. The form value (usually the text or checkbox you entered) is sent by AutoConnectSubmit using the POST method with HTTP. The post method sends the actual form data which is a query string whose contents are the name and value of AutoConnectElements. You can retrieve the value for the parameter with the Sketch from the query string with ESP8266WebServer::arg function or PageArgument class of the AutoConnect::on handler when the form is submitted.

    "},{"location":"acelements.html#autoconnectelement-a-basic-class-of-elements","title":"AutoConnectElement - A basic class of elements","text":"

    AutoConnectElement is a base class for other element classes and has common attributes for all elements. It can also be used as a variant of each element. The following items are attributes that AutoConnectElement has and are common to other elements.

    Sample AutoConnectElement element(\"element\", \"<hr>\");

    On the page:

    "},{"location":"acelements.html#constructor","title":"Constructor","text":"
    AutoConnectElement(const char* name, const char* value, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name","title":"name","text":"

    Each element has a name. The name is the String data type. You can identify each element by the name to access it with sketches.

    "},{"location":"acelements.html#value","title":"value","text":"

    The value is the string which is a source to generate an HTML code. Characteristics of Value vary depending on the element. The value of AutoConnectElement is native HTML code. A string of value is output as HTML as it is.

    "},{"location":"acelements.html#post","title":"post","text":"

    The post specifies a tag to add behind the HTML code generated from the element. Its purpose is to place elements on the custom Web page as intended by the user sketch. AutoConnect will not actively be involved in the layout of custom Web pages generated from AutoConnectElements. Each element follows behind the previous one, with the exception of some elements. You can use the post value to arrange vertically or horizontal when the elements do not have the intended position on the custom Web Page specifying the following enumeration value as ACPosterior_t type for the post.

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.

    The default interpretation of the post value is specific to each element.

    AutoConnectElements Default interpretation of the post value AutoConnectElement AC_Tag_None AutoConnectButton AC_Tag_None AutoConnectCheckBox AC_Tag_BR AutoConnectFile AC_Tag_BR AutoConnectInput AC_Tag_BR AutoConnectRadio AC_Tag_BR AutoConnectRange AC_Tag_BR AutoConnectSelect AC_Tag_BR AutoConnectSubmit AC_Tag_None AutoConnectText AC_Tag_None

    A placement posterior of AutoConnectText

    A placement posterior for AutoConnectText has a slightly peculiar specification. AutoConnectText element without the style attribute will be drained to HTML as a raw value and is accompanied by <p>, <br> or <div> tags according to the post enumeration values. If the style attribute is specified, the post enumeration value will be ignored and always be enclosed in the <div> tag, and the style value will be inserted into style attribute of the <div> tag.

    "},{"location":"acelements.html#type","title":"type","text":"

    The type indicates the type of the element and represented as the ACElement_t enumeration type in the Sketch. Since AutoConnectElement also acts as a variant of other elements, it can be applied to handle elements collectively. At that time, the type can be referred to by the typeOf() function. The following example changes the font color of all AutoConnectText elements of a custom Web page to gray.

    AutoConnectAux  customPage;\n\nAutoConnectElementVT& elements = customPage.getElements();\nfor (AutoConnectElement& elm : elements) {\nif (elm.typeOf() == AC_Text) {\n    AutoConnectText& text = reinterpret_cast<AutoConnectText&>(elm);\n    text.style = \"color:gray;\";\n  }\n}\n

    The enumerators for ACElement_t are as follows:

    • AutoConnectButton: AC_Button
    • AutoConnectCheckbox: AC_Checkbox
    • AutoConnectElement: AC_Element
    • AutoConnectFile: AC_File
    • AutoConnectInput: AC_Input
    • AutoConnectRadio: AC_Radio
    • AutoConnectRange: AC_Range
    • AutoConnectSelect: AC_Select
    • AutoConnectStyle: AC_Style
    • AutoConnectSubmit: AC_Submit
    • AutoConnectText: AC_Text
    • Uninitialized element: AC_Unknown

    Furthermore, to convert an entity that is not an AutoConnectElement to its native type, you must re-interpret that type with c++. Or, you can be coding the Sketch more easily with using the as<T> function.

    AutoConnectAux  customPage;\n\nAutoConnectElementVT& elements = customPage.getElements();\nfor (AutoConnectElement& elm : elements) {\nif (elm.type() == AC_Text) {\n    AutoConnectText& text = customPage[elm.name].as<AutoConnectText>();\n    text.style = \"color:gray;\";\n// Or, it is also possible to write the code further reduced as follows.\n// customPage[elm.name].as<AutoConnectText>().style = \"color:gray;\";\n  }\n}\n
    "},{"location":"acelements.html#autoconnectbutton","title":"AutoConnectButton","text":"

    AutoConnectButton generates an HTML <button type=\"button\"> tag and locates a clickable button to a custom Web page. Currently AutoConnectButton corresponds only to name, value, an onclick attribute of HTML button tag. An onclick attribute is generated from an action member variable of the AutoConnectButton, which is mostly used with a JavaScript to activate a script.

    Sample AutoConnectButton button(\"button\", \"OK\", \"myFunction()\");

    On the page:

    "},{"location":"acelements.html#constructor_1","title":"Constructor","text":"
    AutoConnectButton(const char* name, const char* value, const String& action, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_1","title":"name","text":"

    It is the name of the AutoConnectButton element and matches the name attribute of the button tag. It also becomes the parameter name of the query string when submitted.

    "},{"location":"acelements.html#value_1","title":"value","text":"

    It becomes a value of the value attribute of an HTML button tag.

    "},{"location":"acelements.html#action","title":"action","text":"

    action is String data type and is an onclick attribute fire on a mouse click on the element. It is mostly used with a JavaScript to activate a script.1 For example, the following code defines a custom Web page that copies a content of Text1 to Text2 by clicking Button.

    const char* scCopyText = R\"(\n<script>\nfunction CopyText() {\n  document.getElementById(\"Text2\").value = document.getElementById(\"Text1\").value;\n}\n</script>\n)\";\nACInput(Text1, \"Text1\");\nACInput(Text2, \"Text2\");\nACButton(Button, \"COPY\", \"CopyText()\");\nACElement(TextCopy, scCopyText);\n
    "},{"location":"acelements.html#post_1","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_None.

    "},{"location":"acelements.html#autoconnectcheckbox","title":"AutoConnectCheckbox","text":"

    AutoConnectCheckbox generates an HTML <input type=\"checkbox\"> tag and a <label> tag. It places horizontally on a custom Web page by default.

    Sample AutoConnectCheckbox checkbox(\"checkbox\", \"uniqueapid\", \"Use APID unique\", false);

    On the page:

    "},{"location":"acelements.html#constructor_2","title":"Constructor","text":"
    AutoConnectCheckbox(const char* name, const char* value, const char* label, const bool checked, const ACPosition_t labelPosition, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_2","title":"name","text":"

    It is the name of the AutoConnectCheckbox element and matches the name attribute of the input tag. It also becomes the parameter name of the query string when submitted.

    "},{"location":"acelements.html#value_2","title":"value","text":"

    It becomes a value of the value attribute of an HTML <input type=\"checkbox\"> tag.

    "},{"location":"acelements.html#label","title":"label","text":"

    A label is an optional string. A label is always arranged on the right side of the checkbox. Specification of a label will generate an HTML <label> tag with an id attribute. The checkbox and the label are connected by the id attribute. Only will be displayed if a label is not specified.

    "},{"location":"acelements.html#checked","title":"checked","text":"

    A checked is a Boolean value and indicates the checked status of the checkbox. The value of the checked checkbox element is packed in the query string and sent.

    "},{"location":"acelements.html#labelposition","title":"labelPosition","text":"

    The position of the label belonging to the checkbox can be specified around the element. The labelPosition specifies the position of the label to generate with ACPostion_t enumeration value. The default value is AC_Behind.

    • AC_Infront : Place a label in front of the check box.
    • AC_Behind : Place a label behind the check box.
    "},{"location":"acelements.html#post_2","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#autoconnectfile","title":"AutoConnectFile","text":"

    AutoConnectFile generates an HTML <input type=\"file\"> tag and a <label> tag. AutoConnectFile enables file upload from the client through the web browser to ESP8266/ESP32 module. You can select the flash in the module, external SD device or any output destination as the storage of the uploaded file.

    Sample AutoConnectFile file(\"file\", \"\", \"Upload:\", AC_File_FS)

    On the page:

    "},{"location":"acelements.html#constructor_3","title":"Constructor","text":"
    AutoConnectFile(const char* name, const char* value, const char* label, const ACFile_t store, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_3","title":"name","text":"

    It is the name of the AutoConnectFile element and matches the name attribute of the input tag. It also becomes the parameter name of the query string when submitted.

    "},{"location":"acelements.html#value_3","title":"value","text":"

    File name to be upload. The value contains the value entered by the client browser to the <input type=\"file\"> tag and is read-only. Even If you give a value to the constructor, it does not affect as an initial value like a default file name.

    "},{"location":"acelements.html#label_1","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the input box. Specification of a label will generate an HTML <label> tag with an id attribute. The input box and the label are connected by the id attribute.

    "},{"location":"acelements.html#store","title":"store","text":"

    Specifies the destination to save the uploaded file. The destination can be specified the following values in the ACFile_t enumeration type.

    • AC_File_FS : Save as the SPIFFS file in flash of ESP8266/ESP32 module.
    • AC_File_SD : Save to an external SD device connected to ESP8266/ESP32 module.
    • AC_File_Extern : Pass the content of the uploaded file to the uploader which is declared by the Sketch individually. Its uploader must inherit AutoConnectUploadHandler class and implements _open, _write and _close function.

    Built-in uploader is ready.

    AutoConnect already equips the built-in uploader for saving to the SPIFFS as AC_File_FS and the external SD as AC_File_SD. It is already implemented inside AutoConnect and will store uploaded file automatically.

    "},{"location":"acelements.html#post_3","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#autoconnectinput","title":"AutoConnectInput","text":"

    AutoConnectInput generates an HTML <input type=\"text\">, <input type=\"number\"> or <input type=\"password\"> tag and a <label> tag. It can also have a placeholder. The value of the input box is passed to the destination in the query string and can be retrieved programmatically. You can also update from the Sketches.

    Sample AutoConnectInput input(\"input\", \"\", \"Server\", \"MQTT broker server\");

    On the page:

    "},{"location":"acelements.html#constructor_4","title":"Constructor","text":"
    AutoConnectInput(const char* name, const char* value, const char* label, const char* pattern, const char* placeholder, const ACPosterior_t post, const ACInput_t apply)\n
    "},{"location":"acelements.html#name_4","title":"name","text":"

    It is the name of the AutoConnectInput element and matches the name attribute, the id attribute of the input tag. It also becomes the parameter name of the query string when submitted.

    "},{"location":"acelements.html#value_4","title":"value","text":"

    It becomes a string value of the value attribute of an HTML <input type=\"text\"> tag. The text entered from the custom Web page will be grouped in the query string of the form submission and the string set before accessing the page will be displayed as the initial value.

    "},{"location":"acelements.html#label_2","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the input box. Specification of a label will generate an HTML <label> tag with an id attribute. The input box and the label are connected by the id attribute.

    "},{"location":"acelements.html#pattern","title":"pattern","text":"

    A pattern specifies a regular expression that the AutoConnectInput element's value is checked against on form submission. If it is invalid, the background color will change, but it will be sent even if the data format does not match. To check whether the entered value matches the pattern, use the isValid function.

    • The password that must contain 8 or more characters that are of at least one number, and one uppercase and lowercase letter:(?=.*\\d)(?=.*[a-z])(?=.*[A-Z]).{8,}

    • Email address as characters@characters.domain:[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}

    • IP address:(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])

    • Host name of Internet:(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\-]*[A-Za-z0-9])

    • Date (MM/DD/YYYY) as range 1900-2099:(0[1-9]|1[012])[- \\/.](0[1-9]|[12][0-9]|3[01])[- \\/.](19|20)\\d\\d

    • Twitter account:^@?(\\w){1,15}$

    "},{"location":"acelements.html#placeholder","title":"placeholder","text":"

    A placeholder is an option string. Specification of a placeholder will generate a placeholder attribute for the input tag.

    "},{"location":"acelements.html#post_4","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#apply","title":"apply","text":"

    Specifies the type of input that the text box accepts. AutoConnectInput will generate either a input type=\"text\", input type=\"password\", or input type=\"number\" tag based on the apply specifying as input type. The input type can be specified the following values in the ACInput_t enumeration type.

    • AC_Input_Text : input type=\"text\"
    • AC_Input_Password : input type=\"password\"
    • AC_Input_Number : input type=\"number\"

    Numerical keypad is different

    When the AutoConnectInput element with the AC_Input_Number applied is focused on the browser, the numeric keypad may be displayed automatically. For popular mobile OSes such as Android and iOS, the numeric keypad has the following styles and is different with each OS.

    "},{"location":"acelements.html#autoconnectradio","title":"AutoConnectRadio","text":"

    AutoConnectRadio generates several HTML <input type=\"radio\"> tags grouped together. It also assigns an equal number of <label> tags to each <input type=\"radio\"> tag and stores the values of the choices that make up a radio button as a String collection.

    Sample AutoConnectRadio radio(\"radio\", { \"30 sec.\", \"60 sec.\", \"180 sec.\" }, \"Update period\", AC_Vertical, 1);

    On the page:

    "},{"location":"acelements.html#constructor_5","title":"Constructor","text":"
    AutoConnectRadio(const char* name, std::vector<String> const& values, const char* label, const ACArrange_t order, const uint8_t checked, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_5","title":"name","text":"

    It is the name of the AutoConnectRadio element, which matches the name attribute of the input tag and defines the radio group by this name. It is also the name parameter in the query string during submission.

    "},{"location":"acelements.html#values","title":"values","text":"

    A group of radio buttons is a set of <input type=\"radio\"> tags with the same name; AutoConnectRadio defines a radio group based on an array of Strings specified as values. A values is an array of String, actually a std::vector. The sketch can allocate its String array using std::vector's List-initialization.

    "},{"location":"acelements.html#label_3","title":"label","text":"

    A label is an optional string. A label will be arranged in the left or top of the radio buttons according to the order. Specification of a label will generate an HTML <label> tag with an id attribute. The radio buttons and the label are connected by the id attribute.

    "},{"location":"acelements.html#order","title":"order","text":"

    A order specifies the direction to arrange the radio buttons. It is a value of type ACArrange_t and accepts one of the following:

    • AC_Horizontal : Horizontal arrangement.
    • AC_Vertical : Vertical arrangement.

    A label will place in the left or the top according to the order.

    "},{"location":"acelements.html#checked_1","title":"checked","text":"

    A checked specifies the index number (1-based) of the values to be checked. If this parameter is not specified neither item is checked.

    "},{"location":"acelements.html#post_5","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#autoconnectrange","title":"AutoConnectRange","text":"

    AutoConnectRange generates an HTML <input type=\"range\"> tag and a <label> tag.

    Sample AutoConnectRange range(\"bri\", 0, \"Brightness\", -2, 2, 1, AC_Infront);

    On the page:

    "},{"location":"acelements.html#constructor_6","title":"Constructor","text":"
    AutoConnectRange(const char* name, const int value, const char* label, const int min, const int max, const int step, const ACPosition_t magnify, const ACPosterior_t post, const char* style)\n
    "},{"location":"acelements.html#name_6","title":"name","text":"

    It is the name of the AutoConnectRange element and matches the name attribute, the id attribute of the input tag. It also becomes the parameter name of the query string when submitted.

    "},{"location":"acelements.html#value_5","title":"value","text":"

    It becomes a string value of the value attribute of an HTML <input type=\"range\"> tag, which indicates the default value of the range.

    "},{"location":"acelements.html#label_4","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the range slider. Specification of a label will generate an HTML <label> tag with an id attribute. The range slider and the label are connected by the id attribute.

    "},{"location":"acelements.html#min","title":"min","text":"

    Specifies the most negative value within the range of allowed values and must not be less than the value argument.

    "},{"location":"acelements.html#max","title":"max","text":"

    It defines the greatest value in the range of permitted values.

    "},{"location":"acelements.html#step","title":"step","text":"

    It is a number that specifies the granularity that the value must adhere to. The default is 1. As you move the slider, it increases or decreases the value according to the step in granularity.

    "},{"location":"acelements.html#magnify","title":"magnify","text":"

    Displays the current value of the range on the left or right side of the slider.

    • AC_Infront : Displays the current value on the left side.
    • AC_Behind : Displays the current value on the right side.
    • AC_Void : No display the current value. This is the default.
    "},{"location":"acelements.html#post_6","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#style","title":"style","text":"

    A style specifies the qualification style to give to the content and can use the style attribute format as it is.

    "},{"location":"acelements.html#autoconnectstyle","title":"AutoConnectStyle","text":"

    AutoConnectStyle inserts the string given by the value into the style block of a custom Web page as it is raw.

    The validity as CSS will not be checked

    AutoConnectStyle does not do syntax checking and semantic analysis of value. Insert the specified string into the style block of the custom Web page without processing it. Therefore, specifying the wrong CSS will modulate the behavior of the custom Web page.

    "},{"location":"acelements.html#constructor_7","title":"Constructor","text":"
    AutoConnectStyle(const char* name, const char* value)\n
    "},{"location":"acelements.html#name_7","title":"name","text":"

    It is the name of the AutoConnectStyle element and is useful only to access this element from the Sketch. It does not affect the generated HTML code.

    "},{"location":"acelements.html#value_6","title":"value","text":"

    The raw CSS code. It is not necessary to write <style> </style> tags.

    "},{"location":"acelements.html#autoconnectselect","title":"AutoConnectSelect","text":"

    AutoConnectSelect generates an HTML <select> tag (drop-down list) and few <option> tags.

    Sample AutoConnectSelect select(\"select\", { String(\"Europe/London\"), String(\"Europe/Berlin\"), String(\"Europe/Helsinki\"), String(\"Europe/Moscow\"), String(\"Asia/Dubai\") }, \"Select TZ name\");

    On the page:

    "},{"location":"acelements.html#constructor_8","title":"Constructor","text":"
    AutoConnectSelect(const char* name, std::vector<String> const& options, const char* label, const uint8_t selected, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_8","title":"name","text":"

    It is the name of the AutoConnectSelect element and matches the name attribute of the select tags.

    "},{"location":"acelements.html#options","title":"options","text":"

    An options is an array of String type for the options which as actually std::vector for an HTML <option> tag. It is an initialization list can be used. The option tags will be generated from each entry in the options, the amount of which is the same as the number of items in an options.

    "},{"location":"acelements.html#label_5","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the drop-down list. Specification of a label will generate an HTML <label> tag with an id attribute. The select tag and the label are connected by the id attribute.

    "},{"location":"acelements.html#selected","title":"selected","text":"

    A selected is an optional value. Specifies that an option should be pre-selected when the page loads.

    "},{"location":"acelements.html#post_7","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#autoconnectsubmit","title":"AutoConnectSubmit","text":"

    AutoConnectSubmit generates an HTML <input type=\"button\"> tag attached onclick attribute. The native code of the onclick attribute is the submission of the form with the POST method.

    Sample AutoConnectSubmit submit(\"submit\", \"Save\", \"/mqtt_save\");

    On the page:

    "},{"location":"acelements.html#constructor_9","title":"Constructor","text":"
    AutoConnectSubmit(const char* name, const char* value, const char* uri, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_9","title":"name","text":"

    It is the name of the AutoConnectSubmit element and matches the name attribute of the input tag.

    "},{"location":"acelements.html#value_7","title":"value","text":"

    It becomes a string of the value attribute of an HTML <input type=\"button\"> tag. The value will be displayed as a label of the button.

    "},{"location":"acelements.html#uri","title":"uri","text":"

    A uri specifies the URI to send form data when the button declared by AutoConnectSubmit is clicked.

    The query string of the form data sent with AutoConnectSubmit contains the URI of the page. Its parameter name is _acuri. In Sketch, you can know the called URI by referring to the _acuri parameter with the destination page handler. The actual query string is as follows:

    _acuri=CALLER_URI

    "},{"location":"acelements.html#post_8","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_None.

    "},{"location":"acelements.html#autoconnecttext","title":"AutoConnectText","text":"

    AutoConnectText generates a text content enclosed in <div>, <p> or <span> tags; if the style parameter is provided, the style attributes is added. A kind of HTML tag applied depends on the value of the post parameter as follows:

    • AC_Tag_None: <span id='name' style='style'>value</span>
    • AC_Tag_BR: <span id='name' style='style'>value</span><br>
    • AC_Tag_P: <p id='name' style='style'>value</p>
    • AC_Tag_DIV: <div id='name' style='style'>value</div>

    Sample AutoConnectText text(\"text\", \"Publishing the WiFi signal strength to MQTT channel. RSSI value of ESP8266 to the channel created on ThingSpeak\", \"font-family:serif;color:#4682b4;\");

    On the page:

    "},{"location":"acelements.html#constructor_10","title":"Constructor","text":"
    AutoConnectText(const char* name, const char* value, const char* style, const char* format, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_10","title":"name","text":"

    A name does not exist in the generated HTML. It provides only a means of accessing elements with the Sketches.

    "},{"location":"acelements.html#value_8","title":"value","text":"

    It becomes content and also can contain the native HTML code, but remember that your written code is enclosed by the div tag.

    "},{"location":"acelements.html#style_1","title":"style","text":"

    A style specifies the qualification style to give to the content and can use the style attribute format as it is.

    "},{"location":"acelements.html#format","title":"format","text":"

    A format is a pointer to a null-terminated multi byte string specifying how to interpret the value. It specifies the conversion format when outputting values. The format string conforms to C-style printf library functions, but depends on the Espressif's SDK implementation. The conversion specification is valid only in %s format. (Left and Right justification, width are also valid.)

    "},{"location":"acelements.html#post_9","title":"post","text":"

    Specifies an HTML element that completes the text content. AutoConnectText's post parameter does not specify any behind-supplements, unlike when applied to other elements. A kind of HTML tag applied depends on the enumerated value of the post parameter as follows:

    • AC_Tag_None: <span id='name' style='style'>value</span>
    • AC_Tag_BR: <span id='name' style='style'>value</span><br>
    • AC_Tag_P: <p id='name' style='style'>value</p>
    • AC_Tag_DIV: <div id='name' style='style'>value</div>
    "},{"location":"acelements.html#how-to-coding-for-the-elements","title":"How to coding for the elements","text":""},{"location":"acelements.html#declaration-for-the-elements-in-sketches","title":"Declaration for the elements in Sketches","text":"

    Variables of each AutoConnetElement can be declared with macros. By using the macros, you can treat element name that is String type as variable in sketches.2

    ACElement ( name [ , value ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACButton ( name [ , value ] [ , action ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACCheckbox ( name [ , value ] [ , label ] [ , true | false ] [ , AC_Infront | AC_Behind ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACFile ( name [ , value ] [ , label ] [ , AC_File_FS | AC_File_SD | AC_File_Extern ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACInput ( name [ , value ] [ , label ] [ , pattern ] [ , placeholder ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] [ , AC_Input_Text | AC_Input_Password | AC_Input_Number ])

    ACRadio ( name [ , values ] [ , label ] [ , AC_Horizontal | AC_Vertical ] [ , checked ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACRange ( name [ , value ] [ , label ] [ , min ] [ , max ] [ , step ] [ , AC_Infront | AC_Behind | AC_Void ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] [ , style ] )

    ACSelect ( name [ , options ] [ , label ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACStyle ( name [ , value ] )

    ACSubmit ( name [ , value ] [ , uri ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACText ( name [ , value ] [ , style ] [ , format ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    Declaration macro usage

    For example, AutoConnectText can be declared using macros. 

    AutoConnectText caption(\"caption\", \"hello, world\", \"color:blue;\")\n
    equals by using ACText macro. 
    ACText(caption, \"hello, world\", \"color:blue;\")\n

    "},{"location":"acelements.html#variant-for-autoconnectelements","title":"Variant for AutoConnectElements","text":"

    Some AutoConnectAux APIs specify AutoConnectElements as an argument. There are also functions that return a pointer to AutoConnectElements. AutoConnectElement behaves as a variant type of each element class to make these interfaces a single. Use reinterpret_cast to cast from a variant pointer to an Actual type pointer of AutoConnectElements.

    AutoConnectAux aux;\nACText(Text1, \"hello, world\");\naux.add(Text1);\nAutoConnectText* text_p = reinterpret_cast<AutoConnectText*>(aux.getElement(\"Text1\"));\nAutoConnectText& text = aux.getElement<AutoConnectText>(\"Text1\");\n

    1. JavaScript can be inserted into a custom Web page using AutoConnectElement.\u00a0\u21a9

    2. The square brackets in the syntax are optional parameters, the stroke is a selection parameter, the bold fonts are literal.\u00a0\u21a9

    "},{"location":"achandling.html","title":"Handling the custom Web pages","text":""},{"location":"achandling.html#page-container-component","title":"Page, Container, Component","text":"

    AutoConnectAux is the container for a custom Web page, AutoConnectElement is the component of a page. AutoConnectElements must be contained in AutoConnectAux object. (ie. they are the elements displayed on the custom Web page.) Then AutoConnect makes an AutoConnectAux to a page.

    AutoConnectElements declared in sketch must be programmed to add to AutoConnectAux one after another. Elements are automatically included in AutoConnectAux by AutoConnect if you load it from the JSON document. In either method, it is common to use the function of AutoConnectAux to access an element with a sketch.

    "},{"location":"achandling.html#custom-web-page-handler-programming-model","title":"Custom Web page handler programming model","text":"

    To handle Custom Web pages properly, the sketches need to implement to match the programming model. Custom Web page programming model is depicted as follows:

    Custom Web page handler acts as an event handler for processing the HTTP request captured by the WebServer class. The WebServer class parses the HTTP request and calls the registered uri handler appropriately. The custom web page uri (it should be specified by the JSON description for the custom web page, the AutoConnectAux constructor, or the AutoConnect::on function) is not registered directly with the WebServer class, and the Requests always go through the request dispatcher inside AutoConnect.

    When implementing the custom Web page handler, it is possible to give an appropriate function to the handler by understanding the above internal structure in advance. Custom web page handler can be sketched as regular function and has interface is as follows:

    String customWebpageHandler(AutoConnectAux& aux, PageArgument& args)\n
    "},{"location":"achandling.html#parameters-for-the-customwebagehandler","title":"Parameters for the customWebageHandler","text":"

    When the custom web page handler is called, AutoConnect passes the following two parameters:

    "},{"location":"achandling.html#1-reference-to-the-autoconnectaux-instance","title":"1. Reference to the AutoConnectAux instance","text":"

    Custom Web page handlers can access the AutoConnectElements owned by its page through a reference to the AutoConnectAux instance. It can use this access to update the AutoConnectElements value before the user views the page or get the value of AutoConnectElements owned by the page that triggered the transition.

    A list of commonly used functions to access AutoConnectElements with your Sketch via reference to an AutoConnectAux instance is following:

    • [] operator : Access to an AutoConnectElement by specified element name.
    • getElement function : Access to an AutoConnectElement by specified element name.
    • as<> function : Cast from a variant of AutoConnectElement type to an actual type such as AutoConnectText or AutoConnectInput etc. To access attributes that exist only in the actual type, it is necessary to convert from the AutoConnectElement type obtained with [] operator or getElement function.

    See the section Get AutoConnectElement from the AutoConnectAux and the section AutoConnectElements API for usage examples and API specifications for each above function.

    "},{"location":"achandling.html#2-reference-to-the-pageargument-instance","title":"2. Reference to the PageArgument instance","text":"

    The values of the AutoConnectCheckbox, AutoConnectFile, AutoConnectInput, AutoConnectRadio, and AutoConnectSelect elements are packed into the form data of the HTTP POST method by the page transition caused by AutoConnectSubmit. Use the PageArgument instance to retrieve the values of these transmitted AutoConnectElements with the customWebpageHandler. A list of commonly used functions to access PageArgment member variables with your Sketch via a reference to an PageArgument instance is following:

    • arg function : Get an element value by specified element name.
    • hasArg function : Checks for the existence of an element with the specified name.

    The method to get the form data attached to the HTTP request via PageArgument is described with the section How you can reach the values.

    "},{"location":"achandling.html#3-access-to-the-autoconnectelement-values","title":"3. Access to the AutoConnectElement values","text":"

    Here, you have one thing to note. The custom web page handler registered with AutoConnect::on function is called to respond to an HTTP request to the URL of its page. And, the AutoConnectAux instance then references the custom web page assigned to the requested URL. That is, the AutoConnectAux instance passed to the custom web page handler owns the AutoConnectElements for that page, while the PageArgument instance has the AutoConnectElements value of the custom web page that caused the page transition. You need to keep the difference between the two in mind when implementing the custom web page handler with your Sketch and access these values via the appropriate approach.

    You can access the AutoConnect Elements of the custom web page itself via the AutoConnectAux& argument by specifying the element name. You can also use the PageArgument& argument to get the value of AutoConnectElements for the page that caused the transition to that custom web page. (the URL that issued the HTTP request)

    The following screenshots are outputs of custom web pages that are based on a scenario to help you understand how to access AutoConnectElements properly with a custom web page handler. The requirements for this scenario are:

    • Calculate an addition simply, add B to A.
    • Perform the calculation with a customWebPageHandler.
    • Returns the calculated result in another custom web page with page transitions.

    The first thing to work on is defining two custom web pages. Here, Value A and Value B are easily defined by applying AutoConnectInput. Also, add an action button to perform the calculation with AutoConnectSubmit.

    {\n\"uri\": \"/add\",\n\"title\": \"Adder\",\n\"menu\": true,\n\"element\": [\n    {\n\"name\": \"valueA\",\n\"type\": \"ACInput\",\n\"label\": \"Value A\",\n\"apply\": \"number\"\n    },\n    {\n\"name\": \"valueB\",\n\"type\": \"ACInput\",\n\"label\": \"Value B\",\n\"apply\": \"number\"\n    },\n    {\n\"name\": \"add\",\n\"type\": \"ACSubmit\",\n\"value\": \"ADD\",\n\"uri\": \"/results\"\n    }\n  ]\n}\n

    Next, define an additional page to display the results. Here we use AutoConnectText to display the calculation as a representation string of the expression. There is one thing to watch out for here. That is, the transition destination of the action button as ADD that accept the operand (it is specified by the uri of the ACSubmit element named \"add\") and the uri of the page that displays the answer are the same.

    {\n\"uri\": \"/results\",\n\"title\": \"Adder\",\n\"menu\": false,\n\"element\": [\n    {\n\"name\": \"results\",\n\"type\": \"ACText\"\n    }\n  ]\n}\n

    When implementing a custom web page handler, it's usually a good idea to pre-determine the page design (which consists of the elements and layouts you want to use) for a better outlook when coding your Sketch. Especially when coding a custom web page handler, you need to specify the AutoConnectElements exactly, and it is recommended to implement it along the JSON defined earlier.

    After this, sketch the handlers for the above two custom web pages.

    First, the handler for the page allocated to /add. The role of this handler is to initialize the values respectively for the valueA and valueB input boxes. Both of these two input boxes are on the /add page, so the handler only references the AutoConnectAux& aux argument.

    You can use the [] operator with the element name like as aux[\"valueA\"] to get a reference to an AutoConnectElement by name. Then, once the reference is converted to AutoConnectInput, the value member of AutoConnectInput can be accessed. Use the as<AutoConnectInput>() function to convert from the AutoConnectElement type to the actual AutoConnectInput type.

    String onAdd(AutoConnectAux& aux, PageArgument& args) {\n  aux[\"valueA\"].as<AutoConnectInput>().value = \"0\";\n  aux[\"valueB\"].as<AutoConnectInput>().value = \"0\";\nreturn String();\n}\n

    Next, the handler for the page allocated to /results. The role of this handler is to add the value B to A for the calculation. The /results page does not have an element that contains the operands Value A and Value B to calculate. Only the /add page has them. The /results page handler is called when ACSubmit on the /add page works, so valueA and valueB are included in the form data of the HTTP POST request to the /results page. That is, the handler for the /results page will get valueA and valueB from the PageArgument& args argument.

    String onResults(AutoConnectAux& aux, PageArgument& args) {\nint valueA = args.arg(\"valueA\").toInt();\nint valueB = args.arg(\"valueB\").toInt();\n\n  aux[\"results\"].as<AutoConnectText>().value = String(valueA) + \" + \" + String(valueB) + \" = \" + String(valueA + valueB);\nreturn String();\n}\n

    PageArgument is a built-in class in the PageBuilder library. You can use the PageArgument::arg function to retrieve the parameters of the form data contained in the POST request by name. Since the PageArgument::arg function returns the parameters of the POSTed form data as a string, it converts Value A and Value B to the operand integer value of the addition via the String::toInt() function.

    int valueA = args.arg(\"valueA\").toInt();\nint valueB = args.arg(\"valueB\").toInt();\n

    In this scenario, in addition to the calculation result, the calculation formula is also displayed on the result page.

    aux[\"results\"].as<AutoConnectText>().value = String(valueA) + \" + \" + String(valueB) + \" = \" + String(valueA + valueB);\n
    "},{"location":"achandling.html#the-customwebpagehandler-return-value","title":"The customWebpageHandler return value","text":"

    The customWebpageHandler returns a string. The returned string is used internally by AutoConnect to temporarily qualify the HTML generating of the custom web page. AutoConnect typically calls a custom web page handler before HTML generation.

    When the customWebpageHandler returns an HTML string for qualification, it applies to the drawing area for the elements of AutoConnectElements. Additionally, you can then specify where the modifier HTML will be inserted. The second parameter of the AutoConnectAux::on function, which allows the registration of custom web page handlers, indicates where to insert the modifier HTML.

    The Sketch can specify the following three values for the second parameter of AutoConnectAux::on function:

    • AC_EXIT_AHEAD : Modifiers HTML returned by the custom Web page handler is inserted into the front of the list expansion of AutoConnectElements.

    • AC_EXIT_LATER : Modifiers HTML returned by the custom Web page handler is inserted into the back of the list expansion of AutoConnectElements.

    • AC_EXIT_BOTH : The customWebpageHandle will be called twice before and after list expansion of AutoConnectElements.

    A detailed description of the AutoConnectAux::on function can be found in Section AutoConnectAux API.

    The actual sketch code implemented following these steps above would look like this (case of ESP8266):

    #include <Arduino.h>\n#include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nconst char PAGE_ADD[] PROGMEM = R\"(\n{\n  \"uri\": \"/add\",\n  \"title\": \"Adder\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"valueA\",\n      \"type\": \"ACInput\",\n      \"label\": \"Value A\",\n      \"apply\": \"number\"\n    },\n    {\n      \"name\": \"valueB\",\n      \"type\": \"ACInput\",\n      \"label\": \"Value B\",\n      \"apply\": \"number\"\n    },\n    {\n      \"name\": \"add\",\n      \"type\": \"ACSubmit\",\n      \"value\": \"ADD\",\n      \"uri\": \"/results\"\n    }\n  ]\n}\n)\";\n\nconst char PAGE_RESULTS[] PROGMEM = R\"(\n{\n  \"uri\": \"/results\",\n  \"title\": \"Adder\",\n  \"menu\": false,\n  \"element\": [\n    {\n      \"name\": \"results\",\n      \"type\": \"ACText\"\n    }\n  ]\n}\n)\";\n\nAutoConnect portal;\nAutoConnectAux  page_add;\nAutoConnectAux  page_results;\n\nString onAdd(AutoConnectAux& aux, PageArgument& args) {\n  aux[\"valueA\"].as<AutoConnectInput>().value = \"0\";\n  aux[\"valueB\"].as<AutoConnectInput>().value = \"0\";\nreturn String();\n}\n\nString onResults(AutoConnectAux& aux, PageArgument& args) {\nint valueA = args.arg(\"valueA\").toInt();\nint valueB = args.arg(\"valueB\").toInt();\n\n  aux[\"results\"].as<AutoConnectText>().value = String(valueA) + \" + \" + String(valueB) + \" = \" + String(valueA + valueB);\nreturn String();\n}\n\nvoid setup() {\n  delay(1000);\n  page_add.load(PAGE_ADD);\n  page_results.load(PAGE_RESULTS);\n  portal.join({ page_add, page_results });\n  portal.on(\"/add\", onAdd);\n  portal.on(\"/results\", onResults);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"achandling.html#handing-autoconnectelements-with-the-sketches","title":"Handing AutoConnectElements with the Sketches","text":"

    The AutoConnectAux class has several functions to manipulate AutoConnectElements. The functions can add, delete, retrieve elements, and get and set values.

    "},{"location":"achandling.html#add-autoconnectelements-to-the-autoconnectaux-object","title":"Add AutoConnectElements to the AutoConnectAux object","text":"

    To add AutoConnectElment(s) to an AutoConnectAux object, use the add function.

    void AutoConnectAux::add(AutoConnectElement& addon)\n
    void AutoConnectAux::add(AutoConnectElementVT addons)\n

    The add function adds the specified AutoConnectElement to AutoConnectAux. The AutoConnectElementVT type is the std::vector of the reference wrapper to AutoConnectElements, and you can add these elements in bulk by using the list initialization with the Sketch.

    typedef std::vector<std::reference_wrapper<AutoConnectElement>> AutoConnectElementVT;\n

    AutoConnectElements contained in AutoConnectAux object are uniquely identified by name. When adding an AutoConnectElement, if an element with the same name already exists in the AutoConnectAux, checking the type, and if it is the same, the value will be replaced. If another type of AutoConnectElement exists with the same name, that add operation will be invalid.1 In the following example, AutoConnectButton button addition will invalid because hello with the same name already exists as AutoConnectText.

    AutoConnectAux  aux;\nAutoConnectText text(\"hello\", \"hello, world\");\nAutoConnectButton button(\"hello\", \"hello, world\", \"alert('Hello world!')\");  // This is invalid.\naux.add({ text, button });\n

    Similarly this, the uniqueness of the name is also necessary within the JSON document

    {\n\"name\" : \"aux\",\n\"uri\" : \"/aux\",\n\"menu\" : true,\n\"element\" : [\n    {\n\"name\": \"hello\",\n\"type\": \"ACText\",\n\"value\": \"hello, world\"\n    },\n    {\n\"name\": \"hello\",\n\"type\": \"ACButton\",\n\"value\": \"hello, world\",\n\"action\": \"alert('Hello world!')\"\n    }\n  ]\n}\n

    Load all elements from JSON document

    If you load all AutoConnectElements from JSON document into AutoConnect, you do not need to sketch the population process of the AutoConnectElements. It is managed by the AutoConnect library automatically.

    "},{"location":"achandling.html#get-autoconnectelement-from-the-autoconnectaux","title":"Get AutoConnectElement from the AutoConnectAux","text":"

    To retrieve an element from AutoConnectAux, use the getElement or getElements function. Normally, the getElement is needed when accessing the value of AutoConnectElement in the Sketch.

    AutoConnectElement* AutoConnectAux::getElement(const char* name)\n
    AutoConnectElement* AutoConnectAux::getElement(const __FlashStringHelper* name)\n
    AutoConnectElement* AutoConnectAux::getElement(const String& name)\n
    T& AutoConnectAux::getElement<T>(const String& name)\n
    AutoConnectElementVT* AutoConnectAux::getElements(void)\n

    The getElement function returns an AutoConnectElement with the specified name as a key. When you use this function, you need to know the type of AutoConnectElement in advance and specify its type <T> to an argument of the getElement. A type of <T> can be specified as follows.

    AutoConnectButton& AutoConnectAux::getElement<AutoConnectButton>(const String& name)\nAutoConnectCheckbox& AutoConnectAux::getElement<AutoConnectCheckbox>(const String& name)\nAutoConnectElement& AutoConnectAux::getElement<AutoConnectElement>(const String& name)\nAutoConnectFile& AutoConnectAux::getElement<AutoConnectFile>(const String& name)\nAutoConnectInput& AutoConnectAux::getElement<AutoConnectInput>(const String& name)\nAutoConnectRadio& AutoConnectAux::getElement<AutoConnectRadio>(const String& name)\nAutoConnectSelect& AutoConnectAux::getElement<AutoConnectSelect>(const String& name)\nAutoConnectSubmit& AutoConnectAux::getElement<AutoConnectSubmit>(const String& name)\nAutoConnectText& AutoConnectAux::getElement<AutoConnectText>(const String& name)\n

    To retrieve an AutoConnectElement by specifying its type, use the following method.

    AutoConnectAux  aux;\naux.load(\"SOME_JSON_DOCUMENT\");\n\n// Retrieve the pointer of the AutoConnectText\nAutoConnectText* text = reinterpret_cast<AutoConnectText*>(aux.getElement(\"TEXT_ELEMENT_NAME\"));\n\n// Retrieve the reference of the AutoConnectText\nAutoConnectText& text = aux.getElement<AutoConnectText>(\"TEXT_ELEMENT_NAME\");\n

    The AutoConnectElement type behaves as a variant of other element types. Therefore use cast or template to convert to actual type as above. In the Sketch, you access the real type of AutoConnectElement after casting it and storing into the variable.

    const String auxJson = String(\"{\\\"title\\\":\\\"Page 1 title\\\",\\\"uri\\\":\\\"/page1\\\",\\\"menu\\\":true,\\\"element\\\":[{\\\"name\\\":\\\"caption\\\",\\\"type\\\":\\\"ACText\\\",\\\"value\\\":\\\"hello, world\\\"}]}\");\nAutoConnect portal;\nportal.load(auxJson);\nAutoConnectAux* aux = portal.aux(\"/page1\");  // Identify the AutoConnectAux instance with uri\nAutoConnectText& text = aux->getElement<AutoConnectText>(\"caption\");  // Cast to real type and access members\nSerial.println(text.value);\n

    You can also use the operator [] of AutoConnectAux as another way to get the desired element. An operator [] is a shortcut for getElement function with the reference casting and makes simplify the Sketch code and treats like an array with the elements placed on a custom Web page. Its argument is the name of the element to be acquired similarly to getElement function. In the Sketch, by combining the AutoConnectElement::as<T> function with the operator [], you can access the AutoConnectElements reference according to its actual type. For example, the following sketch code returns the same as a reference of AutoConnectText element as the caption.

    AutoConnect portal;\nportal.load(auxJson);\nAutoConnectAux&  aux = *portal.aux(\"/page1\");\nAutoConnectText& text1 = aux.getElement<AutoConnectElement>(\"caption\");\nAutoConnectText& text2 = aux[\"caption\"].as<AutoConnectText>();\n

    Need cast to convert to the actual type

    An operator [] returns a reference of an AutoConnectElement. It is necessary to convert the type according to the actual element type with AutoConnectElement::as<T> function. 

    AutoConnectButton& AutoConnectElement::as<AutoConnectButton>()\nAutoConnectCheckbox& AutoConnectElement::as<AutoConnectCheckbox>()\nAutoConnectElement& AutoConnectElement::as<AutoConnectElement>()\nAutoConnectFile& AutoConnectElement::as<AutoConnectFile>()\nAutoConnectInput& AutoConnectElement::as<AutoConnectInput>()\nAutoConnectRadio& AutoConnectElement::as<AutoConnectRadio>()\nAutoConnectSelect& AutoConnectElement::as<AutoConnectSelect>()\nAutoConnectSubmit& AutoConnectElement::as<AutoConnectSubmit>()\nAutoConnectText& AutoConnectElement::as<AutoConnectText>()\n

    To get all the AutoConnectElements in an AutoConnectAux object use the getElements function. This function returns the vector of the reference wrapper as AutoConnectElementVT to all AutoConnectElements registered in the AutoConnectAux.

    AutoConnectElementVT& AutoConnectAux::getElements(void)\n
    "},{"location":"achandling.html#enable-autoconnectelements-during-the-sketch-execution","title":"Enable AutoConnectElements during the Sketch execution","text":"

    AutoConnectElemets have an enable attribute to activate its own HTML generation. Sketches can change the HTMLization of their elements dynamically by setting or resetting the enable value. An element whose the enable attribute is true will generate itself HTML and place on the custom Web page. And conversely, it will not generate the HTML when the value is false.

    For example, to enable the submit button only when the ESP module is connected to the access point in STA mode, you can sketch the following:

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char AUX[] PROGMEM = R(\"\n{\n\"name\" : \"aux\",\n\"uri\" : \"/aux\",\n\"menu\" : true,\n\"element\" : [\n    {\n\"name\": \"input\",\n\"type\": \"ACInput\",\n\"label\": \"Input\"\n    },\n    {\n\"name\": \"send\",\n\"type\": \"ACSubmit\",\n\"uri\": \"/send\"\n    }\n  ]\n}\n\");\n\nAutoConnect    portal;\nAutoConnectAux page;\n\nString onPage(AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectSubmit& send = aux[\"send\"].as<AutoConnectSubmit>();\nif (WiFi.isConnected())\n    send.enable = (WiFi.getMode() == WIFI_STA);\nelse\n    send.enable = false;\nreturn String();\n}\n\nvoid setup() {\n  page.load(AUX);\n  page.on(onPage);\n  portal.join(page);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    Desirable to set or reset the enable attribute in the page handler

    The enable attribute can be set at any time during the Sketch execution. The page handler with the AC_EXIT_AHEAD option is sure to handle it.

    "},{"location":"achandling.html#loading-saving-autoconnectelements-with-json","title":"Loading & saving AutoConnectElements with JSON","text":"

    AutoConnect supports reading the custom Web page definitions written in JSON and also supports loading and saving of AutoConnectAux or AutoConnectElements. In both cases, the target object is a JSON document for AutoConnect. However, it can not save all AutoConnectElements contained in the page as a custom Web page. (ie. AutoConnectAux)

    "},{"location":"achandling.html#loading-autoconnectaux-autoconnectelements-with-json","title":"Loading AutoConnectAux & AutoConnectElements with JSON","text":"

    To load a JSON document as AutoConnectAux use the AutoConnect::load function and load the JSON document of each AutoConnectElement using the AutoConnectAux::loadElement function. Although the functions of both are similar, the structure of the target JSON document is different.

    The AutoConnect::load function loads the entire AutoConnectAux and creates both the AutoConnectAux instance and each AutoConnectElement instance. A single JSON document can contain multiple custom Web pages. If you write JSON of AutoConnectAux as an array, the load function generates all the pages contained in that array. Therefore, it is necessary to supply the JSON document of AutoConnectAux as an input of the load function and must contain the elements described section JSON document structure for AutoConnectAux.

    The AutoConnectAux::loadElement function loads the elements individually into an AutoConnectAux object. The structure of its supplying JSON document is not AutoConnectAux. It must be a JSON structure for AutoConnectElement, but you can specify an array.

    // AutoConnectAux as a custom Web page.\nconst char page[] PROGMEM = R\"raw(\n{\n  \"title\": \"Settings\",\n  \"uri\": \"/settings\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"server\",\n      \"type\": \"ACInput\",\n      \"label\": \"Server\"\n    },\n    {\n      \"name\": \"set\",\n      \"type\": \"ACSubmit\",\n      \"value\": \"SET\",\n      \"uri\" : \"/set\"\n    }\n  ]\n}\n)raw\";\n\n// Additional AutoConnectElements.\nconst char addons[] PROGMEM = R\"raw(\n[\n  {\n    \"name\": \"notes\",\n    \"type\": \"ACText\",\n    \"value\": \"An update period as the below optionally.\"\n  },\n  {\n    \"name\": \"period\",\n    \"type\": \"ACRadio\",\n    \"value\": [\n      \"30 sec.\",\n      \"60 sec.\",\n      \"180 sec.\"\n    ],\n    \"arrange\": \"vertical\",\n    \"checked\": 1\n  }\n]\n)raw\";\n\nAutoConnect     portal;\nAutoConnectAux* auxPage;\n\n// Load a custom Web page.\nportal.load(page);\n// Get a '/settings' page\nauxPage = portal.aux(\"/settings\");\n\n// Also, load only AutoConnectRadio named the period.\nauxPage->loadElement(addons, \"period\");\n// Retrieve a server name from an AutoConnectText value.\nAutoConnectText& serverName = auxPage->getElement<AutoConnectText>(\"server\");\nSerial.println(serverName.value);\n
    "},{"location":"achandling.html#saving-autoconnectelements-with-json","title":"Saving AutoConnectElements with JSON","text":"

    To save the AutoConnectAux or the AutoConnectElement as a JSON document, use the AutoConnectAux::saveElement function. It serializes the contents of the object based on the type of the AutoConnectElement. You can persist a serialized AutoConnectElements as a JSON document to a stream.

    // Open a parameter file on the SPIFFS.\nSPIFFS.begin();\nFILE param = SPIFFS.open(\"/param\", \"w\");\n\n// Save elements as the parameters.\nauxPage->saveElement(param, { \"server\", \"period\" });\n\n// Close a parameter file.\nparam.close();\nSPIFFS.end();\n

    The example above saves server and period elements from the AutoConnectAux object as mentioned above to the /param file on SPIFFS. Its JSON document of AutoConnectElements saved by its code looks like this:

    [\n  {\n\"name\": \"server\",\n\"type\": \"ACInput\",\n\"value\": \"An inputted server name\",\n\"label\": \"Server\",\n\"placeholder\": \"\"\n  },\n  {\n\"name\": \"period\",\n\"type\": \"ACRadio\",\n\"value\": [\n\"30 sec.\",\n\"60 sec.\",\n\"180 sec.\"\n    ],\n\"arrange\": \"vertical\",\n\"checked\": 2\n  }\n]\n

    Above JSON document can be loaded as it is into a custom Web page using the loadElement function. The loadElement function also loads the value of the element, so the saved value can be restored on the custom Web page.

    "},{"location":"achandling.html#custom-field-data-handling","title":"Custom field data handling","text":"

    A sketch can access variables of AutoConnectElements in the custom Web page. The value entered into the AutoConnectElements on the page is stored in the member variable of each element by AutoConnect whenever GET/POST transmission occurs.

    The following diagram shows the flow of the input values of a custom Web page into a sketch and is the basis for actions to manipulate the values of custom Web pages using sketches.

    "},{"location":"achandling.html#where-to-pick-up-the-values","title":"Where to pick up the values","text":"

    A sketch composed of handlers can receive the value of AutoConnectElements entered in a custom Web page after sending, but that handler is different from the page where the value was entered. It is necessary to be aware that can accept the entered values by the next page handler after the transition.

    Usually, two ways to retrieve entered values we have. One is to use the ESP8266WebServer::arg (or WebServer::arg for ESP32) function in the on handler attached by ESP8266WebServer (WebServer w/ESP32 also).

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char addonJson[] PROGMEM = R\"raw(\n{\n  \"title\": \"Hello\",\n  \"uri\": \"/hello\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"feels\",\n      \"type\": \"ACInput\",\n      \"label\": \"What's up?\"\n    },\n    {\n      \"name\": \"send\",\n      \"type\": \"ACSubmit\",\n      \"value\": \"Just it!\",\n      \"uri\": \"/feels\"\n    }\n  ]\n}\n)raw\";\n\nESP8266WebServer webServer;\nAutoConnect portal(webServer);\n\n// Here, /feels handler\nvoid feelsOn() {\n\n// Retrieve the value of a input-box named \"feels\"\n  String feel = webServer.arg(\"feels\");\n// Echo back the value\n  String echo = \"<html><p style=\\\"color:blue;font-family:verdana;font-size:300%;\\\">\" + feel + String(\" and a bold world!</p></html>\");\n  webServer.send(200, \"text/html\", echo);\n}\n\nvoid setup() {\n  delay(1000);\n  webServer.on(\"/feels\", feelsOn);  // Register /feels handler\n  portal.load(addonJson);           // Load a custom Web page\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    An above example is the most simple sketch of handling values entered into a custom Web page. This sketch obtains the string entered in the AutoConnectInput named feels with the /feels handler after page transition, and the AutoConnectInput is an <input type=\"text\" name=\"feels\"> element wrapped in the form as the actual HTML code.

    Should be accessed /_ac first

    When you actually try the above sketch, there is no a root handler. So the URL that should be accessed first is /_ac concatenated with the local IP address of the esp8266 module.

    Another method is effective when custom Web pages have complicated page transitions. It is a way to straight access the AutoConnectElements member value. You can get the AutoConnectElement with the specified name using the getElement function. The following sketch executes the above example with AutoConnect only, without using the function of ESP8266WebServer.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nconst static char addonJson[] PROGMEM = R\"raw(\n[\n  {\n    \"title\": \"Hello\",\n    \"uri\": \"/hello\",\n    \"menu\": true,\n    \"element\": [\n      {\n        \"name\": \"feels\",\n        \"type\": \"ACInput\",\n        \"label\": \"What's up?\"\n      },\n      {\n        \"name\": \"send\",\n        \"type\": \"ACSubmit\",\n        \"value\": \"Just it!\",\n        \"uri\": \"/feels\"\n      }\n    ]\n  },\n  {\n    \"title\": \"Hello\",\n    \"uri\": \"/feels\",\n    \"menu\": false,\n    \"element\": [\n      {\n        \"name\": \"echo\",\n        \"type\": \"ACText\",\n        \"style\": \"color:blue;font-family:verdana;font-size:300%;\"\n      }\n    ]\n  }\n]\n)raw\";\n\nAutoConnect portal;\n\n// Here, /feels handler\nString feelsOn(AutoConnectAux& aux, PageArgument& args) {\n\n// Get the AutoConnectInput named \"feels\".\n// The where() function returns an uri string of the AutoConnectAux that triggered this handler.\n  AutoConnectAux* hello = portal.aux(portal.where());\n  AutoConnectInput& feels = hello->getElement<AutoConnectInput>(\"feels\");\n// Get the AutoConnectText named \"echo\".\n  AutoConnectText&  echo = aux.getElement<AutoConnectText>(\"echo\");\n// Echo back from input-box to /feels page.\n  echo.value = feels.value +  String(\" and a bold world!\");\nreturn String(\"\");\n}\n\nvoid setup() {\n  delay(1000);\n  portal.load(addonJson);                       // Load custom Web pages\n  portal.on(\"/feels\", feelsOn, AC_EXIT_AHEAD);  // Register /feels handler\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    The above example handles in the handler for the values of a custom Web page. An AutoConnect::on function registers a handler for the AutoConnectAux page of the specified uri. The argument of the custom Web page handler is an AutoConnectAux of the page itself and the PageArgument object.

    To retrieve the values entered in a custom Web page you need to access the AutoConnectElement of the page that caused the request to this page and to do this, you use the AutoConnect::where function. The AutoConnect::where function returns an uri string of the AutoConnectAux object of the custom Web page that caused the HTTP request.

    The where() function is available for only AutoConnectAux.

    The AutoConnect::where function is available only for the AutoConnectAux object. It is invalid for HTTP requests from individual pages registered with the on handler of ESP8266WebServer/WebServer for ESP32. In other words, the AutoConnect::where function only returns the last AutoConnecAux page called.

    "},{"location":"achandling.html#when-setting-the-initial-values","title":"When setting the initial values","text":"

    An AutoConnectAux page is dynamically created by AutoConnect when its uri is requested. The initial value of AutoConnectElements can be set before its page request. It is also possible during loop(). To set the initial value when the page is accessed it needs by the handler of its page.

    The AutoConnect::on and AutoConnectAux::on functions register a handler for a custom Web page and also specify when to call that handler. The behavior of the two on functions is the same, only the class and arguments are different.

    bool AutoConnect::on(const String& uri, const AuxHandlerFunctionT handler, AutoConnectExitOrder_t order)\n
    void AutoConnectAux::on(const AuxHandlerFunctionT handler, const AutoConnectExitOrder_t order)\n

    Parameter uri specifies an URI of the custom Web page, but an AutoConnectAux object with its URI must be registered with AutoConnect via the AutoConnect::join function beforehand.

    AutoConnect::on/AutoConnectAux::on is not ESP8266WebServer::on

    The on function for AutoConnect is different from the on function of Arduino core ESP8266WebServer (WebServer for ESP32). You can share the same handler via wrapper, but access to AutoConnectElements is valid only for handlers registered with on function for AutoConnect.

    AuxHandlerFunctionT type is a handler declaration using with std::function.

    String handler(AutoConnectAux& aux, PageArgument& args)\n

    The handler of the custom Web page has two arguments by a reference of AutoConnectAux and a reference of PageArgument, it returns String. AutoConnect appends the string returned from the handler to the generated HTML. This allows you to add an HTML part before displaying the page.

    AutoConnectExitOrder_t specifies when the handler is called with the following enumeration value.
    • AC_EXIT_AHEAD : Called before AutoConnect generates the HTML of the page. You set the value of AutoConnectElements in the handler then its value will be displayed on the page.
    • AC_EXIT_LATER : Called after AutoConnect generates the HTML of the page. You can append to HTML generated by AutoConnect.
    • AC_EXIT_BOTH : Called even before generating HTML and after generated.

    The following example is a part of sketch contained the handlers. 

    // AutoConnect object declarations\nACInput(input1);\nAutoConnectAux aux(\"/aux\", { input1 });\nAutoConnect portal;\n// Pre-declare handlers\nString initialize(AutoConnectAux&, PageArgument&);\nString append(AutoConnectAux&, PageArgument&);\n\n// Register handlers and launch the portal.\naux.on(initialize, AC_AHEAD);\naux.on(append, AC_LATER);\nportal.join(aux);\nportal.begin();\n\n// Some code here...\n\n// The handler called before HTML generating\nString initialize(AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectInput& input1 = aux.getElement<AutoConnectInput>(\"input1\");\n// Set initial value for the input box in a custom Web page.\n  input1.value = \"Initial value\";\n// Nothing appendix for a generated HTML.\nreturn String();\n}\n\n// The handler called after HTML generated\nString append(AutoConnectAux& aux, PageArgument& args) {\n// Append an HTML\nreturn String(\"<p>This text has been added.</p>\");\n}\n
    "},{"location":"achandling.html#how-you-can-reach-the-values","title":"How you can reach the values","text":"

    AutoConnectSubmit uses the POST method to send HTTP requests. A value of AutoConnectInput sent to the ESP8266 or ESP32 with POST is stored in the request body of the HTTP request: 

    POST /feels HTTP/1.1\nHost: ESP8266_IP_ADDRESS\nname1=value1&name2=value2&name3=value3\n
    ESP8266WebServer class will parse the query string and rebuilds its arguments when the above request arrives. A custom page handler registered with the ESP8266WebServer::on function can access the value of AutoConnectElements with ESP8266WebServe::arg function. It reaches the values of AutoConnectElements without the intermediation of AutoConnect. Therefore, its handler will not be AutoConnectAux and can send a response to the client directly. The following example is part of a server sketch which has two web pages. The /hello page is a custom Web page of AutoConnectAux which has an input box named \"input1\". Another /echo page is a page handler for ESP8266WebServer, which uses the ESP8266WebServer::send function to echo back the value of an input1 as an http response.

    ESP8266WebServer server;\nAutoConnect      portal(server);\nACInput(input1, \"\", \"INPUT\");\nACSubmit(send, \"HELLO\", \"/echo\");\nAutoConnectAux  aux(\"/hello\", { input1, send });\n\nserver.on(\"/echo\", []() {\n  String echo = server.arg(\"input1\");\n  Serial.println(echo);\n  server.send(200, \"text/plain\", echo);\n});\n\nportal.join(aux);\nportal.begin();\n

    Also, you can choose another way to access arguments without going through the ESP8266WebServer class. The PageArgument object of the custom Web page handler argument is a copy of the arg object of the ESP8266WebServer class. Either of these methods is a simple and easy way to access parameters in custom Web page handlers. However, if you need to access from outside of the handler to the value of AutoConnectElements, you need to accomplish it using with the AutoConnectAux::getElement function. The following sketch code replaces the above example with JSON and PageArgument, and its behaves is equivalent basically to the above sketch.

    const static char auxPage[] PROGMEM = R\"raw(\n[\n  { \"title\":\"Hello\", \"uri\":\"/hello\", \"menu\":true, \"element\":[\n    { \"name\":\"input1\", \"type\": \"ACInput\", \"label\": \"INPUT\" },\n    { \"name\":\"send\", \"type\":\"ACSubmit\", \"value\":\"HELLO\", \"uri\":\"/echo\" }]\n  },\n  { \"title\":\"Echo\", \"uri\":\"/echo\", \"menu\":false, \"element\":[\n    { \"name\":\"echo\", \"type\":\"ACText\" }]\n  }\n]\n)raw\";\n\nAutoConnect portal;\n\nportal.load(auxPage);\nportal.on(\"/echo\", [](AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectText& ac_echo = aux.getElement<AutoConnectText>(\"echo\");\n  ac_echo.value = args.arg(\"input1\");\nreturn String();  \n});\n\nportal.begin();\n
    "},{"location":"achandling.html#get-autoconnectelement-values-from-the-transition-source","title":"Get AutoConnectElement values from the transition source","text":"

    Usually, the page transition called by the custom web page handler will have an HTTP request directed to the destination URL. Its HTTP request has parameters enclosed by the POST method, all of which are AutoConnectElements placed on the transition source page. On the other hand, the custom web page handler's first argument points to AutoConnectAux after the transition, so the handler cannot access the AutoConnectElement values placed at the transition source using the first argument.

    Custom Web paga handler has two ways to access AutoConnectElements placed on the transition source page: combining the AutoConnect::where and AutoConnect::aux functions or using the AutoConnectAux::referer function. The following code snippet shows the difference between the two methods of identifying the input1 AutoConnectInput with the /echo page handler after the transition based on the /hello page described above.

    portal.on(\"/echo\", [](AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectAux&   ac_hello = *portal.aux(portal.where());\n  AutoConnectInput& ac_input1 = ac_hello[\"input1\"].as<AutoConnectInput>();\n  Serial.println(ac_input1.value);\nreturn String();  \n});\n
    portal.on(\"/echo\", [](AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectAux&   ac_hello = portal.referer();\n  AutoConnectInput& ac_input1 = ac_hello[\"input1\"].as<AutoConnectInput>();\n  Serial.println(ac_input1.value);\nreturn String();  \n});\n
    "},{"location":"achandling.html#transfer-of-input-values-across-pages","title":"Transfer of input values across pages","text":"

    Since v1.0.0, AutoConnect supports a new attribute with each element that allows automatic transfer of input values across pages without sketching. AutoConnect will copy the input value of the elements declared as global to the same-named global elements on a different custom Web pages at the page transition timing.

    The global attribute will be useful for echoing input values back to another custom Web pages. This copy operation can be performed between different types. (eg., copy value from AutoConnectInput to AutoConnectText) The following example reflects the input value of PAGE1 to the AutoConnectText field of PAGE2 without sketch code.

    static const char PAGE1[] PROGMEM = R\"(\n{\n  \"title\": \"PAGE1\",\n  \"uri\": \"/page1\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"input1\",\n      \"type\": \"ACInput\",\n      \"global\": true\n    },\n    {\n      \"name\": \"send\",\n      \"type\": \"ACSubmit\",\n      \"value\": \"OK\",\n      \"uri\": \"/page2\"\n    }\n  ]\n}\n)\";\nstatic const char PAGE2[] PROGMEM = R\"(\n{\n  \"title\": \"PAGE2\",\n  \"uri\": \"/page2\",\n  \"menu\": false,\n  \"element\": [\n    {\n      \"name\": \"input1\",\n      \"type\": \"ACText\",\n      \"global\": true\n    }\n  ]\n}\n)\";\n\nAutoConnect portal;\nAutoConnectAux page1;\nAutoConnectAux page2;\n\nvoid setup() {\n  page1.load(PAGE1);\n  page2.load(PAGE2);\n  portal.join( { page1, page2 });\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    The value entered in input1 declared in PAGE1 is reflected in input1 of PAGE2 as an AutoConnectText value even if there is no sketch code to transfer it to PAGE2. It's shown as like:

    Copy only for same-named and the global

    The input value will be copied only if the global attribute of the destination element is true. If an element with the same name is declared non-global, the value is not copied.

    "},{"location":"achandling.html#retrieve-the-values-with-webserveron-handler","title":"Retrieve the values with WebServer::on handler","text":"

    ESP8266WebServer class and the WebServer class assume that the implementation of the ReqestHandler class contained in the WebServer library will handle the URL requests. Usually, it is sketch code registered by ESP8266WebServer::on function.

    When a page transition from a custom Web page created by AutoConnectAux to a handler registered with ESP2866WebServer::on function, a little trick is needed to retrieve the values of AutoConnectElements. (i.e. the URI of the ESP8266WebServer::on handler is specified in the uri attribute of AutoConnectSubmit) AutoConnect cannot intervene in the procedure in which the ESP8266WebServer class calls the on-page handler coded with the Sketch. Therefore, it is necessary to retrieve preliminary the values of AutoConnectElements using the AutoConnectAux::fetchElement function for value processing with the on-page handler.

    The following sketch is an example of extracting values inputted on a custom web page with an on-page handler and then processing it.

    ESP8266WebServer server;\nAutoConnect portal(server);\nAutoConnectAux Input;\n\nconst static char InputPage[] PROGMEM = R\"r(\n{\n  \"title\": \"Input\", \"uri\": \"/input\", \"menu\": true, \"element\": [\n    { \"name\": \"input\", \"type\": \"ACInput\", \"label\": \"INPUT\" },\n    {\n      \"name\": \"save\",\n      \"type\": \"ACSubmit\",\n      \"value\": \"SAVE\",\n      \"uri\": \"/\"\n    }\n  ]\n}\n)r\";\n\n// An on-page handler for '/' access\nvoid onRoot() {\n  String  content =\n\"<html>\"\n\"<head><meta name='viewport' content='width=device-width, initial-scale=1'></head>\"\n\"<body><div>INPUT: {{value}}</div></body>\"\n\"</html>\";\n\n  Input.fetchElement();    // Preliminary acquisition\n// For this steps to work, need to call fetchElement function beforehand.\n  String value = Input[\"input\"].value;\n  content.replace(\"{{value}}\", value);\n  server.send(200, \"text/html\", content);\n}\n\nvoid setup() {\n  Input.load(InputPage);\n  portal.join(Input);\n  server.on(\"/\", onRoot);  // Register the on-page handler\n  portal.begin();  \n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"achandling.html#overwrite-the-autoconnectelements","title":"Overwrite the AutoConnectElements","text":"

    Sketches can update the attributes of AutoConnectElements with two approaches. A one is to assign directly to the attributes of a member variable of its element. The other is to overwrite them with loading the element by AutoConnectAux::loadElement.

    The elements for attributes described in the JSON document for AutoConnectElements overwrites the member variables of the target AutoConnectElements. However, AutoConnectAux::loadElement keeps the member variables unchanged if there is no element in the JSON document. This overwriting behavior is the same for the AutoConnect::load function.

    For example, the combination of the Sketch and JSON document as follows updates only the style while keeping Caption (ie. \"Hello, world\") as AutoConnectText value.

    External JSON document for the below sketch to modify the text style. 

    {\n\"name\" : \"Caption\",\n\"type\" : \"ACText\",\n\"style\": \"text-align:center;font-size:24px;font-family:'Impact','Futura',sans-serif;color:tomato;\"\n}\n

    the Sketch (a part of code), load above JSON. 

    ACText(Caption, \"Hello, world\");\nAutoConnectAux helloPage(\"/hello\", \"Hello\", true, { Caption });\nAutoConnect portal;\n\nString onHello(AutoConnectAux& aux, PageArgument& args) {\n  aux.loadElement(JSON);\nreturn String();\n}\n\nvoid setup() {\n  helloPage.on(onHello);\n  portal.join(helloPage);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    It's shown as like:

    "},{"location":"achandling.html#check-data-against-on-submission","title":"Check data against on submission","text":"

    By giving a pattern to AutoConnectInput, you can find errors in data styles while typing in custom Web pages. The pattern is specified with regular expression.2 If the value during input of AutoConnectInput does not match the regular expression specified in the pattern, its background color changes to pink. The following example shows the behavior when checking the IP address in the AutoConnectInput field.

    {\n\"title\" : \"Page-1\",\n\"uri\" : \"/page1\",\n\"menu\" : true,\n\"element\" : [\n    {\n\"name\" : \"Server\",\n\"type\" : \"ACInput\",\n\"label\": \"Server address\",\n\"pattern\": \"^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$\"\n    }\n  ]\n}\n

    It's shown as like:

    If you are not familiar with regular expressions, you may feel that description very strange. Matter of fact, it's a strange description for those who are unfamiliar with the formal languages. If your regular expression can not interpret the intended syntax and semantics, you can use an online tester. The regex101 is an exceptional online tool for testing and debugging regular expressions.

    "},{"location":"achandling.html#input-data-validation","title":"Input data validation","text":"

    The pattern attribute of AutoConnectInput only determines the data consistency on the web browser based on the given regular expression. In order to guarantee the validity of input data, it is necessary to verify it before actually using it.

    You can validate input data from AutoConnectInput using the isValid function before actually processing it. The isValid function determines whether the value currently stored in AutoConnectInput matches the pattern.

    You can also use the AutoConnectAux::isValid function to verify the data input to all AutoConnectInput elements on the custom Web page at once. The two sketches below show the difference between using AutoConnectInput::isValid and using AutoConnectAux::isValid. In both cases, it verifies the input data of the same AutoConnectInput, but in the case of using AutoConnectAux::isValid, the amount of sketch coding is small.

    "},{"location":"achandling.html#common-declaration","title":"Common declaration","text":"
    const char PAGE[] PROGMEM = R\"(\n{\n  \"title\": \"Custom page\",\n  \"uri\": \"/page\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"input1\",\n      \"type\": \"ACInput\",\n      \"pattern\": \"^[0-9]{4}$\"\n    },\n    {\n      \"name\": \"input2\",\n      \"type\": \"ACInput\",\n      \"pattern\": \"^[a-zA-Z]{4}$\"\n    }\n  ]\n}\n)\";\nAutoConnectAux page;\npage.load(PAGE);\n
    "},{"location":"achandling.html#using-autoconnectinputisvalid","title":"Using AutoConnectInput::isValid","text":"
    AutoConnectInput& input1 = page[\"input1\"].as<AutoConnectInput>();\nAutoConnectInput& input2 = page[\"input2\"].as<AutoConnectInput>();\nif (!input1.isValid() || !input2.isValid())\n  Serial.println(\"Validation error\");\n
    "},{"location":"achandling.html#using-autoconnectauxisvalid","title":"Using AutoConnectAux::isValid","text":"
    if (!page.isValid())\n  Serial.println(\"Validation error\");\n
    "},{"location":"achandling.html#convert-data-to-actually-type","title":"Convert data to actually type","text":"

    The values in the AutoConnectElements field of the custom Web page are all typed as String. A sketch needs to be converted to an actual data type if the data type required for sketch processing is not a String type. For the typical data type conversion method, refer to section Tips for data conversion.

    "},{"location":"achandling.html#place-html-elements-undefined-in-autoconnectelements","title":"Place HTML elements undefined in AutoConnectElements","text":"

    Of the many HTML elements for markup, AutoConnet can only support a limited number. If you are designing a custom web page and the elements you want are not in AutoConnectElements, consider using an AutoConnectElement. AutoConnectElement can be applied in many cases when trying to place HTML tag elements that are undefined in AutoConnectElemets on custom web pages.

    Not all of them work

    The strongest constraint is the heap size required to generate HTML for the entire custom Web page. AutoConnect creates a custom web page as a chunk of String. It's not a stream. Therefore, it may not be possible to generate long HTML pages. See also FAQ.

    "},{"location":"achandling.html#place-a-markup-or-a-styled-html-tag","title":"Place a markup or a styled HTML tag","text":"

    If the HTML element you want to place is just the tag that makes up the appearance of the web page, assign the tag element directly to the value member of AutoConnectElement. If the tag you are trying to place is for static markup effects, just write the value as follows:

    {\n\"name\": \"headline\",\n\"type\": \"ACElement\",\n\"value\": \"<hr style='height:1px;border-width:0;color:gray;background-color:#52a6ed'>\"\n}\n

    If the element has a hierarchy like a <table> ~ </table>, describe the entire element in the value:

    {\n\"name\": \"table\",\n\"type\": \"ACElement\",\n\"value\": \"<table><tr><th>Board</th><th>Platform</th></tr><tr><td>NodeMCU</td><td>Espressif8266</td></tr><tr><td>ESP32-DevKitC</td><td>Espressif32</td></tr></table>\"\n}\n

    Also, using AutoConnectStyle combined, you can give the style effect of only that element.

    {\n\"name\": \"tablestyle\",\n\"type\": \"ACStyle\",\n\"value\": \"table.style{font-family:arial,sans-serif;border-collapse:collapse;width:100%;color:black;}table.style td,table.style th{border:1px solid #dddddd;text-align:center;padding:8px;}table.style tr:nth-child(even){background-color:#dddddd;}\"\n},\n{\n\"name\": \"table\",\n\"type\": \"ACElement\",\n\"value\": \"<table class='style'><tr><th>Board</th><th>Platform</th></tr><tr><td>NodeMCU</td><td>Espressif8266</td></tr><tr><td>ESP32-DevKitC</td><td>Espressif32</td></tr></table>\"\n}\n

    As you see it: Board Platform NodeMCU Espressif8266 ESP32-DevKitC Espressif32

    "},{"location":"achandling.html#place-the-input-elements-within-a-form","title":"Place the input elements within a form","text":"

    There is still no dedicated AutoConnectElement for entering other than equivalent to checkbox, file, number, password, radio and text for <input type=\"...\"> HTML element. But you can substitute them with the AutoConnectElement.

    For example, if you use the <input> element of type=\"date\" to place a field where you can enter a date, the AutoConnectElement would look like this:

    {\n\"name\": \"date\",\n\"type\": \"ACElement\",\n\"value\": \"<label for='picker'>Date:</label><input type='date' id='picker' name='date'>\"\n}\n

    And it becomes a textbox that validates the input or a special date picker interface. Then, instead of accessing that AutoConnectElement directly, obtains entered date value from the POST body included in the HTTP request from the hosted ESP8266WebServer class. Its process carries out with the AutoConnectAux page handler following:

    String aux_page_handler(AutoConnectAux &aux, PageArgument &arg) {\n  Serial.println(arg.arg(\"date\"));  // Obtain a date value entered\nreturn \"\";\n}\n

    AutoConnect passes a PageArgument to the AutoConnectAux page handler. The handler can use the PageArgument::arg function to get the parameters contained in the HTTP request for the page. Also, the equivalent can also be implemented using ESP8266WebServer::arg function with the ESP8266WebServer client request handler.

    "},{"location":"achandling.html#using-javascript","title":"Using JavaScript","text":"

    What is described in this section belongs to the tips of what effectiveness a web page can have using AutoConnectElement, rather than the correct usage for AutoConnect. You can use AutoConnectElement to embed JavaScript into the custom Web page as with HTML elements for markup. The reason for embedding JavaScript on a page depends on your requirements, but One of the most common requirements is the need to access elements of a web page. You can implement the requirements by having the AutoConnectElement have JavaScript that contains DOM access.

    The following screenshot shows an example of accessing AutoConnectText via the DOM using an AutoConnectElement with JavaScript. This web page is a very simple example and returns the result of multiplying the multiplier entered in an AutoConnectInput field.

    This custom Web page is generated from the following JSON document:

    {\n\"uri\": \"/jselement\",\n\"title\": \"Multiply\",\n\"menu\": true,\n\"element\": [\n    {\n\"name\": \"multiplier\",\n\"type\": \"ACInput\",\n\"label\": \"3 &times; \",\n\"apply\": \"number\",\n\"posterior\": \"none\"\n    },\n    {\n\"name\": \"op\",\n\"type\": \"ACButton\",\n\"value\": \" = \",\n\"action\": \"multi()\",\n\"posterior\": \"none\"\n    },\n    {\n\"name\": \"answer\",\n\"type\": \"ACText\"\n    },\n    {\n\"name\": \"js\",\n\"type\": \"ACElement\",\n\"value\": \"<script type='text/javascript'>function multi() {document.getElementById('answer').innerHTML=3*document.getElementById('multiplier').value;}</script>\"\n    }\n  ]\n}  \n

    An input field for a multiplier is defined by AutoConnectInput. The field for displaying the results exists with the name answer. The multiplication function is what AutoConnectElement has as JavaScript and it has the following content:

    function multi() {\n  document.getElementById('answer').innerHTML = 3 * document.getElementById('multiplier').value;\n}\n

    And the action for calling the multi() function is the = labeled button as the AutoConnectButton element. AutoConnect generates the name attribute of each AutoConnectElement as the Id of the HTML tag. The Id should be useful for DOM access.

    JavaScript that is too long can cause insufficient memory

    If it reaches thousands of bytes, AutoConnect will not be able to complete the HTML generation for the page.

    "},{"location":"achandling.html#custom-web-pages-communication-without-page-transitions","title":"Custom Web pages communication without page transitions","text":"

    The request-response form typically provided by AutoConnectAux is based on stateless HTTP page transitions. Its communication between custom Web pages and sketches involves page transitions in the client browser via the request-response form. However, major Web browsers support HTTP asynchronous communication without page transitions. By embedding those Web APIs in your custom Web pages, you can implement sketches that do not disrupt the user working flow with page transitions.

    There are two types of Web APIs that allow asynchronous communication that can be used with AutoConnectAux:

    • XMLHttpRequest

      JavaScript embedded in a custom web page uses the XMLHttpRequest (XHR) objects to communicate with the request handler on the sketch side. A sketch typically embeds its JavaScript coded as a string value with AutoConnectElement into a custom web page JSON description.

      The request handler that is communication partner with the above JavaScript should be implemented in the sketch as the Client request handlers of the ESP8266WebServer (WebServer for ESP32) class.

      The procedure for implementing a sketch in this manner is described in a subsequent section.

    • Fetch API

      The Fetch API supported by AutoConnectAux is even easy to implement than XHR. AutoConnectElements can execute Fetch API-driven JavaScript that can communicate with the server sketch. Its script will be triggered by expected events and automatically be embedded into the HTML source of your custom web page by AutoConnect.

      Also, the sketch process with which the above Fetch API script communicates can access and update the values and properties of each AutoConnectElement. Updated AutoConnectElement contents are immediately reflected on the custom web page by sending a response.

      The Fetch API-driven approach based on AutoConnectElements event firing is described in the section of Interact with sketches by AutoConnectElements event.

    "},{"location":"achandling.html#communicate-with-the-sketch-using-xhr","title":"Communicate with the Sketch using XHR","text":"

    AutoConnectElement allows having scripts that make HTTP sessions based on XHR. XHR (XMLHttpRequest) is a JavaScript API to create AJAX requests. Its methods allow sending network requests between the browser and a server. The sketch implements the server-side process as a response handler to a standard HTTP request and can equip it with a dynamic custom Web page. This technique is tricky but is useful when implementing dynamic pages because it does not cause page transitions. As a matter of fact, AutoConnectOTA class is implemented with this technique and is a custom web page by AutoConnectAux using XHR.

    Here's a simple example of JavaScript-based on XHR and a server-side request handler. It's like a clock that displays the time in real-time on an AutoConnect custom web page. The sketch in the following example is roughly divided into two structures. The AutoConnectElement defined with the name js gets the server time with XHR and updates the response via the DOM with the AutoConnectText named time and substance is the following JavaScript:

    var xhr;\n\nfunction clock() {\nxhr.open('GET', '/clock');\nxhr.responseType = 'text';\nxhr.send();\n}\n\nwindow.onclose = function() {\nxhr.abort();\n};\n\nwindow.onload = function() {\nxhr = new XMLHttpRequest();\nxhr.onreadystatechange = function() {\nif (this.readyState == 4 && xhr.status == 200) {\n      document.getElementById('time').innerHTML = this.responseText;\n    }\n  };\nsetInterval(clock, 1000);\n};\n

    This script issues a GET request to /clock every second and updates the element of Id=time with the text content of its response. As this script shows, it will issue a send request using the XMLHttpRequest object.

    The other component is located on the AutoConnect-hosted ESP8266WebServer server. This component gets the current time from the NTP server and sends the value as text to the client.

    void auxClock() {\ntime_t  t;\nstruct tm *tm;\nchar    dateTime[24];\n\n  t = time(NULL);\n  tm = localtime(&t);\n  sprintf(dateTime, \"%04d/%02d/%02d %02d:%02d:%02d.\",\n                    tm->tm_year + 1900, tm->tm_mon + 1, tm->tm_mday,\n                    tm->tm_hour, tm->tm_min, tm->tm_sec);\n  server.send(200, \"text/plain\", dateTime);\n}\n

    Then just register the auxClock function as a /clock URL handler with the hosted ESP8266Server instance.

    server.on(\"/clock\", auxClock);\n

    As you can see from the above two components, AutoConnect does not intervene in those communications and no page transitions occur. A complete sketch that integrates the above components and includes a custom Web page declaration for time display looks like this:

    #include <Arduino.h>\n#include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n#include <time.h>\n\nstatic const char JSPAGE[] PROGMEM = R\"'(\n{\n  \"uri\": \"/jselement\",\n  \"title\": \"Clock\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"time\",\n      \"type\": \"ACText\"\n    },\n    {\n      \"name\": \"js\",\n      \"type\": \"ACElement\",\n      \"value\": \"<script type='text/javascript'>var xhr;function clock(){xhr.open('GET', '/clock');xhr.responseType='text';xhr.send();}window.onclose=function(){xhr.abort();};window.onload=function(){xhr=new XMLHttpRequest();xhr.onreadystatechange=function(){if(this.readyState==4&&xhr.status==200){document.getElementById('time').innerHTML=this.responseText;}};setInterval(clock,1000);};</script>\"\n    }\n  ]\n}  \n)'\";\n\nESP8266WebServer  server;\nAutoConnect portal(server);\n\nvoid auxClock() {\ntime_t  t;\nstruct tm *tm;\nchar    dateTime[24];\n\n  t = time(NULL);\n  tm = localtime(&t);\n  sprintf(dateTime, \"%04d/%02d/%02d %02d:%02d:%02d.\",\n                    tm->tm_year + 1900, tm->tm_mon + 1, tm->tm_mday,\n                    tm->tm_hour, tm->tm_min, tm->tm_sec);\n  server.send(200, \"text/plain\", dateTime);\n}\n\nvoid setup() {\n  delay(1000);\n  portal.load(FPSTR(JSPAGE));\nif (portal.begin()) {\n    server.on(\"/clock\", auxClock);\n    configTime(0, 0, \"europe.pool.ntp.org\");\n  }\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"achandling.html#interact-with-sketches-by-autoconnectelements-event","title":"Interact with sketches by AutoConnectElements event","text":"

    AutoConnectAux supports Fetch API besides XMLHttpRequest for communication between the client browser and the ESP module. This allows your sketches to get and change values and properties of AutoConnectElements without a page transition on the browser. The changed values and properties are immediately reflected in the page currently being viewed in the browser.

    The following screenshot shows that a custom web page using the Fetch API can blink the LED on the ESP module without any page transitions. And it allows the custom web page changes the text color and button caption in sync with the LED flashing.

    The sketch implemented for the above demonstration does not need to write JavaScript code to handle the Fetch API. Its Fetch API script will automatically be embedded in the HTML source of your custom web page by AutoConnect. All you need to do is describe your custom web page in JSON and write AutoConnectElements event handlers to apply to user interaction.

    How to sketch with the AutoConnectElements events is covered in detail in chapter Interact with Sketch and AutoConnectElements.

    "},{"location":"achandling.html#transitions-of-the-custom-web-pages","title":"Transitions of the custom Web pages","text":""},{"location":"achandling.html#scope-lifetime-of-autoconnectaux","title":"Scope & Lifetime of AutoConnectAux","text":"

    AutoConnectAux and AutoConnectElements must live while the custom Web pages are available. The implementation of the custom Web page inherits from requestHandler driven from ESP8266WebServer (WebServer for ESP32), so the instance of AutoConnectAux and AutoConnectElements must exist for the duration of effect of handleClient. The following example is incorrect for manipulating custom Web pages. Its AutoConnectAux instance will be destructed at the exit of the setup().

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const auxPage[] PROGMEM = R\"raw(\n{\n  \"title\": \"Page-1\",\n  \"uri\": \"/page1\",\n  \"menu\": true,\n  \"element\": [\n    { \"name\":\"Server\", \"type\":\"ACText\", \"label\":\"Server address\" }\n  ]\n}\n)raw\";\n\nAutoConnect  portal;\n\nvoid setup() {\n// This declaration is wrong.\n  AutoConnectAux aux;\n  aux.load(auxPage);\n  portal.join(aux);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"achandling.html#the-uri-of-the-custom-web-pages","title":"The URI of the custom Web pages","text":"

    The transition of the custom Web page follows the URI of the page, but the ESP8266WebServer class does not know the URI of an AutoConnectAux page. (Registering a custom Web page does not use the ESP8266WebServer::on/WebServer::on function.) Therefore ESP8266WebServer class does not detect its URI access. If you want to detect an http request to AutoConnectAux's custom Web page, you need to register its URI with the AutoConnectAux::on function.

    In addition to this, there are restrictions in the handler for the custom Web page as shown in the following section.

    "},{"location":"achandling.html#an-http-response-from-the-custom-web-page-handler","title":"An HTTP response from the custom Web page handler","text":"

    Normally, a custom web page handler does not need to respond to a request from the client. Its HTTP response will be sent by AutoConnect when it returns from the custom web page handler. In that case, the HTTP response code is 200.

    However, this structure requires AutoConnectAux to always respond with the page content. If AutoConnectAux does not have page content as an HTTP response, then the custom web page handler can respond with its own HTTP response by following the steps:

    1. Declare an AutoConnectAux with the responsive argument set to false, or describe \"response\":false with JSON:

      AutoConnectAux aux(\"/aux\", \"AUX\", false, {}, false);\n
      {\n\"title\": \"AUX\",\n\"uri\": \"/aux\",\n\"response\": false,\n\"menu\": false\n}\n

    2. Send an HTTP response from a custom web page handler (Case of ESP32):

      WebServer   server;\nAutoConnect portal(server);\n\nString handleAux(AutoConnectAux& aux, PageArgument& args) {\n  server.send(202, \"text/plain\", \"Accepted\");\nreturn String();\n}\n\nportal.on(\"/aux\", handleAux);\n
      If you want to respond with a 302 from a custom web page handler, you can use the AutoConnectAux::redirect function. 
      String handleAux(AutoConnectAux& aux, PageArgument& args) {\n  aux.redirect(\"http://redirect.url:port/?query\");\nreturn String();\n}\n

    "},{"location":"achandling.html#limitations","title":"Limitations","text":"

    The custom Web pages handler has the following limitations.

    • Do not send HTTP responses from the handler.

      If the handler returns its own response, the custom Web page will be lost.

    • Use AutoConnectSubmit whenever possible.

      AutoConnect will hold the values of a custom Web Page is sent by AutoConnectSubmit.

    • Can not handle the custom Web pages during a connection is not established yet.

      During the connection attempt, the web browser of the client will send a probe for a captive portal. Its request will cause unintended custom Web page transitions.

    • Can not place URI of the custom Web pages to AUTOCONNECT_URI.

      AutoConnect will not work if you place a custom Web page to AUTOCONNECT_URI.

    • Can not use the element named SUBMIT.

      You can not use 'SUBMIT' as the element name of AutoConnectElements in a custom Web page that declares the AutoConnectSubmit element. (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.

    Do not handle for the same page

    Do not duplicate AutoConnect::on with ESP8266WebServer::on (also WebServer::on) for the same custom web page.

    1. The valid scope of the name is within an AutoConnectAux.\u00a0\u21a9

    2. Regular expression specification as a pattern of AutoConnectInput is JavaScript compliant.\u00a0\u21a9

    "},{"location":"acinteract.html","title":"Interact between Sketch and AutoConnectElements","text":""},{"location":"acinteract.html#interaction-with-autoconnectelements-wo-page-transition","title":"Interaction with AutoConnectElements w/o page transition","text":"

    The substance of the custom web page deployed by AutoConnectAux is just HTML content; AutoConnectAux is just a request handler conforming to the RequestHandler class of the ESP8266 and ESP32 Arduino core's WebServer library.

    Therefore, the request-response form typically provided by AutoConnectAux is based on stateless HTTP page transitions. Its communication between custom Web pages and sketches involves page transitions in the client browser via the request-response form.

    However, major Web browsers support HTTP asynchronous communication without page transitions. By embedding those Web APIs in your custom web pages, you can implement sketches that do not disrupt the user working flow with page transitions.

    AutoConnectAux allows the custom web page to use two types of Web APIs for asynchronous communication with the sketch. Both methods can be accomplished by having JavaScript inherent in the custom web page to communicate with the server sketch (i.e., the AutoConnectAux event handler).

    • XMLHttpRequest

      JavaScript embedded in a custom web page uses the XMLHttpRequest (XHR) objects to communicate with the request handler on the sketch side. A sketch typically embeds its JavaScript coded as a string value with AutoConnectElement into a custom web page JSON description.

      The request handler that is communication partner with the JavaScript should be implemented in the sketch as the Client request handlers of the ESP8266WebServer (WebServer for ESP32) class.

      The procedure for implementing a sketch in this manner is covered in Communicate with the Sketch using XHR section.

    • Fetch API

      The Fetch API supported by AutoConnectAux is even easy to implement than XHR. AutoConnectElements can execute Fetch API-driven JavaScript that can communicate with the server sketch. Its script will be triggered by expected events and automatically be embedded into the HTML source of your custom web page by AutoConnect.

      Also, the sketch process with which the Fetch API scripts communicates can access and update the values and properties of each AutoConnectElement. Updated AutoConnectElement contents are immediately reflected on the custom web page by sending a response.

      This section describes a Fetch API-driven approach based on AutoConnectElements event firing and the specific API for the sketch implementation.

      No retries around Fetch API handling

      The JavaScript containing the Fetch API that AutoConnect automatically embeds in custom web pages does not include retry handling. If the connection with the ESP module is unstable, the request will be reset by the client browser without completing the HTTP transmission/reception. However, the state may be difficult to understand at first glance, and the user may not be able to immediately determine what has happened.

      When applying the Fetch API on the AutoConnect custom web page, it is recommended to keep the amount of communication as low as possible.

    "},{"location":"acinteract.html#interact-with-sketches-by-autoconnectelements-event","title":"Interact with sketches by AutoConnectElements event","text":"

    Interaction between AutoConnectElements and sketch without page transitions is very smooth. It allows you to complete data exchange with ESP modules on the same page without interrupting your work.

    The figure below illustrates what a custom web page without page transitions looks like in action. It's a screen capture of a custom web page behavior that controls a simple LED blink (like \"hello, world\\n\" for The C Programming Language), and contains only a caption as AutoConnectText and a button as AutoConnectButton to turn on or off LED.

    The LED ON/OFF button as AutoConnectButton used in this sketch handles the HTML element click event to send the current value to the ESP module. The receiver sketch changes the LED signal level according to the received value and responds to the client with the button's display text and caption color. These send-and-receive exchanges are attribute names and values for AutoConnectButton and AutoConnectText. This sketch handles these actions with the standard HTTP POST method without causing a page transition.

    The following sections describe APIs and programming methods for interacting with custom web pages with no page transitions, following the sketch structure that implements the above figure.

    "},{"location":"acinteract.html#associate-events-with-autoconnectelements","title":"Associate events with AutoConnectElements","text":"

    Custom web pages derived by AutoConnectAux are regular HTML, so it can contain JavaScript that responds to DOM events. The reason why the sketch above figure does not cause a page transition is that the click event with the AutoConnectButton is trigged to send an HTTP POST to the sketch running in the ESP module using the Fetch API.

    AutoConnect automatically inserts JavaScript that communicates via the Fetch API in response to events if AutoConnectElements with registered an event handler is present on the custom web page. The following code is the JSON description of the custom web page shown above. It is no different from the page description with no event handling.

    const char LED_ONOFF[] PROGMEM = R\"(\n{\n  \"uri\": \"/led\",\n  \"title\": \"LED\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"caption\",\n      \"type\": \"ACText\",\n      \"value\": \"BUILT-IN LED\",\n      \"style\": \"font-weight:bold;font-size:25px;text-align:center;\",\n      \"posterior\": \"div\"\n    },\n    {\n      \"name\": \"onoff\",\n      \"type\": \"ACButton\",\n      \"value\": \"ON\"\n    }\n  ]\n}\n)\";\n

    All you need to do is write your custom web page in JSON and write event handlers for AutoConnectElements that apply to user interactions.

    "},{"location":"acinteract.html#allow-autoconnectelements-to-have-event-processing","title":"Allow AutoConnectElements to have event processing","text":"

    AutoConnect will automatically embed the JavaScript into the HTML that communicates with a server-side sketch using the Fetch API if the custom web page has AutoConnectElements with an event handler. Use the on function to allow the event-handling capability to elements used for the interaction with the user.

    To give your custom web page the ability to handle events using Fetch API, roughly follow these steps:

    1. Declare AutoConnectElements for user interaction. It can be declared directly using the constructor of each element or embedded in the JSON description. This procedure is no different from the definition in custom web pages.

    2. Identify elements that allow events after loading a custom web page. Usually, you use the AutoConnectAux::getElement function (or override operator []) accompanied by the AutoConnect::aux or AutoConnect::locate for this. This function takes the element name as an argument and returns a reference to an instance of AutoConnectElements.

      AutoConnect portal;\n\nportal.load(FPSTR(LED_ONOFF));\nAutoConnectAux& led = portal.locate(\"/led\");\nAutoConnectButton& onOff = led[\"onoff\"].as<AutoConnectButton>();\n

    3. Register the event handler with the AutoConnectElement::on function.

      onOff.on(ledOnOff);\n

    4. Write an event handler with the sketch. The event handler will be passed a reference to the instance of AutoConnectElements where the event occurred and a reference to AutoConnectAux. The event handler can use these parameters to receive the element's value of the event occurrence and perform processing according to that value. You can also give attributes such as new values and styles of other elements as return values. Use the AutoConnectElement::response function to set the return values.

      // Event handler that attaches to an AutoConnectButton named `led`.\n// This event handler receives a reference to AutoConnectButton as `led`\n// and a reference to the AutoConnectAux of the page rendered in the client\n// browser.\nvoid ledOnOff(AutoConnectButton& me, AutoConnectAux& ledOnOff) {\nif (me.value == \"ON\") {\n// Since \"ON\" has been passed from the AutoConnectButton as `led`. Let the\n// LED turns on.\n    digitalWrite(LED_BUILTIN, HIGH);\n// Direct assignment to AutoConnectElement values is not reflected on the\n// web page; use the `response` function to update the value of the element\n// on the web page.\n    me.response(\"OFF\");\n// The `on` event handler attached to AutoConnectElements can override the\n// value and attributes of other elements placed on that AutoConnectAux page.\n// For example, a following statement changes the font color of the `caption`\n// element along with a LED blinking.\n    ledOnOff[\"caption\"].response(\"style\", \"{\\\"color\\\":\\\"red\\\"}\");\n  }\nif (me.value == \"OFF\") {\n// Since a value \"OFF\" has been passed from the AutoConnectButton as `led`.\n// Let the LED turns off.\n    digitalWrite(LED_BUILTIN, LOW);\n    me.response(\"ON\");\n    ledOnOff[\"caption\"].response(\"style\", \"{\\\"color\\\":\\\"black\\\"}\");\n  }\n}\n
    "},{"location":"acinteract.html#register-event-handling-for-autoconnectelements","title":"Register Event handling for AutoConnectElements","text":"

    The on function catches different events for each AutoConnectElements1. There are also types of AutoConnectElements for which event handling cannot be registered. The syntax of the on function is as follows:

    void AutoConnectElements::on(eventHandler)

    AutoConnectElements that can catch events and the types of events are as follows:

    Available elements for Event Event type The moment the event occurs AutoConnectButton click Mouse click (only primary button) AutoConnectCheckbox change When an element is checked or unchecked AutoConnectInput change When the element loses focus after its value was changed AutoConnectRadio change When an element is checked (but not when unchecked) AutoConnectSelect change When the user commits the change explicitly

    The eventHandler parameter specifies the function that handles the event.

    "},{"location":"acinteract.html#event-handling-for-autoconnectelements","title":"Event handling for AutoConnectElements","text":""},{"location":"acinteract.html#event-handler-function","title":"Event handler function","text":"

    void eventHandler(AutoConnectElements& me, AutoConnectAux& aux)

    AutoConnectElements1 is actually one of the types listed in the table above for which the event is available. A reference to the element itself and to the AutoConnectAux to which it belongs is passed to the event handler. For example, to receive an event when an AutoConnectRadio named radio changes its checked state by mouse clicking, declare a function like onChangeRadio as follows:

    void onChangeRadio(AutoConnectRadio& me, AutoConnectAux& aux)\n

    Then use the AutoConnectRadio::on function to register the onChangeRadio handler function with the radio instance of AutoConnectRadio.

    AutoConnectRadio radio(\"radio\", {\"Huey\", \"Dewey\", \"Louie\"}, \"Select one\");\n...\nradio.on(onChangeRadio);\n

    AutoConnectElements1 will handle events if an event handler is registered with the on function. AutoConnect automatically inserts a script containing the Fetch API in the HTML generation of your custom web page when an element with an event handler function is registered.

    A type of event source and type of event handler argument is always the same

    The first argument of the event handler will contain a reference to an instance of an actual AutoConnectElements that is source of the event. So, the type of AutoConnectElements that registers the event handler and the type passed to the event handler are always the same. For example, the type of the first argument of the handler that receives the change event of AutoConnectText is the type of AutoConnectText itself.

    "},{"location":"acinteract.html#data-sent-with-the-event","title":"Data sent with the event","text":"

    When the custom web page catches the event, the script inserted by AutoConnect uses the Fetch API to send the value of each AutoConnectElements on the page to the ESP module. This script sends the value of each element as form data via HTTP POST.

    The data sent in this behavior is the same as the data transmission form with page transitions with AutoConnectSubmit. Then AutoConnect will store the transmitted data in the actual instance of AutoConnectElements before control is passed to the user sketch. Details of this behavior are covered in the section Custom field data handling.

    So in your sketch, you can unconsciously access the value of each AutoConnectElements of the custom web page where the event occurred in the event handler function. A reference to the element where the event originated is passed as the first argument, and a reference to the custom web page where the event triggered as the second argument.

    "},{"location":"acinteract.html#make-responses","title":"Make responses","text":"

    Responses to an HTTP POST request triggered by the event will be returned by AutoConnect at the end of the event handler function. The event handler continues processing until it exits, depending on the situation. For example, the event handler that controls the LED on/off described above (i.e., ledOnOff function) responds to the requested HTTP POST by setting the signal level to the LED_BUILTIN port to conform to the sent value of the AutoConnectButton by the event. It then rewrites the button's label with the new value.

    Use the response function for this. The response function has the effect of communicating the contents of AutoConnectElements updated by the event handler to the client browser. In the actual event handler, you should call the response as a member function of AutoConnectElements and specifies the instance of the element that will return the response. For example, to update the value of an AutoConnectText named caption on a page according to the LED ON/OFF control above, the code would look like this:

    ...\n\nACButton(onoff, \"ON\");\nACText(caption, \"LED OFF\");\n...\n\nvoid eventHandler(AutoConnectButton& me, AutoConnectAux& aux) {\n\n...\n\nif (me.value == \"OFF\") {\n    digitalWrite(LED_BUILTIN, LOW);\n    me.response(\"ON\");\n    caption.response(\"LED OFF\");\n  }\nif (me.value == \"ON\") {\n    digitalWrite(LED_BUILTIN, HIGH);\n    me.response(\"OFF\");\n    caption.response(\"LED ON\");\n  }\n\n...\n\n}\n

    The AutoConnectButton::response function rewrites the value attribute and innerHTML property of the onoff element (i.e. button type=\"button id=\"onoff\" node) on the page, while the AutoConnectText::response function rewrites only the innerHTML property of the div or span DOM node on the page. In this way, the value returned by response differs depending on the type of AutoConnectElements that generated the event. The following table shows which attributes of elements on the page the response(const char*) function affects.

    Available AutoConnectElement::response functions Attributes to rewrite AutoConnectButton::response value for the HTMLButtonElementinnerHTML for the HTMLButtonElement node AutoConnectCheckbox::response checked for <input type=\"checkbox\"> AutoConnectInput::response value for the HTMLInputElement AutoConnectText::response innerHTML for the <div> or <span> node

    When the response function updates the value of AutoConnectElements

    The response function also updates the value of the element's instance. For example, AutoConnectText::response function, in addition to sending the text to be updated to the client browser, also updates the value member of the sketch's AutoConnectText variable. However, that update process is done by AutoConnect at the exit of the event handler function.

    So, in the event handler function, even if you execute the response function, the value of AutoConnectElements will be kept as it was before the event occurred.

    Each AutoConnectElements has another response function that takes two arguments. The response(const char*) function updates the value of that element, while the response(const char*, const char*) function with two arguments updates the specified attribute or property and is used to change attributes of an element other than its value. For example, citing the LED ON/OFF example above, you can change the button background color according to the LED lighting state using the response function that takes two arguments.

    To change the button background color via an event handler when an event fires, specifies a String of a response form that allows direct access to the inline styles property of the button element using the CSSStyleDeclaration object.

    In this case, specify the property name of the HTML element to be changed in the first argument of the response function and the value to be changed in the second argument. This specification format conforms to object literals in JavaScript and can be expressed in JSON as follows:

    { style: { backgroundColor: 'red' }}\n

    So, specify style as the property part of the above syntax to the first argument of the response function and the nested {backGroundColor:\"red\"} part to the second argument.

    response(\"style\", \"{backGroundColor:\\\"red\\\"}\");\n

    If the property to be changed is not a nested object property like an inline style, the second argument can be the property value as it is. For example:

    response(\"placeholder\", \"Enter name\");\n

    Also, even if you give a boolean value, specify it as a string in the argument to the response function. AutoConnect automatically converts \"true\"/\"false\" as strings to booleans. For example:

    response(\"hidden\", \"true\");\n
    "},{"location":"acinteract.html#overall-the-led-control-sketch","title":"Overall the LED control sketch","text":"

    Based on the explanation so far, the following sketch is the implementation of the custom web page shown in the opening figure.

    #include <Arduino.h>\n#include <WiFi.h>\n#include <WebServer.h>\n#include <AutoConnect.h>\n\nconst char LED_ONOFF[] PROGMEM = R\"(\n{\n  \"uri\": \"/led\",\n  \"title\": \"LED\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"caption\",\n      \"type\": \"ACText\",\n      \"value\": \"BUILT-IN LED\",\n      \"style\": \"font-weight:bold;font-size:25px;text-align:center;\",\n      \"posterior\": \"div\"\n    },\n    {\n      \"name\": \"onoff\",\n      \"type\": \"ACButton\",\n      \"value\": \"ON\"\n    }\n  ]\n}\n)\";\n\nAutoConnect portal;\nAutoConnectConfig config;\n\n// Event handler that attaches to an AutoConnectButton named `led`.\n// This event handler receives a reference to AutoConnectButton as `led`\n// and a reference to the AutoConnectAux of the page rendered in the client\n// browser.\nvoid ledOnOff(AutoConnectButton& me, AutoConnectAux& ledOnOff) {\nif (me.value == \"ON\") {\n\n// Since \"ON\" has been passed from the AutoConnectButton as `led`. Let the\n// LED turns on.\n    digitalWrite(LED_BUILTIN, HIGH);\n\n// Direct assignment to AutoConnectElement values is not reflected on the\n// web page; use the `response` function to update the value of the element\n// on the web page.\n    me.response(\"OFF\");\n// The `on` event handler attached to AutoConnectElements can override the\n// value and attributes of other elements placed on that AutoConnectAux page.\n// For example, a following statement changes the font color of the `caption`\n// element along with a LED blinking.\n    ledOnOff[\"caption\"].response(\"style\", \"{\\\"color\\\":\\\"red\\\", \\\"font-weight\\\":\\\"bold\\\"}\");\n  }\nif (me.value == \"OFF\") {\n// Since a value \"OFF\" has been passed from the AutoConnectButton as `led`.\n// Let the LED turns off.\n    digitalWrite(LED_BUILTIN, LOW);\n    me.response(\"ON\");\n    ledOnOff[\"caption\"].response(\"style\", \"{\\\"color\\\":\\\"black\\\", \\\"font-weight\\\":\\\"normal\\\"}\");\n  }\n}\n\nvoid setup() {\n  delay(500);\n  Serial.begin(115200);\n  Serial.println();\n\n// Built-in LED port setting up\n  pinMode(LED_BUILTIN, OUTPUT);\n  digitalWrite(LED_BUILTIN, LOW);\n\n// Configure AutoConnect connection behavior.\n// Various configurations depending on the demands of your situation.\n  config.autoReconnect = true;\n  portal.config(config);\n\n// Load the AutoConnectAux page with the LED ON/OFF button into AutoConnect.\n// The sketch can get its instance using the AutoConnect::locate function\n// after AutoConnectAux is loaded.\n  portal.load(FPSTR(LED_ONOFF));\n  AutoConnectAux& led = portal.locate(\"/led\");\n\n// The AutoConnectElement::on function allows the sketch to register an event\n// handler that interacts with the element individually.\n  AutoConnectButton& onOff = led[\"onoff\"].as<AutoConnectButton>();\n  onOff.on(ledOnOff);\n// Start a portal\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    Above custom web page features two major AutoConnectElements:

    • caption: AutoConnectText

      Shows the current LED lighting state. The font color also reflects this status. To change the font color, use the response function for the caption element according to the value of the AutoConnectButton named onoff in the event handler.

      ledOnOff[\"caption\"].response(\"style\", \"{\\\"color\\\":\\\"red\\\", \\\"font-weight\\\":\\\"bold\\\"}\");\n

    • onoff: AutoConnectButton

      LED lighting switch placed on the custom web page. Interact with an event handler of the server sketch by catching click events on the browser. The event handler function name is ledOnOff. Register an event handler with the AutoConnectButton::on function to catch a click event on the onoff element as an AutoConnectButton.

      AutoConnectButton& onOff = led[\"onoff\"].as<AutoConnectButton>();\nonOff.on(ledOnOff);\n

      In the event handler, you can get the current value of the onoff through the reference to AutoConnectButton, which is the first argument as me.

      if (me.value == \"ON\") {\n  digitalWrite(LED_BUILTIN, HIGH);\n}\n

      The label on the onoff button indicates the instruction to turn the LED signal. So the content will be the opposite of the LED lighting state. Use the AutoConnectButton::response function to rewrite the label.

      me.response(\"OFF\");\n

    1. AutoConnectElements is a generic term for elements handled by custom web pages. They are actually replaced by types such as AutoConnectInput or AutoConnectText etc.\u00a0\u21a9\u21a9\u21a9

    "},{"location":"acintro.html","title":"Custom Web pages with AutoConnect","text":""},{"location":"acintro.html#what-it-is","title":"What it is","text":"

    AutoConnect can handle custom Web pages prepared by user sketches individually. Custom Web pages can be integrated into the AutoConnect menu and executed as menu items and can have input-output parameters and handle them.

    For example, you can program some sketches that publish messages by entering the URI or unique ID of the MQTT broker on a custom page. You do not need to code the processing to handle the web page. It retrieves the input parameters and passes to the MQTT broker connection API is only.

    "},{"location":"acintro.html#how-it-works","title":"How it works","text":"

    AutoConnect creates the custom Web pages dynamically at runtime. Sketch describes the custom Web pages using classes and APIs necessary for dynamic creation which are AutoConnectAux and the variant of AutoConnectElements. AutoConnectAux is an object dependent on AutoConnect, which provides an easy way to incorporate custom Web pages into AutoConnect like the one on the right figure. The elements make up a custom Web page are provided as an AutoConnectElement class.

    Furthermore, an input box, a check box, a submit button, etc. are implemented by classes derived from AutoConnectElement.

    AutoConnectAux is a container for AutoConnectElements. To make a custom Web page, create elements that make up the page and put it in the AutoConnectAux object. Joining its AutoConnectAux object to AutoConnect will integrate the custom Web page into the AutoConnect menu.

    The above figure shows a code sequence that declares AutoConnectElements and put in the AutoConnectAux container and integrates those into AutoConnect. It declares two text elements named header and caption, adds them to the AutoConnectAux object as aux, binds to an AutoConnect object named portal. This sequence is the basic procedure for creating custom Web pages with the Sketch. The further explanation is available in section AutoConnectElements also.

    "},{"location":"acintro.html#custom-web-pages-in-autoconnect-menu","title":"Custom Web pages in AutoConnect menu","text":"
    • AutoConnect integrates custom Web page objects into menus as AutoConnectAux. The AutoConnectAux object contains URI and title as member variables and has an indicator to display in the AutoConnect menu.You give the title and URI of the custom Web page to the AutoConnectAux object with Sketch. Then the title of the custom Web page would be displayed in the AutoConnect menu as the left figure.1 It is a hyperlink to a custom Web page which will be displayed tapped it.
    "},{"location":"acintro.html#multiple-custom-web-pages","title":"Multiple custom Web pages","text":"

    You can create multiple custom Web pages and specify pages that can be called from the menu. The following sketch shows a code sequence for integrating three custom Web pages into one and embedding them in a menu.

    • In the above code, the third parameter of aux2 is false. The third parameter of the AutoConnectAux constructor is an indicator for whether it's shown to the AutoConnect menu. Right animation is an execution result of the above code. You will see that the menu applies only two items for three custom Web pages. the Sketch of this animation is written to transition to aux2 by the utility of the AutoConnectSubmit element owned by aux1.2The aux2 page transitions only from the aux1 page. As shown in mqttRSSI in the library example, its page replies the saving result for the parameters entered on the previous page. It can not be invoked directly from the menu and want to hide them with AutoConnect menu items. The utility of the third parameter of the AutoConnectAux constructor is that.

    "},{"location":"acintro.html#basic-steps-to-use-custom-web-pages","title":"Basic steps to use custom Web pages","text":"

    So, the basic procedure for handling of the custom Web pages is as follows:

    1. Create or define AutoConnectAux.
    2. Create or define AutoConnectElement(s).
    3. Add AutoConnectElement(s) to AutoConnectAux.
    4. Create more AutoConnectAux containing AutoConnectElement(s), if necessary.
    5. Register the request handlers for the custom Web pages.
    6. Join prepared AutoConnectAux(s) to AutoConnect.
    7. Invoke AutoConnect::begin().
    8. Perform AutoConnect::handleClient().
    "},{"location":"acintro.html#write-the-custom-web-page-with-json","title":"Write the custom Web page with JSON","text":"

    You can write the custom Web page in JSON without using sketch codes.3 It is possible to describe the entire page in JSON and can be described for each element also. The JSON document can be saved in SPIFFS or SD and read using AutoConnect's load function. you can reduce the steps of the basic procedure with this approach, but this way consumes a lot of memory. The following JSON code and sketch will execute the custom Web page as an example in the above figure. That is, the Sketch of this code and footnote2 is equivalent.

    custom_page.json 

    [\n  {\n\"title\": \"MQTT Setting\",\n\"uri\": \"/mqtt_setting\",\n\"menu\": true,\n\"element\": [\n      {\n\"name\": \"header\",\n\"type\": \"ACText\",\n\"value\": \"MQTT broker settings\"\n      },\n      {\n\"name\": \"caption1\",\n\"type\": \"ACText\",\n\"value\": \"Publishing the WiFi...\"\n      },\n      {\n\"name\": \"save\",\n\"type\": \"ACSubmit\",\n\"value\": \"SAVE\",\n\"uri\": \"/mqtt_save\"\n      }\n    ]\n  },\n  {\n\"title\": \"MQTT Setting\",\n\"uri\": \"/mqtt_save\",\n\"menu\": false,\n\"element\": [\n      {\n\"name\": \"caption2\",\n\"type\": \"ACText\",\n\"value\": \"Save parameters\"\n      },\n      {\n\"name\": \"start\",\n\"type\": \"ACSubmit\",\n\"value\": \"START\",\n\"uri\": \"/mqtt_start\"\n      }\n    ]\n  },\n  {\n\"title\": \"MQTT Start\",\n\"uri\": \"/mqtt_start\",\n\"menu\": true,\n\"element\": []\n  }\n]\n

    the Sketch 

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <FS.h>\n#include <AutoConnect.h>\n\nAutoConnect  portal;\n\nvoid setup() {\n  SPIFFS.begin();\n\n  File page = SPIFFS.open(\"/custom_page.json\", \"r\");\n  portal.load(page);\n  page.close();\n  SPIFFS.end();\n\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    "},{"location":"acintro.html#passing-parameters-with-sketches-and-custom-web-pages","title":"Passing parameters with sketches and custom Web pages","text":"

    A sketch can access variables of AutoConnectElements on the custom Web page. The value entered into the AutoConnectElements is stored to the member variables of the element by AutoConnect whenever GET / POST transmission occurs. Your sketches can get these values with the request handler which will be registered by AutoConnect::on function. And if you assign a value to an element before a request to the page occurs, its value will appear as the initial value when the page is displayed. The details are explained in section Custom field data handling.

    1. There is no overlay in the actual menu.\u00a0\u21a9

    2. the Sketch is actually this: 

      #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect     portal;\n\nACText(header, \"MQTT broker settings\");\nACText(caption1, \"Publishing the WiFi...\");\nACSubmit(save, \"SAVE\", \"/mqtt_save\");\nAutoConnectAux  aux1(\"/mqtt_setting\", \"MQTT Setting\", true, { header, caption1, save });\n\nACText(caption2, \"Save parameters\");\nACSubmit(start, \"START\", \"/mqtt_start\"); \nAutoConnectAux  aux2(\"/mqtt_save\", \"MQTT Setting\", false, { caption2, start });\n\nAutoConnectAux  aux3(\"/mqtt_start\", \"MQTT Start\");\n\nvoid setup() {\n  portal.join({ aux1, aux2, aux3 });\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
      \u21a9

    3. Installation of the ArduinoJson as the latest release of version 5 series is required.\u00a0\u21a9

    "},{"location":"acjson.html","title":"Custom Web pages with JSON","text":"

    You can embed custom Web pages written in JSON into AutoConnect without AutoConnectAux & AutoConnectElements declaration. Custom Web page declaration by JSON can embed in the Sketch as a fixed string or can store in the external file such as SPIFFS for stream loading. Also, you can also load and save AutoConnectElements objects individually.1

    By providing the following JSON document to AutoConnect, you can include the custom Web page like the below:

    A JSON document for AutoConnect can contain the custom Web page multiple. You can further reduce the Sketch process by loading multiple pages of JSON document at once.

    Adopt ArduinoJson v5 or v6

    To handle AutoConnectAux and AutoConnectElements written in JSON, you need to install the ArduinoJson library. You can adopt either version 5 or version 6 for the ArduinoJson. AutoConnect supports both versions.

    "},{"location":"acjson.html#json-objects-elements-for-the-custom-web-page","title":"JSON objects & elements for the custom Web page","text":""},{"location":"acjson.html#json-document-structure-for-autoconnectaux","title":"JSON document structure for AutoConnectAux","text":"

    AutoConnectAux will configure custom Web pages with JSON objects. The elements that make up the object are as follows:

    {\n\"title\" : title,\n\"uri\" : uri,\n\"menu\" : true | false,\n\"response\" : true | false,\n\"auth\": authentication,\n\"element\" : element_array\n}\n
    "},{"location":"acjson.html#title","title":"title","text":"A title of the custom Web page. This is string value and specifies the title will be displayed in the AutoConnection menu."},{"location":"acjson.html#uri","title":"uri","text":"String of URI path that specifies where to place the custom Web page. It needs to be a location from the root path including '/'."},{"location":"acjson.html#menu","title":"menu","text":"This is a Boolean value indicating whether to include the custom Web page in the AutoConnect menu. If the page only responds to another page and you want to prevent the direct use from the menu, you can exclude from the AutoConnect menu. If this key is false, it will not appear in the menu."},{"location":"acjson.html#response","title":"response","text":"This is a Boolean value indicating whether to respond to HTTP responses independently in its custom web page handler. Normally, AutoConnect will respond with a response code of 200 after its custom web page has processed the request from the client. However, depending on the processing status of the handler, it may be necessary to return a response other than 200. For example, it might respond with a 302 redirect. In such situations, the custom web page handler can apply the sendHeader, sendContent, and send functions of the WebServer library to respond with its own response. If the response is false, AutoConnect will not respond with an HTTP response when it returns from the custom web page handler. The custom web page handler needs to perform the HTTP response by itself."},{"location":"acjson.html#auth","title":"auth","text":"It allows that this page requires authentication. An authentication specifies the following string that represents the authentication scheme.
    • NONE: No authentication. This is default.
    • BASIC: Apply Basic scheme.
    • DIGEST: Apply Digest scheme.
    "},{"location":"acjson.html#element","title":"element","text":"Describe an array of JSON objects as element_array. It is a JSON object array of the AutoConnectElements that make up the custom Web page.

    Order of elements on a custom Web page

    The order in which AutoConnectElements are placed on a custom Web page is the order in the JSON document.

    "},{"location":"acjson.html#multiple-custom-web-pages-declaration-in-json-document","title":"Multiple custom Web pages declaration in JSON document","text":"

    You can put declarations of multiple custom Web pages in one JSON document. In that case, declare an array of each custom Web page with JSON. The following JSON document contains three custom Web pages:

    [\n  {\n\"title\" : \"Page 1 title\",\n\"uri\" : \"/page1\",\n\"menu\" : true,\n\"element\" : [\n      {\n\"name\" : \"caption\",\n\"type\" : \"ACText\",\n\"value\" : \"hello, world\"\n      },\n      {\n\"name\" : \"send\",\n\"type\" : \"ACSubmit\",\n\"uri\" : \"/page2\"\n      }\n    ]\n  },\n  {\n\"title\" : \"Page 1 title\",\n\"uri\" : \"/page2\",\n\"menu\" : false,\n\"element\" : [\n      {\n\"name\" : \"responds\",\n\"type\" : \"ACText\",\n\"value\" : \"Good day\"\n      },\n      {\n\"name\" : \"send\",\n\"type\" : \"ACSubmit\",\n\"uri\" : \"/page3\"\n      }\n    ]\n  },\n  {\n\"title\" : \"Page 3 title\",\n\"uri\" : \"/page3\",\n\"menu\" : true,\n\"element\" : [\n      {\n\"name\" : \"responds\",\n\"type\" : \"ACText\",\n\"value\" : \"bye\"\n      }\n    ]\n  }\n]\n

    The above custom Web page definitions can be loaded in a batch using the AutoConnect::load function.

    "},{"location":"acjson.html#json-object-for-autoconnectelements","title":"JSON object for AutoConnectElements","text":"

    JSON description for AutoConnectElements describes as an array in the element with arguments of each constructor.

    {\n\"name\" : name,\n\"type\" : type,\n\"posterior\" : posterior,\nkey_according_to_type : the_value | array_of_value,\n  [ key_according_to_type : the_value | array_of_value ]\n}\n
    "},{"location":"acjson.html#name","title":"name","text":"A string of the name for the element."},{"location":"acjson.html#type","title":"type","text":"A string of the type for the element. For this type, specify the following string corresponding to each element.
    • AutoConnectButton: ACButton
    • AutoConnectCheckbox: ACCheckbox
    • AutoConnectElement: ACElement
    • AutoConnectFile: ACFile
    • AutoConnectInput: ACInput
    • AutoConnectRadio: ACRadio
    • AutoConnectRange: ACRange
    • AutoConnectSelect: ACSelect
    • AutoConnectStyle: ACStyle
    • AutoConnectSubmit: ACSubmit
    • AutoConnectText: ACText
    "},{"location":"acjson.html#posterior","title":"posterior","text":"Specifies a tag to add behind the HTML code generated from the element. Its purpose is to place elements on the custom Web page as intended by the user sketch. You can use the posterior key with the following values to arrange vertically or horizontal when the elements do not have the intended position on the custom Web Page specifying the following:
    • none : No generate additional tags.
    • br : Add a <br> tag to the end of the element.
    • par : Include the element in the <p> ~ </p> tag.
    • div : Include the element in the <div> ~ </div> tag.
    "},{"location":"acjson.html#key_according_to_type","title":"key_according_to_type","text":"

    This is different for each AutoConnectElements, and the key that can be specified by the type of AutoConnectElements is determined.

    "},{"location":"acjson.html#acbutton","title":"ACButton","text":"
    • value : Specifies the button label. This value also applies to the value attribute of an HTML button tag.
    • action : Specifies an action to be fire on a mouse click on the button. It is mostly used with a JavaScript to activate a script, or it directly describes a JavaScript.
    "},{"location":"acjson.html#accheckbox","title":"ACCheckbox","text":"
    • value : Specifies the value to be supplied to the checkbox. It will be packed in the query string as name=value when the checkbox is ticked.
    • label : Specifies a label of the checkbox. Its placement is always to the right of the checkbox.
    • checked : Specifies checking status as a boolean value. The value of the checked checkbox element is packed in the query string and sent.
    "},{"location":"acjson.html#acelement","title":"ACElement","text":"
    • value : Specifies the source code of generating HTML. The value is native HTML code and is output as HTML as it is.
    "},{"location":"acjson.html#acfile","title":"ACFile","text":"
    • value : The file name of the upload file will be stored. The value is read-only and will be ignored if specified.
    • label : Specifies a label of the file selection box. Its placement is always to the left of the file selection box.
    • store : Specifies the destination to save the uploaded file. Its value accepts one of the following:
      • fs : Save as the SPIFFS file in flash of ESP8266/ESP32 module. If the valid file system of the ESP8266 module incorporating the Sketch is LittleFS, AutoConnect assumes the file system to be LittleFS. However, it does not sense the actual file system, so If the Sketch implementation does not match the file system on the ESP8266 depends, a file writing error will occur.
      • sd : Save to an external SD device connected to ESP8266/ESP32 module.
      • extern : Pass the content of the uploaded file to the uploader which is declared by the Sketch individually. Its uploader must inherit AutoConnectUploadHandler class and implements _open, _write and _close function.

    A valid filesystem of ESP8266 on board flash

    AutoConnect has assumed LittleFS as a valid file system since v1.2.0 enhancement. On the other hand, the ESP8266 arduino core has supported LittleFS officially since a release 2.7.0. LittleFS support in AutoConnect relies on the FS instance declared by the arduino core used at compile-time per project, and its FS instance will acquire by either the SPIFFS class or the LittleFS class. That is, you need to choose which file system will be available in the actual Sketch and make consistent it with AutoConnect assumed file system. So, you can choose which one uses the file systems per project via adjustment the AC_USE_SPIFFS macro enable or disable. AutoConnect determines the available file system by the AC_USE_SPIFFS macro which defined in AutoConnectDefs.h header file.

    "},{"location":"acjson.html#acinput","title":"ACInput","text":"
    • value : Specifies the initial text string of the input box. If this value is omitted, placeholder is displayed as the initial string.
    • label : Specifies a label of the input box. Its placement is always to the left of the input box.
    • placeholder : Specifies short hint of the input box.
    • apply : Specifies the type of input that the text box accepts. Its value accepts one of the following:
      • text : A text.
      • password : Password input field. The text is obscured so that it cannot be read, usually by replacing each character with a symbol such as the asterisk (\"*\") or a dot (\"\u2022\").
      • number : A field let the user enter number characters only.

    Numerical keypad is different

    When the AutoConnectInput element with the number applied is focused on the browser, the numeric keypad may be displayed automatically. For popular mobile OSes such as Android and iOS, the numeric keypad has the following styles and is different with each OS.

    "},{"location":"acjson.html#acradio","title":"ACRadio","text":"
    • value : Specifies the collection of radio buttons as an array element.
    • label : Specifies a label of the collection of radio buttons, not for each button. The arrangement will be the top or left side according to the arrange.
    • arrange : Specifies the orientation of the radio buttons. Its value accepts one of the following:
      • horizontal : Horizontal arrangement.
      • vertical : Vertical arrangement.
    • checked : Specifies the index number (1-based) of the radio buttons collection to be checked.
    "},{"location":"acjson.html#acrange","title":"ACRange","text":"
    • value : Specifies the initial value in the range. If the value is not specified, the default value is determined by the following algorithm:value = (max < min) ? min : min + (max - min)/2;
    • label : Specifies a label of the range slider. Its placement is always to the left of the input box.
    • min : Specifies the most negative value within the range of allowed values and must not be less than the value.
    • max : Specifies the greatest value in the range of permitted values.
    • step : Specifies the granularity that the value must adhere to. The default is 1. As you move the slider, it increases or decreases the value according to the step in granularity.
    • magnify : Displays the current value of the range on the left or right side of the slider. The magnify accepts one of the following:
      • infront : Displays the current value on the left side.
      • behind : Displays the current value on the right side.
      • void : No display the current value. This is the default.
    • style : Specifies the qualification style to give to the content and can use the style attribute format as it is.
    "},{"location":"acjson.html#acselect","title":"ACSelect","text":"
    • label : Specifies a label of the drop-down list. Its placement is always to the left of the drop-down list.
    • option : Specifies the initial value collection of the drop-down list as an array element.
    "},{"location":"acjson.html#acstyle","title":"ACStyle","text":"
    • value : Specifies the custom CSS code.
    "},{"location":"acjson.html#acsubmit","title":"ACSubmit","text":"
    • value : Specifies a label of the submit button.
    • uri : Specifies the URI to send form data when the button is clicked.
    "},{"location":"acjson.html#actext","title":"ACText","text":"
    • value : Specifies a content and also can contain the native HTML code, but remember that your written code is enclosed by the div tag.
    • style : Specifies the qualification style to give to the content and can use the style attribute format as it is.
    • format : Specifies how to interpret the value. It specifies the conversion format when outputting values. The format string conforms to the C-style printf library functions, but depends on the espressif SDK implementation. The conversion specification is valid only for %s format. (Left and Right justification, width are also valid.)

    AutoConnect JSON parsing process is not perfect

    It is based on analysis by ArduinoJson, but the semantic analysis is simplified to save memory. Consequently, it is not an error that a custom Web page JSON document to have unnecessary keys. It will be ignored.

    "},{"location":"acjson.html#loading-json-document","title":"Loading JSON document","text":""},{"location":"acjson.html#loading-to-autoconnect","title":"Loading to AutoConnect","text":"

    There are two main ways to load the custom Web pages into AutoConnect.

    1. Load directly into AutoConnect

      This way does not require an explicit declaration of AutoConnectAux objects with sketches and is also useful when importing the custom Web pages JSON document from an external file such as SPIFFS because the page definition and sketch coding structure can be separated.

      Using the AutoCoonnect::load function, AutoConnect dynamically generates the necessary AutoConnectAux objects internally based on the custom Web page definition of the imported JSON document content. In the Sketch, the generated AutoConnectAux object can be referenced using the AutoConnect::aux function. You can reach the AutoConnectElements you desired using the AutoConnectAux::getElement function of its AutoConnectAux.

      In the following example, it loads in a batch a JSON document of custom Web pages stored in SPIFFS and accesses to the AutoConnectInput element.

      [\n  {\n\"title\": \"page1\",\n\"uri\": \"/page1\",\n\"menu\": true,\n\"element\": [\n      {\n\"name\": \"input1\",\n\"type\": \"ACInput\"\n      }\n    ]\n  },\n  {\n\"title\": \"page2\",\n\"uri\": \"/page2\",\n\"menu\": true,\n\"element\": [\n      {\n\"name\": \"input2\",\n\"type\": \"ACInput\"\n      }\n    ]\n  }\n]\n
      AutoConnect portal;\nFile page = SPIFFS.open(\"/custom_page.json\", \"r\");\nportal.load(page);\npage.close();\nAutoConnectAux* aux = portal.aux(\"/page1\");\nAutoConnectInput& input1 = aux->getElement<AutoConnectInput>(\"input1\");\n

    2. Load to AutoConnectAux and join to AutoConnect

      This way declares AutoConnectAux in the Sketch and loads the custom Web pages JSON document there. It has an advantage for if you want to define each page of a custom Web page individually or allocate AutoConnectAux objects dynamically on the Sketch side.

      After loading a JSON document using the AutoConnectAux::load function by each, integrate those into AutoConnect using the AutoConnect::join function.

      In the following example, you can see the difference between two sketches in a sketch modified using the AutoConnectAux::load.

      {\n\"title\": \"page1\",\n\"uri\": \"/page1\",\n\"menu\": true,\n\"element\": [\n    {\n\"name\": \"input1\",\n\"type\": \"ACInput\"\n    }\n  ]\n}\n
      {\n\"title\": \"page2\",\n\"uri\": \"/page2\",\n\"menu\": true,\n\"element\": [\n    {\n\"name\": \"input2\",\n\"type\": \"ACInput\"\n    }\n  ]\n}\n
      AutoConnect portal;\nAutoConnectAux page1;\nAutoConnectAux page2;\nFile page = SPIFFS.open(\"/custom_page1.json\", \"r\");\npage1.load(page);\npage.close();\npage = SPIFFS.open(\"/custom_page2.json\", \"r\");\npage2.load(page);\npage.close();\nportal.join( { page1, page2 } );\nAutoConnectInput& input1 = page1.getElement<AutoConnectInput>(\"input1\");\n

    "},{"location":"acjson.html#loading-from-the-streamed-file","title":"Loading from the streamed file","text":"

    AutoConnect supports loading of JSON document from the following instances:

    • String
    • PROGMEM
    • Stream

    To load custom Web pages JSON document into AutoConnect, use the load function of the AutoConnect class. Its JSON document can read must be completed as a description interpretable by the ArduinoJson library. It cannot import custom Web pages if there are syntax errors for the JSON. If you can not see the custom Web page prepared by JSON, you can check the syntax with ArduinoJson Assistant. It is useful for pre-checking.

    bool AutoConnect::load(const String& aux)\n
    bool AutoConnect::load(const __FlashStringHelper* aux)\n
    bool AutoConnect::load(Stream& aux)\n
    An example of using each function is as follows. 
    AutoConnect  portal;\n\n// Loading from String\nconst String aux = String(\"{\\\"title\\\":\\\"Page 1 title\\\",\\\"uri\\\":\\\"/page1\\\",\\\"menu\\\":true,\\\"element\\\":[{\\\"name\\\":\\\"caption\\\",\\\"type\\\":\\\"ACText\\\",\\\"value\\\":\\\"hello, world\\\"}]}\");\nportal.load(aux);\n\n// Loading from PROGMEM\nconst char aux[] PROGMEM = R\"raw(\n{\n  \"title\" : \"Page 1 title\",\n  \"uri\" : \"/page1\",\n  \"menu\" : true,\n  \"element\" : [\n    {\n      \"name\" : \"caption\",\n      \"type\" : \"ACText\",\n      \"value\" : \"hello, world\"\n    }\n  ]\n}\n)raw\";\nportal.load(FPSTR(aux));\n\n// Loading from Stream assumes \"aux.json\" file should be store in SPIFFS.\nFile aux = SPIFFS.open(\"aux.json\", \"r\");\nportal.load(aux);\naux.close();\n

    AutoConnect passes the given JSON document directly to the parseObject() function of the ArduinoJson library for parsing. Therefore, the constraint of the parseObject() function is applied as it is in the parsing of the JSON document for the AutoConnect. That is, if the JSON string is read-only, duplicating the input string occurs and consumes more memory.

    "},{"location":"acjson.html#adjust-the-json-document-buffer-size","title":"Adjust the JSON document buffer size","text":"

    AutoConnect uses ArduinoJson library's dynamic buffer to parse JSON documents. Its dynamic buffer allocation scheme depends on the version 5 or version 6 of ArduinoJson library. Either version must have enough buffer to parse the custom web page's JSON document successfully. AutoConnect has the following three constants internally to complete the parsing as much as possible in both ArduinoJson version. These constants are macro defined in AutoConnectDefs.h.

    If memory insufficiency occurs during JSON document parsing, you can adjust these constants to avoid insufficiency by using the JsonAssistant with deriving the required buffer size in advance.

    #define AUTOCONNECT_JSONBUFFER_SIZE     256\n#define AUTOCONNECT_JSONDOCUMENT_SIZE   (8 * 1024)\n#define AUTOCONNECT_JSONPSRAM_SIZE      (16* 1024)\n
    "},{"location":"acjson.html#autoconnect_jsonbuffer_size","title":"AUTOCONNECT_JSONBUFFER_SIZE","text":"

    This is a unit size constant of DynamicJsonBuffer and works when the library used is ArduinoJson version 5. A buffer size of the JSON document increases with this unit. This value relates to the impact of the fragmented heap area. If it is too large, may occur run-out of memory.

    "},{"location":"acjson.html#autoconnect_jsondocument_size","title":"AUTOCONNECT_JSONDOCUMENT_SIZE","text":"

    This is a size of DynamicJsonDocument for ArduinoJson version 6. This buffer is not automatically expanding, and the size determines the limit.

    "},{"location":"acjson.html#autoconnect_jsonpsram_size","title":"AUTOCONNECT_JSONPSRAM_SIZE","text":"

    For ESP32 module equips with PSRAM, you can allocate the JSON document buffer to PSRAM. Buffer allocation to PSRAM will enable when PSRAM:Enabled option selected in the Arduino IDE's Board Manager menu. It is available since ArduinoJson 6.10.0.

    "},{"location":"acjson.html#saving-json-document","title":"Saving JSON document","text":"

    the Sketch can persist AutoConnectElements as a JSON document and also uses this function to save the values entered on the custom Web page. And you can reload the saved JSON document into AutoConnectElements as the field in a custom Web page using the load function.

    1. Loading and saving AutoConnect parameters adopt this method.\u00a0\u21a9

    "},{"location":"acupload.html","title":"File upload handler","text":""},{"location":"acupload.html#uploading-file-from-web-browser","title":"Uploading file from Web Browser","text":"

    If you have to write some data individually to the ESP8266/ESP32 module for the Sketch behavior, the AutoConnectFile element will assist with your wants implementation. The AutoConnectFile element produces an HTML <input type=\"file\"> tag and can save uploaded file to the flash or external SD of the ESP8266/ESP32 module. The handler for saving is built into AutoConnect. You can use it to inject any sketch data such as the initial values for the custom Web page into the ESP module via OTA without using the Sketch data upload tool of Arduino-IDE.

    "},{"location":"acupload.html#basic-steps-of-the-file-upload-sketch","title":"Basic steps of the file upload sketch","text":"

    Here is the basic procedure of the Sketch which can upload files from the client browser using AutoConnectFile:1

    1. Place AutoConnectFile on a custom Web page by writing JSON or constructor code directly with the Sketch.
    2. Place other AutoConnectElements as needed.
    3. Place AutoConnectSubmit on the same custom Web page.
    4. Perform the following process in the on-handler of submitting destination:
      • Retrieve the AutoConnectFile instance from the custom Web page where you placed the AutoConnectFile element using the AutoConnectAux::getElement function or the operator [].
      • Start access to the device specified as the upload destination. In usually, it depends on the file system's begin function. For example, if you specified Flash's SPIFFS as the upload destination, invokes SPIFFS.begin().
      • The value member of AutoConnectFile contains the file name of the upload file. Use its file name to access the uploaded file on the device.
      • Invokes the end function associated with the begin to close the device. It is the SPIFFS.end()* if the flash on the ESP module has been begun for SPIFFS.

    The following sketch is an example that implements the above basic steps. The postUpload function is the on-handler and retrieves the AutoConnectFile as named upload_file. You should note that this handler is not for a custom Web page placed with its AutoConnectFile element. The uploaded file should be processed by the handler for the transition destination page from the AutoConnectFile element placed page. AutoConnect built-in upload handler will save the uploaded file to the specified device before invoking the postUpload function.

    However, If you use uploaded files in different situations, it may be more appropriate to place the actual handling process outside the handler. It applies for the parameter file, etc. The important thing is that you do not have to sketch file reception and storing logic by using the AutoConnectFile element and the upload handler built into the AutoConnect.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <FS.h>\n#include <AutoConnect.h>\n\n// Upload request custom Web page\nstatic const char PAGE_UPLOAD[] PROGMEM = R\"(\n{\n  \"uri\": \"/\",\n  \"title\": \"Upload\",\n  \"menu\": true,\n  \"element\": [\n    { \"name\":\"caption\", \"type\":\"ACText\", \"value\":\"<h2>File uploading platform<h2>\" },\n    { \"name\":\"upload_file\", \"type\":\"ACFile\", \"label\":\"Select file: \", \"store\":\"fs\" },\n    { \"name\":\"upload\", \"type\":\"ACSubmit\", \"value\":\"UPLOAD\", \"uri\":\"/upload\" }\n  ]\n}\n)\";\n\n// Upload result display\nstatic const char PAGE_BROWSE[] PROGMEM = R\"(\n{\n  \"uri\": \"/upload\",\n  \"title\": \"Upload\",\n  \"menu\": false,\n  \"element\": [\n    { \"name\":\"caption\", \"type\":\"ACText\", \"value\":\"<h2>Uploading ended<h2>\" },\n    { \"name\":\"filename\", \"type\":\"ACText\" },\n    { \"name\":\"size\", \"type\":\"ACText\", \"format\":\"%s bytes uploaded\" },\n    { \"name\":\"content_type\", \"type\":\"ACText\", \"format\":\"Content: %s\" }\n  ]\n}\n)\";\n\nESP8266WebServer server;\nAutoConnect portal(server);\n// Declare AutoConnectAux separately as a custom web page to access\n// easily for each page in the post-upload handler.\nAutoConnectAux auxUpload;\nAutoConnectAux auxBrowse;\n\n/**\n * Post uploading, AutoConnectFile's built-in upload handler reads the\n * file saved in SPIFFS and displays the file contents on /upload custom\n * web page. However, only files with mime type uploaded as text are\n * displayed. A custom web page handler is called after upload.\n * @param  aux  AutoConnectAux(/upload)\n * @param  args PageArgument\n * @return Uploaded text content\n */\nString postUpload(AutoConnectAux& aux, PageArgument& args) {\n  String  content;\n  AutoConnectFile&  upload = auxUpload[\"upload_file\"].as<AutoConnectFile>();\n  AutoConnectText&  aux_filename = aux[\"filename\"].as<AutoConnectText>();\n  AutoConnectText&  aux_size = aux[\"size\"].as<AutoConnectText>();\n  AutoConnectText&  aux_contentType = aux[\"content_type\"].as<AutoConnectText>();\n// Assignment operator can be used for the element attribute.\n  aux_filename.value = upload.value;\n  aux_size.value = String(upload.size);\n  aux_contentType.value = upload.mimeType;\n// The file saved by the AutoConnect upload handler is read from\n// the EEPROM and echoed to a custom web page.\n  SPIFFS.begin();\n  File uploadFile = SPIFFS.open(String(\"/\" + upload.value).c_str(), \"r\");\nif (uploadFile) {\nwhile (uploadFile.available()) {\nchar c = uploadFile.read();\n      Serial.print(c);\n    }\n    uploadFile.close();\n  }\nelse\n    content = \"Not saved\";\n  SPIFFS.end();\nreturn String();\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  auxUpload.load(PAGE_UPLOAD);\n  auxBrowse.load(PAGE_BROWSE);\n  portal.join({ auxUpload, auxBrowse });\n  auxBrowse.on(postUpload);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"acupload.html#where-will-the-file-upload","title":"Where will the file upload","text":"

    The AutoConnect built-in upload handler can save the upload file to three locations:

    1. Flash memory embedded in the ESP8266/ESP32 module
    2. SD device externally connected to the ESP8266/ESP32 module
    3. Other character devices

    You can specify the device type to save with the store attribute of AutoConnectFile, and it accepts the following values:

    • Flash : AC_File_FS for the API parameter or fs for the JSON document
    • SD : AC_File_SD for the API parameter or sd for the JSON document
    • Other : AC_File_Extern for the API parameter or extern for the JSON document

    The substance of AC_File_FS (fs) is a SPIFFS file system implemented by the ESP8266/ESP32 core, and then AutoConnect uses the Global Instance SPIFFS to access SPIFFS.

    Also, the substance of AC_File_SD (sd) is a FAT file of Arduino SD library ported to the ESP8266/ESP32 core, and then AutoConnect uses the Global Instance SD to access SD. When saving to an external SD device, there are additional required parameters for the connection interface and is defined as the macro in AutoConnectDefs.h.

    #define AUTOCONNECT_SD_CS       SS\n#define AUTOCONNECT_SD_SPEED    4000000\n

    AUTOCONNECT_SD_CS defines which GPIO for the CS (Chip Select, or SS as Slave Select) pin. This definition is derived from pins_arduino.h, which is included in the Arduino core distribution. If you want to assign the CS pin to another GPIO, you need to change the macro definition of AutoConnectDefs.h.

    AUTOCONNECT_SD_SPEED defines SPI clock speed depending on the connected device.

    Involves both the begin() and the end()

    The built-in uploader executes the begin and end functions regardless of the Sketch whence the file system of the device will terminate with the uploader termination. Therefore, to use the device in the Sketch after uploading, you need to restart it with the begin function.

    "},{"location":"acupload.html#when-it-will-be-uploaded","title":"When it will be uploaded","text":"

    Upload handler will be launched by ESP8266WebServer/WebServer(as ESP32) library which is triggered by receiving an HTTP stream of POST BODY including file content. Its launching occurs before invoking the page handler.

    The following diagram illustrates the file uploading sequence:

    At the time of the page handler behaves, the uploaded file already saved to the device, and the member variables of AutoConnectFile reflects the file name and transfer size.

    "},{"location":"acupload.html#the-file-name-for-the-uploaded-file","title":"The file name for the uploaded file","text":"

    AutoConnetFile saves the uploaded file with the file name you selected by <input type=\"file\"> tag on the browser. The file name used for uploading is stored in the AutoConnetFile's value member, which you can access after uploading. (i.e. In the handler of the destination page by the AutoConnectSubmit element.) You can not save it with a different name. It can be renamed after upload if you need to change the name.

    "},{"location":"acupload.html#upload-to-a-device-other-than-flash-or-sd","title":"Upload to a device other than Flash or SD","text":"

    You can output the file to any device using a custom uploader by specifying extern with the store attribute of AutoConnectFile (or specifying AC_File_Extern for the store member variable) and can customize the uploader according to the need to upload files to other than Flash or SD. Implements your own uploader with inheriting the AutoConnectUploadHandler class which is the base class of the upload handler.

    It's not so difficult

    Implementing the custom uploader requires a little knowledge of the c++ language. If you are less attuned to programming c++, you may find it difficult. But don't worry. You can make it in various situations by just modifying the Sketch skeleton that appears at the end of this page.

    "},{"location":"acupload.html#upload-handler-base-class","title":"Upload handler base class","text":"

    AutoConnectUploadHandler is a base class of upload handler and It has one public member function and three protected functions.

    "},{"location":"acupload.html#constructor","title":"Constructor","text":"
    AutoConnectUploadHandler()\n
    "},{"location":"acupload.html#member-functions","title":"Member functions","text":"

    The upload public function is an entry point, the ESP8266WebServer (WebServer as ESP32) library will invoke the upload with each time of uploading content divided into chunks.

    Also, the _open, _write and _close protected functions are actually responsible for saving files and are declared as pure virtual functions. A custom uploader class that inherits from the AutoConnectUploadHandler class need to implement these functions.

    The actual upload process is handled by the three private functions above, and then upload only invokes three functions according to the upload situation. In usually, there is no need to override the upload function in an inherited class.

    public virtual void upload(const String& requestUri, const HTTPUpload& upload)\n
    Parameters requestUriURI of upload request source. uploadA data structure of the upload file as HTTPUpload. It is defined in the ESP8266WebServer (WebServer as ESP32) library as follows: 
    typedef struct {\n  HTTPUploadStatus status;\n  String  filename;\n  String  name;\n  String  type;\nsize_t  totalSize;\nsize_t  currentSize;\nsize_t  contentLength;\nuint8_t buf[HTTP_UPLOAD_BUFLEN];\n} HTTPUpload;\n

    An upload handler needs to implement a procedure corresponding with HTTPUploadStatus enum value indicated by the uploading process of ESP8266WebServer class, which contained in HTTPUpload.status as following values:

    • UPLOAD_FILE_START : Invokes to the _open.
    • UPLOAD_FILE_WRITE : Invokes to the _write.
    • UPLOAD_FILE_END : Invokes to the _close.
    • UPLOAD_FILE_ABORTED : Invokes to the _close.

    The _open function will be invoked when HTTPUploadStatus is UPLOAD_FILE_START. Usually, the implementation of an inherited class will open the file.

    protected virtual bool _open(const char* filename, const char* mode) = 0\n
    Parameters filenameUploading file name. modeAn indicator for the file access mode, a \"w\" for writing. Return value trueFile open successful. falseFailed to open.

    The _write function will be invoked when HTTPUploadStatus is UPLOAD_FILE_WRITE. The content of the upload file is divided and the _write will be invoked in multiple times. Usually, the implementation of an inherited class will write data.

    protected virtual size_t _write(const uint8_t *buf, const size_t size) = 0\n
    Parameters bufFile content block. sizeFile block size to write. Return value Size written.

    The _close function will be invoked when HTTPUploadStatus is UPLOAD_FILE_END or UPLOAD_FILE_ABORTED. Usually, the implementation of an inherited class will close the file.

    protected virtual void _close(void) = 0\n

    For reference, the following AutoConnectUploadFS class is an implementation of AutoConnect built-in uploader and inherits from AutoConnectUploadHandler.

    class AutoConnectUploadFS : public AutoConnectUploadHandler {\npublic:\nexplicit AutoConnectUploadFS(SPIFFST& media) : _media(&media) {}\n~AutoConnectUploadFS() { _close(); }\n\nprotected:\nbool _open(const char* filename, const char* mode) override {\nif (_media->begin()) {\n      _file = _media->open(filename, mode);\nreturn _file != false;      \n    }\nreturn false;\n  }\n\nsize_t _write(const uint8_t* buf, const size_t size) override {\nif (_file)\nreturn _file.write(buf, size);\nelse\nreturn -1;\n  }\n\nvoid _close(void) override {\nif (_file)\n      _file.close();\n    _media->end();\n  }\n\nprivate:\n  SPIFFST*  _media;\n  SPIFileT  _file; \n};\n
    "},{"location":"acupload.html#register-custom-upload-handler","title":"Register custom upload handler","text":"

    In order to upload a file by the custom uploader, it is necessary to register it to the custom Web page beforehand. To register a custom uploader, specify the custom uploader class name in the template argument of the AutoConnectAux::onUpload function and invokes it.

    void AutoConnectAux::onUpload<T>(T& uploadClass)\n
    Parameters TSpecifies a class name of the custom uploader. This class name is a class that you implemented by inheriting AutoConnectUploadHandler for custom upload. uploadClassSpecifies the custom upload class instance.

    The rough structure of the Sketches that completed these implementations will be as follows:

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char PAGE_UPLOAD[] PROGMEM = R\"(\n{\n  \"uri\": \"/\",\n  \"title\": \"Upload\",\n  \"menu\": true,\n  \"element\": [\n    { \"name\":\"caption\", \"type\":\"ACText\", \"value\":\"<h2>File uploading platform<h2>\" },\n    { \"name\":\"upload_file\", \"type\":\"ACFile\", \"label\":\"Select file: \", \"store\":\"extern\" },\n    { \"name\":\"upload\", \"type\":\"ACSubmit\", \"value\":\"UPLOAD\", \"uri\":\"/upload\" }\n  ]\n}\n)\";\n\nstatic const char PAGE_RECEIVED[] PROGMEM = R\"(\n{\n  \"uri\": \"/upload\",\n  \"title\": \"Upload ended\",\n  \"menu\": false,\n  \"element\": [\n    { \"name\":\"caption\", \"type\":\"ACText\", \"value\":\"<h2>File uploading ended<h2>\" }\n  ]\n}\n)\";\n\n// Custom upload handler class\nclass CustomUploader : public AutoConnectUploadHandler {\npublic:\n  CustomUploader() {}\n~CustomUploader() {}\n\nprotected:\nbool   _open(const char* filename, const char* mode) override;\nsize_t _write(const uint8_t *buf, const size_t size) override;\nvoid   _close(void) override;\n};\n\n// _open for custom open\nbool CustomUploader::_open(const char* filename, const char* mode) {\n// Here, an implementation for the open file.\n}\n\n// _open for custom write\nsize_t CustomUploader::_write(const uint8_t *buf, const size_t size) {\n// Here, an implementation for the writing the file data.\n}\n\n// _open for custom close\nvoid CustomUploader::_close(void) {\n// Here, an implementation for the close file.\n}\n\nAutoConnect     portal;\nAutoConnectAux  uploadPage;\nAutoConnectAux  receivePage;\nCustomUploader  uploader;   // Declare the custom uploader\n\nvoid setup() {\n  uploadPage.load(PAGE_UPLOAD);\n  receivePage.load(PAGE_RECEIVED);\n  portal.join({ uploadPage, receivePage });\n  receivePage.onUpload<CustomUploader>(uploader);  // Register the custom uploader\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    Don't forget to specify the store

    When using a custom uploader, remember to specify the extern for the store attribute of AutoConnectFile.

    1. The AutoConnectFile element can be used with other AutoConnectElements on the same page.\u00a0\u21a9

    "},{"location":"adauthentication.html","title":"Authentication settings","text":"

    The Sketch may use authentication to protect custom Web pages and prevent unauthorized access. AutoConnect has implemented HTTP authentication feature that can be applied to multiple scopes using the authentication methods provided by the platform's WebServer library for ESP8266 or ESP32.1

    • Applying HTTP authentication
    • Applying HTTP authentication for Built-in OTA
    • Authentication within the captive portal state
    "},{"location":"adauthentication.html#applying-http-authentication","title":"Applying HTTP authentication","text":"

    AutoConnectConfig::auth setting allows the Sketch to HTTP authenticate with \"BASIC\" or \"DIGEST\" scheme. AutoConnectConfig::authScope specifies the scope covered by authentication which is the whole range for all pages of the Sketch, custom web pages, or AutoConnect pages. AutoConnectConfig::username and AutoConnectConfig::password specifies credential as user-id/password pairs.

    The Sketch enables HTTP authentication with the AutoConnectConfig::auth setting, also specifies the authentication scheme:

    • AC_AUTH_NONE AutoConnect pages and custom Web pages do not require authentication. Not protected from all HTTP access. This is the default.
    • AC_AUTH_DIGEST Protect AutoConnect pages and custom Web pages with DIGEST authentication.
    • AC_AUTH_BASIC Protect AutoConnect pages and custom Web pages with BASIC authentication.

    Note that the authentication scope specified in AutoConnectConfig::authScope is different from the protection space shown by Realm for HTTP authentication. AutoConnect assumes only one Realm and defines it as AUTOCONNECT_AUTH_REALM in AutoConnectDefs.h header file. Instead, the Sketch will be able to expand or narrow the range of authentication by AutoConnectConfig::authScope setting, which can be either as follows:

    • AC_AUTHSCOPE_PORTAL Require authentication to access for all AutoConnect pages, including custom Web pages.
    • AC_AUTHSCOPE_AUX Require authentication to access for all custom Web pages, excepting AutoConnect pages. This is the Default.
    • AC_AUTHSCOPE_PARTIAL Authenticate only specific custom Web pages which are specified by AutoConnectAux::authentication function or JSON.

    Also, a credential used for authentication is specified in the Sketch using the AutoConnectConfig::username and AutoConnectConfig::password settings.2

    Here's a minimal Sketch with HTTP authentication for the custom Web page:

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char PAGE_AUTH[] PROGMEM = R\"(\n{\n  \"uri\": \"/auth\",\n  \"title\": \"Auth\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"text\",\n      \"type\": \"ACText\",\n      \"value\": \"AutoConnect has authorized\",\n      \"style\": \"font-family:Arial;font-size:18px;font-weight:400;color:#191970\"\n    }\n  ]\n}\n)\";\n\nWebServerClass    server;\nAutoConnect       portal(server);\nAutoConnectConfig config;\n\nvoid setup() {\n  config.auth = AC_AUTH_DIGEST;\n  config.authScope = AC_AUTHSCOPE_AUX;\n  config.username = \"user\";\n  config.password = \"password\";\n  portal.config(config);\n  portal.load(FPSTR(PAGE_AUTH));\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    If you want to authenticate only specific pages in a Sketch that handles multiple custom Web pages, set AC_AUTHSCOPE_PARTIAL to AutoConnectConfig::authScope. Then, it specifies the authentication scheme with the auth key in the JSON description of the page should be authenticated.

    AutoConnect determines which authentication method to use for custom Web pages (such as AutoConnectAux) based on its association with AutoConnectConfig::authScope setting. The table below shows which authentication scheme will be finally adopted. As shown in this table, the final authentication scheme depends on the AutoConnectConfig::authScope setting, and if AC_AUTHSCOPE_PARTIAL is specified it, AutoConnectAux's authentication setting takes precedence over the AutoConnectConfig::auth setting.

    AutoConnectConfig::authScope Authentication scheme for the custom Web page AC_AUTHSCOPE_PORTAL Specified by AutoConnectConfig::auth AC_AUTHSCOPE_AUX Specified by AutoConnectConfig::auth AC_AUTHSCOPE_PARTIAL Specified by AutoConnectAux::authentication, The default values is AC_AUTH_NONE.

    Authentication designation for AutoConnectAux can also be specified by giving the following value to the auth key by the JSON description:

    • \"auth\" : \"basic\"
    • \"auth\" : \"digest\"
    • \"auth\" : \"none\"

    The following example Sketch has two custom Web pages, Hello and Auth. It applies authentication only to the Auth page by setting AC_AUTHSCOPE_PARTIAL to AutoConnectConfig::authScope.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char PAGE_HELLO[] PROGMEM = R\"(\n{\n  \"uri\": \"/hello\",\n  \"title\": \"Hello\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"text\",\n      \"type\": \"ACText\",\n      \"value\": \"Hello, word\",\n      \"style\": \"font-family:Arial;font-size:18px;font-weight:400;color:#191970\"\n    }\n  ]\n}\n)\";\n\nstatic const char PAGE_AUTH[] PROGMEM = R\"(\n{\n  \"uri\": \"/auth\",\n  \"title\": \"Auth\",\n  \"menu\": true,\n  \"auth\": \"digest\",\n  \"element\": [\n    {\n      \"name\": \"text\",\n      \"type\": \"ACText\",\n      \"value\": \"AutoConnect has authorized\",\n      \"style\": \"font-family:Arial;font-size:18px;font-weight:400;color:#191970\"\n    }\n  ]\n}\n)\";\n\nWebServerClass    server;\nAutoConnect       portal(server);\nAutoConnectConfig config;\n\nvoid setup() {\n// It's a default value but has no meaning in the AC_AUTHSCOPE_PARTIAL setting.\n// config.auth = AC_AUTH_NONE;\n  config.authScope = AC_AUTHSCOPE_PARTIAL;\n  config.username = \"user\";\n  config.password = \"password\";\n  portal.config(config);\n  portal.load(FPSTR(PAGE_HELLO));\n  portal.load(FPSTR(PAGE_AUTH));\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    PageBuilder v1.4.0 or later needed

    PageBuilder v1.4.0 or later is required to use HTTP authentication with AutoConnect. Also, v1.4.2 or later is required to eliminate SPIFFS, which is deprecated as a file system for ESP8266 module.

    Can not use DIGEST authentication for ESP32 arduino core 1.0.4 stable release

    For ESP32, Arduino core 1.0.4 stable has a bug for DIGEST authentication. The upstream of the master is recommended. (or use BASIC authentication)

    "},{"location":"adauthentication.html#applying-http-authentication-for-built-in-ota","title":"Applying HTTP authentication for Built-in OTA","text":"

    AutoConnectConfig::auth setting also affects the built-in OTA feature. AC_AUTH_BASIC or AC_AUTH_DIGEST setting allows Built-in OTA to authenticate with the UPDATE page. This setting is valid even if AutoConnectConfig::authScope is AC_AUTHSCOPE_PARTIAL. That is if the AutoConnectConfig::auth setting is BASIC or DIGEST, authentication will be required for Built-in OTA. See also Authentication with AutoconnectOTA.

    "},{"location":"adauthentication.html#authentication-within-the-captive-portal-state","title":"Authentication within the captive portal state","text":"

    When accessing the ESP module from an iOS or Android device in the captive portal state, the HTTP authentication framework is disabled in the OS of the client device. Even if the ESP module responds with a 401 unauthorized with WWW-Authenticate, those client device OSs under the captive portal do not display the login dialog and deprive the user of the opportunity to enter their credentials. There will always be an unauthorized error.

    AutoConnect's authentication operation based on HTTP (not HTTPS) depends on the OS of the client device, so in the captive portal state, most devices will unconditionally result in an authentication error. Therefore, the default authentication behavior of AutoConnect does not apply authentication in the captive portal state. (It will be ignored even if the AutoConnect setting is not AC_AUTH_NONE)

    However, if you want to deny unauthorized access to the protected page even in the captive portal state, you can use the extension bit of AutoConnectConfig::authScope. The AC_AUTHSCOPE_WITHCP flag allows AutoConnect to authentication in the captive portal state. It is set using a logical OR operator for the AutoConnectConfig::authScope setting and AutoConnect will enable authentication at the captive portal if the AC_AUTHSCOPE_WITHCP is ON.

    AutoConnectConfig config;\n...\nconfig.auth = AC_AUTH_DIGEST;\nconfig.authScope = AC_AUTHSCOPE_AUX | AC_AUTHSCOPE_WITHCP;\n...\n

    1. ESP32 Arduino core has the authenticate method provided by the WebServer library, similar to that of the ESP8266.\u00a0\u21a9

    2. The default user name and password for authentication inherits the setting of AutoConnectConfig::apid and AutoConnectConfig::psk.\u00a0\u21a9

    "},{"location":"adconnection.html","title":"AutoConnect WiFi connection control","text":"

    AutoConnect aims to connect the ESP module as a station to a WiFi access point and equips with various APIs to maintain a WiFi connection as possible while sketch running. The main APIs are AutoConnect::begin and AutoConnect::handleClient. You can make sketches with flexible WiFi connection capability by properly using these two APIs and the settings by AutoConnectConfig.

    • Automatic reconnect
    • Automatic reconnect (Background)
    • Configure WiFi channel
    • Connects depending on the WiFi signal strength
    • Detects connection establishment to AP
    • Match with known access points by SSID
    • Preserve AP mode
    • Timeout settings for a connection attempt
    • Verify the WiFi connection conditions
    "},{"location":"adconnection.html#automatic-reconnect","title":"Automatic reconnect","text":"

    AutoConnect will change the WiFi mode depending on the situation. The AutoConnect::begin function starts the Web Server with WIFI_STA mode when the connection is successful with 1st-WiFi.begin. If the connection with the last access point fails, AutoConnect will switch the WiFi mode to WIFI_AP_STA, launching a DNS server and allowing the ESP module to launch the captive portal.

    The captive portal launches SoftAP at its start and disconnects the STA. At this time, the ESP module discards its stored station configuration data (known as the SDK's station_config structure). This is the default behavior of AutoConnect.

    On the other hand, AutoConnect can connect to an access point again that has disconnected once, and its control is allowed by AutoConnectConfig::autoReconnect that option specifies to attempt to reconnect to the past established access point using the saved credentials. If the autoReconnect is enabled, AutoConnect will not launch SoftAP immediately even if 1st-WiFi.begin fails. When AutoConnect fails WiFi connection, it will scan the WiFi signal and try to find the access point that the ESP module has connected to in the past. If AutoConnect finds one of the saved credentials from the broadcast with BSSID, it will explicitly apply the matching credential and attempt to reconnect while in WIFI_STA mode. (AutoReconnect works well even with hidden SSID access points)

    AutoConnect       Portal;\nAutoConnectConfig Config;\nConfig.autoReconnect = true;\nPortal.config(Config);\nPortal.begin();\n

    The autoReconnect option is only available for AutoConnect::begin without SSID and PASSWORD parameter. If you use AutoConnect::begin with an SSID and PASSWORD, no reconnection attempt will be made if the 1st-WiFi.begin fails to connect to that SSID.

    The autoReconnect is not autoreconnect

    The WiFiSTAClass::disconnect 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 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 the arduino-esp32 core. AutoConnect's automatic reconnection is a mechanism independent from the automatic reconnection of the arduino-esp32 core.

    "},{"location":"adconnection.html#automatic-reconnect-background","title":"Automatic reconnect (Background)","text":"

    Combining autoReconnect with AutoConnectConfig::reconnectInterval allows you to periodically repeat connection attempts to known access points within AutoConnect::handleClient. This process is pseudo-asynchronous and does not block the Sketch process in the loop() function.

    The reconnectInterval specifies the interval time to seek for known access points with saved credentials during the handleClient loop and attempt to connect to the AP.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  Config.autoReconnect = true;    // Attempt automatic reconnection.\n  Config.reconnectInterval = 6;   // Seek interval time is 180[s].\n  Portal.config(Config);\n  Portal.begin();\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n// Here to do when WiFi is connected.\n  }\nelse {\n// Here to do when WiFi is not connected.\n  }\n\n  Portal.handleClient();\n}\n

    Above Sketch shows a configuration example that you want to keep connecting to known access points as long as possible. When the WiFi connection is lost, it will start seeking the WiFi network every 30 seconds during the handleClient loop.

    Limitation for automatic reconnection to a specific access point

    An access point that ESP module to reconnect automatically depends on whether the SSID and password argument existence with AutoConnect::begin. If the Sketch calls AutoConnect::begin without specifying an SSID or password, the autoReconnect will connect to one of the detected access points and cannot be pre-determined. The other one, the case of the Sketch specifies SSID and password with AutoConnect::begin, the autoReconnect will try to reconnect to a specified access point periodically during the handleClient loop.

    Also, you can combine the background automatic reconnect performing inside the loop function by handleClient with AutoConnectConfig::retainPortal and AutoConnectConfig::autoReset, to enable pop up the captive portal automatically on the client device each time the ESP module disconnects from the access point.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  Config.autoReset = false;     // Not reset the module even by intentional disconnection using AutoConnect menu.\n  Config.autoReconnect = true;  // Reconnect to known access points.\n  Config.reconnectInterval = 6; // Reconnection attempting interval is 3[min].\n  Config.retainPortal = true;   // Keep the captive portal open.\n  Portal.config(Config);\n  Portal.begin();\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n// Here to do when WiFi is connected.\n  }\nelse {\n// Here to do when WiFi is not connected.\n  }\n}\n

    The effective range of the reconnectInterval depending on the setting value

    The range of values that reconnectInterval can take is 0 to 255. (Actual seconds are from 0 to 255\u00d7AUTOCONNECT_UNITTIME) Reconnect behavior depends on the setting value. If it is 0, reconnection will work if the 1st-WiFi.begin in AutoConnect::begin fails and will suspend during the handleClient loop. If reconnectInterval is greater than 0, AutoConnect will attempt to reconnect both in AutoConnect::begin and during the handleClient loop.

    "},{"location":"adconnection.html#configure-wifi-channel","title":"Configure WiFi channel","text":"

    Appropriately specifying the WiFi channel to use for ESP8266 and ESP32 is essential for a stable connection with the access point. AutoConnect remembers the WiFi channel with a credential of the access point once connected and reuses it.

    The default channel when a captive portal starts and AutoConnect itself becomes an access point is the AutoConnectConfig::channel member. If this channel is different from the channel of the access point you will attempt to connect, WiFi.begin may fail. The cause is that the ESP module shares the same channel in AP mode and STA mode. If the connection attempt is not stable, specifying a proper channel using AutoConnectConfig::channel may result in a stable connection.

    "},{"location":"adconnection.html#connects-depending-on-the-wifi-signal-strength","title":"Connects depending on the WiFi signal strength","text":"

    When the ESP module found the multiple available access points (i.e. AutoConnect has connected in the past), the default behavior AutoConnect will attempt to connect to the least recent one. However, If the ESP module can operate properly with any access point, it is advantageous to establish a connection with the best one of the reception sensitivity.

    The AutoConnectConfig::principle parameter has the connection disposition, and specifying AC_PRINCIPLE_RSSI will attempt to connect to one of the highest RSSI value among multiple available access points. Also You can expect stable WiFi connection by specifying the lower limit of signal strength using AutoConnectConfig::minRSSI. Combining these two parameters allows you to filter the destination AP when multiple available access points are found.

    AutoConnectConfig::principle affects the behavior of both 1st-WiFi.begin and autoReconnect. If you specify AC_PRINCIPLE_RECENT for the principle, it will try according to the conventional connection rules, but if you specify AC_PRINCIPLE_RSSI, it will try to connect to the access point that is sending the strongest WiFi signal at that time instead of the last accessed AP. Also, the static IPs will be restored from a saved credential instead of AutoConnectConfig. (The values specified by AutoConnectConfig is ignored)

    SSID &Password AutoConnectConfig::principle Which credentials would be selected Static IPs AutoConnect::begin NULL specified AC_PRINCIPLE_RECENT Nothing, depends on SDK saves Use the specified value of AutoConnectConfig AC_PRINCIPLE_RSSI Auto-selected credentials with max RSSI Restoring static IPs suitable for the SSID from saved credentials Specified with the Sketch Not effective By AutoConnect::begin parameters Use the specified value of AutoConnectConfig AutoReconnect Load fromsaved credential AC_PRINCIPLE_RECENT Recently saved SSID would be chosen Restoring static IPs suitable for the SSID from saved credentials AC_PRINCIPLE_RSSI Auto-selected credentials with max RSSI

    In ESP32, the difference between the AutoConnectConfig::principle and WIFI_ALL_CHANNEL_SCAN in WiFi.begin

    In ESP32, if there are multiple access points with the same SSID and PW within reach, WiFi.begin with the SSID and PW explicitly specified will scan all radio channels and connect to the AP which has the highest signal strength. This feature has been enabled since ESP32 Arduino Release 1.0.6. The principle setting is slightly different from this feature. AutoConnect does not specify the SSID and PW in the 1st-WiFi.begin. It leaves that to the contents stored in the SDK. Even if there is an AP with a stronger signal nearby, it will try to connect to an AP with a smaller channel number. However, in the case where autoReconnect setting will attempt to reconnect, AutoConnect will read the SSID and PW from the saved credentials and explicitly pass them to WiFi.begin. Therefore, in this case, the connection will be made to the AP with the highest signal strength by WIFI_ALL_CHANNEL_SCAN. But it is only valid across multiple APs with the same SSID and PW. On the other hand, AC_PRINCIPLE_RSSI tries to connect the AP with the strongest signal from the connection candidates after selecting the SSID when multiple APs with different SSIDs are mixed in the reachable range.

    "},{"location":"adconnection.html#detects-connection-establishment-to-ap","title":"Detects connection establishment to AP","text":"

    The Sketch can detect that the ESP module has established a WiFi connection as a station to the access point. The AutoConnect::begin or AutoConnect::handleClient will transit the control temporarily to the function in the Sketch registered by AutoConnect::onConnect when the ESP module establish a WiFi connection. The ConnectExit function registered with AutoConnect::onConnect should have the following types and arguments:

    void ConnectExit(IPAddress& ip)\n

    The ConnectExit function is of type void. The argument ip is the IP address assigned to the ESP module by the connected AP. AutoConnect::onConnect allows the Sketch registers a ConnectExit function to AutoConnect. Also, you can make the function using a lambda expression.

    AutoConnect Portal;\n\nvoid onConnect(IPAddress& ipaddr) {\n  Serial.print(\"WiFi connected with \");\n  Serial.print(WiFi.SSID());\n  Serial.print(\", IP:\");\n  Serial.println(ipaddr.toString());\n}\nvoid setup() {\n  Serial.begin(115200);\n  Portal.onConnect(onConnect);  // Register the ConnectExit function\n  Portal.begin();\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    In addition, a sketch that shuts down SoftAP when the ESP module connects to the access point can be described using a lambda expression as follows:

    AutoConnect Portal;\n\nvoid setup() {\n  Serial.begin(115200);\n  Portal.onConnect([](IPAddress& ipaddr){\n    Serial.printf(\"WiiFi connected with %s, IP:%s\\n\", WiFi.SSID().c_str(), ipaddr.toString().c_str());\nif (WiFi.getMode() & WIFI_AP) {\n      WiFi.softAPdisconnect(true);\n      WiFi.enableAP(false);\n      Serial.printf(\"SoftAP:%s shut down\\n\", WiFi.softAPSSID().c_str());\n    }\n  });\n  Portal.begin();\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    It is not an event

    AutoConnect::onConnect has the same effect on the Sketch as the WiFi.onStationModeConnected, but AutoConnect does not use the event. Sketch can use WiFi.onEvent independently of AutoConnect.

    "},{"location":"adconnection.html#match-with-known-access-points-by-ssid","title":"Match with known access points by SSID","text":"

    By default, AutoConnect uses the BSSID to search for known access points. (Usually, it's the MAC address of the device) By using BSSID as the key to finding the WiFi network, AutoConnect can find even if the access point is hidden. However BSSIDs can change on some mobile hotspots, the BSSID-keyed searches may not be able to find known access points. If you operate inconvenience in aiming at the access point by BSSID, you can change the collation key from BSSID to SSID by uncommenting AUTOCONNECT_APKEY_SSID macro definition in AutoConnectDefs.h library source code.

    #define AUTOCONNECT_APKEY_SSID\n

    Allow you to use PlatformIO as a build system and give the following description to the platformio.ini, you can enable AUTOCONNECT_APKEY_SSID each build without modifying the library source code:

    build_flags=-DAUTOCONNECT_APKEY_SSID\n

    Can't be found hidden APs in SSID-keyed

    The hidden access point's SSID will be blank on the broadcast. So if the seek key is an SSID, AutoConnect will not find it.

    "},{"location":"adconnection.html#preserve-ap-mode","title":"Preserve AP mode","text":"

    Sketch using AutoConnect can open a gateway to the Internet by connecting to a WiFi router even through use Espressif's peculiar WiFi protocol (e.g. ESP-MESH or ESP-NOW). These specific communication protocols require to keeps AP + STA as the WiFi mode. That is, to apply these protocols, it needs to launch SoftAP by a sketch itself and then call AutoConnect::begin. But the default behavior of AutoConnect::begin will turn off SoftAP always then it will unable to open a connection.

    AutoConnectConfig::preserveAPMode setting maintains WIFI_AP mode without disabling SoftAP inside AutoConnect::begin. The Sketch can utilize the WiFi connection via AutoConnect with ESP-MESH and ESP-NOW protocol by enabling this option.

    The following diagram quoted from the ESP-MESH documentation that illustrates the typical topology of the MESH network. The module located at the Root Node bridges between the mesh network and the router by an application that handles two protocols, TCP/IP and ESP-MESH. Its SoftAP communicates with the internal mesh network as an interface of the mesh layer. On the other hand, STA performs station communication with the WiFi router as an interface of the TCP/IP layer. AutoConnect allows assists the connection between the router and the STA of the Root Node using AutoConnectConfig::preserveAPMode and starting the SoftAP via Sketch separately.

    Also in general, the Sketch should set false to AutoConnectConfig::autoRise, true to AutoConnectConfig::immediateStart when applying to those protocols.

    "},{"location":"adconnection.html#timeout-settings-for-a-connection-attempt","title":"Timeout settings for a connection attempt","text":"

    AutoConnect uses AutoConnectConfig::beginTimeout value to limit time to attempt when connecting the ESP module to the access point as a WiFi station. The default value is AUTOCONNECT_TIMEOUT defined in AutoConnectDefs.h and the initial value is 30 seconds. (actually specified in milliseconds) For example, the following sketch sets the connection timeout to 15 seconds:

    AutoConnect Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  Config.beginTimeout = 15000; // Timeout sets to 15[s]\n  Portal.config(Config);\n  Portal.begin();\n}\n\nvoid loop () {\n  Portal.handleClient();\n}\n

    In addition, the limit of the waiting time for connection attempts can be specified by the AutoConnect::begin parameter too. The timeout parameter specified in AutoConnect::begin takes precedence over AutoConnectConfig::beginTimeout.

    The beginTimeout has an effect on handleClient

    The beginTimeout value will be applied with handleClient when requesting a connection from the captive portal and when attempting to reconnect with autoReconnect.

    "},{"location":"adconnection.html#verify-the-wifi-connection-conditions","title":"Verify the WiFi connection conditions","text":"

    AutoConnect has the following indicators regarding WiFi connection attempts. These states are indicated as bitwise values and are the logical disjunction of multiple states. For example, if the 1st-WiFi.begin fails and the connection is restored by the AutoConnectConfig::autoReconnect setting, this status value will indicate both AC_AUTORECONNECT and AC_ESTABLISHED.

    A sketch can get this status value using the AutoConnect::portalStatus function. AutoConnect::portalStatus returns a value of type uint8_t. The return value is a bitwise value that indicates each status in the table below. In the sketch, the WiFi connection status is detected by taking the AND of the return value and the enum value shown in the following table:

    Values of the status indication WiFi connection situations AutoConnect::AC_IDLE Initial state: This is the initial state, AutoConnect is not making any WiFi connection attempts. This state is reached immediately after AutoConnect::begin starts. AutoConnect::AC_ESTABLISHED Connection successful: Successfully connected to the WiFi access point. AutoConnect::AC_AUTORECONNECT The autoReconnect was applied: AutoConnectConfig::autoReconnect setting was applied during the WiFi connection attempt process. This flag does not indicate a successful connection. It only shows that a condition that triggers autoReconnect has occurred. Whether the connection was actually successful should be determined by WiFi.status()==WL_CONNECTED. AutoConnect::AC_TIMEOUT Connection timeout: WiFi connection attempt timed out. Or, the captive portal was shut down by the AutoConnectConfig::portalTimeout setting. AutoConnect::AC_INTERRUPT Connection interrupted due to an indication with the exit: The whileConnecting exit routine returned false. or the whileCaptivePortal exit routine returned false. AutoConnect aborted the WiFi connection attempt with those indications. AutoConnect::AC_CAPTIVEPORTAL Captive portal is available: SoftAP mode is enabled, and the DNS server is available. AutoConnect will redirect connection requests to SoftAP from client devices to a captive portal site within AutoConnect. The state of this flag is equivalent to the return value of AutoConnect::isPortalAvailable function.NOTE: AC_CAPTIVEPORTAL is false if only SoftAP is available and no DNS server is enabled. AutoConnect::AC_INPROGRESS WiFi.begin in progress: AutoConnect requests WiFi.begin and is waiting for the connection to succeed or times out; this state will reset when terminating WiFi.begin attempts. 
    AutoConnect portal;\nAutoConnectConfig config;\n\nuint8_t state;\n\nvoid setup() {\n// Configure automatic reconnection and captive portal retention, then start\n// AutoConnect. In subsequent steps, it will use the portalStatus function to\n// detect the WiFi connection status in this configuration.\n  config.portalTimeout = 180000;\n  config.autoReconnect = true;\n  config.reconnectInterval = 1;\n  config.retainPortal = true;\n  portal.config(config);\n\n  portal.begin();\n\n  state = portal.portalStatus();\nif (WiFi.status() == WL_CONNECTED) {\nif (state & AutoConnect::AC_AUTORECONNECT)\n      Serial.println(\"Auto reconnection applied\");\n  }\nelse {\nif (state & AutoConnect::AC_TIMEOUT)\n      Serial.println(\"Connection timeout\");\n  }\n\nif (state & AutoConnect::AC_CAPTIVEPORTAL)\n    Serial.println(\"Captive portal is still alive\");\nelse\n    Serial.println(\"Captive portal is not available\");\n}\n\nvoid loop() {\n  portal.handleClient();\nuint8_t transition = portal.portalStatus();\n\nif (transition != state) {\nif (transition & AutoConnect::AC_CAPTIVEPORTAL)\n      Serial.println(\"Captive portal activated\");\nif (transition & AutoConnect::AC_AUTORECONNECT)\n      Serial.println(\"Auto reconnection applied\");\nif (!(transition & AutoConnect::AC_ESTABLISHED))\n      Serial.println(\"WiFi connection lost\");\n\n    state = transition;\n  }\n}\n

    AutoConnect::portalStatus within the loop of AutoConnect::handleClient

    AutoConnect::portalStatus function is also valid during the AutoConnect::handleClient loop inside the loop function. With the background reconnection enabled using the AutoConnectConfig::autoReconnect and AutoConnectConfig::reconnectInterval settings, the AutoConnect::portalStatus function will return a value indicating the reconnection status at every time AutoConnect::handleClient in the loop().

    "},{"location":"adcpcontrol.html","title":"Captive portal control","text":"

    The default behavior of AutoConnect is to launch the captive portal if 1st-WiFi.begin attempting inside AutoConnect::begin fails. You can change this default behavior through the AutoConnectConfig settings join together with Sketch code that implements to control the WiFi connection attempting.

    • Captive portal start control
    • Captive portal start detection
    • Captive portal state identification
    • Captive portal timeout control
    • Disable the captive portal
    • Launch the captive portal on demand by external trigger
    • Launch the captive portal on-demand at losing WiFi
    • Shutdown the captive portal
    • Sketch execution during the captive portal loop
    "},{"location":"adcpcontrol.html#captive-portal-start-control","title":"Captive portal start control","text":"

    AutoConnect will launch the captive portal based on the AutoConnectConfig settings when the WiFi connection status will become to certain conditions. AutoConnectConfig::autoRise and AutoConnectConfig::immediateStart are concern the conditions to launch the captive portal. Also, the AutoConnectConfig::retainPortal controls the continuity of the captive portal state and allows the Sketch to launch the captive portal dynamically even while in a handleClient loop.

    The autoRise allows or disallows the launch of the captive portal. AutoConnect launches the captive portal only if the autoRise is true. If the autoRise is false, the captive portal will not start even if the WiFi connection is lost.

    Basically, the captive portal initiation is triggered by the result of 1st-WiFi.begin, but Sketch can control it according to direct the following four actions by configuring AutoConnectConfig with two parameters, the immediateStart and the autoRise.

    AutoConnectConfig::immediateStart AutoConnectConfig::autoRise true false true Skip *1st-WiFi.begin*ESP module becomes SoftAP and the captive portal starts immediately. Not attempt WiFi connection.Only WebServer will start in STA mode. false Attempts WiFi connection in STA mode.In some cases, the autoReconnect may restore the connection even if 1st-WiFiBeing fails.If the connection is completely lost, the captive portal will be launched.This is the default. Attempts WiFi connection in STA mode.In some cases, the autoReconnect may restore the connection even if 1st-WiFiBeing fails.ESP module stays in STA mode and WebServer will start.

    The retainPortal specifies the continuity of the captive portal after AutoConnect::begin, allowing the captive portal would be launched after the Sketch execution has transitioned into the loop function. When AutoConnect establishes a WiFi connection while in the captive portal within AutoConnect::begin, it stops the DNS server to close the captive portal with SoftAP still running. In this situation, if the Sketch loses the established WiFi connection while executing the loop function, it can reopen the captive portal.

    However, this behavior can be redundant depending on the Sketch characteristics. In such a case, you can prevent to starting the captive portal during the loop() by autoRise setting to false.

    "},{"location":"adcpcontrol.html#captive-portal-start-detection","title":"Captive portal start detection","text":"

    The captive portal will only be activated if 1st-WiFi::begin fails. Sketch can detect with the AutoConnect::onDetect function that the captive portal has started. For example, the Sketch can be written like as follows that turns on the LED at the start captive portal.

    AutoConnect Portal;\n\nbool startCP(IPAddress& ip) {\n  digitalWrite(BUILTIN_LED, HIGH);\n  Serial.println(\"C.P. started, IP:\" + ip.toString());\nreturn true;\n}\n\nvoid setup() {\n  Serial.begin(115200);\n  pinMode(BUILTIN_LED, OUTPUT);\n  digitalWrite(BUILTIN_LED, LOW);\n  Portal.onDetect(startCP);\nif (Portal.begin()) {\n    digitalWrite(BUILTIN_LED, LOW);\n  }\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n
    "},{"location":"adcpcontrol.html#captive-portal-state-identification","title":"Captive portal state identification","text":"

    You can use the AutoConnect::isPortalAvailable function to identify if AutoConnect is in a captive portal state.

    Captive-Portal - i.e., just a spoofed response to a DNS lookup for Internet connection verification that occurs on a new connection attempt from the client device; it needs a DNS server and SoftAP to work. AutoConnect implements it with HTTP redirection. The AutoConnect::isPortalAvailable function returns true if all of the following conditions are met.

    • ESP module is in WIFI_AP mode and enable SoftAP.
    • IP address assigned to SoftAP is the equivalent of AutoConnectConfig::apip.
    • AutoConnect is running a DNS server for directing to the captive portal. Through its action, DNS lookups issued by client devices for Internet transparency validation are directed to the ESP module SoftAP.

    A similar utility is AutoConnect::portalStatus

    See Verify the WiFi connection conditions and AutoConnect::portalStatus function.

    "},{"location":"adcpcontrol.html#captive-portal-timeout-control","title":"Captive portal timeout control","text":"

    Once AutoConnect has entered the captive portal state due to the above conditions, the default behavior is that AutoConnect::begin will not exit until a WiFi connection is established. Captive portal timeout control prevents AutoConnect from blocking the Sketch progress. It allows Sketch to abort AutoConnect::begin and returns control to Sketch.

    AutoConnect has two parameters for timeout control. The first is the timeout value used when trying to connect to the specified AP. It works like a typical timeout control for connection attempts with WiFi.begin. This setting is specified by the AutoConnectConfig::beginTimeout or third argument of the AutoConnect::begin function. The default value is the macro defined by AUTOCONNECT_TIMEOUT in the AutoConnectDefs.h header file.

    Another timeout control is for the captive portal itself. It is useful if you want to keep the Sketch offline running even if a WiFi connection is not possible. You can also combine its setting with the immediateStart option to create highly mobile sketches. The timeout of the captive portal is specified by the AutoConnectConfig::portalTimeout as follows.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect  portal;\nAutoConnectConfig  config;\n\nvoid setup() {\n  config.portalTimeout = 60000;  // It will time out in 60 seconds\n  portal.config(config);\n  portal.begin();\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n// Some sketch code for the connected scene is here.\n  }\nelse {\n// Some sketch code for not connected scene is here.\n  }\n  portal.handleClient();\n}\n

    Also, if you want to stop AutoConnect completely when the captive portal is timed out, you need to call the AutoConnect::end function. It looks like the following code:

    bool acEnable;\n\nvoid setup() {\n  config.portalTimeout = 60000;  // It will time out in 60 seconds\n  portal.config(config);\n  acEnable = portal.begin();\nif (!acEnable) {\n    portal.end();\n  }\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n// Some sketch code for the connected scene is here.\n  }\nelse {\n// Some sketch code for not connected scene is here.\n  }\nif (acEnable) {\n    portal.handleClient();\n  }\n}\n

    AutoConnectConfig has another option related to timeouts that you can enable to take advantage of the captive portal feature after a timeout occurrence. The AutoConnectConfig::retainPortal option will not shut down SoftAP and the internal DNS server even though AutoConnect::begin has aborted due to a timeout occurrence. Even after the captive portal times out, you can always try to connect to the AP while keeping the Sketch running offline.

    The following sample code is the Sketch above with the retainPortal setting added. As you can see, the implementation for captive portal continuation does not affect the main logic of the Sketch.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect  portal;\nAutoConnectConfig  config;\n\nvoid setup() {\n  config.portalTimeout = 60000;  // It will time out in 60 seconds\n  config.retainPortal = true;\n  portal.config(config);\n  portal.begin();\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n// Some sketch code for the connected scene is here.\n  }\nelse {\n// Some sketch code for not connected scene is here.\n  }\n  portal.handleClient();\n}\n
    "},{"location":"adcpcontrol.html#disable-the-captive-portal","title":"Disable the captive portal","text":"

    It can also prevent the captive portal from starting even if the connection at the 1st-WiFi.begin fails. In this case, AutoConnect::begin behaves same as WiFi.begin.

    For disabling the captive portal, autoRise sets to false with AutoConnectConfig.

    AutoConnect       portal;\nAutoConnectConfig acConfig;\n\nacConfig.autoRise = false;\nportal.config(acConfig);\nportal.begin();\n
    "},{"location":"adcpcontrol.html#launch-the-captive-portal-on-demand-by-external-trigger","title":"Launch the captive portal on demand by external trigger","text":"

    The default behavior of AutoConnect::begin gives priority to connect to the least recently established access point. In general, We expect this behavior in most situations, but will intentionally launch the captive portal on some occasion.

    Here section describes how to launch on demand the captive portal, and suggests two templates that you can use to implement it.

    1. Offline for usual operation, connect to WiFi with an external switch

      You can use this template if the ESP module does not connect to WiFi at an ordinal situation and need to establish by a manual trigger. In this case, it is desirable that AutoConnect not start until an external switch fires. This behavior is similar to the WiFiManager's startConfigPortal function. AutoConnectConfig::immediateStart is an option to launch the portal by the SoftAP immediately without attempting 1st-WiFi.begin. Also, by setting the AutoConnectConfig::autoRise option to false, it is possible to suppress unintended automatic pop-ups of the portal screen when connecting to an ESP module SSID. To implement this, execute AutoConnect::config within the setup() function as usual, and handle AutoConnect::begin inside the loop() function.

      #define TRIGGER_PIN 5     // Trigger switch should be LOW active.\n#define HOLD_TIMER  3000\n\nAutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  pinMode(5, INPUT_PULLUP);\n  Config.immediateStart = true;\n// Config.autoRise = false;   // If you don't need to automatically pop-up the portal when connected to the ESP module's SSID.\n  Portal.config(Config);\n}\n\nvoid loop() {\nif (digitalRead(TRIGGER_PIN) == LOW) {\nunsigned long tm = millis();\nwhile (digitalRead(TRIGGER_PIN) == LOW) {\n      yield();\n    }\n// Hold the switch while HOLD_TIMER time to start connect.\nif (millis() - tm > HOLD_TIMER)\n      Portal.begin();\n  }\n\nif (WiFi.status() == WL_CONNECTED) {\n// Here, what to do if the module has connected to a WiFi access point\n  }\n\n// Main process of your sketch\n\n  Portal.handleClient();  // If WiFi is not connected, handleClient will do nothing.\n}\n

      It will not be automatic reconnect

      The above example does not connect to WiFi until TRIGGER_PIN goes LOW. When TRIGGER_PIN goes LOW, the captive portal starts and you can connect to WiFi. Even if you reset the module, it will not automatically reconnect.

    2. Register new access points on demand

      The following template is useful for controlling the registration of unknown access points. In this case, the ESP module establishes a WiFi connection using WiFi.begin natively without relying on AutoConnect. Known access point credentials are saved by AutoConnect, to the ESP module can use the saved credentials to handle WiFi.begin natively. This means that you can explicitly register available access points when needed, and the ESP module will not use unknown access points under normal situations.

      AutoConnect* portal = nullptr;\n\nbool detectSwitch() {\n/*\n  Returns true if an external switch to configure is active.\n  */\n}\n\nbool connectWiFi(const char* ssid, const char* password, unsigned long timeout) {\n  WiFi.mode(WIFI_STA);\n  delay(100);\n  WiFi.begin(ssid, password);\nunsigned long tm = millis();\nwhile (WiFi.status() != WL_CONNECTED) {\nif (millis() - tm > timeout)\nreturn false;\n  }\nreturn true;\n}\n\nvoid setup() {\n  AutoConnectCredential credt;\n  station_config_t  config;\nfor (int8_t e = 0; e < credt.entries(); e++) {\n    credt.load(e, &config);\nif (connectWiFi(config.ssid, config.password, 30000))\nbreak;\n  }\nif (WiFi.status() != WL_CONNECTED) {\n// Here, do something when WiFi cannot reach.\n  }\n}\n\nvoid loop() {\nif (detectSwitch()) {\n    AutoConnectConfig config;\n    config.immediateStart= true;\nif (!portal) {\n      portal = new AutoConnect;\n    }\n    portal->config(config);\nif (portal->begin()) {\n      portal->end();\ndelete portal;\n      portal = nullptr;\n    }\n  }\n// Here, ordinary sketch logic.\n}\n
    "},{"location":"adcpcontrol.html#launch-the-captive-portal-on-demand-at-losing-wifi","title":"Launch the captive portal on-demand at losing WiFi","text":"

    If the ESP module loses the established WiFi connection during the loop of handleClient, you can prevent the ESP module from going absolutely standalone by launching the captive portal on demand.

    When retainPortal and autoRise settings are enabled, AutoConnect will launch SoftAP and start DNS when it detects a WiFi disconnect with the router during a handleClient loop. This behavior will occur caused by a WiFi disconnect detection even if the WiFi mode is STA.

    Since AutoConnect v1.2.0, An improved retainPortal option allows the captive portal to be restarted during a handleClient loop even if it is closed once in AutoConnect::begin. In this case, the Sketch execution stage has already transitioned into the loop function, so the Sketch process seems running concurrently with the captive portal loop. Its captive portal launched from inside handleClient does not block the execution of the Sketch, unlike that launched from AutoConnect::begin.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  Config.autoRise = true; // It's the default, no setting is needed explicitly.\n  Config.retainPortal = true;\n  Portal.config(Config);\n  Portal.begin();\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    Need autoRise enabled

    Need AutoConnectConfig::autoRise setting enabled to start the captive portal on demand during a handleClient loop.

    Although the Sketch above specifies the retainPortal, it does not instruct starts the captive portal always. AutoConnect will try WiFi.begin once in AutoConnect::begin unless the immediateStart option is specified. If AutoConnect fails the 1st-WiFi.begin, the captive portal will be launched at that point and the Sketch execution will stay within the AutoConnect::begin function.

    There is also a way to avoid starting the captive portal inside AutoConnect::begin and start the captive portal according to the WiFi connection status after the Sketch execution transitions to a handleClient loop. Adjusting the timing of autoRise activation will allow the captive portal to start only from inside AutoConnect::handleClient function.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  Config.retainPortal = true;\n  Config.autoRise = false;  // Suppresses the launch of the captive portal from AutoConnect::begin.\n  Portal.config(Config);    // Don't forget it.\n  Portal.begin();\n  Config.autoRise = true;   // Enable the launch of the captive portal.\n  Portal.config(Config);    // Don't forget it.\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    The retainPortal option will keep SoftAP even if WiFi has established a connection as a client with the router. Since it has the effect of stopping the DNS server, the phenomenon that the portal screen will not pop up automatically even though SoftAP is in action occur. This is a legacy behavior to ensure backward compatibility with up to AutoConnect v1.1.7. To stop SoftAP on escape from the on-demand captive portal, you need to explicitly call WiFi.softAPdisconnect(true) and WiFi.enableAP(false) in the Sketch.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nbool  Connected;\nunsigned long Elapsed;\n\nvoid onConnect(IPAddress& clientIP) {\n  Connected = true;\n  Elapsed = millis();\n}\n\nvoid setup() {\n  Config.retainPortal = true;\n  Portal.config(Config);\n  Portal.onConnect(onConnect);\n  Portal.begin();\n}\n\nvoid loop() {\nif (WiFi.status() != WL_CONNECTED) {\n    connected = false;\n    Elapsed = millis();\n  }\n\nif ((WiFi.getMode() & WIFI_AP) && Connected) {\nif (millis() - Elapsed > 30000) {\n      WiFi.softAPdisconnect(true);\n      WiFi.enableAP(false);\n    }\n  }\n// Actual sketch process is here.\n\n  Portal.handleClient();\n}\n

    The above sketch will shutdown the SoftAP after elapsed time exceeds 30 seconds since the connection was re-established. Its logic is a bit tricky and does not stop SoftAP immediately after the connection established, which has several seconds delay. Doing it ensures that AutoConnect can send the HTML response.

    Stopped SoftAP is still displayed

    After SoftAP stopped, there is a time lag before it disappears from the detected access points list on the client device.

    "},{"location":"adcpcontrol.html#shutdown-the-captive-portal","title":"Shutdown the captive portal","text":"

    There is some complexity in the conditions under which AutoConnect shuts down the captive portal. Making a sketch that activates SoftAP only when needed can seem tedious. But there is a reason why. Even if AutoConnect could establish a connection using a captive portal, your cell phone as a client device would still have to keep connected to the ESP module-generated SoftAP in order to send the page for notifying the connection successful to a user. At that point, your client device that opened the captive portal still needs a connection with SoftAP.

    What happens, after all, is as follows:

    1. You made a connection to the access point such as WiFi router using the captive portal and took a successful page.
    2. Your sketch will rush into the loop function and starts to works well, hooray!
    3. Oops. Don't celebrate yet. I can see SoftAP ID on my cell phone. But the AutoConnect page never pops up automatically. Why?

    Because, for the above reasons, we can not promptly shut down the SoftAP. (However, DNS will stop)

    So, If you want to stop SoftAP after connecting to the access point using the captive portal, you need to implement the shutdown process with Sketch explicitly. A template of the basic sketch that can stop the SoftAP after the connection is the following:

    AutoConnect Portal;\n\nvoid setup() {\nif (Portal.begin()) {\nif (WiFi.getMode() & WIFI_AP) {\n      WiFi.softAPdisconnect(true);\n      WiFi.enableAP(false);\n    }\n  }\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    If you stop SoftAP, the connection will be lost

    If you stop SoftAP immediately after the AutoConnect::begin successful, will part with the connection and cannot see the result notifying on your client device. You can expect to receive result notifications if you run handleClient before stopping SoftAP. (although you may not always succeed; it will not work if the WiFi radio signal is weak)

    "},{"location":"adcpcontrol.html#sketch-execution-during-the-captive-portal-loop","title":"Sketch execution during the captive portal loop","text":"

    With AutoConnect::begin, once the captive portal is started without being able to connect to a known WiFi access point, control will not return to sketch until the WiFi connection is established or times out. This behavior helps to pin the ESP module's network participation as a WiFi client (that is, AutoConnect::begin is an alternative to WiFi.begin) but it can not rush into the loop function of the Sketch. Therefore, while the ESP module is in the captive portal state and waiting for a connection operation to the access point, the behavior of the Sketch will be restrained by the escape conditions from AutoConnect::begin.

    The whileCaptivePortal exit allows the Sketch to continue the process temporarily while the ESP module remains standalone and the captive portal is open. AutConnect::whileCaptivePortal function registers the user's sketch function to be called by AutoConnect::begin or AutoConnect::handleClient during the execution of the captive portal session loop.

    The whileCaptivePortal exit can be registered by following: 

    AutoConnect portal;\n\nbool whileCP(void) {\nbool  rc;\n// Here, something to process while the captive portal is open.\n// To escape from the captive portal loop, this exit function returns false.\n// rc = true;, or rc = false;\nreturn rc;\n}\n\nvoid setup() {\n  ...\n  portal.whileCaptivePortal(whileCP);\n  portal.begin();\n  ...\n}\n

    AutoConnect will open the captive portal in the AutoConnect::begin and AutoConnect::handleClient scenes, but the whileCaptive portal exit will be called repeatedly from AutoConnect::begin until exits from it. The whileCaptivePortal exit will be called repeatedly while the captive portal is open until WiFi connected or times out occurs. In the Sketch, returning a FALSE value from the whileCaptivePortal function allows the control to escape from the captive portal loop even before the session elapsed time exceeds the limits.

    "},{"location":"adcredential.html","title":"Credential accesses","text":"

    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
    "},{"location":"adcredential.html#access-to-saved-credentials","title":"Access to saved credentials","text":"

    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.

    "},{"location":"adcredential.html#autosave-credential","title":"Autosave Credential","text":"

    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;\nAutoConnectConfig Config;\nConfig.autoSave = AC_SAVECREDENTIAL_NEVER;\nPortal.config(Config);\nPortal.begin();\n

    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 corefor ESP8266 Arduino core for ESP32 1.0.2 earlier 1.0.3 later v0.9.12 earlier EEPROM EEPROM (partition) Not supported v1.0.0 later Preferences (nvs)

    (Can be used EEPROM with turning off AUTOCONNECT_USE_PREFERENCES macro)

    Preferences (nvs)"},{"location":"adcredential.html#move-the-saving-area-of-eeprom-for-the-credentials","title":"Move the saving area of EEPROM for the credentials","text":"

    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:

    |--------------|-------|---------------|--|--|--|--|--|\n^              ^       ^               ^     ^\nSketch    OTA update   File system   EEPROM  WiFi config (SDK)\n

    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;\nAutoConnectConfig config;\n\n// Defines the custom data should be stored in EEPROM.\ntypedef struct {\nchar  data1[8];\nchar  data2[8];\nchar  data3[8];\n} EEPROM_CONFIG_t;\nEEPROM_CONFIG_t eepromConfig;\n...\n// Declares to reserve the EEPROM_CONFIG_t area for a Sketch using.\nconfig.boundaryOffset = sizeof(eepromConfig);\nportal.config(config);\n...\nstrcpy(eepromComfig.data1, \"data1\");\nstrcpy(eepromComfig.data2, \"data2\");\nstrcpy(eepromComfig.data3, \"data3\");\n\n// Use getEEPROMUsedSize to access the EEPROM with the appropriate region size.\nEEPROM.begin(portal.getEEPROMUsedSize());\nEEPROM.put<EEPROM_CONFIG_t>(0, eepromConfig);\nEEPROM.commit();\nEEPROM.end();\n...\n
    "},{"location":"adcredential.html#save-and-restore-credentials","title":"Save and restore credentials","text":"

    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>\n#include <LittleFS.h>\n\n...\n\nAutoConnect portal;\n\nvoid setup() {\n  LittleFS.begin(true);\n\nif (portal.begin()) {\n    portal.saveCredential(\"/cred\", LittleFS);\n  }\n}\n
    #include <FS.h>\n#include <LittleFS.h>\n\n...\n\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  LittleFS.begin();\n\n  config.autoReconnect = true;\n  portal.config(config);\n  portal.restoreCredential(\"/cred\", LittleFS);\n  portal.begin();\n}\n

    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>\n#include <SD.h>\n\n...\n\nAutoConnect portal;\n\nvoid setup() {\n  SD.begin();\n\nif (portal.begin()) {\n    portal.saveCredential<SDClass>(\"/cred\", SDFS);   // For ESP8266\n// portal.saveCredential<fs::SDFS>(\"/credentials\", SDFS);  // For ESP32\n  }\n}\n
    #include <SPI.h>\n#include <SD.h>\n\n...\n\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  SD.begin();\n\n  config.autoReconnect = true;\n  portal.config(config);\n  portal.restoreCredential<SDClass>(\"/cred\", SDFS);  // For ESP8266\n// portal.restoreCredential<fs::SDFS>(\"/credentials\", SDFS);  // For ESP32\n\n  portal.begin();\n}\n
    "},{"location":"adexterior.html","title":"Customizing page appearance","text":"

    The design of various AutoConnect web pages is basically inflexible. Its appearance and layout don't have many customizable visual aspects but nevertheless, you can customize the following appearances of your AutoConnect web pages:

    • AutoConnect menu colorize (See Appendix)
    • Make different menu labels
    • Make different menu title
    • Capture the legacy web pages as items into the menu
    "},{"location":"adexterior.html#make-different-menu-labels","title":"Make different menu labels","text":"

    You can change the label text for each menu item but cannot change them at run time. There are two ways to change the label text, both of which require coding the label literal.

    1. Overwrite the label literal of library source code directly.

      You can change the label of the AutoConnect menu item by rewriting the default label literal in AutoConnectLabels.h macros. However, changing menu items literal influences all the Sketch's build scenes.

      #define AUTOCONNECT_MENULABEL_CONFIGNEW   \"Configure new AP\"\n#define AUTOCONNECT_MENULABEL_OPENSSIDS   \"Open SSIDs\"\n#define AUTOCONNECT_MENULABEL_DISCONNECT  \"Disconnect\"\n#define AUTOCONNECT_MENULABEL_RESET       \"Reset...\"\n#define AUTOCONNECT_MENULABEL_UPDATE      \"Update\"\n#define AUTOCONNECT_MENULABEL_HOME        \"HOME\"\n#define AUTOCONNECT_MENULABEL_DEVINFO     \"Device info\"\n#define AUTOCONNECT_BUTTONLABEL_RESET     \"RESET\"\n#define AUTOCONNECT_BUTTONLABEL_UPDATE    \"UPDATE\"\n

      build_flags with PlatformIO will no effect

      The mistake that many people make is to use PlatformIO's build_flags to try to redefine any literal at compile time. The AutoConnect library statically contains the label literals which are embedded as binary data when compiling the library code. The label literals will not change without compiling the library source. And PlatformIO is a build system. Library sources will not be compiled unless AutoConnectLabels.h is updated.

    2. Change the label literals for each Arduino project

      Another way to change the label literal is to provide a header file that defines the label literals, as mentioned in Appendix. You can also use this method to display label text and fixed text in the local language on the AutoConnect page. See Change the item's label text section for details.

    "},{"location":"adexterior.html#make-different-menu-title","title":"Make different menu title","text":"

    Although the default menu title is AutoConnect, you can change the title by setting AutoConnectConfig::title. To set the menu title properly, you must set before calling AutoConnect::begin.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n// Set menu title\n  Config.title = \"FSBrowser\";\n  Portal.config(Config);\n  Portal.begin();\n}\n

    Executing the above sketch will rewrite the menu title for the FSBrowser as the below.

    "},{"location":"adexterior.html#capture-the-legacy-web-pages-as-items-into-the-menu","title":"Capture the legacy web pages as items into the menu","text":"

    You can embed the ordinary page processed by the ESP8266WebServer request handler as an item into the AutoConnect menu. AutoConnect can capture the legacy web pages for ESP8266WebServer or WebServer of ESP32 and extends the menu containing these items. In ordinary, the Sketch registers the request handler for the page depending on URI using the ESP8266WebServer::on function. AutoConnect allows Sketch to bundle the registered legacy page into a menu. the Sketch is able to include its URI to a menu item using AutoConnect::append function that creates internally an AutoConnectAux depended on its URI and integrates into the menu.

    The following code has a mixture of both AutoConnectAux and the legacy web page. An AutoConnectAux page is menued automatically with the AutoConnect::join or AutoConnect::load function. Similarly, a legacy page is integrated by the AutoConnect::append function.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nESP8266WebServer server;\nAutoConnect      portal(server);\n\n// Definitions of AutoConnectAux page\nstatic const char PAGE[] PROGMEM = R\"(\n{\n  \"title\": \"PAGE\",\n  \"uri\": \"/page\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"cap\",\n      \"type\": \"ACText\",\n      \"value\": \"This is a custom web page.\"\n    }\n  ]\n}\n)\";\n\nvoid setup() {\n// The Web page handler located to /hello\n  server.on(\"/hello\", [](){\n    server.send(200, \"text/html\", String(F(\n\"<html>\"\n\"<head><meta name='viewport' content='width=device-width,initial-scale=1.0'></head>\"\n\"<body><h2>Hello, world</h2></body>\"\n\"</html>\"\n    )));\n  });\n\n  portal.append(\"/hello\", \"HELLO\");  // Adds an item as HELLO into the menu\n  portal.load(FPSTR(PAGE));               // Load AutoConnectAux custom web page\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    The AutoConnect::append function also has the third parameter that directly specifies the request handler. It has similar efficacy to calling the append and ESP8266WebSever::on at once. 1

    portal.append(\"/hello\", \"HELLO\", [](){\n  server.send(200, \"text/html\", String(F(\n\"<html>\"\n\"<head><meta name='viewport' content='width=device-width,initial-scale=1.0'></head>\"\n\"<body><h2>Hello, world</h2></body>\"\n\"</html>\"\n  )));\n});\n

    For more details, see section Attach the menus of Examples page.

    An instance of ESP8266WebServer/WebServer is needed

    When calling the append function with request handler parameters, an instance of the WebServer as the registration destination must exist. AutoConnect can instantiate and host a WebServer internally, but in that case, the point in time to call the AutoConnect::append function with a request handler parameter must be after AutoConnect::begin.

    1. However, the pages registered this way remain legacy. Therefore, the AutoConnect menu bar is not appeared.\u00a0\u21a9

    "},{"location":"adnetwork.html","title":"Settings and controls for network and WiFi","text":"

    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
    • Assign user sketch's home path
    • Change SSID and Password for SoftAP
    • Combination with mDNS
    • Make SSID of SoftAP unique
    • Relocate the AutoConnect home path
    • SoftAP access point IP settings
    • Static IP assignment as a client
    • Static IP preservation
    • Station hostname
    "},{"location":"adnetwork.html#404-handler","title":"404 handler","text":"

    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.

    "},{"location":"adnetwork.html#assign-user-sketchs-home-path","title":"Assign user sketch's home path","text":"

    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:

    • AUTOCONNECT_URI The ROOT URI of AutoConnect. It is defined in AutoConnectDefs.h file and is assigned to AutoConnect statistics screen by default.
    • AutoConnectConfig::homeUri It is the hyperlink of listed on the AutoConnect menu as HOME.
    • AutoConnectConfig::bootUri Which page appears at the captive portal, AUTOCONNECT_URI, or the homeUri. Its page will pop up automatically when you visit the captive portal.
    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 HOMEAlso, 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"},{"location":"adnetwork.html#change-ssid-and-password-for-softap","title":"Change SSID and Password for SoftAP","text":"

    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;\nAutoConnectConfig config;\n\nvoid setup() {\n config.apid = \"ap_portal\";\n  config.psk  = \"new_password\";\n  portal.config(config);\n  portal.begin();\n}\n

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

    AutoConnect portal;\nAutoConnectConfig config(\"ap_portal\", \"new_password\");\nvoid setup() {\n  portal.config(config);\n  portal.begin();\n}\n

    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.

    "},{"location":"adnetwork.html#combination-with-mdns","title":"Combination with mDNS","text":"

    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>\n#include <ESP8266mDNS.h>\n#include <ESP8266WebServer.h>\nAutoConnect Portal;\nvoid setup() {\nif (Portal.begin()) {\nif (MDNS.begin(\"esp8266\")) {\n      MDNS.addService(\"http\", \"tcp\", 80);\n    }\n  }\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n
    "},{"location":"adnetwork.html#make-ssid-of-softap-unique","title":"Make SSID of SoftAP unique","text":"

    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;\nAutoConnectConfig acConfig;\n\nacConfig.apid = \"ESP-\" + String(ESP.getChipId(), HEX);\naConfig.psk = YOUR_PASSWORD;\nportal.config(acConfig);\nportal.begin();\n

    Obtaining chip ID for ESP32

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

    "},{"location":"adnetwork.html#relocate-the-autoconnect-home-path","title":"Relocate the AutoConnect home path","text":"

    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\"\n
    "},{"location":"adnetwork.html#softap-access-point-ip-settings","title":"SoftAP access point IP settings","text":"

    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"},{"location":"adnetwork.html#static-ip-assignment-as-a-client","title":"Static IP assignment as a client","text":"

    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;\nAutoConnectConfig  Config;\nConfig.staip = IPAddress(192, 168, 1, 10);\nConfig.staGateway = IPAddress(192, 168, 1, 1);\nConfig.staNetmask = IPAddress(255, 255, 255, 0);\nConfig.dns1 = IPAddress(192,168,1,1);\nportal.config(Config);\nportal.begin();\n
    "},{"location":"adnetwork.html#static-ip-preservation","title":"Static IP preservation","text":"

    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;\nAutoConnectConfig config;\n\nvoid setup() {\n// If the connection to the last established AP fails, attempt to\n// connect to the nearest AP using known credentials.\n  config.autoReconnect = true;\n\n// Apply the following static IP configuration to reconnect.\n  config.staip = IPAddress(192, 168, 1, 10);\n  config.staGateway = IPAddress(192, 168, 1, 1);\n  config.staNetmask = IPAddress(255, 255, 255, 0);\n  config.dns1 = IPAddress(192, 168, 1, 1);\n\n// The above settings take precedence over the IP settings of the\n// stored credentials.\n// If this value is left false, the station IP configuration contained\n// in the stored credentials takes precedence.\n  config.preserveIP = true;\n  portal.config(config);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    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.

    "},{"location":"adnetwork.html#station-hostname","title":"Station hostname","text":"

    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.\u00a0\u21a9

    "},{"location":"adothers.html","title":"Other operation settings and controls","text":"

    AutoConnect also has features that are not directly related to WiFi connection abilities. They're mostly like a little accessory but can reduce the amount of sketch code.

    • Built-in OTA update
    • Choice of the filesystem for ESP8266
    • Debug Print
    • File uploading via built-in OTA feature
    • Refers the hosted ESP8266WebServer/WebServer
    • Reset the ESP module after disconnecting from WLAN
    • Ticker for WiFi status
    • Usage for automatically instantiated ESP8266WebServer/WebServer
    • Use with the PageBuilder library
    "},{"location":"adothers.html#built-in-ota-update-feature","title":"Built-in OTA update feature","text":"

    AutoConnect features a built-in OTA function to update ESP module firmware. You can easily make the Sketch that equips OTA and able to operate with the AutoConnect menu.

    AutoConnectConfig::ota specifies to import the built-in OTA update class into the Sketch. See the Updates with the Web Browser chapter for details.

    "},{"location":"adothers.html#choice-of-the-filesystem-for-esp8266","title":"Choice of the filesystem for ESP8266","text":"

    For ESP8266, since the Arduino core v2.7.0, SPIFFS has deprecated and the migration to LittleFS is being promoted currently. AutoConnect has adopted LittleFS as the default filesystem to follow the core standard.

    However, SPIFFS is still valid. AutoConnect can correctly compile and execute sketches made with SPIFFS assumed. When you make an AutoConnect sketch with SPIFFS enabled, you need to change the macro definition that AutoConnectDefs.h has. AC_USE_SPIFFS definition will enable SPIFFS as the filesystem.

    #define AC_USE_SPIFFS\n

    See also the FAQ to help you enable AC_USE_SPIFFS correctly. Note that refers to the Using Filesystem chapter to know the utilization capabilities of the file system with AutoConnect.

    "},{"location":"adothers.html#debug-print","title":"Debug Print","text":"

    You can output AutoConnect monitor messages to the Serial. A monitor message activation switch is in an include header file AutoConnectDefs.h of library source. Define AC_DEBUG macro to output the monitor messages.1

    #define AC_DEBUG\n

    AutoConnect does not automatically start the Serial even if AC_DEBUG is activated. The Sketch should start the Serial during its setup phase using Serial.begin(BAUDRATE).

    How to enable AC_DEBUG

    The #define is a C++ preprocessor directive. The build process of the Sketch by the Arduino IDE is processed independently of the subsequent C++ compilation unit. Writing the #define directive for AC_DEBUG in the Sketch has no effect on the AutoConnect library. To compile the AutoConnect library with the AC_DEBUG directive, you can either edit the library source code directly (usually it is located in ~/Arduino/libraries/AutoConnect/src) or use a build system which can configure the preprocessor directives externally such as PlatformIO. To enable AC_DEBUG using PlatformIO without modifying the library source, specify the build_flags directive in the platformio.ini file with each project. 

    build_flags = -DAC_DEBUG\n

    "},{"location":"adothers.html#file-uploading-via-built-in-ota-feature","title":"File uploading via built-in OTA feature","text":"

    The built-in OTA update feature can update the firmware as well as upload regular files placed in the file system on the ESP module. It allows a regular file is uploaded via OTA using the Update of AutoConnect menu without adding a particular custom Web page that contains AutoConnectFile. This ability is useful for transferring the JSON document of the custom web page definition, the external parameter file of your sketch, and so on into the target ESP module via OTA.

    The built-in OTA update feature determines where to save the uploaded file according to the filename pattern. By default, a filename with ends a .bin extension is subject to firmware updates. A file that has the other extension will be saved as a regular to the filesystem in the flash. The file extension that should be treated as the firmware is defined as the AUTOCONNECT_UPLOAD_ASFIRMWARE macro in AutoConnectDefs.h header file of the library source code. When dealing with another extension for the updating file as firmware change this macro definition.

    #define AUTOCONNECT_UPLOAD_ASFIRMWARE \".bin\"\n

    Specify with the PlatformIO

    AUTOCONNECT_UPLOAD_ASFIRMWARE pattern will be embedded into the binary sketch is determined at compile time. The PlatformIO build system allows you to change the pattern expression for each project without modifying the library source code.

    build_flags=-DAUTOCONNECT_UPLOAD_ASFIRMWARE='\".bin\"'\n
    "},{"location":"adothers.html#refers-the-hosted-esp8266webserverwebserver","title":"Refers the hosted ESP8266WebServer/WebServer","text":"

    Constructing an AutoConnect object variable without parameters then creates and starts an ESP8266WebServer/WebServer inside the AutoConnect. This object variable could be referred by AutoConnect::host function to access ESP8266WebServer/WebServer instance as like below.

    AutoConnect Portal;\n\nPortal.begin();\nESP8266WebServer& server = Portal.host();\nserver.send(200, \"text/plain\", \"Hello, world\");\n

    When host() is valid

    The host() can be referred at after AutoConnect::begin.

    "},{"location":"adothers.html#reset-the-esp-module-after-disconnecting-from-wlan","title":"Reset the ESP module after disconnecting from WLAN","text":"

    Disconnect by menu operation allows the ESP8266/ESP32 module to reset automatically after disconnecting from WLAN. This behavior is enabled by default and can be disabled by AutoConnectConfig::autoReset settings.

    AutoConnect       Portal;\nAutoConnectConfig Config;\nConfig.autoReset = false; // Continue sketch processing even after disconnecting from by AutoConnect menu.\nPortal.config(Config);\nPortal.begin();\n

    The autoReset setting will automatically reset the ESP module when disconnecting WiFi only if you intentionally navigate the menu. And it does not participate in passive disconnection conditions such as disconnection due to sketch processing or loss of WiFi signal.

    You can combine autoReset with autoReconnect to disconnect from WiFi and automatically reconnect to another AP while continuing the Sketch operation.

    The Sketch below shows an example of a meaningful combination of autoReset and autoReconnect. It can connect to the access point once with the captive portal but assumes that it can be disconnected from the WLAN by intentional menu navigation. In that case, the Sketch will continue processing without resetting the module. Then an external switch allows to start automatic reconnecting. In this situation, if known access points appear nearby, the ESP module will automatically reconnect to them in the handleClient loop. In this state transition, the module continues the Sketch process without resetting.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nconst int reconnectSwitch = 14; // Assign the reconnect switch to GPIO14\n\nICACHE_RAM_ATTR void detectsReconnect() {\nif (!Config.autoReconnect) {  // Chattering elimination\n// autoReconnect is enabled by interrupt of the GPIO trigger,\n    Config.autoReconnect = true;  // Activate reconnection\n    Config.reconnectInterval = 2; // Attempt to reconnect at 60 seconds intervals.\n    Portal.config(Config);\n    Serial.printf(\"Turn on autoReconnect, interval %d[s]\\n\", Config.reconnectInterval * AUTOCONNECT_UNITTIME);\n  }\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  Config.ticker = true;   // Setting up WiFi connection indicator\n  Portal.config(Config);  \n\nif (Portal.begin()) {\n    Config.autoReset = false;\n    Portal.config(Config);\n\n// Set external switch pin to reconnect as interrupt, assign interrupt function and set RISING mode\n    pinMode(reconnectSwitch, INPUT_PULLUP);\n    attachInterrupt(digitalPinToInterrupt(reconnectSwitch), detectsReconnect, RISING);\n  }\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n/*\n    Here, your sketch process with WiFi connection\n    */\n  }\nelse {\n/*\n    Here, your sketch process without WiFi connection\n    */\n  }\n\n// Post process, turn to initial state of autoReconnect.\nif (Config.autoReconnect) {\nif (WiFi.status() == WL_CONNECTED) {\n      Config.autoReconnect = false;\n      Portal.config(Config);\n    }\n  }\n\n// The actual reconnection takes place within handleClient.\n  Portal.handleClient();\n}\n

    An external switch wiring to GPIO

    The wiring for the above Sketch assumes a momentary effects switch that connects the GPIO pin 14 to GND. You can experience it with easily wire on a breadboard using a NodeMCU as like:

    "},{"location":"adothers.html#ticker-for-wifi-status","title":"Ticker for WiFi status","text":"

    Flicker signal can be output from the ESP8266/ESP32 module according to WiFi connection status. By wiring the LED to the signal output pin with the appropriate limiting resistor, you can know the WiFi connection status through the LED blink during the inside behavior of AutoConnect::begin and loop of AutoConnect::handleClient.

    AutoConnectConfig::ticker option specifies flicker signal output. The following sketch is an example of blinking the active-low LED connected to GPIO16 depending on the WiFi connection status.2

    AutoConnect        portal;\nAutoConnectConfig  Config;\nConfig.ticker = true;\nconfig.tickerPort = 16;\nConfig.tickerOn = LOW;\nportal.config(Config);\nportal.begin();\n

    The AutoConnect ticker indicates the WiFi connection status in the following three flicker patterns:

    • Short blink: The ESP module stays in AP_STA mode.
    • Short-on and long-off: No STA connection state. (i.e. WiFi.status != WL_CONNECTED)
    • No blink: WiFi connection with access point established and data link enabled. (i.e. WiFi.status = WL_CONNECTED)

    The flicker cycle length is defined by some macros in AutoConnectDefs.h header file.

    #define AUTOCONNECT_FLICKER_PERIODAP  1000 // [ms]\n#define AUTOCONNECT_FLICKER_PERIODDC  (AUTOCONNECT_FLICKER_PERIODAP << 1) // [ms]\n#define AUTOCONNECT_FLICKER_WIDTHAP   96  // (8 bit resolution)\n#define AUTOCONNECT_FLICKER_WIDTHDC   16  // (8 bit resolution)\n
    • AUTOCONNECT_FLICKER_PERIODAP: Assigns a flicker period when the ESP module stays in AP_STA mode.
    • AUTOCONNECT_FLICKER_PERIODDC: Assigns a flicker period when WiFi is disconnected.
    • AUTOCONNECT_FLICKER_WIDTHAP and AUTOCONNECT_FLICKER_WIDTHDC: Specify the duty rate for each period [ms] in 8-bit resolution.

    Ticker during OTA

    The LED blinking will always be a short blinking during the update via OTA, regardless of the definition of the flicker cycle.

    AutoConnectConfig::tickerPort specifies a port that outputs the flicker signal. If you are using an LED-equipped ESP module board, you can assign a LED pin to the tick-port for the WiFi connection monitoring without the external LED. The default pin is arduino valiant's LED_BUILTIN. You can refer to the Arduino IDE's variant information to find out which pin actually on the module assign to LED_BUILTIN.3

    AutoConnectConfig::tickerOn specifies the active logic level of the flicker signal. This value indicates the active signal level when driving the ticker. For example, if the LED connected to tickPort lights by LOW, the tickerOn is LOW. The logic level of LED_BUILTIN for popular modules are as follows:

    module Logic level LED_BUILTIN Pin Arduino alias NodeMCU V1.0 Active-low 16 D0 WEMOS D1 mini Active-low 2 D4 SparkFun ESP8266 Thing Active-high 5 Adafruit Feather HUZZAH ESP8266 Active-low 0 NodeMCU 32s Active-high 2 T2 LOLIN32 Pro Active-low 5 SS SparkFun ESP32 Thing Active-high 5 Adafruit Feather HUZZAH32 Active-high 13 A12"},{"location":"adothers.html#usage-for-automatically-instantiated-esp8266webserverwebserver","title":"Usage for automatically instantiated ESP8266WebServer/WebServer","text":"

    The Sketch can handle URL requests using ESP8266WebServer or WebServer that AutoConnect started internally. ESP8266WebServer/WebServer instantiated dynamically by AutoConnect can be referred to by AutoConnect::host function. The Sketch can use the 'on' function, 'send' function, 'client' function and others by ESP8266WebServer/WebServer reference of its return value.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect       Portal;\n\nvoid handleRoot() {\n  ESP8266WebServer& IntServer = Portal.host();\n  IntServer.send(200, \"text/html\", \"Hello, world\");\n}\n\nvoid handleNotFound() {\n  ESP8266WebServer& IntServer = Portal.host();\n  IntServer.send(404, \"text/html\", \"Unknown.\");\n}\n\nvoid setup() {\nbool r = Portal.begin();\nif (r) {\n    ESP8266WebServer& IntServer = Portal.host();\n    IntServer.on(\"/\", handleRoot);\n    Portal.onNotFound(handleNotFound);    // For only onNotFound.\n  }\n}\n\nvoid loop() {\n  Portal.host().handleClient();\n  Portal.handleRequest();\n/* or following one line code is equ.\n  Portal.handleClient();\n  */\n}\n

    ESP8266WebServer/WebServer function should be called after AutoConnect::begin

    The Sketch cannot refer to an instance of ESP8266WebServer/WebServer until AutoConnect::begin completes successfully.

    Do not use with ESP8266WebServer::begin or WebServer::begin

    ESP8266WebServer/WebServer is already running inside the AutoConnect.

    "},{"location":"adothers.html#use-with-the-pagebuilder-library","title":"Use with the PageBuilder library","text":"

    In ordinary, the URL handler will respond to the request from the client by sending some HTML. It will dynamically generate the HTML to respond to based on the sensing data etc. for the changing scene, but it contains elements of variable values in the middle of the HTML fixed string. Therefore, sketches tend to be in a tangled that repeats the logic for data handling and string splicing in turn, which tends to be less readable and maintainable.

    PageBuilder library is an HTML assembly aid. it can handle predefined HTML like the template and simplify an HTML string assemble logic, and also the generated HTML send automatically.

    An example sketch used with the PageBuilder as follows and it explains how it aids for the HTML generating. Details for GitHub repository.

    1. The source code placement of common macros for AutoConnect since v0.9.7 has changed.\u00a0\u21a9

    2. The ESP module pin mapping is different for each breakout. Definitions for assigning pin numbers to pin names usually exist in the variant definition program of Arduino core packages. (e.g. esp8266/arduino core, arduino-esp32 core) You may find the definition as pins_arduino.h.\u00a0\u21a9

    3. It's defined in the pins_arduino.h file, located in the sub-folder named variants wherein Arduino IDE installed folder.\u00a0\u21a9

    "},{"location":"advancedusage.html","title":"Advanced usage","text":""},{"location":"advancedusage.html#summary","title":"Summary","text":"

    To make sketches work as you intended with AutoConnect, make sure you understand the implications of the setting parameters and configure AutoConnect. AutoConnectConfig allows you to incorporate settings into AutoConnect that coordinate control over WiFi connectivity and captive portal behavior. For advanced usages, the configuration settings and the Sketch examples are followings:

    • AutoConnect WiFi connection control
    • Captive portal control
    • Authentication settings
    • Credential accesses
    • Settings for customizing the page exterior
    • Settings and controls for network and WiFi
    • Other operation settings and controls

    Don't forget AutoConnect::config

    The configuration cannot be reflected by only changing the member variables of AutoConnectConfig settings. It will be reflected in the actual ones by AutoConnect::config function. Don't forget to run the AutoConnect::config after changing the AutoConnectConfig member variables.

    AutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  config.autoReconnect = true;\n  portal.config(config);  // Don't forget.\n  portal.begin();\n}\n
    "},{"location":"api.html","title":"AutoConnect API","text":""},{"location":"api.html#include-headers","title":"Include headers","text":"

    The AutoConnect class is limited in its available APIs by the AutoConnect component it contains. The AutoConnect.h header file makes all AutoConnect features available. On the other hand, the AutoConnectCore.h header file does not include extensions such as custom web pages or OTAs; AutoConnectCore.h reduces memory consumption by limiting functionality to WiFi connectivity utilities only. See the Reducing Binary Size chapter for details.

    "},{"location":"api.html#autoconnecth","title":"AutoConnect.h","text":"
    #include <AutoConnect.h>\n

    AutoConnect.h header file provides all AutoConnect features.

    "},{"location":"api.html#autoconnectcoreh","title":"AutoConnectCore.h","text":"
    #include <AutoConnectCore.h>\n

    AutoConnectCore.h header file provides the AutoConnect class that excludes Custom Web pages and OTA-related components of the AutoConnect features. When you include this header in your sketch, you cannot use the AutoConnectAux, AutoConnectElements, AutoConnectOTA, and AutoConnectUpdate classes.

    "},{"location":"api.html#defined-macros","title":"Defined macros","text":"

    They contain in AutoConnectDefs.h.

    #define AC_USE_SPIFFS                           // Use SPIFFS for the file system on the onboard flash\n#define AC_USE_LITTLEFS                         // Use LittleFS for the file system on the onboard fash\n#define AC_DEBUG                                // Monitor message output activation\n#define AC_DEBUG_PORT           Serial          // Default message output device\n#define AUTOCONNECT_AP_IP       0x011CD9AC      // Default SoftAP IP\n#define AUTOCONNECT_AP_GW       0x011CD9AC      // Default SoftAP Gateway IP\n#define AUTOCONNECT_AP_NM       0x00FFFFFF      // Default subnet mask\n#define AUTOCONNECT_DNSPORT     53              // Default DNS port at captive portal\n#define AUTOCONNECT_HTTPPORT    80              // Default HTTP\n#define AUTOCONNECT_MENU_TITLE  \"AutoConnect\"   // Default AutoConnect menu title\n#define AUTOCONNECT_URI         \"/_ac\"          // Default AutoConnect root path\n#define AUTOCONNECT_TIMEOUT     30000           // Default connection timeout[ms]\n#define AUTOCONNECT_CAPTIVEPORTAL_TIMEOUT  0    // Captive portal timeout value\n#define AUTOCONNECT_STARTUPTIME 30              // Default waiting time[s] for after reset\n#define AUTOCONNECT_USE_JSON                    // Allow AutoConnect elements to be handled by JSON format\n#define AUTOCONNECT_USE_UPDATE                  // Indicator of whether to use the AutoConnectUpdate feature.\n#define AUTOCONNECT_UPDATE_PORT 8000            // Available HTTP port number for the update\n#define AUTOCONNECT_UPDATE_TIMEOUT  8000        // HTTP client timeout limitation for the update [ms]\n#define AUTOCONNECT_TICKER_PORT LED_BUILTIN     // Ticker port\n#endif\n

    Macros placement moved

    Source code placement of the above macros provided for user sketch changed from v0.9.7. The new code is in AutoConnectDefs.h.

    "},{"location":"api.html#constructors","title":"Constructors","text":""},{"location":"api.html#autoconnect","title":"AutoConnect","text":"
    AutoConnect()\n

    AutoConnect default constructor. This entry internally allocates the ESP8266WebServer for ESP8266 or WebServer for ESP32 and is activated internally.

    AutoConnect will call the user added handler to respond to the HTTP request using the ESP8266WebServer::on (WebServer::on for ESP32) funtion. This call will be made from during the handleClient of AutoConnect function. Therefore, in the use case of assigning AutoConnect in this constructor, it is necessary to know the instance of ESP8266WebServer in order to register the request handler. Sketch can use host functions to obtain a reference to an ESP8266WebServer instance that is internally hosted by AutoConnect.

    • For ESP8266
    AutoConnect(ESP8266WebServer& webServer)\n
    • For ESP32
    AutoConnect(WebServer& webServer)\n

    Run the AutoConnect site using the externally ensured ESP8266WebServer for ESP8266 or WebServer for ESP32. Parameter webServerA reference of ESP8266WebServer or WebServer instance.

    "},{"location":"api.html#public-member-functions","title":"Public member functions","text":""},{"location":"api.html#append","title":"append","text":"
    • ESP8266/ESP32 Common
    AutoConnectAux* append(const String& uri, const String& title)\n
    • For ESP8266
    AutoConnectAux* append(const String& uri, const String& title, ESP8266WebServer::THandlerFunction handler)\n
    • For ESP32
    AutoConnectAux* append(const String& uri, const String& title, WebServer::THandlerFunction handler)\n

    Creates an AutoConnectAux dynamically with the specified URI and integrates it into the menu. Calls with a request handler parameter can use this function as menu registration for a legacy page of ESP8266WebServer/WebServer. If the handler parameter specified, also it will register the request handler for the ESP8266WebServer/WebServer. AutoConnect manages the menu items using a sequence list, and this function always adds the item to the end of the list. Therefore, the order of the menu items is the additional order. Returns the pointer to created AutoConnectAux instance, the nullptr if an AutoConnectAux with the same URI already exists. Parameter uriA string of the URI. titleTitle for menu item. handlerRequest handler function as type of ESP8266WebServer::THandlerFunction/WebServer::THandlerFunction. Return value A Pointer to a created AutoConnectAux instance.

    An instance of ESP8266WebServer/WebServer is needed

    The WebServer must have instantiated for calling with a request handler parameter. AutoConnect can instantiate and host a WebServer internally, but in that case, the point in time to call the append function with a request handler parameter must be after AutoConnect::begin.

    "},{"location":"api.html#aux","title":"aux","text":"
    AutoConnectAux* aux(const String& uri) const\n

    Returns a pointer to AutoConnectAux with the URI specified by uri. If AutoConnectAux with that URI is not bound, it returns nullptr. Parameter uriA string of the URI. Return value A Pointer of the AutoConnectAux instance.

    "},{"location":"api.html#begin","title":"begin","text":"
    bool begin()\n
    bool begin(const char* ssid, const char* passphrase)\n
    bool begin(const char* ssid, const char* passphrase, unsigned long timeout)\n

    Starts establishing the WiFi connection. The WiFi mode at this time is WIFI_STA. AutoConnect first invokes WiFi.begin. If the ssid and the passphrase are missing, its WiFi.begin has no SSID and Password. Regardless of the result, ESP8266WebServer/WebServer will start immediately after the first WiFi.begin. The captive portal will not be started if the connection has been established with first WiFi.begin. If the connection cannot establish, switch to WIFI_AP_STA mode and activate SoftAP. Then DNS server starts. Parameters ssidSSID to be connected. passphrasePassword for connection. timeoutA time out value in milliseconds for waiting connection. Return value trueConnection established, AutoConnect service started with WIFI_STA mode. falseCould not connected, Captive portal started with WIFI_AP_STA mode.

    "},{"location":"api.html#config","title":"config","text":"
    bool config(AutoConnectConfig& config)\n
    bool config(const char* ap, const char* password = nullptr)\n

    Set AutoConnect configuration settings. Parameters configReference to AutoConnectConfig containing SoftAP's parameters and static IP parameters. apSSID for SoftAP. The default value is esp8266ap for ESP8266, esp32ap for ESP32. passwordPassword for SodtAP. The default value is 12345678. Return value trueSuccessfully configured. falseConfiguration parameter is invalid, some values out of range.

    "},{"location":"api.html#detach","title":"detach","text":"
    bool detach(const String& uri)\n

    Detach the AutoConnectAux with the specified URI from the management of AutoConnect. An unmanaged AutoConnectAux will no longer appear in menu items, and its page handler will no longer respond even if the URI is accessed directly. Parameter uriURI of AutoConnectAux to be detached. Return value trueSuccessfully detached. falseAn AutoConnectAux with the specified URI does not exist.

    If the request handler registered in the detaching AutoConnectAux is for a legacy page of the ESP8266WebServer/WebServer, the URI is still valid after detaching. AutoConnect does not delete the request handler registered to ESP8266WebServer/WebServer with the on function. (It cannot be removed)

    Deleting the AutoConnectAux

    If the AutoConnectAux to detach was added by AutoConnect::append, it will be automatically removed and freed from memory.

    "},{"location":"api.html#disablemenu","title":"disableMenu","text":"
    void disableMenu(const uint16_t items)\n

    Disable the AutoConnect menu items specified by the items parameter with logical OR value using AC_MENUITEM_t constant. This function only works for AutoConnect primary menu items. It has no effect on disable for AutoConnectAux items. To disable the items by AutoConnectAux, use the AutoConnectAux::menu function. Parameter itemsSpecify 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 about AC_MENUITEM_t.

    "},{"location":"api.html#enablemenu","title":"enableMenu","text":"
    void enableMenu(const uint16_t items)\n
    Enable the AutoConnect menu items specified by the items parameter with logical OR value using AC_MENUITEM_t constant. This function only works for AutoConnect primary menu items. It has no effect on enable for AutoConnectAux items. To enable the items by AutoConnectAux, use the AutoConnectAux::menu function. Parameter itemsSpecify the combined value of AC_MENUITEM_t of the items applying to the AutoConnect menu. It provides the value calculated from the logical OR by the AC_MENUITEM_t value of each item applied as a menu. AC_MENUITEM_t is enumeration type to identify each menu item and it has the below values.
    • AC_MENUITEM_CONFIGNEW : Configure new AP
    • AC_MENUITEM_OPENSSIDS : Open SSIDs
    • AC_MENUITEM_DISCONNECT : Disconnect
    • AC_MENUITEM_RESET : Reset...
    • AC_MENUITEM_HOME : HOME
    • AC_MENUITEM_UPDATE : Update
    • AC_MENUITEM_DEVINFO : Device statistics as AutoConnect root page
    • AC_MENUITEM_DELETESSID : Enable to delete credentials on Open SSIDs.

    It is added, not replaced.

    The initial configuration of the AutoConnect menu items: AC_MENUITEM_CONFIGNEW | AC_MENUITEM_OPENSSIDS | AC_MENUITEM_DISCONNECT | AC_MENUITEM_RESET | AC_MENUITEM_HOME The enableMenu function adds an indication of the specified items to the current. Therefore, use the disableMenu to remove the specified item from the initial menu.

    "},{"location":"api.html#end","title":"end","text":"
    void end(void)\n

    Stops AutoConnect captive portal service. Release ESP8266WebServer/WebServer and DNSServer.

    Attention to end

    The end function releases the instance of ESP8266WebServer/WebServer and DNSServer. It can not process them after the end function.

    "},{"location":"api.html#geteepromusedsize","title":"getEEPROMUsedSize","text":"
    uint16_t getEEPROMUsedSize(void)\n

    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. Return value Total amount size of saved AutoConnect credentials and custom data.

    The getEEPROMUsedSize is available for only ESP8266 use

    It is available for only ESP8266 use and will return 0 when used with ESP32.

    "},{"location":"api.html#handleclient","title":"handleClient","text":"
    void handleClient(void)\n

    Process the AutoConnect menu interface. The ESP8266WebServer::handleClient1 function hosted by AutoConnect is also called from within AutoConnect to handle the request handlers contained in Sketch.

    Enhanced AutoConnect::handleClient

    The handleClient function enhanced since AutoConnect 1.2.0 can start the captive portal according to the WiFi connection status. By properly specifying AutoConnectConfig::retainPortal and AutoConnectConfig::autoRise, when handleClient detects WiFi disconnection, it shifts WiFi mode to WIFI_AP_STA and starts the DNS server together with SoftAP dynamically. Then trapping for incoming HTTP requests from client devices will be started by AutoConnect. Thus it will open the captive portal behind the execution of the sketch loop() function. The captive portal launched by enhanced handleClient does not interfere with sketch execution except waiting for the result of WiFi.begin. Also, AutoConnectConfig::autoReconnect has improved. The Sketch can specify the AutoConnectConfig::reconnectInterval to continue retrying the reconnection with enhanced handleClient.

    "},{"location":"api.html#handlerequest","title":"handleRequest","text":"
    void handleRequest(void)\n

    Handling for the AutoConnect menu request.

    About used in combination with handleClient

    The handleRequest function is not supposed to use with AutoConnect::handleClient. It should be used following ESP8266WebServer::handleClient or WebServer::handleClient.

    "},{"location":"api.html#home","title":"home","text":"
    void home(String& uri)\n

    Put a user site's home URI. The URI specified by home is linked from \"HOME\" in the AutoConnect menu. Parameter uriA URI string of user site's home path.

    "},{"location":"api.html#host","title":"host","text":"
    • For ESP8266
    ESP8266WebServer& host(void)\n
    • For ESP32
    WebServer& host(void)\n

    Returns the reference of the ESP8266WebServer/WebServer which is allocated in AutoConnect automatically. Return value A reference of the ESP8266WebServer/WebServer.

    &reference is not a pointer

    A reference cannot be re-assigned, and must be assigned at initialization. It's like as bind as alias. 

    ESP8266WebServer& server = portal.host();\nserver.handleClient();\n
    or 
    portal.host().handleClient();\n

    "},{"location":"api.html#isportalavailable","title":"isPortalAvailable","text":"
    bool isPortalAvailable(void)\n

    Returns a boolean value indicating whether a captive portal is available. Return value trueCaptive portal is available. It has SoftAP enabled and is spoofing DNS lookup responses by AutoConnect. Usually, in this state, requests from client devices for Internet transparency validation are redirected to the ESP module. falseAutoConnect is not in captive portal state.

    void join(std::vector<std::reference_wrapper<AutoConnectAux>> aux)\n
    "},{"location":"api.html#join","title":"join","text":"
    void join(AutoConnectAux& aux)\n
    void join(std::vector<std::reference_wrapper<AutoConnectAux>> aux)\n

    Join the AutoConnectAux object to AutoConnect. AutoConnectAux objects can be joined one by one, or joined altogether. The AutoConnectAux object joined by the join function can be handled from the AutoConnect menu. Parameter auxReference to AutoConnectAux. It can be std::vector of std::reference_wrapper of AutoConnectAux with list initialization.

    "},{"location":"api.html#load","title":"load","text":"
    bool load(const String& aux)\n
    bool load(PGM_P aux)\n
    bool load(const __FlashStringHelper* aux)\n
    bool load(Stream& aux)\n

    Load JSON document of AutoConnectAux which contains AutoConnectElements. If there is a syntax error in the JSON document, false is returned. Parameter auxThe input string to be loaded. Return value trueThe JSON document as AutoConnectAux successfully loaded. falseLoading JSON document unsuccessful, probably syntax errors have occurred or insufficient memory. You can diagnose the cause of loading failure using the ArduinoJson Assistant.

    "},{"location":"api.html#locate","title":"locate","text":"
    AutoConnectAux& locate(const String& uri)\n

    Returns a reference to the AutoConnectAux assigned to the uri passed in the argument. Parameter uriURI string of the custom web page to be located. Return value A reference to the AutoConnectAux that has a specified URI.

    AutoConnectAux for the specified uri must exist

    If the AutoConnectAux for the uri specified to the locate function does not exist, the function returns a reference to an empty AutoConnectAux. It's just a frame without any AutoConnectElements. No processing can continue using that AutoConnectAux. (causes an exception) A common cause of exceptions for the locate function is syntax errors in the JSON description of a custom web page.

    "},{"location":"api.html#on","title":"on","text":"
    bool on(const String& uri, const AuxHandlerFunctionT handler, AutoConnectExitOrder_t order = AC_EXIT_AHEAD)\n
    Register the handler function of the AutoConnectAux. Parameters uriA string of the URI assigned to the AutoConnectAux page. handlerA function that behaves when a request to the AutoConnectAux page occurs. AuxHandlerFunctionT type is defined by the following declaration.

    String handler(AutoConnectAux&, PageArgument&)

    orderSpecifies when the handler is called with the following enumeration value.
    • AC_EXIT_AHEAD : Called before AutoConnect generates the HTML of the page. You set the value of AutoConnectElements in the handler then its value will be displayed on the page.
    • AC_EXIT_LATER : Called after AutoConnect generates the HTML of the page. You can append to HTML generated by AutoConnect.
    • AC_EXIT_BOTH : Called even before generating HTML and after generated.

    It is not ESP8266WebServer::on, not WebServer::on for ESP32.

    This function effects to AutoConnectAux only. However, it coexists with that of ESP8266WebServer::on or WebServer::on of ESP32.

    "},{"location":"api.html#onconnect","title":"onConnect","text":"
    void onConnect(ConnectExit_ft fn)\n

    Register the function which will call from AutoConnect at the WiFi connection established. Parameter fnA function called at the WiFi connected.

    An fn specifies the function called when the WiFi connected. Its prototype declaration is defined as ConnectExit_ft.

    typedef std::function<void(IPAddress& localIP)> ConnectExit_ft\n
    Parameter localIPAn IP address of the ESP module as STA."},{"location":"api.html#ondetect","title":"onDetect","text":"
    void onDetect(DetectExit_ft fn)\n

    Register the function which will call from AutoConnect at the start of the captive portal. Parameter fnA function called at the captive portal start.

    An fn specifies the function called when the captive portal starts. Its prototype declaration is defined as DetectExit_ft.

    typedef std::function<bool(IPAddress& softapIP)>  DetectExit_ft\n
    Parameter softapIPAn IP address of SoftAP for the captive portal. Return value trueContinues captive portal handling. falseCancel the captive portal. AutoConnect::begin function will return with a false."},{"location":"api.html#onnotfound","title":"onNotFound","text":"
    • For ESP8266
    void onNotFound(ESP8266WebServer::THandlerFunction fn)\n
    • For ESP32
    void onNotFound(WebServer::THandlerFunction fn)\n

    Register the handler function for undefined URL request detected. Parameter fnA function of the \"not found\" handler.

    "},{"location":"api.html#onotaend","title":"onOTAEnd","text":"
    void onOTAEnd(OTAEndExit_ft fn)\n

    Register the on-end exit routine that is called only once when the OTA is finished. Parameter fnA function called when the OTA has been finished.

    An fn specifies the function called when the OTA has been finished. Its prototype declaration is defined as OTAEndExit_ft.

    typedef std::function<void(void)> OTAEndExit_ft\n
    "},{"location":"api.html#onotaerror","title":"onOTAError","text":"
    void onOTAError(OTAErrorExit_ft fn)\n

    Register the exit routine that is called when some error occurred. Parameter fnA function called when some OTA error occurs.

    An fn specifies the function called when the some error occurred. Its prototype declaration is defined as OTAErrorExit_ft.

    typedef std::function<void(uint8_t error)> OTAErrorExit_ft\n
    Parameter errorError code of OTA. It is defined in the Updater class or the Update class of the Arduino core for each platform."},{"location":"api.html#onotaprogress","title":"onOTAProgress","text":"
    void onOTAProgress(OTAProgressExit_ft fn)\n

    Register the exit routine that is called during the OTA progress. Parameter fnA function called during the OTA progress.

    An fn specifies the function called during the OTA progress. Its prototype declaration is defined as OTAProgressExit_ft.

    typedef std::function<void(unsigned int amount, unsigned int size)> OTAProgressExit_ft\n
    Parameters amountTotal amount of bytes received. sizeBlock size of current send."},{"location":"api.html#onotastart","title":"onOTAStart","text":"
    void onOTAStart(OTAStartExit_ft fn)\n

    Register the on-start exit routine that is called only once when the OTA has been started. Parameter fnA function called at the OTA start.

    An fn specifies the function called when the OTA starts. Its prototype declaration is defined as OTAStartExit_ft.

    typedef std::function<void(void)> OTAStartExit_ft\n
    "},{"location":"api.html#portalstatus","title":"portalStatus","text":"
    uint8_t portalStatus(void)\n
    Returns the status of the portal inside AutoConnect::begin and AutoConnect::handleClient. Return value A bitwise value that indicates each status and is the logical disjunction of multiple states.
    • AutoConnect::AC_IDLE: Initial state. AutoConnect is not making any WiFi connection attempts. This state is reached immediately after AutoConnect::begin starts.
    • AutoConnect::AC_ESTABLISHED: Successfully connected to the WiFi access point.
    • AutoConnect::AC_AUTORECONNECT: AutoConnectConfig::autoReconnect setting was applied during the WiFi connection attempt process. This flag does not indicate a successful connection. It only shows that a condition that triggers autoReconnect has occurred. Whether the connection was actually successful should be determined by WiFi.status()==WL_CONNECTED.
    • AutoConnect::AC_TIMEOUT: WiFi connection attempt timed out. Or, the captive portal was shut down by the AutoConnectConfig::portalTimeout setting.
    • AutoConnect::AC_INTERRUPT: Connection interrupted due to an indication with the exit. The whileConnecting exit routine returned false. or the whileCaptivePortal exit routine returned false. AutoConnect aborted the WiFi connection attempt with those indications.
    • AutoConnect::AC_CAPTIVEPORTAL: Captive portal is available. It means that SoftAP mode is enabled, and the DNS server is available. The state of this flag is equivalent to the return value of AutoConnect::isPortalAvailable function.
    • AutoConnect::AC_INPROGRESS: WiFi.begin in progress. AutoConnect is waiting for the connection to succeed or times out; this state will reset when terminating WiFi.begin attempts.
    "},{"location":"api.html#restorecredential","title":"restoreCredential","text":"
    • For ESP8266
    bool restoreCredential(const char* filename = \"/ac_credt\", fs::FS& fs = FS)\n
    • For ESP32
    bool restoreCredential(const char* filename = \"/ac_credt\", fs::SPIFFSFS& fs = SPIFFS)\n
    bool restoreCredential(const char* filename = \"/ac_credt\", fs::LittleFSFS& fs = LittleFS)\n
    • For using SD
    bool restoreCredential<fs::SDFS>(const char* filename, fs::SDFS& fs)\n

    Restore credentials from the file as named filename with specified fs file system. The file containing the credentials of the restore source must have been saved with the AutoConnect::saveCredential function. Parameter filenameSpecify the file from which to restore the credentials. The filename must include /, the root directory. If this parameter is not specified, ac_credt is assumed. fsSpecifies the file system of the source file to be restored. It must be mounted by the begin function of the file system concerned. Return value trueCredentials has been restored. falseFailed to restore the credentials. Current credentials may have been lost.

    "},{"location":"api.html#savecredential","title":"saveCredential","text":"
    • For ESP8266
    bool saveCredential(const char* filename = \"/ac_credt\", fs::FS& fs = FS)\n
    • For ESP32
    bool saveCredential(const char* filename = \"/ac_credt\", fs::SPIFFSFS& fs)\n
    bool saveCredential(const char* filename = \"/ac_credt\", fs::LittleFSFS& fs)\n
    • For using SD
    bool saveCredential<fs::SDFS>(const char* filename, fs::SDFS& fs)\n

    Saves the current credentials stored by AutoConnect to the specified file. A credential file saved with this function can be treated as input to the AutoConnect::restoreCredential function. Parameter filenameSpecify the file from which to save the credentials. The filename must include /, the root directory. If this parameter is not specified, ac_credt is assumed. fsSpecifies the file system of the destination file to be saved. It must be mounted by the begin function of the file system concerned. Return value trueCredentials has been saved. falseFailed to save the credentials.

    "},{"location":"api.html#where","title":"where","text":"
    String where(void)\n

    Returns an uri string of the AutoConnectAux uri object of the custom Web page that caused the request to the page. AutoConnect identifies the URI (ie. the referrer URI) that caused the request each time from the client occurs and will save the URI If the request source is a custom Web page of AutoConnectAux. The where function returns a pointer of AutoConnectAux which is a URI of a least recent request from the custom Web page. This function is provided to access the fields (ie. the AutoConnectElements) with a custom Web page handler of a page and is available only for request source that is the custom Web pages. It is invalid for HTTP requests from individual pages registered with the on handler of ESP8266WebServer/WebServer for ESP32. In other words, this function only returns the AutoConnecAux page which is a least recently displayed. Return value An uri string of the AutoConnectAux that caused the request the page.

    The where function usage is described in the section Where to pick up the values.

    "},{"location":"api.html#whilecaptiveportal","title":"whileCaptivePortal","text":"
    void whileCaptivePortal(WhileCaptivePortalExit_ft fn)\n

    Register the function which will call from AutoConnect during a stay in the captive portal. Parameter fnFunction called at the captive portal start.

    An fn specifies the function called while staying in the captive portal. Its prototype declaration is defined as WhileCaptivePortalExit_ft.

    typedef std::function<bool(void)>   WhileCaptivePortalExit_ft\n
    Return value trueContinues captive portal handling. falseCancel the captive portal. AutoConnect::begin function will return with a false."},{"location":"api.html#whileconnecting","title":"whileConnecting","text":"
    void whileConnecting(WhileConnectingExit_ft fn)\n

    Register the function that will call from AutoConnect while waiting for connection after WiFi.begin. Parameter fnFunction that will call from AutoConnect while waiting for connection.

    An fn specifies the a function called while waiting for a WiFi connection. Its prototype declaration is defined as WhileConnectingExit_ft.

    typedef std::function<bool(String&)>    WhileConnectingExit_ft\n
    Parameter ssidSSID of an access point to which connection is being attempted. Return value trueContinue attempts to connect to WiFi. falseCancel the WiFi connection attempt.

    1. Equivalent to the WebServer::handleClient function on the ESP32 platform.\u00a0\u21a9

    "},{"location":"apiaux.html","title":"AutoConnectAux API","text":"

    Only for AutoConnect

    The following AutoConnectAux API are valid only for AutoConnect; they are not available for AutoConnectCore.

    "},{"location":"apiaux.html#constructor","title":"Constructor","text":""},{"location":"apiaux.html#autoconnectaux","title":"AutoConnectAux","text":"
    AutoConnectAux(const String& uri = String(\"\"), const String& title = String(\"\"), const bool menu = true, const AutoConnectElementVT addons = AutoConnectElementVT(), const bool responsive = true, const bool CORS = false)\n
    Parameters uriURI of this custom Web Page. titlePage title of this custom Web page. It will appear on the auto connection menu and at the top of that page. menuSpecifies whether to display this page on menu. addonsReference to AutoConnectElement collection. responsiveSpecifies whether to make HTTP response or not. CORSInclude Access-Control-Allow-Origin:* in the HTTP response headers of the custom web page. This indicates that the response can be shared."},{"location":"apiaux.html#public-member-functions","title":"Public member functions","text":""},{"location":"apiaux.html#operator","title":"operator [ ]","text":"
    AutoConnectElement& operator[](const char* name)\n
    AutoConnectElement& operator[](const __FlashStringHelper* name)\n

    AutoConnectElement& operator[](const String& name)\n
    Returns a reference to the element specified by name. An operator [] is a shortcut for getElement function with the reference casting. Unlike getElement, which returns a pointer to that element, an operator [] returns a reference to that element. You also need to cast the return value to the actual type, just like the getElement function. Parameter nameName of the AutoConnectElements to be retrieved. Return valueA reference to AutoConnectElement. It is different from the actual element type.

    "},{"location":"apiaux.html#add","title":"add","text":"
    void add(AutoConnectElement& addon)\n
    void add(AutoConnectElementVT addons)\n

    Add an element to the AutoConnectAux. An added element is displayed on the custom Web page invoked from the AutoConnect menu. Parameters addonReference of AutoConnectElements. Specifies one of the AutoConnectElements classes. addonsAn array list of reference of AutoConnectElements. The list initialization with braced-init-list of the std::vector can be used for the addons parameter cause the actual definition of type AutoConnectElementVT is std::vector<std::reference_wrapper<AutoConnectElement>>.

    "},{"location":"apiaux.html#authentication","title":"authentication","text":"
    void authentication(const AC_AUTH_t auth)\n

    Set to require authentication with access to a page. When you access a page that requires authentication, HTTP authentication will be performed according to the scheme specified with the auth parameter. Parameters authSpecifies authentication scheme with the following enumeration value.

    • AC_AUTH_BASIC : Basic scheme.
    • AC_AUTH_DIGEST : Digest scheme.
    "},{"location":"apiaux.html#content","title":"content","text":"
    size_t content(void)\n

    Returns the number of AutoConnectElements the AutoConnectAux contains. Return valueA number of the registered AutoConnectElements.

    "},{"location":"apiaux.html#fetchelement","title":"fetchElement","text":"

    void fetchElement(void)\n
    Retrieve the values of the AutoConnectElements on the custom Web page. Refer to how to use the fetchElement.

    "},{"location":"apiaux.html#getelement","title":"getElement","text":"
    T& getElement<T>(const String& name)\n
    AutoConnectElement* getElement(const char* name)\n
    AutoConnectElement* getElement(const __FlashStringHelper* name)\n
    AutoConnectElement* getElement(const String& name)\n

    Get a registered AutoConnectElement as specified name. If T is specified as an actual type of AutoConnectElements, it returns a reference to that instance. Parameters TActual type name of AutoConnectElements as AutoConnectButton, AutoConnectCheckbox, AutoConnectElement, AutoConnectFile, AutoConnectInput, AutoConnectRadio, AutoConnectSelect, AutoConnectSubmit, AutoConnectText. nameName of the AutoConnectElements to be retrieved. Return valueA reference of the AutoConnectElements. If a type is not specified returns a pointer.

    "},{"location":"apiaux.html#getelements","title":"getElements","text":"
    AutoConnectElementVT& getElements(void)\n

    Get vector of reference of all elements. Return value A reference to std::vector of reference to AutoConnecctElements.

    The getElements returns a reference to std::vector of reference to AutoConnecctElements. This function is provided to handle AutoConnectElemets owned by AutoConnectAux in bulk, and you can use each method of std::vector for a return value.

    // An example of getting type and name of all AutoConnectElements registered in AutoConnectAux.\nAutoConnectAux aux;\n// some code here...\nAutoConnectElementVt& elements = aux.getElements();\nfor (AutoConnectElement& elm : elements) {\n    Serial.printf(\"name<%s> as type %d\\n\", elm.name.c_str(), (int)elm.typeOf());\n}\n
    "},{"location":"apiaux.html#ismenu","title":"isMenu","text":"
    bool isMenu(void)\n

    Returns whether embedded in the menu or not. The isMenu is a function that complements the menu function. Return value trueThe custom Web page has been incorporated into the AutoConnect menu as a menu item. falseThis custom Web page is not currently a menu item.

    "},{"location":"apiaux.html#isvalid","title":"isValid","text":"
    bool isValid(void)\n

    Performs validation of all AutoConnectInput elements owned by AutoConnectAux and returns the result. The isValid function will return the true even if the AutoConnectAux does not own AutoConnectInputs. Return value trueValidation is successful. A value of all AutoConnectInputs match with each pattern. falseSome elements failed validation.

    "},{"location":"apiaux.html#load","title":"load","text":"
    bool load(const String& in)\n
    bool load(PGM_P in)\n
    bool load(const __FlashStringHelper* in)\n
    bool load(Stream& in)\n

    Load all AutoConnectElements elements from JSON document into AutoConnectAux as custom Web pages. The JSON document specified by the load function must be the document structure of AutoConnectAux. Its JSON document can describe multiple pages as an array. Parameter inSpecifies the JSON document to be load. The load function can input the following objects.

    • String : Read-only String
    • PROGMEM : Character array contained in the flash
    • Stream : An entity that inherits stream class, generally SPIFFS or SD. Return value trueJSON document as the custom Web pages successfully loaded. falseJSON document loading failed.

    Load multiple custom Web pages separately

    Multiple custom Web pages can be loaded at once with JSON as an array. But it will consume a lot of memory. By loading a JSON document by page as much as possible, you can reduce memory consumption.

    "},{"location":"apiaux.html#loadelement","title":"loadElement","text":"
    bool loadElement(const String& in, const String& name = String(\"\"))\n
    bool loadElement(const String& in, std::vector<String> const& names)\n
    bool loadElement(PGM_P in, const String& name = String(\"\"))\n
    bool loadElement(PGM_P in, std::vector<String> const& names)\n
    bool loadElement(const __FlashStringHelper* in, const String& name = String(\"\"))\n
    bool loadElement(const __FlashStringHelper* in, std::vector<String> const& names)\n
    bool loadElement(Stream& in, const String& name = String(\"\"))\n
    bool loadElement(Stream& in, std::vector<String> const& names)\n

    Load specified element from JSON document into AutoConnectAux. The JSON document specified by the loadElement function must be the AutoConnectElement document structure. When loading from a JSON document that describes multiple elements, its description must be an array syntax. Parameters inSpecifies the JSON document to be load. The load function can input the following objects.

    • String : Read-only String
    • PROGMEM : Character array contained in the flash
    • Stream : An entity that inherits stream class, generally SPIFFS or SD. nameSpecifies the name to be load. If the name is not specified, the loadElement function will load all elements contained in the JSON document. names Specifies an array list of String indicating the name of the element to be loaded. The list initialization with braced-init-list of the std::vector can be used. Return value trueSpecified AutoConnectElements successfully loaded. falseJSON document loading failed.

    Maybe it is an array

    Please note that the JSON document that is the input for loadElement is an array syntax of AutoConnectElements when there are multiple elements. For example, the following JSON document has a syntax error:

    {\n\"name\": \"Caption\",\n\"type\": \"ACText\",\n\"value\": \"Hello, world\"\n},\n{\n\"name\": \"Server\",\n\"type\": \"ACInput\",\n\"label\": \"Server address\"\n}\n
    The outermost [, ] is missing.

    "},{"location":"apiaux.html#menu","title":"menu","text":"
    void menu(const bool post)\n

    Set or reset the display as menu item for this AutoConnectAux. This function programmatically manipulates the menu parameter of the AutoConnectAux constructor. Parameter trueShow on the menu. falseHidden on the menu.

    "},{"location":"apiaux.html#on","title":"on","text":"
    void on(const AuxHandlerFunctionT handler, const AutoConnectExitOrder_t order = AC_EXIT_AHEAD)\n
    Register the handler function of the AutoConnectAux. Parameters handlerA function that behaves when a request to the AutoConnectAux page occurs. AuxHandlerFunctionT type is defined by the following declaration.

    String handler(AutoConnectAux&, PageArgument&)

    orderSpecifies when the handler is called with the following enumeration value.
    • AC_EXIT_AHEAD : Called before AutoConnect generates the HTML of the page. You set the value of AutoConnectElements in the handler then its value will be displayed on the page.
    • AC_EXIT_LATER : Called after AutoConnect generates the HTML of the page. You can append to HTML generated by AutoConnect.
    • AC_EXIT_BOTH : Called even before generating HTML and after generated.
    "},{"location":"apiaux.html#onupload","title":"onUpload","text":"
    void onUpload<T&>(T handler)\n
    void onUpload(PageBuilder::UploadFuncT uploadFunc)\n

    Register the upload handler of the AutoConnectAux. Parameters TSpecifies a class name of the custom uploader inherited from AutoConnectUploadHandler class. Refer to the appendix for details. handlerSpecifies the custom uploader inherited from AutoConnectUploadHandler class. Refer to the appendix for details. uploadFuncA function that behaves when request to upload with the AutoConnectAux page. UploadFuncT type is defined by the following declaration.

    void(const String&, const HTTPUpload&)

    A data structure of the upload file as HTTPUpload. It is defined in the ESP8266WebServer (the WebServer for ESP32) library as follows:

    typedef struct {\n  HTTPUploadStatus status;\n  String  filename;\n  String  name;\n  String  type;\nsize_t  totalSize;\nsize_t  currentSize;\nsize_t  contentLength;\nuint8_t buf[HTTP_UPLOAD_BUFLEN];\n} HTTPUpload;\n

    Refer to 'To upload to a device other than Flash or SD' in section appendix for details.

    "},{"location":"apiaux.html#redirect","title":"redirect","text":"
    void redirect(const char* url)\n

    Generate a Location header field with the specified url and responds with a 302 response code to the client. This function is intended to be used from within the Custom Web Page handler. If the AutoConnectAux is going to redirect to another page without responding with page content, declare the responsive argument false in the AutoConnectAux constructor. With this construction, AutoConnectAux will not respond to HTTP responses. The redirect function can be useful in this situation to respond to a 302 redirect. Parameter urlSpecifies the URL to redirect a page to.

    "},{"location":"apiaux.html#referer","title":"referer","text":"
    AutoConnectAux& referer(void)\n

    Returns a reference to the AutoConnectAux from which this AutoConnectAux was called. Return value A reference to the AutoConnectAux from which this AutoConnectAux was called. If the source of the transition is not an AutoConnectAux page, it returns a reference to itself.

    "},{"location":"apiaux.html#release","title":"release","text":"
    bool release(const String& name)\n

    Release a specified AutoConnectElement from AutoConnectAux. The release function is provided to dynamically change the structure of the custom Web pages with the Sketch. By combining the release function and the add function or the loadElement function, the Sketch can change the style of the custom Web page according to its behavior. Parameter nameSpecifies the name of AutoConnectElements to be released. Return value trueThe AutoConnectElement successfully released. falseThe AutoConnectElement can not be released.

    "},{"location":"apiaux.html#saveelement","title":"saveElement","text":"
    size_t saveElement(Stream& out, std::vector<String> const& names = {})\n

    Write elements of AutoConnectAux to the stream. The saveElement function outputs the specified AutoConnectElements as a JSON document using the prettyPrintTo function of the ArduinoJson library. Parameters outOutput stream to be output. SPIFFS, SD also Serial can be specified generally. namesThe array of the name of AutoConnectElements to be output. If the names parameter is not specified, all AutoConnectElements registered in AutoConnectAux are output. Return value The number of bytes written.

    The output format is pretty

    The saveElement function outputs a prettified JSON document.

    It is not complementary with loadElement

    The saveElement function which missing the names parameter without name list to be saved that saves an entire AutoConnectAux element, not just AutoConnectElements. Its saved JSON document is not a complementary input to the loadElement function. The JSON document describing AutoConnectAux saved without the names parameter must be loaded by the AutoConnectAux::load function or AutoConnect::load function.

    "},{"location":"apiaux.html#setelementvalue","title":"setElementValue","text":"
    bool setElementValue(const String& name, const String value)\n
    bool setElementValue(const String& name, std::vector<String> const& values)\n

    Sets the value of the specified AutoConnectElement. If values is specified as a std::vector of String, the element that can set the values is the AutoConnectRadio or the AutoConnectSelect. Parameters nameSpecifies the name of the AutoConnectElements that you want to set the value. valueSpecifies the value to be set. valuesSpecifies a reference of a std::vector of String. It contains the values of the AutoConnectRadio or the AutoConnectSelect. Return value trueThe value has been set. falseAutoConnectElements with the specified name are not registered. Or the type of the value is not consistent with the specified AutoConnectElements.

    You can directly access the value member variable.

    If you are gripping with the Sketch to the AutoConnectElements of the target that sets the value, you can access the value member variable directly. The following sketch code has the same effect. 

    AutoConnectAux aux;\n// ... Griping the AutoConnectText here.\naux.setElementValue(\"TEXT_FIELD\", \"New value\");\n
    AutoConnectAux aux;\n// ... Griping the AutoConnectText here.\nAutoConnectText& text = aux.getElement<AutoConnectText>(\"TEXT_FIELD\");\ntext.value = \"New value\";\n
    The difference between the setElementValue and the value access with the getElement is the certainty of the registration state for the element. The getElement returns an empty object if the element is not registered then a sketch assigns the value to it. May occur unexpected results and crashes. You should use the setElementValue if its registration is unsettled.

    "},{"location":"apiaux.html#settitle","title":"setTitle","text":"
    void setTitle(const String& title)\n

    Set the title string of the custom Web page. This title will be displayed as the menu title of the custom Web page. Parameter titleTitle string to be display.

    Not the menu title

    The setTitle function is not set for the AutoConnect menu title. The effect of this function is that custom Web page only. To change the AutoConnect menu title use AutoConnectConfig::title.

    "},{"location":"apiconfig.html","title":"AutoConnectConfig API","text":"

    The AutoConnectConfig class does not present some members regarding custom web page features due to differences in the AutoConnect component used in the sketch.

    Sketch allows by including either AutoConnect.h or AutoConnectCore.h header file to use the AutoConnect library. If you include the AutoConnectCore.h with the sketch, AutoConnect will drop the functions involved custom web page facility. And correspondingly, some members that depend on custom web page functions will omit from the AutoConnectConfig class. See the Reducing Binary Size chapter for details.

    "},{"location":"apiconfig.html#constructor","title":"Constructor","text":""},{"location":"apiconfig.html#autoconnectconfig","title":"AutoConnectConfig","text":"
    AutoConnectConfig()\n
    AutoConnectConfig(const char* ap, const char* password)\n
    AutoConnectConfig(const char* ap, const char* password, const unsigned long timeout)\n
    AutoConnectConfig(const char* ap, const char* password, const unsigned long timeout, const uint8_t channel)\n
    Parameters apSSID for SoftAP. The length should be up to 31. The default value is esp8266ap for ESP8266, esp32ap for ESP32. passwordPassword for SoftAP. The length should be from 8 to up to 63. The default value is 12345678. timeoutThe timeout value of the captive portal in [ms] units. The default value is 0. channelThe channel number of WIFi when SoftAP starts. The default values is 1."},{"location":"apiconfig.html#public-member-variables","title":"Public member variables","text":""},{"location":"apiconfig.html#apid","title":"apid","text":"

    SoftAP's SSID. Type StringThe default value is esp8266ap for ESP8266, esp32ap for ESP32.

    "},{"location":"apiconfig.html#apip","title":"apip","text":"

    Sets IP address for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this. Type IPAddressThe default value is 172.217.28.1

    "},{"location":"apiconfig.html#auth","title":"auth","text":"

    Apply HTTP authentication with the AutoConnect web page. This This setting allows the Sketch to authenticate with \"BASIC\" or \"DIGEST\" scheme. It is given as an enumeration value of AC_AUTH_t that indicates the authentication scheme. This setting determines the default scheme for HTTP authentication with AutoConnect. When the AutoConnectConfig::authScope is AC_AUTHSCOPE_PARTIAL, each AutoConnectAux authentication scheme has priority. Type AC_AUTH_t Value AC_AUTH_NONE No authentication. This is the default. AC_AUTH_DIGEST Use the digest scheme. AC_AUTH_BASIC Use the basic scheme.

    "},{"location":"apiconfig.html#authscope","title":"authScope","text":"

    Specifies the authentication scope of AutoConnect Web pages. The Sketch will be able to expand or narrow the range of authentication by this setting, which can be either as AC_AUTHSCOPE_t enumeration value. Type AC_AUTHSCOPE_t Value AC_AUTHSCOPE_AUX Require authentication to access for all custom Web pages, excepting AutoConnect's pages. This is the Default. AC_AUTHSCOPE_PARTIAL Authenticate only specific custom Web pages which are specified by AutoConnectAux::authentication function or JSON description. AC_AUTHSCOPE_PORTAL Require authentication to access for all AutoConnect's pages, including custom Web pages.

    This setting is available only when AutoConnectConfig::auth is other than AC_AUTH_NONE. Ignored if it is AC_AUTH_NONE.

    Also, the authScope setting has another bit that indicates to allow authentication in the captive portal state. Its enum value cannot be used alone and is always for qualifying the above three enum values. Value AC_AUTHSCOPE_WITHCP Allow authentication with the captive portal state. This value cannot be used alone to declare an authentication scope. It indicates to enable authentication in the captive portal by the logical OR operator with one of the AC_AUTHSCOPE_t values above.

    "},{"location":"apiconfig.html#autoreconnect","title":"autoReconnect","text":"

    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 bool Value trueReconnect automatically. falseStarts Captive Portal in SoftAP + STA mode without trying to reconnect. This is the default.

    When the autoReconnect option is enabled, an automatic connection will behave if the following conditions are satisfied.

    • Invokes AutoConnect::begin without user name and password parameter as begin().
    • If one of the saved credentials matches the BSSID (or SSID) detected by the network scan.

    Either BSSID or SSID to aim the access point

    Whether or not it points to the target access point is determined by matching the SSID or BSSID. The default key to collate is BSSID. The BSSID is usually fixed to the MAC address unique to its access point device, but when using some mobile hotspots, the BSSID may change even for the same access point. If you operate inconvenience in aiming at the access point by BSSID, you can change the collation key to SSID by uncomment the below line in AutoConnectDefs.h:

    #define AUTOCONNECT_APKEY_SSID\n

    If AUTOCONNECT_APKEY_SSID macro is defined when the library is compiled, the access points are collated by the SSID.

    "},{"location":"apiconfig.html#autoreset","title":"autoReset","text":"

    Reset ESP8266 module automatically after WLAN disconnected. Type bool Value trueReset after WiFi disconnected automatically. falseNo reset.

    "},{"location":"apiconfig.html#autorise","title":"autoRise","text":"

    Captive portal activation switch. False for disabling the captive portal. It prevents starting the captive portal even if the connection at the 1st-WiFi.begin fails. Type bool Value trueEnable the captive portal. This is the default. falseDisable the captive portal.

    "},{"location":"apiconfig.html#autosave","title":"autoSave","text":"

    The credential saved automatically at the connection establishment. Type AC_SAVECREDENTIAL_t Value AC_SAVECREDENTIAL_AUTO The credential saved automatically. This is the default. AC_SAVECREDENTIAL_ALWAYS Save specified SSID and Password always even if a specified credential has been rejected. AC_SAVECREDENTIAL_NEVER The credential no saved.

    "},{"location":"apiconfig.html#begintimeout","title":"beginTimeout","text":"

    Specify the limit time to attempt WiFi connection to the access point. AutoConnect uses this value to abort the connection attempt at WiFi.begin. Its actual value specified in milliseconds unit. The default value is AUTOCONNECT_TIMEOUT defined in AutoConnectDefs.h and the initial value is 30 seconds. Type unsigned long

    "},{"location":"apiconfig.html#booturi","title":"bootUri","text":"

    Specify the location to be redirected after module reset in the AutoConnect menu. It is given as an enumeration value of AC_ONBOOTURI_t indicating either the AutoConnect root path or the user screen home path. Type AC_ONBOOTURI_t Value AC_ONBOOTURI_ROOT Resetting the module redirects it to the AutoConnect root path. The root path is assumed to be AUTOCONNECT_URI defined in AutoConnectDefs.h. AC_ONBOOTURI_HOME It is redirected to the URI specified by AutoConnectConfig::homeUri.

    "},{"location":"apiconfig.html#boundaryoffset","title":"boundaryOffset","text":"

    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. This option is valid only for ESP8266 or ESP32 arduino core 1.0.2 earlier. Type uint16_t

    It will conflict with user data.

    If the Sketch leaves this offset at zero, it will conflict the storage area of credentials with the user sketch owned data. It needs to use the behind of credential area.

    "},{"location":"apiconfig.html#channel","title":"channel","text":"

    The channel number of WIFi when SoftAP starts. Type uint8_t Value 1 ~ 14. The default value is 1.

    How do I choose Channel

    Espressif Systems had announced the application note about Wi-Fi channel selection.

    "},{"location":"apiconfig.html#dns1","title":"dns1","text":"

    Set primary DNS server address when using static IP address. Type IPAddress

    "},{"location":"apiconfig.html#dns2","title":"dns2","text":"

    Set secondary DNS server address when using static IP address. Type IPAddress

    "},{"location":"apiconfig.html#gateway","title":"gateway","text":"

    Sets gateway address for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this. Type IPAddressThe default value is 172.217.28.1

    "},{"location":"apiconfig.html#hidden","title":"hidden","text":"

    Sets SoftAP to hidden SSID. Type uint8_t Value 0SSID will be appeared. This is the default. 1SSID will be hidden.

    "},{"location":"apiconfig.html#homeuri","title":"homeUri","text":"

    Sets the home path of user sketch. This path would be linked from 'HOME' in the AutoConnect menu. The default for homeUri is \"/\". Type String

    "},{"location":"apiconfig.html#hostname","title":"hostName","text":"

    Sets the station host name of ESP8266/ESP32. Type String

    "},{"location":"apiconfig.html#immediatestart","title":"immediateStart","text":"

    Disable the 1st-WiFi.begin and start the captive portal. If this option is enabled, the module will be in AP_STA mode and the captive portal. The evaluation rank of this parameter is lower than the AutoConnectConfig::autoRise. Even if immediateStart is true, the captive portal will not launch if autoRise is false. Type bool Value trueStart the captive portal with AutoConnect::begin. falseEnable the 1st-WiFi.begin and it will start captive portal when connection failed. This is default.

    "},{"location":"apiconfig.html#menuitems","title":"menuItems","text":"

    Configure applying items of the AutoConnect menu. You can arbitrarily combine valid menus by coordinating the menuItems value. Type uint16_tIt provides the combined AC_MENUITEM_t value of the item to apply to the AutoConnect menu.Specify the value calculated from the logical OR by the AC_MENUITEM_t value of each item applied as a menu. It affects not only disappear the items from the menu also invalidates the URI they have. As a consequence, even if it accesses the URL directly will occur a 404 error.The default value is logical OR of AC_MENUITEM_CONFIGNEW, AC_MENUITEM_OPENSSIDS, AC_MENUITEM_DISCONNECT, AC_MENUITEM_RESET, AC_MENUITEM_UPDATE and AC_MENUITEM_HOME. Value AC_MENUITEM_NONE No assign items except for the AutoConnectAux page item. AC_MENUITEM_CONFIGNEW Appends Configure new AP item. AC_MENUITEM_OPENSSIDS Appends Open SSIDs item. AC_MENUITEM_DISCONNECT Appends Disconnect item. AC_MENUITEM_RESET Appends Reset... item. AC_MENUITEM_UPDATE Appends Update item. This value is valid only for AutoConnect; it is not available for AutoConnectCore. AC_MENUITEM_HOME Appends HOME item. AC_MENUITEM_DEVINFO Appends the Device info item which links to AutoConnect statistics page. AC_MENUITEM_DELETESSID Enables the ability to interactively delete credentials on the Open SSIDs menu screen.

    How to specify the value of the menu items

    An menuItems accepts the logical OR of AC_MENUITEM_t type value. For example, to enable only Open SSIDs and HOME items, specify: 

    AutoConnect portal;\nAutoConnectConfig config;\n\nconfig.menuItems = AC_MENUITEM_OPENSSIDS | AC_MENUITEM_HOME;\nportal.config(config);\n
    Also, to enable the credentials removal feature, follow these settings procedures. 
    AutoConnect portal;\nAutoConnectConfig config;\n\nconfig.menuItems = config.menuItems | AC_MENUITEM_DELETESSID;\nportal.config(config);\n
    However, even if you specify like the above, the AutoConnectAux page items still display on the menu. To remove the AutoConnectAux items, use the AutoConnectAux::menu function.

    "},{"location":"apiconfig.html#minrssi","title":"minRSSI","text":"

    Specify the lower limit of the WiFi signal strength allowed to use as an access point. This value should be greater than -120 as RSSI. Generally, a data link will not be established unless it exceeds -90 dBm. Also, packet transmission is not reliable below -70 dBm to -80 dBm. Type int16_tThe default value is -120

    "},{"location":"apiconfig.html#netmask","title":"netmask","text":"

    Sets subnet mask for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this. Type IPAddressThe default value is 255.255.255.0

    "},{"location":"apiconfig.html#ota","title":"ota","text":"

    Specifies to import the built-in OTA update class into the Sketch. When this option is enabled, an Update item will appear in the AutoConnect menu, and the OTA update via Web browser will be automatically embedded to the Sketch. Type AC_OTA_t Value AC_OTA_EXTRA AutoConnect does not import AutoConnectOTA. This is the default. AC_OTA_BUILTIN Specifies to include AutoConnectOTA in the Sketch.

    "},{"location":"apiconfig.html#otaextracaption","title":"otaExtraCaption","text":"

    Specifies the caption to be displayed as an extra on the OTA update screen. The extra caption you specified will be displayed in the upper right corner of the OTA update screen. Also, you can only specify the caption string, and you cannot specify the style individually. An extra caption will draw up with the default style of AutoConnect. Type const char* An extra caption string pointer.

    "},{"location":"apiconfig.html#password","title":"password","text":"

    Set the password for authentication. Type String The default value is same as psk.

    "},{"location":"apiconfig.html#portaltimeout","title":"portalTimeout","text":"

    Specify the timeout value of the captive portal in [ms] units. It is valid when the station is not connected and does not time out if the station is connected to the ESP module in SoftAP mode (i.e. Attempting WiFi connection with the portal function). If 0, the captive portal will not be timed-out. Type unsigned longCaptive portal timeout value. The default value is 0.

    "},{"location":"apiconfig.html#preserveapmode","title":"preserveAPMode","text":"

    Specifies starting the STA while maintaining the state of the SoftAP mode in the AutoConnect::begin. This setting only applies when the AutoConnectConfig::autoRise is false. Type bool Value trueAutoConnect::begin keeps AP mode. falseAutoConnect::begin will stop SoftAP at the beginning of the process.

    Note that this option is not for starting the SoftAP forcibly in AutoConnect::begin and only keeps AP mode, SoftAP initiation is left to the Sketch.

    "},{"location":"apiconfig.html#preserveip","title":"preserveIP","text":"

    When using existing credentials to connect WiFi, the station IP configuration specified with the AutoConnectConfig::staip, AutoConnectConfig::staGateway, and AutoConnectConfig::staNetmask are preferred over the IP settings of the stored credentials. If this value is set to true, IP configurations stored with credentials will not be restored. Type bool Value trueUse IP addresses specified with the AutoConnectConfig::staip, AutoConnectConfig::staGateway, and AutoConnectConfig::staNetmask as the station IP configuration. falseWhen reconnecting, the station IP configuration specified with AutoConnectConfig is ignored and the saved credential values are used.

    "},{"location":"apiconfig.html#principle","title":"principle","text":"

    Specify the connection order will attempt to connect to one of the highest RSSI values among multiple available access points. It is given as an enumeration value of AC_PRINCIPLE_t indicating. Type AC_PRINCIPLE_t Value AC_PRINCIPLE_RECENT Attempts to connect in the order of the saved credentials entries. The entry order is generally a time series connected in the past. AC_PRINCIPLE_RSSI Attempts to connect to one of the highest RSSI values among multiple available access points.

    "},{"location":"apiconfig.html#psk","title":"psk","text":"

    Sets password for SoftAP. The length should be from 8 to up to 63. The default value is 12345678. Type String

    "},{"location":"apiconfig.html#reconnectinterval","title":"reconnectInterval","text":"

    Specifies the number of units for interval time to attempt automatic reconnection when AutoConnectConfig::autoReconnect is enabled. This value is specified by the number of unit times from 0 to 255, and one unit time is macro-defined as AUTOCONNECT_UNITTIME in AutoConnectDefs.h file of library source code, and its initial value is 30[s]. Type uint8_t

    WiFi connection retry is repeated inside AutoConnect::handleClient after the number of seconds that the reconnectInterval value is multiplied by AUTOCONNECT_UNITTIME from the previous attempt. Then, when the connection with one of the saved credentials is established, the automatic reconnection will stop. And while AutoConnectConfig::autoReconnect is enabled, if the WiFi connection is lost, it will start to auto-reconnect again inside AutoConnect::handleClient.

    If 0 is specified for the reconnectInterval, background reconnection attempt repeatedly will not be made, and only once at the 1st-WiFi.begin failure in AutoConnect::begin. (Only when AutoConnectConfig::autoReconnect is enabled) The default value is 0.

    AUTOCONNECT_UNITTIME

    AUTOCONNECT_UNITTIME as macro defined in AutoConnectDefs.h file of library source code as the below: 

    // Number of seconds in uint time [s]\n#ifndef AUTOCONNECT_UNITTIME\n#define AUTOCONNECT_UNITTIME    30\n#endif\n

    "},{"location":"apiconfig.html#retainportal","title":"retainPortal","text":"

    Specify whether to continue the portal function even if the captive portal timed out. If the true, when a timeout occurs, the AutoConnect::begin function is exited with returns false, but the portal facility remains alive. So SoftAP remains alive and you can invoke AutoConnect while continuing sketch execution. The default is false. Type bool Value trueContinue the portal function even if the captive portal times out. The STA + SoftAP mode of the ESP module continues and accepts the connection request to the AP. falseWhen the captive portal times out, STA + SoftAP mode of the ESP module is stopped. This is default.

    Connection request after timed-out

    With the retainPortal, even if AutoConnect::begin in the setup() is timed out, you can execute the Sketch and the portal function as a WiFi connection attempt by calling AutoConnect::handleClient in the loop().

    All unresolved addresses redirects /_ac

    If you enable the retainPortal option, all unresolved URIs will be redirected to SoftAPIP/_ac. It happens frequently as client devices repeat captive portal probes in particular. To avoid this, you need to exit from the WiFi connection Apps on your device once.

    "},{"location":"apiconfig.html#staip","title":"staip","text":"

    Set a static IP address. The IP will behave with STA mode. Type IPAddress

    "},{"location":"apiconfig.html#stagateway","title":"staGateway","text":"

    Set the gateway address when using static IP address. Type IPAddress

    "},{"location":"apiconfig.html#stanetmask","title":"staNetmask","text":"

    Set the subnetmask when using static IP address. Type IPAddress

    "},{"location":"apiconfig.html#ticker","title":"ticker","text":"

    Set flicker signal output according to WiFi connection status during AutoConnect::begin behavior. Type bool Value trueOutput the flicker signal while AutoConnect::begin operation. The AUTOCONNECT_TICKER_PORT macro in the AutoConnectDefs.h header file assigns pins for signal output. The default pin is arduino valiant's LED_BUILTIN. For boards without the LED_BUILTIN pin, assume pin #2. falseNo flicker signal output.

    "},{"location":"apiconfig.html#tickerport","title":"tickerPort","text":"

    Specifies the GPIO port number to output the flicker signal of the ticker. The default assumes on the board dependent definition LED_BUILTIN macro redefined by AUTOCONNECT_TICKER_PORT in AutoConnectDefs.h. Type uint8_t

    "},{"location":"apiconfig.html#tickeron","title":"tickerOn","text":"

    Specifies the active logic level of the flicker signal. This value indicates the active signal level when driving the ticker. Type uint8_t Value LOWA flicker signal is an active-high. HIGHA flicker signal is an active-low.

    "},{"location":"apiconfig.html#title","title":"title","text":"

    Set the menu title. Type String

    "},{"location":"apiconfig.html#uptime","title":"uptime","text":"

    Specifies the waiting time for the module to reboot. Type intThe default value is AUTOCONNECT_TIMEOUT/1000.

    "},{"location":"apiconfig.html#username","title":"username","text":"

    Set the username for authentication. Type StringThe default value is same as apid.

    "},{"location":"apiconfig.html#autoconnectconfig-initial-values","title":"AutoConnectConfig Initial values","text":"Public member Data type Initial value definition Defined symbol 1 apid String esp8266apesp32ap AUTOCONNECT_APID apip IPAddress 172.217.28.1 AUTOCONNECT_AP_IP auth AC_AUTH_t AC_AUTH_NONE AC_AUTH_NONEAC_AUTH_DIGESTAC_AUTH_BASIC authScope AC_AUTHSCOPE_t AC_AUTHSCOPE_AUX AC_AUTHSCOPE_PARTIALAC_AUTHSCOPE_AUXAC_AUTHSCOPE_ACAC_AUTHSCOPE_PORTALAC_AUTHSCOPE_WITHCP autoReconnect bool false autoReset bool true autoRise bool true autoSave AC_SAVECREDENTIAL_t AC_SAVECREDENTIAL_AUTO AC_SAVECREDENTIAL_AUTOAC_SAVECREDENTIAL_ALWAYSAC_SAVECREDENTIAL_NEVER beginTimeout unsinged long 30000UL AUTOCONNECT_TIMEOUT bootUri AC_ONBOOTURI_t AC_ONBOOTURI_ROOT AC_ONBOOTURI_ROOTAC_ONBOOTURI_HOME boundaryOffset uint16_t 0 AC_IDENTIFIER_OFFSET channel uint8_t 1 AUTOCONNECT_AP_CH dns1 IPAddress 0UL dns2 IPAddress 0UL gateway IPAddress 172.217.28.1 AUTOCONNECT_AP_GW hidden uint8_t 0 homeUri String / AUTOCONNECT_HOMEURI hostName String NULL immediateStart bool false menuItems uint16_t AC_MENUITEM_CONFIGNEW+ AC_MENUITEM_OPENSSIDS+ AC_MENUITEM_DISCONNECT+ AC_MENUITEM_RESET+ AC_MENUITEM_UPDATE+ AC_MENUITEM_HOME AC_MENUITEM_CONFIGNEWAC_MENUITEM_OPENSSIDSAC_MENUITEM_DISCONNECTAC_MENUITEM_RESETAC_MENUITEM_UPDATEAC_MENUITEM_HOME minRSSI int16_t -120 AUTOCONNECT_MIN_RSSI netmask IPAddress 172.217.28.1 AUTOCONNECT_AP_NM ota AC_OTA_t AC_OTA_EXTRA AC_OTA_EXTRAAC_OTA_BUILTIN otaExtraCaption const char* nullptr password String Follow psk portalTimeout unsigned long 0UL AUTOCONNECT_CAPTIVEPORTAL_TIMEOUT preserveAPMode bool false principle AC_PRINCIPLE_t AC_PRINCIPLE_RECENT AC_PRINCIPLE_RECENTAC_PRINCIPLE_RSSI psk String 12345678 AUTOCONNECT_PSK reconnectInterval uint8_t 0 retainPortal bool false staGateway IPAddress 0UL staip IPAddress 0UL staNetmask IPAddress 0UL ticker bool false tickerOn uint8_t LOW AUTOCONNECT_UPDATE_LEDON tickerPort uint8_t LED_BUILTIN AUTOCONNECT_TICKER_PORT title String AutoConnect AUTOCONNECT_MENU_TITLE uptime int AUTOCONNECT_TIMEOUT/1000 AUTOCONNECT_STARTUPTIME username String Follow apid"},{"location":"apiconfig.html#autoconnectconfig-example","title":"AutoConnectConfig example","text":"
    AutoConnect        Portal;\nAutoConnectConfig  Config(\"\", \"passpass\");    // SoftAp name is determined at runtime\nConfig.apid = ESP.hostname();                 // Retrieve host name to SotAp identification\nConfig.apip = IPAddress(192,168,10,101);      // Sets SoftAP IP address\nConfig.gateway = IPAddress(192,168,10,1);     // Sets WLAN router IP address\nConfig.netmask = IPAddress(255,255,255,0);    // Sets WLAN scope\nConfig.autoReconnect = true;                  // Enable auto-reconnect\nConfig.autoSave = AC_SAVECREDENTIAL_NEVER;    // No save credential\nConfig.boundaryOffset = 64;                   // Reserve 64 bytes for the user data in EEPROM.\nConfig.portalTimeout = 60000;                 // Sets timeout value for the captive portal\nConfig.retainPortal = true;                   // Retains the portal function after timed-out\nConfig.homeUri = \"/index.html\";               // Sets home path of Sketch application\nConfig.title =\"My menu\";                      // Customize the menu title\nConfig.staip = IPAddress(192,168,10,10);      // Sets static IP\nConfig.staGateway = IPAddress(192,168,10,1);  // Sets WiFi router address\nConfig.staNetmask = IPAddress(255,255,255,0); // Sets WLAN scope\nConfig.dns1 = IPAddress(192,168,10,1);        // Sets primary DNS address\nPortal.config(Config);                        // Configure AutoConnect\nPortal.begin();                               // Starts and behaves captive portal\n

    1. Those symbols are defined in AutoConnectDefs.h.\u00a0\u21a9

    "},{"location":"apielements.html","title":"AutoConnectElements API","text":"

    Only for AutoConnect

    The following AutoConnectElements are valid only for AutoConnect; they are not available for AutoConnectCore.

    "},{"location":"apielements.html#autoconnectbutton","title":"AutoConnectButton","text":""},{"location":"apielements.html#constructor","title":"Constructor","text":"
    AutoConnectButton(const char* name = \"\", const char* value = \"\", const String& action = String(), const ACPosterior_t post = AC_Tag_None)\n
    Parameters nameThe element name. valueValue of the element. actionNative code of the action script executed when the button is clicked. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables","title":"Public member variables","text":""},{"location":"apielements.html#action","title":"action","text":"

    HTML native code of the action script to be executed when the button is clicked. It is mostly used with a JavaScript to activate a script.1 Type String

    "},{"location":"apielements.html#enable","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#name","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#value","title":"value","text":"

    Value of the element. Type String

    "},{"location":"apielements.html#public-member-functions","title":"Public member functions","text":""},{"location":"apielements.html#canhandle","title":"canHandle","text":"
    bool canHandle(void)\n

    Returns whether the AutoConnectButton element has a registered event handler and can respond to a click event. Return value trueAn event handler is registered. The element can correspond to a click event. falseAn event handler is not registered.

    "},{"location":"apielements.html#off","title":"off","text":"
    void off(void)\n

    Release a registered event handler so that the element does not react to events.

    "},{"location":"apielements.html#on","title":"on","text":"
    void on(std::function<void(AutoConnectButton&, AutoConnectAux&)> eventHandler)\n

    Register an event handler function so that the element can respond to a click event. Parameter eventHandlerA function instance corresponding to a click event on AutoConnectButton. It allows giving with lambda expressions.

    An eventHandler function will be called when a click event occurs with the AutoConnectButton. Its prototype declaration is follows:

    void eventHandler(AutoConnectButton& me, AutoConnectAux& aux)\n
    Parameter meA reference to the instance of the AutoConnectButton that fired the click event. auxReference to the AutoConnectAux instance to which the AutoConnectButton that generated the click event belongs."},{"location":"apielements.html#response","title":"response","text":"
    void response(const char* value)\n
    void response(const char* attribute, const char* value)\n

    Reply the value or attribute of an element to the client. The response is usually used for sending a reply to the client with the element's value or attribute that has been updated in an event handler function.

    The response function itself does not perform communication. It only temporarily accumulates updated values. The stored content constitutes the response data to the HTTP POST request sent from the client browser caused by the AutoConnectElements event.

    The response function has two overloads with different numbers of arguments. A response function suitable for just one argument will only update the value of the AutoConnectButton. It also stores the updated value of the button caption text (i.e., the innerHTML attribute dependent on the button type=\"button\" element) into the response data for real-time rendering in the browser upon response. Also, a response function suitable for two arguments allows updating all attributes of the HTML button type=\"button\" element derived from AutoConnectButton. Parameter valueSuitable for one argument format: A changing value of AutoConnectButton::value as response. It also will update the innerHTML attribute of the button type=\"button\" element derived from AutoConnectButton.Suitable for two argument format: Specifies a value of the HTML button type=\"button\" element to be modified as specified in the attribute argument. attributeAn attribute name of an HTML button type=\"button\" element to be changed.

    "},{"location":"apielements.html#typeof","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectButton. Return value AC_Button

    "},{"location":"apielements.html#autoconnectcheckbox","title":"AutoConnectCheckbox","text":""},{"location":"apielements.html#constructor_1","title":"Constructor","text":"
    AutoConnectCheckbox(const char* name = \"\", const char* value = \"\", const char* label = \"\", const bool checked = false, const ACPosition_t labelPosition = AC_Behind, const ACPosterior_t post = AC_Tag_BR)\n
    Parameters nameThe element name. valueValue of the element. labelA label string prefixed to the checkbox. checkChecked state of the checkbox. labelPositionSpecifies the position of the label to generate. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_1","title":"Public member variables","text":""},{"location":"apielements.html#checked","title":"checked","text":"

    It indicates the checked status of the checkbox. The value of the checked checkbox element is packed in the query string and sent by submit. Type bool"},{"location":"apielements.html#enable_1","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_1","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#label","title":"label","text":"

    A label is an optional string. A label is always arranged on the right side of the checkbox. Specification of a label will generate an HTML <label> tag with an id attribute. The checkbox and the label are connected by the id attribute. Type String

    "},{"location":"apielements.html#labelposition","title":"labelPosition","text":"

    Specifies the position of the label to generate with ACPostion_t enumeration value. Type ACPosition_t

    • AC_Infront : Place a label in front of the check box.
    • AC_Behind : Place a label behind the check box.
    "},{"location":"apielements.html#name_1","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_1","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#value_1","title":"value","text":"

    Value of the element. It becomes a value attribute of an HTML <input type=\"checkbox\"> tag. Type String

    "},{"location":"apielements.html#public-member-functions_1","title":"Public member functions","text":""},{"location":"apielements.html#canhandle_1","title":"canHandle","text":"
    bool canHandle(void)\n

    Returns whether the AutoConnectCheckbox element has a registered event handler and can respond to a change event. Return value trueAn event handler is registered. The element can correspond to a change event. falseAn event handler is not registered.

    "},{"location":"apielements.html#off_1","title":"off","text":"
    void off(void)\n

    Release a registered event handler so that the element does not react to events.

    "},{"location":"apielements.html#on_1","title":"on","text":"
    void on(std::function<void(AutoConnectCheckbox&, AutoConnectAux&)> eventHandler)\n

    Register an event handler function so that the element can respond to a change event. Parameter eventHandlerA function instance corresponding to a change event on AutoConnectCheckbox. It allows giving with lambda expressions.

    An eventHandler function will be called when a change event occurs with the AutoConnectCheckbox. Its prototype declaration is follows:

    void eventHandler(AutoConnectCheckbox& me, AutoConnectAux& aux)\n
    Parameter meA reference to the instance of the AutoConnectCheckbox that fired the change event. auxReference to the AutoConnectAux instance to which the AutoConnectCheckbox that generated the change event belongs."},{"location":"apielements.html#response_1","title":"response","text":"
    void response(const bool checked)\n
    void response(const char* attribute, const char* value)\n

    Reply the value or attribute of an element to the client. The response is usually used for sending a reply to the client with the element's value or attribute that has been updated in an event handler function.

    The response function itself does not perform communication. It only temporarily accumulates updated values. The stored content constitutes the response data to the HTTP POST request sent from the client browser caused by the AutoConnectElements event.

    The response function has two overloads with different numbers of arguments. A response function suitable for just one argument will only update the check status of the AutoConnectCheckbox. Also, a response function suitable for two arguments allows updating all attributes of the HTML input type=\"checkbox\" element derived from AutoConnectCheckbox. Parameter checkedA changing checked status of AutoConnectCheckbox::checked as response. valueSpecifies a value of the HTML input type=\"checkbox\" element to be modified as specified in the attribute argument. attributeAn attribute name of an HTML input type=\"checkbox\" element to be changed.

    "},{"location":"apielements.html#typeof_1","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectCheckbox. Return value AC_Checkbox

    "},{"location":"apielements.html#autoconnectelement","title":"AutoConnectElement","text":""},{"location":"apielements.html#constructor_2","title":"Constructor","text":"
    AutoConnectElement(const char* name = \"\", const char* value = \"\", const ACPosterior_t post = AC_Tag_None)\n
    Parameters nameThe element name. valueValue of the element. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_2","title":"Public member variables","text":""},{"location":"apielements.html#enable_2","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_2","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#name_2","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_2","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#value_2","title":"value","text":"

    Value of the element. It is output as HTML as it is as a source for generating HTML code. Type String

    "},{"location":"apielements.html#public-member-functions_2","title":"Public member functions","text":""},{"location":"apielements.html#typeof_2","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectElement. Return value AC_Element

    "},{"location":"apielements.html#ast","title":"as<T>","text":"
    AutoConnectElement& as<T>(void)\n

    Casts the reference to the AutoConnectElement the specified type. Parameter TThe element type. AutoConnectElements type such as AutoConnectButton, AutoConnectCheckbox, AutoConnectFile, AutoConnectInput, AutoConnectRadio, AutoConnectSelect, AutoConnectStyle, AutoConnectSubmit, AutoConnectText. Return value A reference to the AutoConnectElement with actual type.

    "},{"location":"apielements.html#autoconnectfile","title":"AutoConnectFile","text":""},{"location":"apielements.html#constructor_3","title":"Constructor","text":"
    AutoConnectFile(const char* name = \"\", const char* value = \"\", const char* label = \"\", const ACFile_t store = AC_File_FS, const ACPosterior_t post = AC_Tag_BR)\n
    Parameters nameThe element name. valueFile name to be upload. labelLabel string. storeThe ACFile_t enumerator that represents the media to save the uploaded file. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_3","title":"Public member variables","text":""},{"location":"apielements.html#enable_3","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_3","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#label_1","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the file input box. Specification of a label will generate an HTML <label> tag with an id attribute. The file input box and the label are connected by the id attribute. Type String

    "},{"location":"apielements.html#mimetype","title":"mimeType","text":"

    The mime type of the upload file which included as Media type in the http post request. Set by the client (usually the browser) that requested the upload. It is determined by the file type as application/octet-stream, text etc. which is described in IANA Media Type. Type String

    "},{"location":"apielements.html#name_3","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_3","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#size","title":"size","text":"

    Size of the uploading file. Type size_t

    "},{"location":"apielements.html#store","title":"store","text":"

    Specifies the save destination of the uploaded file. You can use the built-in uploader to save uploaded file to the flash of the ESP8266/ESP32 module or external SD media without writing a dedicated sketch code. It also supports saving to any destination using a custom uploader that inherits from the AutoConnectUploadHandler class. Type ACFile_t

    • AC_File_FS : Save the uploaded file to SPIFFS in the flash.
    • AC_File_SD : Save the uploaded file to SD.
    • AC_File_Extern : Save the file using your own upload handler.
    "},{"location":"apielements.html#value_3","title":"value","text":"

    File name to be upload. The value contains the value entered by the client browser to the <input type=\"file\"> tag and is read-only. Type String

    "},{"location":"apielements.html#public-member-functions_3","title":"Public member functions","text":""},{"location":"apielements.html#typeof_3","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectFile. Return value AC_File

    "},{"location":"apielements.html#autoconnectinput","title":"AutoConnectInput","text":""},{"location":"apielements.html#constructor_4","title":"Constructor","text":"
    AutoConnectInput(const char* name = \"\", const char* value = \"\", const char* label = \"\", const char* pattern = \"\", const char* placeholder = \"\", const ACPosterior_t post = AC_Tag_BR, const ACInput_t apply = AC_Input_Text)\n
    Parameters nameThe element name. valueValue of the element. labelLabel string. patternRegular expression string for checking data format. placeholderA placeholder string. postSpecifies the tag to be output afterward the element. applySpecifies the type of input that the text box accepts."},{"location":"apielements.html#public-member-variables_4","title":"Public member variables","text":""},{"location":"apielements.html#enable_4","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_4","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#label_2","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the input box. Specification of a label will generate an HTML <label> tag with an id attribute. The input box and the label are connected by the id attribute. Type String

    "},{"location":"apielements.html#name_4","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#pattern","title":"pattern","text":"

    A pattern specifies a regular expression that the input-box's value is checked against on form submission. Type String

    "},{"location":"apielements.html#placeholder","title":"placeholder","text":"

    A placeholder is an option string. Specification of a placeholder will generate a placeholder attribute for the input tag. Type String

    "},{"location":"apielements.html#post_4","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#value_4","title":"value","text":"

    Value of the element. It becomes a value attribute of an HTML <input type=\"text\"> tag. An entered text in the custom Web page will be sent with a query string of the form. The value set before accessing the page is displayed as the initial value. Type String

    "},{"location":"apielements.html#apply","title":"apply","text":"

    Specifies the type of input that the text box accepts. AutoConnectInput will generate either a <input type=\"text\">, <input type=\"password\">, or <input type=\"number\"> tag based on the apply specifying as input type. The input type can be specified the following values in the ACInput_t enumeration type. 1 Type ACInput_t

    • AC_Input_Text : input type=\"text\"
    • AC_Input_Password : input type=\"password\"
    • AC_Input_Number : input type=\"number\"
    "},{"location":"apielements.html#public-member-functions_4","title":"Public member functions","text":""},{"location":"apielements.html#canhandle_2","title":"canHandle","text":"
    bool canHandle(void)\n

    Returns whether the AutoConnectInput element has a registered event handler and can respond to a change event. Return value trueAn event handler is registered. The element can correspond to a change event. falseAn event handler is not registered.

    "},{"location":"apielements.html#isvalid","title":"isValid","text":"
    bool isValid(void)\n

    Evaluate the pattern as a regexp and return whether value matches. Always return true if the pattern is undefined. Return value trueThe value matches a pattern. falseThe value does not match a pattern.

    "},{"location":"apielements.html#off_2","title":"off","text":"
    void off(void)\n

    Release a registered event handler so that the element does not react to events.

    "},{"location":"apielements.html#on_2","title":"on","text":"
    void on(std::function<void(AutoConnectInput&, AutoConnectAux&)> eventHandler)\n

    Register an event handler function so that the element can respond to a change event. Parameter eventHandlerA function instance corresponding to a change event on AutoConnectInput. It allows giving with lambda expressions.

    An eventHandler function will be called when a change event occurs with the AutoConnectInput. Its prototype declaration is follows:

    void eventHandler(AutoConnectInput& me, AutoConnectAux& aux)\n
    Parameter meA reference to the instance of the AutoConnectInput that fired the change event. auxReference to the AutoConnectAux instance to which the AutoConnectInput that generated the change event belongs."},{"location":"apielements.html#response_2","title":"response","text":"
    void response(const char* value)\n
    void response(const char* attribute, const char* value)\n

    Reply the value or attribute of an element to the client. The response is usually used for sending a reply to the client with the element's value or attribute that has been updated in an event handler function.

    The response function itself does not perform communication. It only temporarily accumulates updated values. The stored content constitutes the response data to the HTTP POST request sent from the client browser caused by the AutoConnectElements event.

    The response function has two overloads with different numbers of arguments. A response function suitable for just one argument will only update the value of the AutoConnectInput. Also, a response function suitable for two arguments allows updating all attributes of the HTML input type=\"text\" element derived from AutoConnectInput. Parameter valueSuitable for one argument format: A changing value of AutoConnectInput::value as response.Suitable for two argument format: Specifies a value of the HTML input type=\"text\" element to be modified as specified in the attribute argument. attributeAn attribute name of an HTML input type=\"text\" element to be changed.

    "},{"location":"apielements.html#typeof_4","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectInput. Return value AC_Input

    "},{"location":"apielements.html#autoconnectradio","title":"AutoConnectRadio","text":""},{"location":"apielements.html#constructor_5","title":"Constructor","text":"
    AutoConnectRadio(const char* name = \"\", std::vector<String> const& values = {}, const char* label = \"\", const ACArrange_t order = AC_Vertical, const uint8_t checked = 0, const ACPosterior_t post = AC_Tag_BR)\n
    Parameters nameThe element name. valuesAn array of values of the radio buttons. Specifies a std::vector object. labelLabel string. orderThe direction to arrange the radio buttons. checkedAn index to be checked in the radio buttons. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_5","title":"Public member variables","text":""},{"location":"apielements.html#checked_1","title":"checked","text":"

    Specifies the index number (1-based) of the values to be checked. If this parameter is not specified neither item is checked. Type uint8_t

    "},{"location":"apielements.html#enable_5","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_5","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#label_3","title":"label","text":"

    A label is an optional string. A label will be arranged in the left or top of the radio buttons according to the order. Type String

    "},{"location":"apielements.html#name_5","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#order","title":"order","text":"

    Specifies the direction to arrange the radio buttons. A label will place in the left or the top according to the order. It is a value of ACArrange_t type and accepts one of the following: Type ACArrange_t

    • AC_Horizontal : Horizontal arrangement.
    • AC_Vertical : Vertical arrangement.
    "},{"location":"apielements.html#post_5","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#values","title":"values","text":"

    An array of String type for the radio button options. It is an initialization list can be used. The <input type=\"radio\"> tags will be generated from each entry in the values. Type std::vector<String>

    "},{"location":"apielements.html#public-member-functions_5","title":"Public member functions","text":""},{"location":"apielements.html#add","title":"add","text":"
    void add(const String& value)\n

    Adds an option for the radio button. Parameter valueAn option string to add to the radio button.

    "},{"location":"apielements.html#canhandle_3","title":"canHandle","text":"
    bool canHandle(void)\n

    Returns whether the AutoConnectRadio element has a registered event handler and can respond to a change event. Return value trueAn event handler is registered. The element can correspond to a change event. falseAn event handler is not registered.

    "},{"location":"apielements.html#check","title":"check","text":"
    void check(const String& value)\n

    Indicates the check of the specified option for the radio buttons. You can use the check function for checking dynamically with arbitrary of the radio button. Parameter valueAn option string to be checked.

    "},{"location":"apielements.html#empty","title":"empty","text":"
    void empty(const size_t reserve = 0)\n

    Clear the array of option strings that AutoConnectRadio has in the values. When the reserve parameter is specified, a vector container of that size is reserved.

    The empty function resets the checked value to zero. When the empty function is executed, any button will be turned off. Parameter reserveReserved size of a container for the radio button option strings.

    "},{"location":"apielements.html#off_3","title":"off","text":"
    void off(void)\n

    Release a registered event handler so that the element does not react to events.

    "},{"location":"apielements.html#on_3","title":"on","text":"
    void on(std::function<void(AutoConnectRadio&, AutoConnectAux&)> eventHandler)\n

    Register an event handler function so that the element can respond to a change event. Parameter eventHandlerA function instance corresponding to a change event on AutoConnectRadio. It allows giving with lambda expressions.

    An eventHandler function will be called when a change event occurs with the AutoConnectRadio. Its prototype declaration is follows:

    void eventHandler(AutoConnectRadio& me, AutoConnectAux& aux)\n
    Parameter meA reference to the instance of the AutoConnectRadio that fired the change event. auxReference to the AutoConnectAux instance to which the AutoConnectRadio that generated the change event belongs."},{"location":"apielements.html#operator","title":"operator [\u00a0]","text":"
    const String& operator[] (const std::size_t n)\n

    Returns a value string of the index specified by n. Parameter nIndex of values array to return. Its base number is 0. Return value A reference of a value string indexed by the specified the n.

    "},{"location":"apielements.html#size_1","title":"size","text":"
    size_t size(void)\n

    Returns number of options which contained. Return value Number of options which contained.

    "},{"location":"apielements.html#typeof_5","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectRadio. Return value AC_Radio

    "},{"location":"apielements.html#value_5","title":"value","text":"
      const String& value(void) const\n

    Returns current checked option of the radio buttons. Return value A String of an option current checked. If there is no checked option, a null string returned.

    "},{"location":"apielements.html#autoconnectrange","title":"AutoConnectRange","text":""},{"location":"apielements.html#constructor_6","title":"Constructor","text":"
    AutoConnectRange(const char* name = \"\", const int value = 0, const char* label = \"\", const int min = 0, const int max = 0, const int step = 1, const ACPosition_t magnify = AC_Void, const ACPosterior_t post = AC_Tag_BR, const char* style = \"\")\n
    Parameters nameThe element name. valueThe initial value in the range. labelLabel string. minThe most negative value within the range of allowed values. maxThe greatest value in the range of permitted values. stepThe granularity that the value must adhere to. magnifySpecifies the display position of the current value of the range. postSpecifies the tag to be output afterward the element. styleA style code with CSS format that qualifiers the range slider."},{"location":"apielements.html#public-member-variables_6","title":"Public member variables","text":""},{"location":"apielements.html#enable_6","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_6","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#label_4","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the input box. Specification of a label will generate an HTML <label> tag with an id attribute. The range slider and the label are connected by the id attribute. Type String

    "},{"location":"apielements.html#magnify","title":"magnify","text":"Display position of the current value of the range. Type ACPosition_t
    • AC_Infront : Displays the current value on the left side.
    • AC_Behind : Displays the current value on the right side.
    • AC_Void : No display the current value. This is the default.
    "},{"location":"apielements.html#max","title":"max","text":"

    The greatest value in the range. Type int

    "},{"location":"apielements.html#min","title":"min","text":"

    The most negative value within the range. Type int

    "},{"location":"apielements.html#name_6","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_6","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#step","title":"step","text":"

    The granularity that the value must adhere to. Type int

    "},{"location":"apielements.html#style","title":"style","text":"

    A style code with CSS format that qualifiers the range slider. Type String

    "},{"location":"apielements.html#value_6","title":"value","text":"

    Value of the element. It becomes a value attribute of an HTML <input type=\"range\"> tag. A value of range in the custom Web page will be sent with a query string of the form. Type int

    "},{"location":"apielements.html#public-member-functions_6","title":"Public member functions","text":""},{"location":"apielements.html#typeof_6","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectRange. Return value AC_Range

    "},{"location":"apielements.html#autoconnectselect","title":"AutoConnectSelect","text":""},{"location":"apielements.html#constructor_7","title":"Constructor","text":"
    AutoConnectSelect(const char* name = \"\", std::vector<String> const& options = {}, const char* label = \"\", const uint8_t selected = 0, const ACPosterior_t post = AC_Tag_BR)\n
    Parameters nameThe element name. optionsAn array of options of the select element. Specifies a std::vector object. labelLabel string. selectedAn option should be pre-selected when the page loads. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_7","title":"Public member variables","text":""},{"location":"apielements.html#enable_7","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_7","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#name_7","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#label_5","title":"label","text":"

    A label is an optional string. A label will be arranged in the top of the selection list. Type String

    "},{"location":"apielements.html#options","title":"options","text":"

    An array of String type for the selection options. It is an initialization list can be used. The <option value> tags will be generated from each entry in the options. Type std::vector<String>

    "},{"location":"apielements.html#post_7","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#selected","title":"selected","text":"

    A selected is an optional value. Specifies 1-based index value of an options array that an option should be pre-selected when the page loads. Type uint8_t

    "},{"location":"apielements.html#public-member-functions_7","title":"Public member functions","text":""},{"location":"apielements.html#add_1","title":"add","text":"
    void add(const String& option)\n
    "},{"location":"apielements.html#canhandle_4","title":"canHandle","text":"
    bool canHandle(void)\n

    Returns whether the AutoConnectSelect element has a registered event handler and can respond to a change event. Return value trueAn event handler is registered. The element can correspond to a change event. falseAn event handler is not registered.

    Adds a selectable option string for the selection list. Parameter optionA string of selectable item to be contained in the select element.

    "},{"location":"apielements.html#empty_1","title":"empty","text":"
    void empty(const size_t reserve = 0)\n

    Clear the array of options list that AutoConnectSelect has in the options. When the reserve parameter is specified, a vector container of that size is reserved.

    The empty function resets the selected value to zero. When the empty function is executed, there are no selected options and the first item is placed at the beginning. Parameter reserveReserved size of a container for the options.

    "},{"location":"apielements.html#off_4","title":"off","text":"
    void off(void)\n

    Release a registered event handler so that the element does not react to events.

    "},{"location":"apielements.html#on_4","title":"on","text":"
    void on(std::function<void(AutoConnectSelect&, AutoConnectAux&)> eventHandler)\n

    Register an event handler function so that the element can respond to a change event. Parameter eventHandlerA function instance corresponding to a change event on AutoConnectSelect. It allows giving with lambda expressions.

    An eventHandler function will be called when a change event occurs with the AutoConnectSelect. Its prototype declaration is follows:

    void eventHandler(AutoConnectSelect& me, AutoConnectAux& aux)\n
    Parameter meA reference to the instance of the AutoConnectSelect that fired the change event. auxReference to the AutoConnectAux instance to which the AutoConnectSelect that generated the change event belongs."},{"location":"apielements.html#operator_1","title":"operator [\u00a0]","text":"
    const String& operator[] (const std::size_t n)\n

    Returns an option string of the index specified by n. Parameter nIndex of options array to return. Its base number is 0. Return value A reference of a option string indexed by the specified the n.

    "},{"location":"apielements.html#select","title":"select","text":"
    void  select(const String& value);\n

    Selects an option with the value. Parameter valueString value that option should be selected in an option array.

    "},{"location":"apielements.html#size_2","title":"size","text":"
    size_t size(void)\n

    Returns number of options which contained. Return value Number of options which contained.

    "},{"location":"apielements.html#typeof_7","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectSelect. Return value AC_Select

    "},{"location":"apielements.html#value_7","title":"value","text":"
    const String& value(void) const;\n

    Returns current selected option of the select list. Return value A String of an option current selected. If there is no select option, a null string returned.

    "},{"location":"apielements.html#autoconnectstyle","title":"AutoConnectStyle","text":""},{"location":"apielements.html#constructor_8","title":"Constructor","text":"
    AutoConnectStyle(const char* name = \"\", const char* value = \"\")\n
    Parameters nameThe element name. valueRaw CSS code to insert into a style block in a custom web page to generate."},{"location":"apielements.html#public-member-variables_8","title":"Public member variables","text":""},{"location":"apielements.html#enable_8","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#name_8","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#value_8","title":"value","text":"

    Raw CSS code to insert into a style block in a custom web page to generate. Type String

    "},{"location":"apielements.html#public-member-functions_8","title":"Public member functions","text":""},{"location":"apielements.html#typeof_8","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectStyle. Return value AC_Style

    "},{"location":"apielements.html#autoconnectsubmit","title":"AutoConnectSubmit","text":""},{"location":"apielements.html#constructor_9","title":"Constructor","text":"
    AutoConnectSubmit(const char* name = \"\", const char* value =\"\", char* uri = \"\", const ACPosterior_t post = AC_Tag_None)\n
    Parameters nameThe element name. valueThe name of the submit button as an HTML `#!html ` tag, it will also be the label of the button. uriDestination URI. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_9","title":"Public member variables","text":""},{"location":"apielements.html#enable_9","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_8","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#name_9","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_8","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#uri","title":"uri","text":"

    Destination URI. Type String

    "},{"location":"apielements.html#value_9","title":"value","text":"

    The name of the submit button. It will also be the label of the button. Type String

    "},{"location":"apielements.html#public-member-functions_9","title":"Public member functions","text":""},{"location":"apielements.html#typeof_9","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectSubmit. Return value AC_Submit

    "},{"location":"apielements.html#autoconnecttext","title":"AutoConnectText","text":""},{"location":"apielements.html#constructor_10","title":"Constructor","text":"
    AutoConnectText(const char* name = \"\", const char* value = \"\", const char* style = \"\", const char* format = \"\", const ACPosterior_t post = AC_Tag_None)\n
    Parameters nameThe element name. valueString of content for the text element. styleA style code with CSS format that qualifiers the text. formatA pointer to a null-terminated multibyte string specifying how to interpret the value. It specifies the conversion format when outputting values. The format string conforms to C-style printf library functions postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_10","title":"Public member variables","text":""},{"location":"apielements.html#enable_10","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#format","title":"format","text":"

    The conversion format when outputting values. The format string conforms to C-style printf library functions. Type String

    "},{"location":"apielements.html#global_9","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#name_10","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_9","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#style_1","title":"style","text":"

    A style code with CSS format that qualifiers the text. Type String

    "},{"location":"apielements.html#value_10","title":"value","text":"

    A content string of the text element. Type String

    "},{"location":"apielements.html#public-member-functions_10","title":"Public member functions","text":""},{"location":"apielements.html#response_3","title":"response","text":"
    void response(const char* value)\n
    void response(const char* attribute, const char* value)\n

    Reply the value or attribute of an element to the client. The response is usually used for sending a reply to the client with the element's value or attribute that has been updated in an event handler function.

    The response function itself does not perform communication. It only temporarily accumulates updated values. The stored content constitutes the response data to the HTTP POST request sent from the client browser caused by the AutoConnectElements event.

    The response function has two overloads with different numbers of arguments. A response function suitable for just one argument will only update the DOM text (i.e., the innerHTML attribute dependent on the div or span node) of the AutoConnectText. Also, a response function suitable for two arguments allows updating all attributes of the HTML div or span node derived from AutoConnectText. Parameter valueSuitable for one argument format: A changing value of AutoConnectText::value as response. It also will update the innerHTML attribute of the div or span node derived from AutoConnectText.Suitable for two argument format: Specifies a value of the HTML div or span node to be modified as specified in the attribute argument. attributeAn attribute name of an HTML div or span node to be changed.

    "},{"location":"apielements.html#typeof_10","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectText. Return value AC_Text

    1. ACInput_t does not mind what kind of display effects on the browser. For example, input type=\"number\" has a spin button in Chrome, but has no display effects in iOS Safari. You will see the numeric keypad at inputting the number field with giving the pattern as \\d*.\u00a0\u21a9\u21a9

    "},{"location":"apiextra.html","title":"Something extra","text":""},{"location":"apiextra.html#icons","title":"Icons","text":"

    The library presents two PNG icons which can be used to embed a hyperlink to the AutoConnect menu.

    • Bar type
    • Cog type

    To reference the icon, use the AUTOCONNECT_LINK macro in the Sketch. It expands into the string literal as an HTML <a></a> tag with PNG embedded of the AutoConnect menu hyperlinks. Icon type is specified by the parameter of the macro.

    BAR_24Bars icon, 24x24. BAR_32Bars icon, 32x32. BAR_48Bars icon, 48x48. COG_16Cog icon, 16x16. COG_24Cog icon, 24x24. COG_32Cog icon, 32x32.

    Usage

    String html = \"<html>\";\nhtml += AUTOCONNECT_LINK(BAR_32);\nhtml += \"</html>\";\nserver.send(200, \"text/html\", html);\n
    "},{"location":"apiextra.html#captive-portal-availability-identification","title":"Captive Portal Availability Identification","text":"

    A check mark icon can be displayed adjacent to the AutoConnect menu title to indicate that a captive portal is available. This check mark indicates that the ESP module is not connected to any access point, SoftAP is enabled, and DNS lookup spoofing is working through the AutoConnect-initiated DNS server.

    This setting is enabled by turning on the AC_SHOW_PORTALIDENTIFIER macro defined in AutoConnectDefs.h header file.

    #define AC_SHOW_PORTALIDENTIFIER\n

    Using the PlatformIO as a build environment, you can enable it in the build_flags setting without modifying the library's AutoConnectDefs.h source file.

    platform = espressif32\nframework = arduino\nbuild_flags = -DAC_SHOW_PORTALIDENTIFIER\n
    "},{"location":"apiupdate.html","title":"AutoConnectUpdate API","text":"

    Only for AutoConnect

    The following AutoConnectUpdate API are valid only for AutoConnect; they are not available for AutoConnectCore.

    "},{"location":"apiupdate.html#constructor","title":"Constructor","text":""},{"location":"apiupdate.html#autoconnectupdate","title":"AutoConnectUpdate","text":"
    AutoConnectUpdate(const String& host, const uint16_t port, const String& uri, const int timeout, const uint8_t ledOn)\n
    Parameters hostUpdate server address. Specifies IP address or FQDN. portSpecifies HTTP port for the updating process. The default assumes AUTOCONNECT_UPDATE_PORT defined in the AutoConnectDefs.h header file. uriSpecifies a URI on the update server that has deployed available binary sketch files. timeoutSpecifies the maximum response time for the update server. The default assumes AUTOCONNECT_UPDATE_TIMEOUT in the AutoConnectDefs.h header file. ledOnActive signal to light the LED ticker during the update. Specifies HIGH or LOW

    The AutoConnectUpdate class inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    "},{"location":"apiupdate.html#public-member-functions","title":"Public member functions","text":""},{"location":"apiupdate.html#attach","title":"attach","text":"
    void AutoConnectUpdate::attach(AutoConnect& portal)\n

    Attaches the AutoConnectUpdate to the AutoConnect which constitutes the bedrock of the update process. This function creates a dialog page for the update operation as an instance of AutoConnectAux and participates in the AutoConnect menu. Parameter portalSpecifies a reference to the AutoConnect instance to attach.

    "},{"location":"apiupdate.html#disable","title":"disable","text":"
    void AutoConnectUpdate::disable(const bool activate)\n

    Disable the Update item in AutoConnect menu. The AutoConnect::disable function only hides the Update item from the menu, and the AutoConnectUpdate class is still active with the parameter condition. You can use the AutoConnectUpdate::enable function to appear it again in the menu. Parameter activateIf specified the true then the Update item will be displayed on the AutoConnect menu and OTA update will be available during the WiFi status is WL_CONNECTED. For the false, the OTA update feature is disabled.

    "},{"location":"apiupdate.html#enable","title":"enable","text":"
    void AutoConnectUpdate::enable(void)\n

    Makes AutoConnectUpdate class available by incorporating the OTA update function into the AutoConnect menu. In ordinarily, the AutoConnectUpdate class becomes available by just calling the AutoConnectUpdate::attach function.

    "},{"location":"apiupdate.html#handleupdate","title":"handleUpdate","text":"
    void AutoConnectUpdate::handleUpdate(void)\n

    Performs the update process. This function is called by AutoConnect::handleClient when AutoConnectUpdate is enabled. In many cases, sketches do not need to call this function on purpose.

    "},{"location":"apiupdate.html#isenabled","title":"isEnabled","text":"
    bool AutoConnectUpdate::isEnabled(void)\n

    Returns whether AutoConnectUpdate is enabled.

    "},{"location":"apiupdate.html#rebootonupdate","title":"rebootOnUpdate","text":"
    void AutoConnectUpdate::rebootOnUpdate(bool reboot)\n

    Specifies whether or not to automatically restart the module as a result of the successful completion of the update process. Parameter rebootIf specified the true then the ESP module will reboot after the updating successfully completed. For the false, The module does not reboot automatically. The uploaded new firmware remains in the updating stage of the flash on the ESP module. The boot process during the next start turn of the module by reset will copy the updated firmware to the actual program area and a new sketch program will start. The default value is true.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    "},{"location":"apiupdate.html#onend","title":"onEnd","text":"

    void AutoConnectUpdate::onEnd(HTTPUpdateEndCB fn)\n
    Register the on-end exit routine that is called only once when the update is finished. For the ESP32 platform, this function is only available in ESP32 Arduino core 2.0.0 or later. Parameter fnA function called when the update has been finished.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    An fn specifies the function called when the update has been finished. Its prototype declaration is defined as HTTPUpdateEndCB.

    using HTTPUpdateEndCB = std::function<void()>;\n
    "},{"location":"apiupdate.html#onerror","title":"onError","text":"
    void AutoConnectUpdate::onError(HTTPUpdateErrorCB fn)\n

    Register the exit routine that is called when some error occurred. For the ESP32 platform, this function is only available in ESP32 Arduino core 2.0.0 or later. Parameter fnA function called when some updating error occurs.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    An fn specifies the function called when the some error occurred. Its prototype declaration is defined as HTTPUpdateErrorCB.

    using HTTPUpdateErrorCB = std::function<void(int error)>;\n
    Parameter errorError code of the Update. It is defined in the ESP8266HTTPClient class, ESP8266HTTPUpdate class or the HTTPUpdate class of the Arduino core for each platform."},{"location":"apiupdate.html#onprogress","title":"onProgress","text":"
    void AutoConnectUpdate::onProgress(HTTPUpdateProgressCB fn)\n

    Register the exit routine that is called during the update progress. For the ESP32 platform, this function is only available in ESP32 Arduino core 2.0.0 or later. Parameter fnA function called during the updating progress.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    An fn specifies the function called during the updating progress. Its prototype declaration is defined as HTTPUpdateProgressCB.

    Updating Progress bar will not available

    AutoConnectUpdate uses the onProgress exit to update the progress bar on a web page during updating. If the user sketch registers its own exit routine with the onProgress function, AutoConnectUpdate's progress bar on the web page will not be updated.

    using HTTPUpdateProgressCB = std::function<void(int amount, int size)>;\n
    Parameters amountTotal amount of bytes received. sizeBlock size of current send."},{"location":"apiupdate.html#onstart","title":"onStart","text":"
    void AutoConnectUpdate::onStart(HTTPUpdateStartCB fn)\n

    Register the on-start exit routine that is called only once when the update has been started. For the ESP32 platform, this function is only available in ESP32 Arduino core 2.0.0 or later. Parameter fnA function called at the update start.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    An fn specifies the function called when the OTA starts. Its prototype declaration is defined as HTTPUpdateStartCB.

    using HTTPUpdateStartCB = std::function<void()>;\n
    "},{"location":"apiupdate.html#setledpin","title":"setLedPin","text":"
    void AutoConnectUpdate::setLedPin(int ledPin, uint8_t ledOn)\n

    Sets the port and the ON signal level of the externally connected LED that should act as a ticker during the update process. Parameter ledPinSpecifies the PIN connected external LED for the ticker. The default assumes AUTOCONNECT_TICKER_PORT defined in the AutoConnectDefs.h header file and it is derived from the board-specific LED_BUILTIN. By default, the AutoConnectUpdate class does not use the ticker for boards without the LED_BUILTIN definition. If you connect the ticker LED externally, you need to specify the PIN using the setLedPin function. ledOnSpecifies the the ON signal level of the LED PIN port. It is HIGH or LOW.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    "},{"location":"apiupdate.html#status","title":"status","text":"
    AC_UPDATESTATUS_t AutoConnectUpdate::status(void)\n

    Returns the update process status transition indicator as an enumerated value of the AC_UPDATESTATUS_t type that indicates the process status of the AutoConnectUpdate class. Return value One of the enumerated values indicating the status of the Update class as follows:

    • UPDATE_RESET : Update process ended, need to reset.
    • UPDATE_IDLE : Update process has not started.
    • UPDATE_START : Update process has been started.
    • UPDATE_PROGRESS : Update process has been started.
    • UPDATE_SUCCESS : Update successfully completed.
    • UPDATE_NOAVAIL : No available update.
    • UPDATE_FAIL : Update failed.
    "},{"location":"apiupdate.html#public-member-variables","title":"Public member variables","text":""},{"location":"apiupdate.html#host","title":"host","text":"

    Update server address. Specifies IP address or FQDN. Type String

    "},{"location":"apiupdate.html#port","title":"port","text":"

    HTTP port for the updating process. Type StringThe default assumes AUTOCONNECT_UPDATE_PORT defined in the AutoConnectDefs.h header file.

    "},{"location":"apiupdate.html#uri","title":"uri","text":"

    URI on the update server that has deployed available binary sketch files. Type String

    "},{"location":"basicusage.html","title":"Basic usage","text":""},{"location":"basicusage.html#simple-usage","title":"Simple usage","text":""},{"location":"basicusage.html#embed-to-the-sketches","title":"Embed to the Sketches","text":"

    How embed the AutoConnect to the Sketches you have. Most simple approach to applying AutoConnect for the existing Sketches, follow the below steps. The below Sketch is for ESP8266. For ESP32, replace ESP8266WebServer with WebServer and ESP8266WiFi.h with WiFi.h respectively.

    Insert #include <AutoConnect.h> to behind of #include <ESP8266WebServer.h>.

    Insert AutoConnect PORTAL(WEBSERVER); to behind of ESP8266WebServer WEBSERVER; declaration.1

    Remove WiFi.begin(SSID,PSK) and the subsequent logic for the connection status check.

    Replace WEBSERVER.begin() to PORTAL.begin().2

    Replace WEBSERVER.handleClient() to PORTAL.handleClient().3

    If the connection checks logic is needed, you can check the return value according to PORTAL.begin() with true or false.

    "},{"location":"basicusage.html#basic-usage","title":"Basic usage","text":""},{"location":"basicusage.html#basic-logic-sequence-for-the-user-sketches","title":"Basic logic sequence for the user Sketches","text":""},{"location":"basicusage.html#1-a-typical-logic-sequence","title":"1. A typical logic sequence","text":"
    1. Include headers, ESP8266WebServer.h/WebServer.h and AutoConnect.h
    2. Declare an ESP8266WebServer variable for ESP8266 or a WebServer variable for ESP32.
    3. Declare an AutoConnect variable.
    4. Implement the URL handlers provided for the on method of ESP8266WebServer/WebServer with the function().
    5. setup() 5.1 Sets URL handler the function() to ESP8266WebServer/WebServer byESP8266WebServer::on/WebServer::on. 5.2 Starts AutoConnect::begin(). 5.3 Check WiFi connection status.
    6. loop() 6.1 Do the process for actual Sketch. 6.2 Invokes AutoConnect::handleClient(), or invokes ESP8266WebServer::handleClient()/WebServer::handleClient then AutoConnect::handleRequest().
    "},{"location":"basicusage.html#2-declare-autoconnect-object","title":"2. Declare AutoConnect object","text":"

    Two options are available for AutoConnect constructor.

    AutoConnect VARIABLE(&ESP8266WebServer);  // For ESP8266\nAutoConnect VARIABLE(&WebServer);         // For ESP32\n
    or

    AutoConnect VARIABLE;\n

    • The parameter with an ESP8266WebServer/WebServer variable: An ESP8266WebServer/WebServer object variable must be declared. AutoConnect uses its variable to handles the AutoConnect menu.

    • With no parameter: the Sketch does not declare ESP8266WebServer/WebServer object. In this case, AutoConnect allocates an instance of the ESP8266WebServer/WebServer internally. The logic sequence of the Sketch is somewhat different as the above. To register a URL handler function by ESP8266WebServer::on or WebServer::on should be performed after AutoConnect::begin.

    "},{"location":"basicusage.html#3-no-need-wifibegin","title":"3. No need WiFI.begin(...)","text":"

    AutoConnect internally performs WiFi.begin to establish a WiFi connection. There is no need for a general process to establish a connection using WiFi.begin with a Sketch code.

    "},{"location":"basicusage.html#4-alternate-esp8266webserverbegin-and-webserverbegin","title":"4. Alternate ESP8266WebServer::begin() and WebServer::begin()","text":"

    AutoConnect::begin executes ESP8266WebServer::begin/WebServer::begin internally too and it starts the DNS server to behave as a Captive portal. So it is not needed to call ESP8266WebServer::begin/WebServer::begin in the Sketch.

    Why DNS Server starts

    AutoConnect traps the detection of the captive portal and achieves a connection with the WLAN interactively by the AutoConnect menu. It responds SoftAP address to all DNS queries temporarily to trap. Once a WiFi connection establishes, the DNS server contributed by AutoConnect stops.

    "},{"location":"basicusage.html#5-autoconnectbegin-with-ssid-and-password","title":"5. AutoConnect::begin with SSID and Password","text":"

    SSID and Password can also specify by AutoConnect::begin. ESP8266/ESP32 uses provided SSID and Password explicitly. If the connection false with specified SSID with Password then a captive portal is activated. SSID and Password are not present, ESP8266 SDK will attempt to connect using the still effectual SSID and password. Usually, it succeeds.

    "},{"location":"basicusage.html#6-use-esp8266webserveron-and-webserveron-to-handle-url","title":"6. Use ESP8266WebServer::on and WebServer::on to handle URL","text":"

    AutoConnect is designed to coexist with the process for handling the web pages by user Sketches. The page processing function which will send an HTML to the client invoked by the \"on::ESP8266WebServer\" or the \"on::WebServer\" function is the same as when using ESP8266WebServer/WebServer natively.

    "},{"location":"basicusage.html#7-use-either-esp8266webserverhandleclientwebserverhandleclient-or-autoconnecthandleclient","title":"7. Use either ESP8266WebServer::handleClient()/WebServer::handleClient() or AutoConnect::handleClient()","text":"

    Both classes member function name is the same: handleClient, but the behavior is different. Using the AutoConnect embedded along with ESP8266WebServer::handleClient/WebServer::handleClient has limitations. Refer to the below section for details.

    "},{"location":"basicusage.html#esp8266webserverwebserver-hosted-or-parasitic","title":"ESP8266WebServer/WebServer hosted or parasitic","text":"

    The interoperable process with an ESP8266WebServer/WebServer depends on the parameters of the AutoConnect constructor.

    Declaration parameter for the constructor Use ESP8266WebServer::handleClient or WebServer::handleClient only Use AutoConnect::handleClient None AutoConnect menu not available.To use AutoConnect menu, need AutoConnect::handleRequest().also to use ESP8266WebServer/WebServer natively, need AutoConnect::host(). AutoConnect menu available.To use ESP8266WebServer/WebServer natively, need AutoConnect::host(). Reference to ESP8266WebServer/WebServer AutoConnect menu not available.To use AutoConnect menu, need AutoConnect::handleRequest(). AutoConnect menu available.

    • By declaration for the AutoConnect variable with no parameter: The ESP8266WebServer/WebServer instance is hosted by AutoConnect automatically then the Sketches use AutoConnect::host as API to get it after AutoConnect::begin performed.

    • By declaration for the AutoConnect variable with the reference of ESP8266WebServer/WebServer: AutoConnect will use it. the Sketch can use it is too.

    • In use ESP8266WebServer::handleClient()/WebServer::handleClient(): AutoConnect menu can be dispatched but not works normally. It is necessary to call AutoConnect::handleRequest after ESP8255WebServer::handleClient/WebServer::handleClient invoking.

    • In use AutoConnect::handleClient(): The handleClient() process and the AutoConnect menu is available without calling ESP8266WebServer::handleClient.

    Why AutoConnect::handleRequest is needed when using ESP8266WebServer::handleClient/WebServer::handleClient

    The AutoConnect menu function may affect WiFi connection state. It follows that the menu process must execute outside ESP8266WebServer::handleClient and WebServer::handleClient. AutoConnect::handleClient is equivalent ESP8266WebServer::handleClient and WEbServer::handleClient included AutoConnect::handleRequest.

    "},{"location":"basicusage.html#reducing-binary-size","title":"Reducing Binary Size","text":"

    Typically, AutoConnect components include AutoConnectAux for handling Custom Web pages; AutoConnectAux plays a central role in responding to requests for Custom Web pages. It also incorporates several AutoConnectElements used in the sketch, which may exceed 1 MB in binary size after the build. To reduce the binary size, you can deactivate the component to handle these custom web pages, depending on the use case. If your sketch does not use Custom web pages, allows you to exclude the AutoConnectAux component to reduce the built binary size.

    AutoConnect.h header file enables all AutoConnect components. In a normal sketch, including this header enables all AutoConnect functionality. On the other hand, for sketches that don't use custom web pages, you can apply the AutoConnectCore.h header file.

    AutoConnectCore.h provides an AutoConnect class that excludes AutoConnectAux and AutoConnectElements from AutoConnect. Therefore, it does not implement the APIs required for custom web page processing. Also, AutoConnectOTA and AutoConnectUpdate cannot be used. (i.e., to use AutoConnect's equipped OTA Update feature, you must include the full AutoConnect component in your sketch) Instead, the binary size of the AutoConnectCore component is reduced by about 170 KB (1.3 KB for RAM) compared to the ESP32 AutoConnect full component. (60KB for ESP8266)

    To switch between AutoConnect and AutoConnectCore, simply change the corresponding header file with #include header.

    "},{"location":"basicusage.html#using-autoconnect-full-component","title":"Using AutoConnect Full component","text":"
    #include <WiFi.h>\n#include <WebServer.h>\n#include <AutoConnect.h>\nstatic const char PAGE_HELLO[] = R\"(\n{\n  \"uri\": \"/\",\n  \"title\": \"Hello\",\n  \"menu\": false,\n  \"element\": [\n    {\n      \"name\": \"caption\",\n      \"type\": \"ACText\",\n      \"value\": \"Hello, World\"\n    },\n  ]\n}\n)\";\n\nWebServer Server;\nAutoConnect Portal(Server);\nAutoConnectConfig Config;\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  Config.ota = AC_OTA_BUILTIN;\n  Portal.config(Config);\n\n  portal.load(PAGE_HELLO);\n  Portal.begin();\n  Serial.println(\"Web Server started:\" + WiFi.localIP().toString());\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n
    "},{"location":"basicusage.html#using-autoconnectcore-without-custom-web-pages-and-ota-update-facilities","title":"Using AutoConnectCore without Custom Web pages and OTA Update facilities","text":"

    Even in the sketch with AutoConnectCore.h applied, the class name remains AutoConnect.

    #include <WiFi.h>\n#include <WebServer.h>\n#include <AutoConnectCore.h>\nWebServer Server;\nAutoConnect Portal(Server);\nvoid rootPage() {\nchar content[] = \"Hello, World\";\n  Server.send(200, \"text/plain\", content);\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  Server.on(\"/\", rootPage);\n  Portal.begin();\n  Serial.println(\"Web Server started:\" + WiFi.localIP().toString());\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    Either AutoConnect.h or AutoConnectCore.h

    A sketch can include either AutoConnect.h or AutoConnectCore.h. These two header files are mutually exclusive and cannot be included together at the same time. Also, If the sketch includes AutoConnectCore.h, some members involved in the custom web page facility are excluded from AutoConnectConfig class.

    1. Each VARIABLE conforms to the actual declaration in the Sketches.\u00a0\u21a9

    2. WiFi SSID and Password can be specified AutoConnect::begin() too.\u00a0\u21a9

    3. Replacement the handleClient method is not indispensable. AutoConnect can still connect with the captive portal as it is ESP8266WebServer::handleClient. But it can not valid AutoConnect menu.\u00a0\u21a9

    "},{"location":"changelabel.html","title":"Change label text","text":""},{"location":"changelabel.html#change-the-items-label-text","title":"Change the item's label text","text":"

    You can change the text of AutoConnect menu items. The easiest way is to rewrite the header file directly in the library that defines the menu label. Advanced Usage section describes the detailed how to change the label text directly.

    However, this way is less preferred as it modifies the library code and further affects the entire Arduino project you compile. So, here's how to change the label text for each Arduino project without directly modifying the library code. Using this method, you can also display the label text and fixed text on AutoConnect pages in your national language.

    (e.g. in Japanese)

    "},{"location":"changelabel.html#preparation","title":"Preparation","text":"

    AutoConnect needs a definition file as c++ header (.h) to change the label text. It is used when your Arduino project is compiled, and there is no additional memory consumption due to changing the label text. This header file describes each fixed text of AutoConnect with the #define preprocessor directive.

    The next thing you need is PlatformIO. PlatformIO is a very powerful environment for embedded development with multi-platform and multi-architecture build systems. And you can easily set up a PlatformIO for the Arduino development system as follows on your host machine.

    • Microsoft Visual Studio Code
    • PlatformIO IDE (included PlatformIO core)

    Install PlatformIO and VSCode

    Please refer to the official documentation for PlatformIO and VSCode installation.

    The rest of this section assumes that you have a PlatformIO environment with VSCode as the front end that has installed on your host machine.

    "},{"location":"changelabel.html#how-to-change-the-label-text","title":"How to change the label text","text":""},{"location":"changelabel.html#label-text-replacement-header-file","title":"Label text replacement header file","text":"

    AutoConnect label texts are pre-assigned with a fixed string so that it can be determined at compile time. Their default definitions are in the AutoConnectLabels.h file that has all the replaceable label text defined by the #define directive.

    Label placedPre-defined textID (#define macro) Menu itemConfigure new APAUTOCONNECT_MENULABEL_CONFIGNEW Open SSIDsAUTOCONNECT_MENULABEL_OPENSSIDS DisconnectAUTOCONNECT_MENULABEL_DISCONNECT Reset...AUTOCONNECT_MENULABEL_RESET HOMEAUTOCONNECT_MENULABEL_HOME UpdateAUTOCONNECT_MENULABEL_UPDATE Device infoAUTOCONNECT_MENULABEL_DEVINFO Button labelRESETAUTOCONNECT_BUTTONLABEL_RESET UPDATEAUTOCONNECT_BUTTONLABEL_UPDATE Page titlePage not foundAUTOCONNECT_PAGETITLE_NOTFOUND AutoConnect configAUTOCONNECT_PAGETITLE_CONFIG AutoConnect connectingAUTOCONNECT_PAGETITLE_CONNECTING AutoConnect connection failedAUTOCONNECT_PAGETITLE_CONNECTIONFAILED AutoConnect credentialsAUTOCONNECT_PAGETITLE_CREDENTIALS AutoConnect disconnectedAUTOCONNECT_PAGETITLE_DISCONNECTED AutoConnect resettingAUTOCONNECT_PAGETITLE_RESETTING AutoConnect statisticsAUTOCONNECT_PAGETITLE_STATISTICS Page:[statistics] rowEstablished connectionAUTOCONNECT_PAGESTATS_ESTABLISHEDCONNECTION ModeAUTOCONNECT_PAGESTATS_MODE IPAUTOCONNECT_PAGESTATS_IP GWAUTOCONNECT_PAGESTATS_GATEWAY Subnet maskAUTOCONNECT_PAGESTATS_SUBNETMASK SoftAP IPAUTOCONNECT_PAGESTATS_SOFTAPIP AP MACAUTOCONNECT_PAGESTATS_APMAC STA MACAUTOCONNECT_PAGESTATS_STAMAC ChannelAUTOCONNECT_PAGESTATS_CHANNEL dBmAUTOCONNECT_PAGESTATS_DBM Chip IDAUTOCONNECT_PAGESTATS_CHIPID CPU Freq.AUTOCONNECT_PAGESTATS_CPUFREQ Flash sizeAUTOCONNECT_PAGESTATS_FLASHSIZE Free memoryAUTOCONNECT_PAGESTATS_FREEMEM Page:[config] textTotal:AUTOCONNECT_PAGECONFIG_TOTAL Hidden:AUTOCONNECT_PAGECONFIG_HIDDEN SSIDAUTOCONNECT_PAGECONFIG_SSID PassphraseAUTOCONNECT_PAGECONFIG_PASSPHRASE Enable DHCPAUTOCONNECT_PAGECONFIG_ENABLEDHCP ApplyAUTOCONNECT_PAGECONFIG_APPLY Page:[open SSIDs] textDelete a credential?AUTOCONNECT_TEXT_DELETECREDENTIAL could not deletedAUTOCONNECT_TEXT_COULDNOTDELETED Page:[update] textUpdating firmwareAUTOCONNECT_TEXT_UPDATINGFIRMWARE Select firmware:AUTOCONNECT_TEXT_SELECTFIRMWARE Successfully updated, rebooting...AUTOCONNECT_TEXT_OTASUCCESS Failed to update:AUTOCONNECT_TEXT_OTAFAILURE Page:[connection failed]Connection FailedAUTOCONNECT_PAGECONNECTIONFAILED_CONNECTIONFAILED TextNo saved credentials.AUTOCONNECT_TEXT_NOSAVEDCREDENTIALS Menu TextConnectingAUTOCONNECT_MENUTEXT_CONNECTING DisconnectAUTOCONNECT_MENUTEXT_DISCONNECT FailedAUTOCONNECT_MENUTEXT_FAILED

    The definition of label text must conform to a certain coding pattern. Undefine with #undef the #define directive corresponding to the above IDs, and then redefine the ID with the replacement text. And surround it with #ifdef ~ #endif.

    #ifdef AUTOCONNECT_MENULABEL_CONFIGNEW\n#undef AUTOCONNECT_MENULABEL_CONFIGNEW\n#define AUTOCONNECT_MENULABEL_CONFIGNEW   \"NEW_STRING_YOU_WISH\"\n#endif\n

    You may not need to rewrite all definitions. It depends on your wishes and is sufficient that the above the include file contains only the labels you need.

    "},{"location":"changelabel.html#configuration-of-platformioini","title":"Configuration of platformio.ini","text":"

    You prepare its header file and place it in the src folder of the project folder. You can name the file whatever you like, but for the sake of explanation, let's say mylabels.h.

    When you store mylabels.h containing the new label text definition in the src folder, your Arduino project folder structure should look like this:

    <Project folder>\n|-- <pio>\n|-- <.vscode>\n|-- <include>\n|-- <lib>\n|-- <src>\n|   |-- main.cpp\n|   |-- mylabels.h  <-- Depends on the project\n|-- <test>\n|-- .gitignore\n|-- .travis.yml\n|-- platformio.ini\n

    Then, open platformio.ini file and add new build_flags for including mylabels.h to override the label text.

    build_flags = -DAC_LABELS='\"${PROJECT_SRC_DIR}/mylabels.h\"'\n

    Just change the mylabels.h

    Keep -DAC_LABELS='\"${PROJECT_SRC_DIR}/YOUR_FILE_NAME\"' when changing the above build_flags item to match your labels header file name.

    After placing the mylabels.h file and add the build_flags, build the project with the replaced label text. You will see the AutoConnect screen with the new text replaced by mylabels.h.

    Need clean-up before re-build with updated mylabels.h

    When you have updated mylabels.h, you need deleting compiled library object files before build. Use Clean of a PlatformIO task on VSCode status bar.

    "},{"location":"changelog.html","title":"Change log","text":""},{"location":"changelog.html#142-jan-31-2023","title":"[1.4.2] Jan. 31, 2023","text":""},{"location":"changelog.html#enhancements","title":"Enhancements","text":"
    • Supports whileConnecting exit called while waiting for WiFi connection.
    • Added AutoConnect::portalStatus function.
    "},{"location":"changelog.html#fix","title":"Fix","text":"
    • Fixed compilation error with ESP8266 Arduino Core 3.1.0 or later.
    "},{"location":"changelog.html#141-jan-5-2023","title":"[1.4.1] Jan. 5, 2023","text":""},{"location":"changelog.html#enhancements_1","title":"Enhancements","text":"
    • Supports asynchronous communication of custom web pages using the Fetch API. This allows interaction with the user without page transitions. See the chapter Interact between Sketch and AutoConnectElements for details.
    • Added the FetchLED example.
    • Added an AutoConnect::locate function.
    "},{"location":"changelog.html#fix_1","title":"Fix","text":"
    • Fixed AutoConnectConfigBase constructor missing to AutoConnectConfigExt.
    "},{"location":"changelog.html#140-nov-20-2022","title":"[1.4.0] Nov. 20, 2022","text":""},{"location":"changelog.html#enhancements_2","title":"Enhancements","text":"
    • Custom web page related features were decoupled to allow for two different configurations, AutoConnectCore and AutoConnect. AutoConnectCore reduces memory consumption by focusing only on WiFi connectivity utilities. See Reducing Binary Size chapter in the AutoConnect documentation for more information.
    • Supports credentials backup and restoration.
    • Added an AutoConnect::getCurrentCredential function.
    • Added an AutoConnectAux::referer function.
    • Added an AutoConnectConfig::preserveIP setting.
    • Added the WebSocketServer example.
    • Allow navigate to a custom URL once a WiFi connection is established.
    • Revised mqttRSSI examples program structure.
    "},{"location":"changelog.html#fix_2","title":"Fix","text":"
    • Fixed updateserver.py script security vulnerability.
    "},{"location":"changelog.html#137-aug-20-2022","title":"[1.3.7] Aug. 20, 2022","text":""},{"location":"changelog.html#fix_3","title":"Fix","text":"
    • Fixed an authentication failure in Captive Portal state.
    • Fixed loss of current SSID.
    "},{"location":"changelog.html#136-jul-26-2022","title":"[1.3.6] Jul. 26, 2022","text":""},{"location":"changelog.html#fix_4","title":"Fix","text":"
    • Fixed OTA being incomplete.
    "},{"location":"changelog.html#135-jun-03-2022","title":"[1.3.5] Jun. 03, 2022","text":""},{"location":"changelog.html#fix_5","title":"Fix","text":"
    • Fixed Fixed OTA exit not being called.
    • Fixed an ambiguous type call with IPAddress.
    • Fixed loss of response due to OTA session reset occurrence.
    • Made fit the mqttRSSI examples to ThingSpeak's updated channel authentication.

    For ESP-IDF 4.4 with Arduino ESP32 Core

    AutoConnect 1.3.5 is the version compatible with both ESP-IDF 4.4 and ESP-IDF 3.3. It is recommended to use Arduino esp32 core 1.0.6 for ESP-IDF 3.3 based and Arduino esp32 core 2.0.3 or later for ESP-IDF 4.4 based. If you are using PlatformIO as your development platform, you can select any of these two versions by specifying them in platformio.ini file.

    • For ESP-IDF 4.4 with Arduino ESP32 Core 2.0.3
    framework = arduino\nplatform = espressif32@4.4.0\n
    • For ESO-IDF 3.3 with Arduino ESP32 Core 1.0.6
    framework = arduino\nplatform = espressif32@3.5.0\n
    "},{"location":"changelog.html#134-mar-02-2022","title":"[1.3.4] Mar. 02, 2022","text":""},{"location":"changelog.html#enhancements_3","title":"Enhancements","text":"
    • Supports LittleFS_esp32 legacy library with ESP32 Arduino core 1.0.6 or less.
    • Added enablement of credentials removal function with Open SSIDs menu.
    • Migrate the CI platform to GitHub actions.
    "},{"location":"changelog.html#fix_6","title":"Fix","text":"
    • Fixed AutoConnectOTA crashing if there is no OTA partition.
    • Fixed AutoConnectUpdate crashing if there is no OTA partition.
    "},{"location":"changelog.html#133-jan-25-2022","title":"[1.3.3] Jan. 25, 2022","text":""},{"location":"changelog.html#fix_7","title":"Fix","text":"
    • Fixed the missing initialization of MQTT parameter settings of mqttRSSI.ino example sketch.
    • Reverted the MQTT API endpoint of Thingspeak.com in the mqttRSSI example sketches.
    • Changed ESP32Cam XCLK to be attenuated to avoid interference with WiFi signals.
    "},{"location":"changelog.html#132-jan-1-2022","title":"[1.3.2] Jan. 1, 2022","text":""},{"location":"changelog.html#enhancements_4","title":"Enhancements","text":"
    • Supports an AutoConnectRange as a new AutoConnectElement.
    • Adds the responsive parameter with AutoConnectAux.
    • Adds an AutoConnectAux::redirect function.
    • Adds an example for using AutoConnect with the ESP32 camera driver as WebCamServer.
    "},{"location":"changelog.html#fix_8","title":"Fix","text":"
    • Fixed an issue where a password is lost when SoftAP is stopped.
    "},{"location":"changelog.html#131-oct-09-2021","title":"[1.3.1] Oct. 09, 2021","text":""},{"location":"changelog.html#fixes","title":"Fixes","text":"
    • Fixed an issue that was incompatible with ArduinoJson version 5.
    • Fixed LittleFS mount check not working with ESP32.
    • Fixed autoReconnect not being able to restore a static IP setting.
    • Fixed that static IP settings were not cleared when loading credential.
    "},{"location":"changelog.html#130-sep-25-2021","title":"[1.3.0] Sep. 25, 2021","text":""},{"location":"changelog.html#enhancements_5","title":"Enhancements","text":"
    • Supports ESP8266 3.0.0 Arduino core.
    • Supports ESP32 Arduino core 2.0.0.
    • Supports LittleFS with ESP32.
    • Supports AutoConnectOTA status notifications.
    • Supports AutoConnectConfigAux. (Preview)
    • Supports to save credentials always.
    • Adds a style attribute with AutoConnectInput.
    • Adds the div tag generation with the AutoConnectElement.
    • Adds [] operator with const char for AutoConnectAux.
    • Adds [] operator with __FlashStringHelper for AutoConnectAux.
    • Adds AutoConnectAux::content function to get a number of AutoConnectElements.
    • Adds AutoConnect::getConfig function to get an actual instance of AutoConnectConfig.
    "},{"location":"changelog.html#fixes_1","title":"Fixes","text":"
    • Fixed CSS attribute missing of AutoConnectInput with the number type.
    • Fixed garbage being mixed in a loaded credential.
    • Fixed the output place of Posterior attribute for AutoConnectRadio.
    • Improved the the calculation for the size of ArduinoJson document.
    • Fixed Incomplete deletion with AutoConnectCredential.
    • Fixed credentials not erased correctly.
    • Fixed AutoConnectText posterior being unavailable.
    "},{"location":"changelog.html#123-jan-3-2021","title":"[1.2.3] Jan. 3, 2021","text":""},{"location":"changelog.html#enhancements_6","title":"Enhancements","text":"
    • Improved memory management.

    PageBuilder v1.5.0 is required

    Since AutoConnect v1.2.3, PageBuilder v1.5.0 or later is required. Please update PageBuilder to latest version.

    "},{"location":"changelog.html#122-dec-13-2020","title":"[1.2.2] Dec. 13, 2020","text":""},{"location":"changelog.html#fix_9","title":"Fix","text":"
    • Fixed an issue where OTA updates would crash on the ESP32 platform. (issue #284) With this fix, AUTOCONNECT_UPLOAD_ASFIRMWARE_USE_REGEXP must be enabled for regular expressions to be enabled in AUTOCONNECT_UPLOAD_ASFIRMWARE.
    "},{"location":"changelog.html#121-dec-5-2020","title":"[1.2.1] Dec. 5, 2020","text":""},{"location":"changelog.html#fix_10","title":"Fix","text":"
    • Fixed that not declared error with AUTOCONNECT_NOUSE_JSON. (issue #282)
    "},{"location":"changelog.html#120-dec-3-2020","title":"[1.2.0] Dec. 3, 2020","text":""},{"location":"changelog.html#new-features","title":"New features","text":"
    • Supports a whileCaptivePortal exit. (issue #149, issue #244)
    • Supports an onConnect exit.
    • Supports HTTP authentication. (issue #171)
    "},{"location":"changelog.html#enhancements_7","title":"Enhancements","text":"
    • Added AUTOCONNECT_APKEY_SSID definition to seek access points by SSID. (issue #251)
    • Added AutoConnect::append and AutoConnect::detach function that can be dynamically AutoConnectAux attaching and detaching. (issue #230)
    • Added AutoConnect::getEEPROMUsedSize that notifies the occupied size of the credential storage area. (issue #209)
    • Added AutoConnectConfig::beginTimeout setting. (issue #247)
    • Added AutoConnectConfig::preserveAPMode setting. (issue #210)
    • Enable support for the LittleFS as filesystem with ESP8266 platform.
    • Enhanced AutoConnectInput to allow accepts password and number type. (issue #237, issue #255)
    • Enhanced handleClient to dynamically launch the captive portal when losing WiFi connection.
    • Enhanced the ability to upload a regular file with AutoConnectOTA. (issue #236)
    • Enhanced ticker to work even in handleClient loop.
    • Improved autoReconnect to work even in handleClient loop. (issue #234, issue #251)
    "},{"location":"changelog.html#fixes_2","title":"Fixes","text":"
    • Avoids an empty-body warning when AC_DEBUG is disabled. (issue #218)
    • Fixed a core panic in the regex with ESP32.
    • Fixed an exception in the AutoConnect::end function.
    • Fixed an invalid SPIFFS compile error with ESP32.
    • Fixed deficiently forward references with HandleClient.ino example. (PR #275)
    • Fixed incorrect connection wait time. (issue #216)
    • Fixed not being able to specify channel ID with a mqttRSSI.ino example. (issue #262)
    • Fixed posterior being disabled in AutoConnectElement.
    "},{"location":"changelog.html#117-apr-19-2020","title":"[1.1.7] Apr. 19, 2020","text":""},{"location":"changelog.html#fixes_3","title":"Fixes","text":"
    • Fixed Apply button not work.
    "},{"location":"changelog.html#116-apr-17-2020","title":"[1.1.6] Apr. 17, 2020","text":""},{"location":"changelog.html#fixes_4","title":"Fixes","text":"
    • Fixed OTA page translation not work.
    "},{"location":"changelog.html#115-apr-15-2020","title":"[1.1.5] Apr. 15, 2020","text":""},{"location":"changelog.html#new-features_1","title":"New features","text":"
    • Supports AutoConnect menu configuration.
    • Supports the built-in OTA feature as AutoConnectOTA.
    "},{"location":"changelog.html#enhancements_8","title":"Enhancements","text":"
    • Enhanced allows the AutoConnect::begin to connect to the access point in order of signal strength. This option can specify the order of connection attempting according to the WiFi signal strength indicated with RSSI.
    • Changed the bootUri behavior to be an automatic pop-up at the captive portal.
    "},{"location":"changelog.html#114-feb-14-2020","title":"[1.1.4] Feb. 14, 2020","text":""},{"location":"changelog.html#new-features_2","title":"New features","text":"
    • Supports for overriding text of the menu items with user-defined labels.
    "},{"location":"changelog.html#fixes_5","title":"Fixes","text":"
    • Fixed the compiler warning with experimental WiFi mode of ESP8266.
    "},{"location":"changelog.html#113-jan-1-2020","title":"[1.1.3] Jan. 1, 2020","text":""},{"location":"changelog.html#enhancements_9","title":"Enhancements","text":"
    • Improved Config New button behavior.
    • Added AUTOCONNECT_NOUSE_JSON directive
    "},{"location":"changelog.html#fixes_6","title":"Fixes","text":"
    • Fixed relocate Config New menu URI inability.
    • Removed compiler warning of unused.
    "},{"location":"changelog.html#112-oct-22-2019","title":"[1.1.2] Oct. 22, 2019","text":""},{"location":"changelog.html#fixes_7","title":"Fixes","text":"
    • Fixed a crash when no SSID found.
    • Fixed memory leak on destruction.
    "},{"location":"changelog.html#111-oct-17-2019","title":"[1.1.1] Oct. 17, 2019","text":""},{"location":"changelog.html#fixes_8","title":"Fixes","text":"
    • Fixed crash with unique_ptr deleting reference content.
    • Fixed disconnection request initialization missing.
    "},{"location":"changelog.html#110-oct-15-2019","title":"[1.1.0] Oct. 15, 2019","text":""},{"location":"changelog.html#enhancements_10","title":"Enhancements","text":"
    • Enhanced to be able to specify static IP in the Configure new AP menu.
    "},{"location":"changelog.html#fixes_9","title":"Fixes","text":"
    • Fixed compilation error that no member named 'printTo' with ArduinoJson version 5.
    "},{"location":"changelog.html#103-sept-30-2019","title":"[1.0.3] Sept. 30, 2019","text":""},{"location":"changelog.html#fixes_10","title":"Fixes","text":"
    • Fixed a return of AutoConnectCredential::entries().
    "},{"location":"changelog.html#102-sept-19-2019","title":"[1.0.2] Sept. 19, 2019","text":""},{"location":"changelog.html#fixes_11","title":"Fixes","text":"
    • Fixed compilation error that no member named 'success' with ArduinoJson version 5.
    • Fixed SSID non termination.
    • Fixed compilation error that getBytesLength missing with ESP32.
    • Added #include directive restriction for EEPROM and ESP8266httpUpdate to FAQ.
    "},{"location":"changelog.html#101-sept-13-2019","title":"[1.0.1] Sept. 13, 2019","text":""},{"location":"changelog.html#enhancements_11","title":"Enhancements","text":"
    • Added an example sketch for ESP32 boards that migrates credentials stored in EEPROM partition to the Preferences.
    "},{"location":"changelog.html#100-sept-7-2019","title":"[1.0.0] Sept. 7, 2019","text":""},{"location":"changelog.html#new-features_3","title":"New features","text":"
    • Supports AutoConnectUpdate for the OTA update.
    "},{"location":"changelog.html#enhancements_12","title":"Enhancements","text":"
    • Supported Arduino core for ESP32 1.0.3.
    • Added AutoConnectAux::isValid function.
    • Added the global attribute with all AutoConnectElements.
    • Changed the credential storage area to Preferences with ESP32 core 1.0.3 and later. In ESP32, the credentials stored past in EEPROM will lose.
    "},{"location":"changelog.html#0912-aug-18-2019","title":"[0.9.12] Aug. 18, 2019","text":""},{"location":"changelog.html#fixes_12","title":"Fixes","text":"
    • 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.
    "},{"location":"changelog.html#0911-july-13-2019","title":"[0.9.11] July 13, 2019","text":""},{"location":"changelog.html#new-features_4","title":"New features","text":"
    • Supports new element as AutoConnectSytle that can insert the custom CSS into AutoConnectAux page.
    "},{"location":"changelog.html#enhancements_13","title":"Enhancements","text":"
    • Supports that <br> tags can now be added to each element.
    • Supports that able to place the checkbox label forward or backward.
    • Supports flicker signal output according to the status of WiFi_mode.
    • Supports AutoConnectAux::fetchElement function to retrieve inputted element values via a custom Web page.
    "},{"location":"changelog.html#fixes_13","title":"Fixes","text":"
    • Fixed bug in AutoConnectCredential when offset is >256.
    "},{"location":"changelog.html#0910-june-12-2019","title":"[0.9.10] June 12, 2019","text":""},{"location":"changelog.html#fixes_14","title":"Fixes","text":"
    • Fixed the unable to get AutoConnectElemets values in the sketch with ESP8266 arduino core 2.5.2.
    "},{"location":"changelog.html#099-may-25-2019","title":"[0.9.9] May 25, 2019","text":""},{"location":"changelog.html#enhancements_14","title":"Enhancements","text":"
    • Supports ESP8266 Arduino core 2.5.2.
    • Menu text/background color can be statically customized.
    • Added the enable attribute to the AutoConnectElements. This attribute gives dynamically change to the element activation during the sketch executing.
    • Added ID attribute to HTML tag generated from AutoConnectText.
    "},{"location":"changelog.html#fixes_15","title":"Fixes","text":"
    • Fixed the input box layout collapsed.
    • Fixed that the decoration of AutoConnectButton was disabled.
    • Fixed that the value remains even after clearing the option with AutoConnectSelect.
    • Fixed that an alignment violation exception occurred when loading AutoConnectAux described by JSON with PROGMEM attribute.
    "},{"location":"changelog.html#098-may-3-2019","title":"[0.9.8] May 3, 2019","text":""},{"location":"changelog.html#new-features_5","title":"New features","text":"
    • Supports new element type AutoConnectFile and built-in file uploader.
    "},{"location":"changelog.html#enhancements_15","title":"Enhancements","text":"
    • Enhanced to support ArduinoJson 6.9.1 or later.
    • Enhanced to use PSRAM on ESP32 module as the buffer allocation destination of JsonDocument with ArduinoJson 6.10.0 or later.
    • Added an operator[] as a shortcut for AutoConnectAux::getElement function.
    • Added an AutoConnectElement::as<T> function to easily coding for conversion from an AutoConnectElement to an actual type.
    • Added a format attribute with the AutoConnectText element.
    • Added a selected attribute with the AutoConnectSelect element.
    • Enhanced AutoConnectAux::loadElement with multiple elements loading.
    • Changed menu labels placement in source files structure.
    • Changed API interface of AutoConnect::where function.
    "},{"location":"changelog.html#fixes_16","title":"Fixes","text":"
    • Fixed blank page responds with Configure new.
    • Fixed loading elements value missing.
    • Fixed losing elements in saveElement with ArduinoJson version 6.
    • Fixed compile error with older than ESP8266 core 2.5.0.
    "},{"location":"changelog.html#097-jan-25-2019","title":"[0.9.7] Jan. 25, 2019","text":""},{"location":"changelog.html#new-features_6","title":"New features","text":"
    • Supports AutoConnect menu extension by user sketch with AutoConnectAux.
    • Supports loading and saving of user-defined parameters with JSON format.
    "},{"location":"changelog.html#enhancements_16","title":"Enhancements","text":"
    • Improved the WiFi connection sequence at the first WiFi.begin. Even if AutoConnectConfig::autoReconnect is disabled when SSID and PSK are not specified, it will use the information of the last established access point. The autoReconnect option will achieve trying the connect after a previous connection failed.
    • Added the AutoConnectConfig::immediateStart option and immediately starts the portal without first trying WiFi.begin. You can start the captive portal at any time in combination with the AutoConnectConfig::autoRise option.
    • Improved boot uri after reset. AutoConnectConfig::bootUri can be specified either /_ac or HOME path as the uri to be accessed after invoking Reset from AutoConnect menu.
    • Improved source code placement of predefined macros. Defined common macros have been moved to AutoConnectDefs.h.
    • Added AutoConnectConfig::hostName. It activates WiFi.hostname()/WiFi.setHostName().
    • Added the captive portal time-out. It can be controlled by AutoConnectConfig::portalTimeout and AutoConnectConfig::retainPortal.
    "},{"location":"changelog.html#fixes_17","title":"Fixes","text":"
    • Fixed crash in some environments. Thank you @ageurtse
    "},{"location":"changelog.html#096-sept27-2018","title":"[0.9.6] Sept.27, 2018.","text":""},{"location":"changelog.html#enhancements_17","title":"Enhancements","text":"
    • Improvement of RSSI detection for saved SSIDs.
    "},{"location":"changelog.html#fixes_18","title":"Fixes","text":"
    • Fixed disconnection SoftAP completely at the first connection phase of the AutoConnect::begin.
    "},{"location":"changelog.html#095-aug27-2018","title":"[0.9.5] Aug.27, 2018.","text":""},{"location":"changelog.html#enhancements_18","title":"Enhancements","text":"
    • Supports ESP32.
    "},{"location":"changelog.html#fixes_19","title":"Fixes","text":"
    • Fixed that crash may occur if the number of stored credentials in the EEPROM is smaller than the number of found WiFi networks.
    "},{"location":"changelog.html#094-may-5-2018","title":"[0.9.4] May 5, 2018.","text":""},{"location":"changelog.html#new-features_7","title":"New features","text":"
    • Supports AutoConnectConfig::autoReconnect option, it will scan the WLAN when it can not connect to the default SSID, apply the applicable credentials if it is saved, and try reconnecting.
    "},{"location":"changelog.html#enhancements_19","title":"Enhancements","text":"
    • Automatically focus Passphrase after selecting SSID with Configure New AP.
    "},{"location":"changelog.html#093-march-23-2018","title":"[0.9.3] March 23, 2018.","text":""},{"location":"changelog.html#enhancements_20","title":"Enhancements","text":"
    • Supports a static IP address assignment.
    "},{"location":"changelog.html#092-march-19-2018","title":"[0.9.2] March 19, 2018.","text":""},{"location":"changelog.html#enhancements_21","title":"Enhancements","text":"
    • Improvement of string literal declaration with the examples, no library change.
    "},{"location":"changelog.html#091-march-13-2018","title":"[0.9.1] March 13, 2018.","text":"
    • A release of the stable.
    "},{"location":"colorized.html","title":"Custom colorized","text":""},{"location":"colorized.html#autoconnect-menu-colorizing","title":"AutoConnect menu colorizing","text":"

    You can easily change the color of the AutoConnect menu. Menu colors can be changed statically by the AutoConnect menu color definition determined at compile time. You cannot change the color while the Sketch is running.

    The menu color scheme has been separated to AutoConnectLabels.h placed the AutoConnect library folder.1 You can change the color scheme of the menu with the following three color codes. The color code also accepts CSS standard color names.2

    In AutoConnectLabels.h you can find three definition macros for menu colors:

    • #define AUTOCONNECT_MENUCOLOR_TEXT Defines the menu text color.

    • #define AUTOCONNECT_MENUCOLOR_BACKGROUND Defines the menu background color.

    • #define AUTOCONNECT_MENUCOLOR_ACTIVE Defines the active menu item background color.

    "},{"location":"colorized.html#typical-color-schemes","title":"Typical color schemes","text":"

    Here are some color schemes picked up.

    "},{"location":"colorized.html#indigo","title":"Indigo","text":"
    #define AUTOCONNECT_MENUCOLOR_TEXT        \"#ffa500\"\n#define AUTOCONNECT_MENUCOLOR_BACKGROUND  \"#1a237e\"\n#define AUTOCONNECT_MENUCOLOR_ACTIVE      \"#283593\"\n
    "},{"location":"colorized.html#dim-gray","title":"Dim-gray","text":"
    #define AUTOCONNECT_MENUCOLOR_TEXT        \"#fffacd\"\n#define AUTOCONNECT_MENUCOLOR_BACKGROUND  \"#696969\"\n#define AUTOCONNECT_MENUCOLOR_ACTIVE      \"#808080\"\n
    "},{"location":"colorized.html#brown","title":"Brown","text":"
    #define AUTOCONNECT_MENUCOLOR_TEXT        \"#e6e6fa\"\n#define AUTOCONNECT_MENUCOLOR_BACKGROUND  \"#3e2723\"\n#define AUTOCONNECT_MENUCOLOR_ACTIVE      \"#4e342e\"\n

    1. Usually, it will locate to the Arduino/libraries/AutoConnect/src folder of user documents.\u00a0\u21a9

    2. The W3C HTML and CSS standards have listed only 16 valid color names: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, and yellow. Major browsers can accept more color names, but they are not web safe in typically.\u00a0\u21a9

    "},{"location":"credit.html","title":"Saved credentials access","text":""},{"location":"credit.html#saved-credentials-in-the-flash","title":"Saved credentials in the flash","text":"

    AutoConnect stores the credentials of 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 the AutoConnectCredential, which provides the way of access to the credentials stored in flash.1

    "},{"location":"credit.html#credentials-storage-location","title":"Credentials storage location","text":"

    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 nvs2) are used depending on the library versions.

    AutoConnect Arduino corefor ESP8266 Arduino core for ESP32 1.0.2 earlier 1.0.3 later v0.9.12 earlier EEPROM EEPROM (partition) Not supported v1.0.0 later Preferences (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 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_PREFERENCES3 macro definition in AutoConnectCredentials.h file. AutoConnect behaves assuming that credentials are stored in EEPROM if AUTOCONNECT_USE_PREFERENCES is not defined.

    "},{"location":"credit.html#autoconnectcredential","title":"AutoConnectCredential","text":""},{"location":"credit.html#include-header","title":"Include header","text":"
    #include <AutoConnectCredential.h>\n
    "},{"location":"credit.html#constructors","title":"Constructors","text":"
    AutoConnectCredential();\n

    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.

    AutoConnectCredential(uint16_t offset);\n
    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. This parameter is ignored for AutoConnect v1.0.0 or later with arduino-esp32 core 1.0.3 or later."},{"location":"credit.html#public-member-functions","title":"Public member functions","text":""},{"location":"credit.html#backup","title":"backup","text":"
    bool backup(Stream& out)\n

    Outputs all credentials currently stored by AutoConnect to the stream. Parameter outOutput destination stream. Return value trueAll credentials were successfully output. falseFailed to output.

    "},{"location":"credit.html#del","title":"del","text":"
    bool del(const char* ssid)\n

    Delete a credential the specified SSID. Parameter ssidSSID to be deleted. Return value trueSuccessfully deleted. falseFailed to delete.

    Clear saved credentials

    There is no particular API for batch clearing of all credential data stored by AutoConnect. It is necessary to prepare a sketch function that combines several AutoConnectCredential APIs to erase all saved credentials. The following function is an implementation example, and you can use it to achieve batch clearing.

    void deleteAllCredentials(void) {\n  AutoConnectCredential credential;\n  station_config_t config;\nuint8_t ent = credential.entries();\n\nwhile (ent--) {\n    credential.load(0, &config);\n    credential.del((const char*)&config.ssid[0]);\n  }\n}\n
    "},{"location":"credit.html#entries","title":"entries","text":"
    uint8_t entries(void)\n

    Returns number of entries as contained credentials. Return value Number of entries as contained credentials.

    "},{"location":"credit.html#load","title":"load","text":"
    int8_t load(const char* ssid, station_config_t* config)\n

    Load a credential entry and store to config. Parameters ssidSSID to be loaded. configstation_config_t Return value Save the specified SSID's credential entry to station_config_t pointed to by the parameter as config. -1 is returned if the SSID is not saved.

    "},{"location":"credit.html#load_1","title":"load","text":"
    bool load(int8_t entry, station_config_t* config)\n

    Load a credential entry and store to config. Parameters entrySpecifies the index number based 0 to be loaded. configstation_config_t Return value Save the specified credential entry to station_config_t pointed to by the parameter as config. -1 is returned if specified number is not saved.

    "},{"location":"credit.html#restore","title":"restore","text":"
    bool restore(Stream& in)\n

    The credentials data saved by the backup function is input from Storm and saved as AutoConnect credentials. Parameter inAn input stream of a file containing credential data saved with the backup function. Return value trueCredentials successfully restored. falseFailed to restore.

    "},{"location":"credit.html#save","title":"save","text":"
    bool save(const station_config_t* config)\n

    Save a credential entry. Parameter configstation_config_t to be saved. Return value trueSuccessfully saved. falseFailed to save.

    "},{"location":"credit.html#the-data-structures","title":"The data structures","text":""},{"location":"credit.html#station_config_t","title":"station_config_t","text":"

    The saved credential structure is defined as station_config_t in the AcutoConnectCredential header file.

    typedef struct {\nuint8_t ssid[32];\nuint8_t password[64];\nuint8_t bssid[6];\nuint8_t dhcp;   /**< 0:DHCP, 1:Static IP */\nunion _config {\nuint32_t  addr[5];\nstruct _sta {\nuint32_t ip;\nuint32_t gateway;\nuint32_t netmask;\nuint32_t dns1;\nuint32_t dns2;\n    } sta;\n  } config;\n} station_config_t;\n

    The byte size of station_config_t in program memory and stored credentials is different

    There is a gap byte for boundary alignment between the dhcp member and the static IP members of the above station_config_t. Its gap byte will be removed with saved credentials on the flash.

    "},{"location":"credit.html#the-credential-entry","title":"The credential entry","text":"

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

    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 1 Flag for DHCP or Static IP (0:DHCP, 1:Static IP) The following IP address entries are stored only for static IPs. variable(1) 4 Station IP address (uint32_t) variable(5) 4 Gateway address (uint32_t) variable(9) 4 Netmask (uint32_t) variable(13) 4 Primary DNS address (uint32_t) variable(17) 4 Secondary DNS address (uint32_t) variable variable Contained the next entries. (Continuation SSID+Password+BSSID+DHCP flag+Static IPs(if exists)) variable 1 0x00. End of container.

    AutoConnectCredential has changed

    It was lost AutoConnectCredential backward compatibility. Credentials saved by AutoConnect v1.0.3 (or earlier) will not work properly with AutoConnect v1.1.0. You need to erase the flash of the ESP module using the esptool before the sketch uploading. 

    esptool -c esp8266 (or esp32) -p [COM_PORT] erase_flash\n

    1. An example using AutoConnectCredential is provided as an example of a library sketch to delete saved credentials.\u00a0\u21a9

    2. The namespace for Preferences used by AutoConnect is AC_CREDT.\u00a0\u21a9

    3. Available only for AutoConnect v1.0.0 and later.\u00a0\u21a9

    4. There may be 0xff as an invalid data in the credential saving area. The 0xff area would be reused.\u00a0\u21a9

    "},{"location":"datatips.html","title":"Tips for data conversion","text":""},{"location":"datatips.html#convert-autoconnectelements-value-to-actual-data-type","title":"Convert AutoConnectElements value to actual data type","text":"

    The values in the AutoConnectElements field of the custom Web page are all typed as String. A sketch needs to be converted to an actual data type if the data type required for sketch processing is not a String type.

    The AutoConnect library does not provide the data conversion utility, and its function depends on Arduino language functions or functions of the type class. However, commonly used data conversion methods are generally similar.

    Here, represent examples the typical method for the data type conversion for the AutoConnectElements value of custom Web pages.

    "},{"location":"datatips.html#integer","title":"Integer","text":"

    Use int() or toInt() of String.

    AutoConnectInput& input = aux.getElement<AutoConnectInput>(\"INPUT\");\nint value = input.value.toInt();\n
    You can shorten it and write as like: 
    int value = aux[\"INPUT\"].value.toInt();\n

    "},{"location":"datatips.html#float","title":"Float","text":"

    Use float() or toFloat() of String.

    AutoConnectInput& input = aux.getElement<AutoConnectInput>(\"INPUT\");\nfloat value = input.value.toFloat();\n
    You can shorten it and write as like: 
    float value = aux[\"INPUT\"].value.toFloat();\n

    "},{"location":"datatips.html#date-time","title":"Date & Time","text":"

    The easiest way is to use the Arduino Time Library. Sketches must accommodate differences in date and time formats depending on the time zone. You can absorb the difference in DateTime format by using sscanf function.1

    #include <TimeLib.h>\n\ntime_t tm;\nint Year, Month, Day, Hour, Minute, Second;\n\nAutoConnectInput& input = aux.[\"INPUT\"].as<AutoConnectInput>();\nsscanf(input.value.c_str(), \"%d-%d-%d %d:%d:%d\", &Year, &Month, &Day, &Hour, &Minute, &Second);\ntm.Year = CalendarYrToTm(Year);\ntm.Month = Month;\ntm.Day = Day;\ntm.Hour = Hour;\ntm.Minute = Minute;\ntm.Second = Second;\n
    "},{"location":"datatips.html#ip-address","title":"IP address","text":"

    To convert a String to an IP address, use IPAddress::fromString. To stringize an instance of an IP address, use IPAddress::toString.

    IPAddress ip;\nAutoConnectInput& input aux[\"INPUT\"].as<AutoConnectInput>();\nip.fromString(input.value);\ninput.value = ip.toString();\n
    "},{"location":"datatips.html#validation-for-the-value","title":"Validation for the value","text":"

    To convert input data correctly from the string, it must match its format. The validation implementation with sketches depends on various perspectives. Usually, the tiny devices have no enough power for the lexical analysis completely. But you can reduce the burden for data verification using the pattern of AutoConnectInput.

    By giving a pattern to AutoConnectInput, you can find errors in data format while typing in custom Web pages. Specifying the input data rule as a regular expression will validate the type match during input. If there is an error in the format during input, the background color of the field will change to pink. Refer to section Handling the custom Web pages.

    However, input data will be transmitted even if the value does not match the pattern. Sketches require the validation of the received data. You can use the AutoConnectInput::isValid function to validate it. The isValid function validates whether the value member variable matches a pattern and returns true or false.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char input_page[] PROGMEM = R\"raw(\n[\n  {\n    \"title\": \"IP Address\",\n    \"uri\": \"/\",\n    \"menu\": true,\n    \"element\": [\n      {\n        \"name\": \"ipaddress\",\n        \"type\": \"ACInput\",\n        \"label\": \"IP Address\",\n        \"pattern\": \"^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$\"\n      },\n      {\n        \"name\": \"send\",\n        \"type\": \"ACSubmit\",\n        \"value\": \"SEND\",\n        \"uri\": \"/check\"\n      }\n    ]\n  },\n  {\n    \"title\": \"IP Address\",\n    \"uri\": \"/check\",\n    \"menu\": false,\n    \"element\": [\n      {\n        \"name\": \"result\",\n        \"type\": \"ACText\"\n      }\n    ]\n  }\n]\n)raw\";\n\nAutoConnect portal;\n\nString checkIPAddress(AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectAux&   input_page = *portal.aux(\"/\");\n  AutoConnectInput& ipaddress = input_page[\"ipaddress\"].as<AutoConnectInput>();\n  AutoConnectText&  result = aux[\"result\"].as<AutoConnectText>();\n\nif (ipaddress.isValid()) {\n    result.value = \"IP Address \" + ipaddress.value + \" is OK.\";\n    result.style = \"\";\n  }\nelse {\n    result.value = \"IP Address \" + ipaddress.value + \" error.\";\n    result.style = \"color:red;\";\n  }\nreturn String(\"\");\n}\n\nvoid setup() {\n  portal.load(input_page);\n  portal.on(\"/check\", checkIPAddress);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    Regular Expressions for JavaScript

    Regular expressions specified in the AutoConnectInput pattern conforms to the JavaScript specification.

    Here, represent examples the typical regular expression for the input validation.

    "},{"location":"datatips.html#url","title":"URL","text":"
    ^\\w+([-+.]\\w+)*@\\w+([-.]\\w+)*\\.\\w+([-.]\\w+)*$\n
    "},{"location":"datatips.html#dns-hostname","title":"DNS hostname","text":"
    ^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\-]*[A-Za-z0-9])$\n
    "},{"location":"datatips.html#email-address-2","title":"email address 2","text":"
    ^[a-zA-Z0-9.!#$%&'*+\\/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*$\n
    "},{"location":"datatips.html#ip-address_1","title":"IP Address","text":"
    ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$\n
    "},{"location":"datatips.html#date-as-mmddyyyy-3","title":"Date as MM/DD/YYYY 3","text":"
    ^(0[1-9]|1[012])[- \\/.](0[1-9]|[12][0-9]|3[01])[- \\/.](19|20)\\d\\d$\n

    Contain with backquote

    If that regular expression contains a backquote it must be escaped by backquote duplication.

    1. The ssanf library function cannot be used with the old Arduino core.\u00a0\u21a9

    2. This regular expression does not fully support the format of the e-mail address requested in RFC5322.\u00a0\u21a9

    3. This regular expression does not consider semantic constraints. It is not possible to detect errors that do not exist as actual dates.\u00a0\u21a9

    "},{"location":"esp32cam.html","title":"Works with ESP32-CAM","text":""},{"location":"esp32cam.html#what-this-example-presents","title":"What this example presents","text":"

    ESP-IDF is offering ESP32 Camera Driver as an interface to small image sensors that can work with ESP32. This driver supports a variety of popular image sensors, such as the OV2640, which has low power consumption and mega-pixel sensing capability. By reading through this chapter you will know how to make the sketch featuring a UI that looks like the followings. Of course, it has the convenience of AutoConnect as well. This example shows how to sketch the Web Camera Application that involves using AutoConnect together with the ESP32 Camera Driver.

    "},{"location":"esp32cam.html#why-we-can-not-use-app_httpdcpp-together-with-autoconnect","title":"Why we can not use app_httpd.cpp together with AutoConnect","text":"

    The ESP32 library of the ESP32 Arduino core features a CameraWebServer.ino that includes an interface to drive the Camera Driver. The core process of the server-side of that sketch application is app_httpd.cpp, which consists of initializing and configuring the image sensor, configuring and capturing image frames, and sending the image frames through an internally started HTTP server.

    While Web UI provided by CameraWebServer.ino is sophisticated, the role of app_httpd.cpp is focused on responding to the Fetch required by the Web UI (which is actually an HTML page specific to each sensor model that is extracted from the gzipped camera_index.h). It is a set of primitive functions that are integrated with the Web UI. Also, app_httpd.cpp has hardcoded the TCP port of the internally invoking HTTP server as fixed at 80, which conflicts with the HTTP port used by a typical captive portal. Therefore, It is impossible to apply app_httpd.cpp which has fixed 80 TCP port depending on the WebUI of CameraWebServer.ino to sketches using AutoConnect as it is.

    CameraWebServer.ino extended version available on GitHub

    An extended version of app_httpd.cpp is available on the GitHub repository to make it a bit more flexible for different usage scenarios. It also can handling the captive portal itself.

    "},{"location":"esp32cam.html#strategy","title":"Strategy","text":"

    As mentioned earlier, app_httpd.cpp is integrated with CameraWebServer.ino's Web UI. However, its functionality can be separated into two parts: an interface for driving the image sensor correctly and sending the captured images on the HTTP stream as requested by the client. It also has the ability to configure the sensor settings over the network remotely, but this can be omitted at the expense of interactivity. (We can implement that feature after the initial purpose is achieved)

    So, I have prepared two separate classes with these functions. ESP32WebCam and ESP32Cam are independent classes inspired by app-httpd.cpp, and they can interface with the ESP32 Camera Driver individually, or send out motion JPEGs via an HTTP server task running inside the class.

    These two classes are completely independent of the AutoConnect library and can be incorporated into your various other sketches on their own. the source code for the ESP32WebCam and ESP32Cam classes can be found in the AutoConnect library examples and are distributed together. The API specifications for these two classes are described later in this chapter.

    "},{"location":"esp32cam.html#implementing-a-streaming-server-with-esp32-cam-using-autoconnect","title":"Implementing a Streaming Server with ESP32-CAM using AutoConnect","text":"

    A minimal sketch that involves the ESP32WebCam and ESP32Cam classes and incorporates them together with AutoConnect is shown below. This sketch will work with Ai-Thinker ESP32-CAM, which is one of the most popular ESP32 modules with OmniVision OV2640 image sensor.

    In order to experience this sketch, copy the five files ESP32WebCam.h, ESP32WebCam.cpp, ESP32Cam.h, ESP32Cam.cpp, and ESP32Cam_pins.h from the WebCamServer folder located AutoConnect library examples to the same folder as the sketchbook folder where you placed this sketch. Connect the ESP32-CAM module to your PC and launch the Arduino IDE. Then select the correct board you using from the Tool menu of Arduino IDE and compile it. (Don't forget to open the serial monitor)

    #include <Arduino.h>\n#include <WiFi.h>\n#include <WebServer.h>\n#include <AutoConnect.h>\n#include \"ESP32WebCam.h\"\n\nconst char  CAMERA_VIEWER[] = R\"*(\n{\n  \"title\": \"Camera\",\n  \"uri\": \"/\",\n  \"menu\": false,\n  \"element\": [\n    {\n      \"name\": \"viewport\",\n      \"type\": \"ACText\",\n      \"format\": \"<img src='http://%s'>\",\n      \"posterior\": \"none\"\n    },\n    {\n      \"name\": \"discon\",\n      \"type\": \"ACElement\",\n      \"value\": \"<script>window.addEventListener('pagehide',function(){window.stop();});</script>\"\n    }\n  ]\n}\n)*\";\n\n// Declare ESP32-CAM handling interface. It contains ESP-IDF Web Server.\nESP32WebCam webcam(ESP32Cam::CAMERA_MODEL_AI_THINKER);\n\n// AutoConnect portal. It contains the WebServer from ESP32 Arduino Core.\nAutoConnect portal;\nAutoConnectConfig config;\n\n// AutoConnectAux page handler, it starts streaming by adding the ESP32WebCam\n// streaming endpoint to the src attribute of the img tag on the AutoConnectAux page.\nString viewer(AutoConnectAux& aux, PageArgument &args) {\n  AutoConnectAux& viewer = *portal.aux(\"/\");\n// Set the Streaming server host, port, and endpoint\n  viewer[\"viewport\"].value = WiFi.localIP().toString() + \":\" + String(webcam.getServerPort())\n+ String(webcam.getStreamPath());\nreturn String();\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n// Start Image sensor\nif (webcam.sensorInit() != ESP_OK) {\n    Serial.println(\"Camera initialize failed\");\n  }\n\n// Allow automatic re-connection as long as the WiFi connection is established.\n  config.autoReconnect = true;\n  config.reconnectInterval = 1;\n  portal.config(config);\n\n// Start the portal, it will launch the WebServer for the portal from inside of AutoConnect.\nif (portal.begin()) {\n    portal.load(CAMERA_VIEWER);\n    portal.on(\"/\", viewer);\n// Start ESP32 Camera Web Server\nif (webcam.startCameraServer() == ESP_OK) {\n      Serial.printf(\"ESP32WebCam server %s port %u ready\\n\", WiFi.localIP().toString().c_str(),\n        webcam.getServerPort());\n    }\nelse {\n      Serial.println(\"ESP32WebCam server start failed\");\n    }\n  }\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    If your ESP32-CAM module still has no connection with any access point, a captive portal will open. Use your cellphone to connect the ESP32-CAM to the access point. When ESP32-CAM successfully connects to the access point, you will see the IP address on the serial monitor. You visit the IP address from your browser, you can see the image captured by the ESP32-CAM.

    Streaming stops caused by ERR_CONNECTION_RESET

    Sometimes the browser will throw the above error and the streaming will stop. In the simple sketch above, which does not include the transmission error recovery process, the TCP packet transmission is incomplete due to a weak WiFi signal or other reasons, and the browser will stop loading the image. Send errors can be recovered by incorporating an event handler into the img tag, and an example of its implementation is shown later in this chapter.

    "},{"location":"esp32cam.html#program-structure","title":"Program structure","text":"

    The sketch of AutoConnect using ESP32WebCam and ESP32Cam classes is divided into several components, which will take a similar form in any sketch application. Their logical components are as follows:

    1. Include ESP32WebCam.h header file. 

      #include \"ESP32WebCam.h\"\n

    2. AutoConnectAux defines a custom web page in JSON description. It includes an img tag that displays the captured image. The src attribute of the img tag is not hard-coded and can be dynamically set in a custom web page handler to make the sketch more applicable to various situations. 

      {\n\"name\": \"viewport\",\n\"type\": \"ACText\",\n\"format\": \"<img src='http://%s'>\",\n\"posterior\": \"none\"\n}\n

    3. Insert AutoConnectElement in the JSON description of your custom web page with JavaScript enclosed in <script>~</script> in HTML to stop streaming on page transition. 

      window.addEventListener('pagehide', function () {\n  window.stop();\n});\n

      Why window.stop() is needed

      That's because image streaming is achieved by continuous loading of Motion JPEG using HTTP multipart/x-mixed-replace keep-alive stream. With this type of MIME content, the server will continue to push the content unless the client explicitly notifies the server of the end of the session. The method of notifying the end of the session varies depending on the client browser, and by issuing window.stop(), the difference in the behavior of each browser is absorbed.

    4. Declare ESP32WebCam instance. It accompanies the parameters with the appropriate model specifiers. 

      ESP32WebCam webcam(ESP32Cam::CAMERA_MODEL_AI_THINKER);\n
      For details on identifiers that can be specified as image sensor models, please refer to the APIs described below.

    5. Declare AutoConnect instance. If your sketch requires a native web page that is not an AutoConnectAux, you can declare a WebServer instance at the same place to make it easier to call from functions in your sketch. 

      AutoConnect portal;\n

    6. Declare AutoConnectConfig to control WiFi connection behavior if necessary. 

      AutoConnectConfig config;\n

    7. Prepare an AutoConnectAux custom page handler for the declared above AutoConnectAux JSON. Typically, this handler is responsible for handling the ESP32Cam class via the endpoint interface provided by the ESP32Cam class. In the above sketch, we have only given the endpoint (i.e. http://{WiFi.localIP}:3000/_stream) for streaming by the ESP32WebCam class as the src attribute of the img tag identified id=viewport, since we are focusing on the minimum necessary processing. ESP32WebCam class will deliver the captured image with just this operation. 

      AutoConnectAux& viewer = *portal.aux(\"/\");\nviewer[\"viewport\"].value = WiFi.localIP().toString() + \":\" + String(webcam.getServerPort())\n+ String(webcam.getStreamPath());\n
      For more information about ESP32Cam capability and ESP32WebCam endpoints, please refer to the Endpoint interfaces described below.

      Using AutoConnectText with format string

      In the sketch above, the format attribute of AutoConnectText is used to set the src attribute of the img tag. The AutoConnectText format attribute produces the same output as a C-style printf(format, value), depending on the string that can be derived from the value. 

      printf(\"<img src='http://%s'>\", \"localhost:3000/_stream\");\n

    8. Start the sketch and initialize the camera using ESP32WebCam::sensorInit. ESP_OK will returned on success to initialize the image sensor. 

      ESP32WebCam webcam(ESP32Cam::CAMERA_MODEL_AI_THINKER);\n\nif (webcam.sensorInit() != ESP_OK) {\n  Serial.println(\"Camera initialize failed\");\n}\n

    9. Configure WiFi state control to maintain connection. Usually, AutoConnectConfig::autoReconnect will keep WiFi connection stateful. 

      config.autoReconnect = true;\nconfig.reconnectInterval = 1;\nportal.config(config);\n

    10. Start the portal, and load the view page. 

      portal.begin();\nportal.load(CAMERA_VIEWER);\n

    11. Register the view page handler and start the streaming server using ESP32WebCam::startCameraServer. ESP_OK will returned on start the streaming server successfully. 

      portal.on(\"/\", viewer);\nif (webcam.startCameraServer() == ESP_OK) {\n  Serial.printf(\"ESP32WebCam server ready: %s\\n\", WiFi.localIP().toString().c_str());\n}\nelse {\n  Serial.println(\"ESP32WebCam server start failed\");\n}\n

    12. Loop for portal.handleClient().

    The app_httpd.cpp, which is the core of CameraWebServer.ino's functionality, has a mixture of an interface with the ESP32 Camera Driver and remote control over the network via an HTTP server. While it is highly functional, but it will cause a decline in versatility. ESP32WebCam and ESP32Cam separate the mixed functionality of app_httpd.cpp into two classes, each with a single role. This makes them versatile and simple to use. And they can coexist with AutoConnect.

    If you only need to stream from the image sensor, you can simplify the sketch structure as in the example above. The simplicity of the sketch is mainly due to the usefulness of the ESP32WebCam and ESP32Cam classes. In driving the ESP32 Camera Driver on the ESP32-CAM module, the sketch interfaces with the ESP32WebCam class and processes the ESP32Cam class through the ESP32WebCam endpoint interface.

    "},{"location":"esp32cam.html#esp32webcam-class-and-esp32cam-class","title":"ESP32WebCam Class and ESP32Cam Class","text":"

    The ESP32WebCam class has an endpoint interface to allow the sketch to manipulate the image sensor over the network. The sketch can use HTTP GET method to capture images, stream the captured images, and save them to SD card. It also starts its own HTTP server task internally, and this HTTP server runs as a separate task from the WebServer hosted by AutoConnect.

    The ESP32Cam class is a wrapper that governs the native interface with the ESP32 Camera Driver which is a component of ESP-IDF. It can initialize the sensor, set the sensor characteristics, save and load the settings, and save the captured images to the SD card.

    In the case of accessing image sensors located across a network, the sketch will usually have a UI to remotely control the ESP32-CAM. If the UI is intended to be a web interface, the sketch will use a request handler that is compatible with the ESP32 WebServer hosted by AutoConnect to serve the manipulation web page. That page can be an AutoConnectAux-based custom web page, or it can be the RequestHanlder callback that can respond to the ESP32 WebServer class. In any case, those UI pages can remotely access the image sensor of the ESP32-CAM module through the HTTP endpoint interface deployed at a specific URL of the HTTP server launched by the ESP32WebCam class, and do the required processing.

    "},{"location":"esp32cam.html#esp32webcam-features","title":"ESP32WebCam features:","text":"
    • Run the HTTP server as a background task.
    • Stream Motion JPEG via HTTP multipart/x-mixed-replace MIME.
    • Serves a captured image via HTTP.
    • Instruct the ESP32Cam to save the captured image to the SD card via HTTP.

    Of these processing requests, the ESP32Cam class is responsible for the ones that actually need to interface with the camera driver. (However, reading from the frame buffer is excluded. ESP32WebCam reads image data directly from the frame buffer of the image sensor without ESP32Cam.) The ESP32Cam class manipulates sensor characteristics, including setting image frame properties, image format settings, and exposure, gain, white balance, and band filter settings. It also saves the captured image to an SD card wired to the ESP32-CAM.

    "},{"location":"esp32cam.html#esp32cam-features","title":"ESP32Cam features:","text":"
    • Directs and acquires sensor settings.
    • Save and load the sensor settings to the flash memory on the ESP32 module.
    • Save the captured image to the SD card which is wired to ESP32 module.
    • Save captured images to SD card periodically using an ESP32 built-in hardware timer.
    "},{"location":"esp32cam.html#esp32webcam-class-apis","title":"ESP32WebCam Class APIs","text":""},{"location":"esp32cam.html#constructor","title":"Constructor","text":"
    ESP32WebCam(const uint16_t port = ESP32CAM_DEFAULT_HTTPPORT)\n
    ESP32WebCam(const ESP32Cam::CameraId model, const uint16_t port = ESP32CAM_DEFAULT_HTTPPORT)\n

    Instantiate ESP32WebCam. The constructor also instantiates ESP32Cam, so there is no need to explicitly declare the ESP32Cam class in the sketch. At the time of declaring the constructor, the camera is not initialized and the HTTP server is not started. Each of them requires a separate dedicated function to be called. Parameters portPort number of the HTTP server that ESP32WebCam starts. Default port number defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h modelSpecifies the model of the onboard image sensor. The image sensor models that can be specified are as follows:

    • ESP32Cam::CAMERA_MODEL_WROVER_KIT
    • ESP32Cam::CAMERA_MODEL_ESP_EYE
    • ESP32Cam::CAMERA_MODEL_M5STACK_NO_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_V2_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_WIDE
    • ESP32Cam::CAMERA_MODEL_M5STACK_ESP32CAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_UNITCAM
    • ESP32Cam::CAMERA_MODEL_AI_THINKER
    • ESP32Cam::CAMERA_MODEL_TTGO_T_JOURNAL
    "},{"location":"esp32cam.html#getcapturepath","title":"getCapturePath","text":"
    const char* getCapturePath(void)\n

    Get a path containing the first '/' of the currently valid endpoint URL to capture. Return valueA path of capturing URL. Default path defined by ESP32CAM_DEFAULT_PATH_CAPTURE macro directive in ESP32WebCam.h.

    "},{"location":"esp32cam.html#getpromptpath","title":"getPromptPath","text":"
    const char* getPromptPath(void)\n

    Get a path containing the first '/' of the currently valid endpoint URL to prompt. Return valueA path of prompting URL. Default path defined by ESP32CAM_DEFAULT_PATH_PROMPT macro directive in ESP32WebCam.h.

    "},{"location":"esp32cam.html#getserverhandle","title":"getServerHandle","text":"
    httpd_handle_t getServerHandle(void)\n

    Returns the handle of the HTTP server started by ESP32WebCam. Return valueReturns the httpd_handle_t value of an HTTP server started by ESP32WebCam. If the HTTP server task is not running, nullptr is returned.

    "},{"location":"esp32cam.html#getserverport","title":"getServerPort","text":"
    uint16_t getServerPort(void)\n

    Returns the port number that the HTTP server on listens to. Return valueReturns a port number of an HTTP server started by ESP32WebCam. Default port number defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h

    "},{"location":"esp32cam.html#getstreampath","title":"getStreamPath","text":"
    const char* getStreamPath(void)\n

    Get a path containing the first '/' of the currently valid endpoint URL to streaming. Return valueA path of streaming URL. Default path defined by ESP32CAM_DEFAULT_PATH_STREAM macro directive in ESP32WebCam.h.

    "},{"location":"esp32cam.html#isserverstarted","title":"isServerStarted","text":"
    bool isServerStarted(void)\n

    Returns a boolean value indicating whether the HTTP server task is running or not. Return value trueThe HTTP Server tasks is running. falseThe HTTP server task has not been started.

    "},{"location":"esp32cam.html#sensor","title":"sensor","text":"
    ESP32Cam& sensor(void)\n

    Returns a reference to ESP32Cam, which is instantiated internally by ESP32WebCam constructor. Return valueA reference to ESP32Cam instance. The image sensor is not initialized just by calling the ESP32WebCam constructor. To initialize the sensor, you need to call the sensorInit() function.

    ESP32WebCam webcam();\nwebcam.sensorInit();\n

    "},{"location":"esp32cam.html#sensorinit","title":"sensorInit","text":"
    esp_err_t sensorInit(void)\n
    esp_err_t sensorInit(const ESP32Cam::CameraId model)\n

    Initialize the image sensor via the ESP32Cam class. The sketch needs to initialize the sensor with the sensorInit function prior to all processing of the image sensor. Parameters modelSpecifies the model of the onboard image sensor. The image sensor models that can be specified are same as the constructor parameter. Return value ESP_OKAn image sensor successfully initialized. ESP_ERR_CAMERA_NOT_SUPPORTEDSpecified model is not supported. ESP_ERR_CAMERA_NOT_DETECTEDAn image sensor not detected. ESP_ERR_CAMERA_FAILED_TO_SET_FRAME_SIZEFrame identifier is invalid. ESP_ERR_CAMERA_FAILED_TO_SET_OUT_FORMATOutput image format is invalid. ESP_FAILOther error occurred.

    "},{"location":"esp32cam.html#setcapturepath","title":"setCapturePath","text":"
    void setCapturePath(const char* path)\n

    Reconfigure the already defined path of the endpoint for capture. Parameters pathSpecifies the path of the capture endpoint to be set newly, as a string starting with '/'. If this path is not specified, the default path defined by ESP32CAM_DEFAULT_PATH_CAPTURE macro directive will be assumed.

    "},{"location":"esp32cam.html#setpromptpath","title":"setPromptPath","text":"
    void setPromptPath(const char* path)\n

    Reconfigure the already defined path of the endpoint for prompt. Parameters pathSpecifies the path of the prompt endpoint to be set newly, as a string starting with '/'. If this path is not specified, the default path defined by ESP32CAM_DEFAULT_PATH_PROMPT macro directive will be assumed.

    "},{"location":"esp32cam.html#setserverport","title":"setServerPort","text":"
    void setServerPort(const uint16_t port)\n

    Reconfigure the already defined port number of an HTTP server. Parameters portSpecifies port number of an HTTP Server. Default port number defined by ESP32CAM_DEFAULT_HTTPPORT macro directive will be assumed.

    "},{"location":"esp32cam.html#setstreampath","title":"setStreamPath","text":"
    void setStreamPath(const char* path)\n

    Reconfigure the already defined path of the endpoint for stream. Parameters pathSpecifies the path of the stream endpoint to be set newly, as a string starting with '/'. If this path is not specified, the default path defined by ESP32CAM_DEFAULT_PATH_STREAM macro directive will be assumed.

    "},{"location":"esp32cam.html#startcameraserver","title":"startCameraServer","text":"
    esp_err_t startCameraServer(const char* streamPath)\n
    esp_err_t startCameraServer(const char* streamPath, const char* capturePath, const char* promptPath)\n
    esp_err_t startCameraServer(const char* streamPath, const char* capturePath, const char* promptPath, const uint16_t port)\n
    esp_err_t startCameraServer(const char* streamPath, const uint16_t port)\n
    esp_err_t startCameraServer(const uint16_t port)\n
    esp_err_t startCameraServer(void)\n

    Begins the HTTP server task, and start the endpoint service. By starting the HTTP server task, the endpoint interface provided by ESP32WebCam will be available. Parameters streamPathSpecifies the path of the stream endpoint. Default stream path is defined by ESP32CAM_DEFAULT_PATH_STREAM macro directive in ESP32WebCam.h header file. capturePathSpecifies the path of the capture endpoint. Default capture path is defined by ESP32CAM_DEFAULT_PATH_CAPTURE macro directive in ESP32WebCam.h header file. promptPathSpecifies the path of the prompt endpoint. Default prompt path is defined by ESP32CAM_DEFAULT_PATH_PROMPT macro directive in ESP32WebCam.h header file. portSpecifies port number on which the HTTP server listens. Default port number is 3000 which defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h header file. Return value ESP_OKAn HTTP server task successfully started. ESP_ERR_HTTPD_HANDLERS_FULLAll slots for registering URI handlers have been consumed. ESP_ERR_HTTPD_ALLOC_MEMFailed to dynamically allocate memory for resource. ESP_ERR_HTTPD_TASKFailed to launch server task/thread. ESP_FAILOther error occurred.

    HTTP server task stack size

    ESP32WebCam allocates 8KB of stack when it starts the HTTP server task. This stack size is larger than the size allocated by the default HTTPD_DEFAULT_CONFIG in ESP-IDF. This is to include the stack consumed by the file system of the SD card triggered by the timer shot. This stack size can be changed as needed, and the default value is defined in the ESP32Cam.h header file as ESP32CAM_TIMERTASK_STACKSIZE.

    "},{"location":"esp32cam.html#stopcameraserver","title":"stopCameraServer","text":"
    void stopCameraServer(void)\n

    Stop an HTTP server task and free resources.

    "},{"location":"esp32cam.html#esp32webcam-endpoint-interfaces","title":"ESP32WebCam Endpoint Interfaces","text":"

    ESP32WebCam has endpoint interfaces for simple manipulation of image sensors over the network via an internally launched HTTP server, which follows the traditional HTTP request and response, not WebAPI or REST. It supports the HTTP GET1 method and will be available after the HTTP server is started by the ESP32WebCam::startCameraServer function.

    If you are using Visual Studio Code as your build system for Arduino sketch, you can easily experiment with the ESP32WebCam endpoint interface using the VSCode extension. REST Client is an excellent VSCode extension that allows you to send HTTP requests directly from within the editor. The following screenshot shows the result of sending an HTTP request directly to the capture endpoint of ESP32WebCam using the REST Client on a VSCode with the PlatformIO build system.

    The top left editor pane is the sketch code described above, and the bottom pane is the serial monitor output of the sketch. The pane between the top and bottom panes is the REST Client. Run the sketch, and when the serial monitor shows a message that ESP32Cam has started the HTTP server, use the REST client to send an HTTP GET request as GET http://{HOST}:{PORT}/_capture (In the screenshot above, the request is sent to http://192.168.1.19:3000/_capture) to the capture endpoint.2 You will see the response of the image captured by ESP32-CAM in the right pane.

    "},{"location":"esp32cam.html#the-default-settings-for-the-endpoint-interface-provided-by-esp32webcam-are-as-follows","title":"The default settings for the endpoint interface provided by ESP32WebCam are as follows:","text":"Endpoint Default path Function Default value defined in ESP32WebCam.h Capture /_capture Responds as a captured image ESP32CAM_DEFAULT_PATH_CAPTURE Prompt /_prompt Save and load the captured image, Save the sensor settings ESP32CAM_DEFAULT_PATH_PROMPT Stream /_stream Stream image ESP32CAM_DEFAULT_PATH_STREAM"},{"location":"esp32cam.html#capture","title":"Capture","text":"
    GET http://{HOST}:{PORT}{PATH}\n

    The capture endpoint responds captured image with the image/jpeg mime format. Parameters HOSTHost address of ESP32-CAM. PORTPort number of HTTP server listening on. Default port number is 3000 which defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h header file. PATHA path for the capture endpoint. Response code 200Content body contains captured image data.

    "},{"location":"esp32cam.html#prompt","title":"Prompt","text":"
    GET http://{HOST}:{PORT}{PATH}?{QUERY}\n

    You can use the prompt endpoint to save the captured image to the SD card at that moment or in a timer cycle, save the sensor settings, and load them into the flash memory built into the ESP32 module. The instructions for the prompt action performed by ESP32WebCam are specified as the query string with \"key=value\" form for the parameters of the GET request.Parameters HOSTHost address of ESP32-CAM. PORTPort number of HTTP server listening on. Default port number is 3000 which defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h header file. PATHA path for the capture endpoint. QUERYThe QUERY that Prompt can accept are different for each feature. The query formats that can be specified and the corresponding functions are shown below. Response code 202Request accepted. 400Query string has syntax error, or Fatal error occurred. Content body has detailed error code.

    "},{"location":"esp32cam.html#the-following-features-are-currently-supported-by-the-prompt-endpoint","title":"The following features are currently supported by the prompt endpoint:","text":"Specifying by query string Function Behavior mf=oneshot[&fs={sd|mmc}][&filename=<FILENAME>] One-shot Take a one-shot image and save it to the SD card. mf=timershot[&fs={sd|mmc}][&filename=<FILENAME>][&period=<INTERVAL>] Timer-shot Repeatedly takes a one-shot image at specified an INTERVAL of seconds and saves it to the SD card. mf=distimer Disable timer Suspend timer for Timer-shot mf=entimer Enable timer Resume timer for Timer-shot mf=load Load settings Load the image sensor settings from the NVS mf=save Save settings Save the image sensor settings to the NVS

    The query formats that can be specified and their corresponding functions are described below.Functions: Specifies with the mf= query. oneshotCapture an image at the requested timing and save them to the SD card. Species either sd or mmc for the fs argument. If the fs argument does not exist, mmc is assumed.Saves the captured image with the file name specified by the filename argument; if the filename argument does not exist, it assumes a file name consisting of a prefix and a timestamp. In that case, the fixed string defined by the ESP32CAM_GLOBAL_IDENTIFIER macro directive in ESP32Cam.h is used as the prefix. timershotRepeatedly takes a one-shot image at specified an INTERVAL of seconds with period argument and saves it to the SD card. Species either sd or mmc for the fs argument. If the fs argument does not exist, mmc is assumed.Saves the captured image to a file whose name consists of the prefix and timestamp suffix specified by the filename argument. If the filename argument does not exist, the prefix will be assumed a fixed string defined by the ESP32CAM_GLOBAL_IDENTIFIER macro directive in ESP32Cam.h header file. distimerTemporarily stops the timer for the timershot. This can be resumed with entimer. entimerResumes a timer-shot that was temporarily stopped by distimer. loadLoad the image sensor settings from NVS. saveSave the image sensor settings to NVS.

    Whether it is SD or MMC depends on the hardware

    The ESP32 Arduino SD library supports two types of SD cards with different interfaces. Which type of SD card is used depends on the ESP32 module and needs to be chosen appropriately. In the case of the Ai-Thinker ESP32-CAM 3, the ESP32 is wired to the SD slot with each HS2 signal. Hence, We can see from the schematic that it is using MMC.

    "},{"location":"esp32cam.html#stream","title":"Stream","text":"
    GET http://{HOST}:{PORT}{PATH}\n

    The stream endpoint responds captured image with the image/jpeg mime format with multipart/x-mixed-replace HTTP header. Parameters HOSTHost address of ESP32-CAM. PORTPort number of HTTP server listening on. Default port number is 3000 which defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h header file. PATHA path for the stream endpoint. Response code 200Content body contains captured image data with multipart boundary.

    "},{"location":"esp32cam.html#esp32cam-class-apis","title":"ESP32Cam Class APIs","text":""},{"location":"esp32cam.html#constructor_1","title":"Constructor","text":"
    ESP32Cam()\n
    ESP32Cam(const CameraId model)\n

    Instantiate ESP32Cam. The image sensor is not initialized just by calling the constructor. To initialize the sensor, you need to call the init function. Parameters modelSpecifies the model of the onboard image sensor. The image sensor models that can be specified are as follows:

    • ESP32Cam::CAMERA_MODEL_WROVER_KIT
    • ESP32Cam::CAMERA_MODEL_ESP_EYE
    • ESP32Cam::CAMERA_MODEL_M5STACK_NO_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_V2_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_WIDE
    • ESP32Cam::CAMERA_MODEL_M5STACK_ESP32CAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_UNITCAM
    • ESP32Cam::CAMERA_MODEL_AI_THINKER
    • ESP32Cam::CAMERA_MODEL_TTGO_T_JOURNAL
    "},{"location":"esp32cam.html#getstatus","title":"getStatus","text":"
    esp_err_t getStatus(camera_status_t* status)\n

    Get the camera_status_t data structure from the image sensor. Parameters statusPointer to the buffer to store the acquired camera_status_t structure. Return value ESP_OKcamera_status_t is read successfully. ESP_FAILImage sensor is not initialized.

    "},{"location":"esp32cam.html#getframesize","title":"getFramesize","text":"
    framesize_t getFramesize(void)\n

    Get the current configuration of the image sensor frame size. Return value framesize_tThe framesize_t enumeration value.

    "},{"location":"esp32cam.html#getframeheight","title":"getFrameHeight","text":"
    uint16_t  getFrameHeight(void)\n

    Returns the height of the current image frame in pixels. Return value uint16_tHeight of the image frame.

    "},{"location":"esp32cam.html#getframewidth","title":"getFrameWidth","text":"
    uint16_t  getFrameWidth(void)\n

    Returns the width of the current image frame in pixels. Return value uint16_tWidth of the image frame.

    "},{"location":"esp32cam.html#init","title":"init","text":"
    esp_err_t init(void)\n
    esp_err_t init(const CameraId model)\n

    Initialize the image sensor. Parameters modelSpecifies the model of the onboard image sensor. The image sensor models that can be specified are as follows:

    • ESP32Cam::CAMERA_MODEL_WROVER_KIT
    • ESP32Cam::CAMERA_MODEL_ESP_EYE
    • ESP32Cam::CAMERA_MODEL_M5STACK_NO_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_V2_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_WIDE
    • ESP32Cam::CAMERA_MODEL_M5STACK_ESP32CAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_UNITCAM
    • ESP32Cam::CAMERA_MODEL_AI_THINKER
    • ESP32Cam::CAMERA_MODEL_TTGO_T_JOURNAL
    "},{"location":"esp32cam.html#loadsettings","title":"loadSettings","text":"
    esp_err_t loadSettings(const char* key = nullptr)\n

    Load the image sensor settings from NVS in the ESP32 flash. Parameters keySpecifies NVS key name. If key is nullptr or not specified, default key which defined by ESP32CAM_NVS_KEYNAME macro directive in ESP32Cam.h header file will be assumed. Return value ESP_OKThe image sensor settings has been successfully loaded.

    "},{"location":"esp32cam.html#savesettings","title":"saveSettings","text":"
    esp_err_t saveSettings(const char* key = nullptr)\n

    Save the current image sensor settings to NVS in the ESP32 flash. Parameters keySpecifies NVS key name. If key is nullptr or not specified, default key which defined by ESP32CAM_NVS_KEYNAME macro directive in ESP32Cam.h header file will be assumed. Return value ESP_OKThe image sensor settings has been successfully saved.

    "},{"location":"esp32cam.html#setstatus","title":"setStatus","text":"
    esp_err_t setStatus(const camera_status_t& status)\n

    Set the content of camera_status_t structure to the image sensor. Parameters statusReference of the camera_status_t structure. Return value ESP_OKcamera_status_t has been set successfully. ESP_FAILImage sensor is not initialized.

    "},{"location":"esp32cam.html#setframesize","title":"setFramesize","text":"
    esp_err_t setFramesize(const framesize_t framesize)\n

    Set the image sensor frame size. Parameters framesizeThe framesize_t enumeration value to be set. Return value ESP_OKFramesize has been set. ESP_ERR_CAMERA_FAILED_TO_SET_FRAME_SIZEImage sensor is not initialized, the framesize is invalid, or the pixel format is not JPEG.

    "},{"location":"esp32cam.html#setimageformat","title":"setImageFormat","text":"
    esp_err_t setImageFormat(const pixformat_t format)\n

    Set the image format. Parameters formatThe pixformat_t enumeration value to be set. Return value ESP_OKFormat has been set. ESP_ERR_CAMERA_FAILED_TO_SET_OUT_FORMATSpecified format is invalid. ESP_FAILImage sensor is not initialized.

    "},{"location":"esp32cam.html#oneshot","title":"oneShot","text":"
    esp_err_t oneShot(fs::SDFS& sd, const char* filename = nullptr)\n
    esp_err_t oneShot(fs::SDMMCFS& mmc, const char* filename = nullptr)\n

    Take a one-shot image and save it to the SD card or MMC. This function writes to a file compliant with the ESP32 Arduino SD library. Either fs::SDFS or fs::SDMMCFS can be specified for the file system that represents sd or mmc. Parameters sdSpecifies the SD file system when the SD card is wired with SPI interface. In usually, you can use a SD variable that is instantiated and exported globally by the ESP32 Arduino core. mmcSpecifies the SD_MMC file system when the SD card is wired with HS2 interface. In usually, you can use a SD_MMC variable that is instantiated and exported globally by the ESP32 Arduino core. filenameSpecifies the file name when saving the captured image to the SD card. if the filename does not exist, it assumes a file name consisting of a prefix and a timestamp. In that case, the fixed string defined by the ESP32CAM_GLOBAL_IDENTIFIER macro directive in ESP32Cam.h is used as the prefix. Return value ESP_OKFormat has been set. ESP_ERR_NOT_FOUNDSD card is not mounted. ESP_FAILOther error occurred.

    "},{"location":"esp32cam.html#timershot","title":"timerShot","text":"
    esp_err_t timerShot(const unsigned long period, fs::SDFS& sd, const char* filePrefix = nullptr)\n
    esp_err_t timerShot(const unsigned long period, fs::SDMMCFS& mmc, const char* filePrefix = nullptr)\n

    Repeatedly takes a one-shot image at specified an interval of seconds with period parameter and saves it to the SD card or MMC. This function writes to a file compliant with the ESP32 Arduino SD library. Either fs::SDFS or fs::SDMMCFS can be specified for the file system that represents sd or mmc. Parameters periodSpecifies the shooting interval time in second unit. sdSpecifies the SD file system when the SD card is wired with SPI interface. In usually, you can use a SD variable that is instantiated and exported globally by the ESP32 Arduino core. mmcSpecifies the SD_MMC file system when the SD card is wired with HS2 interface. In usually, you can use a SD_MMC variable that is instantiated and exported globally by the ESP32 Arduino core. filePrefixSpecifies the prefix of file name when saving the captured image to the SD card. This function saves files each time whose name consists of the prefix and timestamp suffix specified by the filePrefix parameter. If the filePrefix does not exist, it assumes a fixed string defined by the ESP32CAM_GLOBAL_IDENTIFIER macro directive in ESP32Cam.h for the prefix. Return value ESP_OKFormat has been set. ESP_ERR_NOT_FOUNDSD card is not mounted. ESP_FAILOther error occurred.

    "},{"location":"esp32cam.html#disabletimershot","title":"disableTimerShot","text":"
    void disableTimerShot(void)\n

    Temporarily stops the timerShot. To restart it, call enableTimerShot.

    "},{"location":"esp32cam.html#enabletimershot","title":"enableTimerShot","text":"
    void enableTimerShot(void)\n

    Restarts the timerShot that was temporarily stopped by disableTimerShot.

    "},{"location":"esp32cam.html#deq","title":"deq","text":"
    void deq(void)\n

    Release a semaphore.

    "},{"location":"esp32cam.html#enq","title":"enq","text":"
    portBASE_TYPE enq(TickType_t ms)\n

    Take a semaphore to prevent resource collisions with the image sensor. ESP32Cam uses a semaphore for each of oneShot and timerShot to prevent image sensor resources from colliding while performing each other's tasks. The enq function reserves a semaphore to wait for a subsequent oneShot or timerShot task. Parameters msSpecifies the maximum waiting time in milliseconds for a semaphore to be released. If portMAX_DELAY is specified, it will wait indefinitely for the semaphore to be released. Return value pdTRUESemaphore was reserved. !pdTRUESemaphore was not released within the specified ms time.

    "},{"location":"esp32cam.html#webcamserver-like-as-camerawebserver","title":"WebCamServer like as CameraWebServer","text":"

    The WebCamServer.ino sketch combines AutoConnectAux's custom web pages with native HTML pages. The image viewer is placed on the native HTML page using the img tag, and the slide-in navigation panel is incorporated using CSS. AutoConnect is only directly involved in the image sensor setup page, which is JSON defined in CAMERA_SETUP_PAGE. The setSensor function in the sketch is a handler for a custom web page for CAMERA_SETUP_PAGE, and its role is to communicate the sensor settings to the ESP32 camera driver via ESP32Cam.

    In the WebCamServer.ino sketch, most of the front-end is taken care of by the UI, which is a web page written in HTML. The slide-in menu allows navigation to stream images, capture still images, save a one-shot image to the SD card, and the timer-shot. Image streaming and capture are achieved by giving the URLs of the Stream endpoint and Capture endpoint in the src attribute of the img tag in the HTML using JavaScript DOM interface.

    <body>\n  <li id=\"onair\" onclick=\"stream(!isStreaming())\">Start Streaming</li>\n  <img id=\"img-frame\" />\n</body>\n
    const onAir = document.getElementById('onair');\nconst imgFrame = document.getElementById('img-frame');\n\nfunction isStreaming() {\nstatus.innerText = null;\nreturn onAir.innerText.startsWith(\"Stop\");\n}\n\nfunction stream(onOff) {\nif (onOff && !isStreaming()) {\n    window.stop();\nimgFrame.src = streamUrl;\nonAir.innerText = onAir.innerText.replace(\"Start\", \"Stop\");\ncontent.focus();\n  }\nelse if (!onOff && isStreaming()) {\n    window.stop();\nimgFrame.src = noa;\nonAir.innerText = onAir.innerText.replace(\"Stop\", \"Start\");\n  }\n}\n

    Also, One-shot and timer-shot also use JavaScript Fetch API to send a query string compliant with each function to the Prompt endpoint.

    <li id=\"oneshot\" onclick=\"oneshot()\">One-Shot</li>\n<li><label for=\"period\">Period [s]</label><input type=\"number\" name=\"peirod\" id=\"period\" min=\"1\" value=\"1\" pattern=\"\\d*\"/></li>\n<li><input type=\"button\" value=\"ARM\" onclick=\"arm()\"/></li>\n
    var promptUrl = endpoint(host, promptPath, port);\n\nfunction endpoint(host, path, port) {\nvar url = new URL(path, \"http://\" + host);\nurl.port = port;\nreturn url;\n}\n\nfunction prompt(url) {\nvar res;\nstream(false);\nfetch(url)\n    .then(response => {\nres = \"status:\" + response.status + \" \";\nif (!response.ok) {\nreturn response.text().then(text => {\nthrow new Error(text);\n        });\n      }\nelse {\nstatus.style.color = '#297acc';\nstatus.innerText = res + response.statusText;\n      }\n    })\n    .catch(err => {\nvar desc = err.message;\nif (err.message.indexOf(\"0x0103\", 1) > 0) {\ndesc = \"SD not mounted\";\n      }\nif (err.message.indexOf(\"0x0105\", 1) > 0) {\ndesc = \"SD open failed\";\n      }\nstatus.style.color = '#cc2929';\nstatus.innerText = res + desc;\n    });\n}\n\nfunction oneshot() {\npromptUrl.search = \"?mf=oneshot&fs=mmc\";\nprompt(promptUrl);\n}\n\nfunction arm() {\npromptUrl.search = \"?mf=timershot&fs=mmc&period=\" + document.getElementById('period').value;\nprompt(promptUrl);\n}\n

    The following diagram shows the program structure of the WebCamServer.ino sketch. Its structure is somewhat more complex than the simple sketch presented at the beginning of this chapter because of the native HTML intervening.

    1. ESP32WebCam endpoint interface supports only HTTP GET method, it cannot respond to other HTTP methods such as POST.\u00a0\u21a9

    2. Do not use the REST Client to send requests to the stream endpoints, the REST Client does not fully support multipart/x-mixed-replace mime.\u00a0\u21a9

    3. When using MMC on AI-Thinker ES32-CAM, the LED flash on the module blinks every time the SD is accessed, because the HS2 DATA1 signal is wired to the driver transistor of the LED FLASH. I can't envision why HS2 DATA1 signal was chosen to drive the LED.\u00a0\u21a9

    "},{"location":"faq.html","title":"FAQ","text":""},{"location":"faq.html#after-connected-autoconnect-menu-performs-but-no-happens","title":"After connected, AutoConnect menu performs but no happens.","text":"

    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().

    See also the explanation here.

    "},{"location":"faq.html#after-updating-to-autoconnect-v100-established-aps-disappear-from-open-ssids-with-esp32","title":"After updating to AutoConnect v1.0.0, established APs disappear from Open SSIDs with ESP32.","text":"

    Since AutoConnect v1.0.0 for ESP32, the storage location in the flash of established credentials has moved from EEPROM to Preferences. After You update AutoConnect to v1.0.0, past credentials saved by v0.9.12 earlier will not be accessible from the AutoConnect menu - Open SSIDs. You need to transfer once the stored credentials from the EEPROM area to the Preferences area.

    You can migrate the past saved credentials using CreditMigrate.ino which the examples folder contains.

    Needs to Arduino core for ESP32 1.0.2 or earlier

    EEPROM area with arduino-esp32 core 1.0.3 has moved from partition to the nvs. CreditMigrate.ino requires arduino-esp32 core 1.0.2 or earlier to migrate saved credentials.

    "},{"location":"faq.html#an-esp8266ap-as-softap-was-connected-but-captive-portal-does-not-start","title":"An esp8266ap as SoftAP was connected but Captive portal does not start.","text":"

    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.

    "},{"location":"faq.html#autoconnect-web-pages-are-broken","title":"AutoConnect Web Pages are broken.","text":"

    When the captive portal opens, AutoConnect's embedded web page may be broken or display an incomplete menu like the one below. This is due to AutoConnect temporarily abandoning HTML generation because the ESP module's heap memory was exhausted. This phenomenon may frequently occur, especially with ESP8266 Arduino core 3.1.0 or later.

    ESP8266 Arduino core 3.1.0 or later has increased heap consumption due to the application of Non-OS SDK 3.0.x. This makes the ESP8266 more prone to running out of memory than previous core versions.

    To reduce RAM consumption, apply workarounds such as reducing the number of AutoConnectElements placed on the custom web pages, or enabling AutoConnectOTA only when a WiFi connection is established to an access point. For example, the code snippet for enabling OTA when a WiFi connection is established is as follows:

    AutoConnect portal;\nAutoConnectConfig config;\n\nvoid wifiConnect(IPAddress& ip) {\n  Serial.println(\"WiFi connected:\" + WiFi.SSID());\n  Serial.println(\"IP:\" + WiFi.localIP().toString());\n  config.ota = AC_OTA_BUILTIN;\n  portal.config(config);\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  portal.onConnect(wifiConnect);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"faq.html#cannot-automatically-reconnect-to-a-wifi-hotspot","title":"Cannot automatically reconnect to a WiFi Hotspot","text":"

    WiFi Hotspot ability using a cell phone has no official designation name, but it is commonly referred to as a mobile hotspot or a Personal Hotspot. Generally, this feature using data communication with your cellular to ensure the connection to the Internet. AutoConnect allows you to connect to a WiFi hotspot that has been temporarily launched as an access point and then stores a credential for establishing a connection in the same way as a regular fixed access point.

    However, there's a case where it may not be able to reconnect automatically to a known WiFi hotspot. For security reasons, some device operating systems randomly change the MAC address of the WiFi hotspot at each boot for a hotspot. (Especially iOS14) AutoConnect uses the BSSID to find the known SSID from among WiFi signals being broadcast. (it's the MAC address) This method works if the BSSID that the hotspot originates is fixed, but AutoConnect will not be able to find known SSIDs when it changes. Consider activating the AUTOCONNECT_APKEY_SSID definition if you want to reconnect automatically to a known WiFi hotspot.

    Cannot immobilize the MAC address of Personal Hotspot

    We may not be able to immobilize the MAC address of Personal Hotspot on iOS14. This specification change seems to be related to the private network connection enhancement of iOS14 devices. I found this change during the testing phase, but it is not the confirmed information. (iOS14 offers an option to immobilize the MAC address as a client device, but there is still no option to immobilize it where the device became a hotspot)

    "},{"location":"faq.html#captive-portal-does-not-pop-up","title":"Captive portal does not pop up.","text":"

    If the ESP module is already transparent to the Internet, the device's captive portal screen does not pop up even if AutoConnectConfig::retainPortal is enabled. The captive portal popup may also be misinterpreted as automatically activated when AutoConnect is disconnected from the Internet.

    When your device connects to an access point, it determines if it is also transparent to the Internet according to the HTTP response from a specific URL. AutoConnect traps the HTTP request issued by the device and responds with a portal screen for AutoConnect. Then the device automatically pops up the HTML in response. It means the auto-popup when opening a captive portal is a feature your device OS has. In this mechanism, AutoConnect impersonates an internally launched DNS server response to trap HTTP requests for Internet transparency determination.

    However, its DNS response disguise is very rough, redirecting all FQDNs that do not end in .local to the SoftAP IP address of the ESP module. The redirect location is /_ac, and the responder for /_ac is AutoConnect. This kind of hack is also available as an example in the Arduino ESP8266/ESP32 DNS server library.

    The reason AutoConnect shuts down the DNS server after establishing a connection with a WiFi access point and stops hacking HTTP requests for Internet transparency detection is because AutoConnect can only trap a broad range of DNS requests. After the ESP module connects to the access point, the sketch can access the Internet using the FQDN. To prevent it from interfering with that access, AutoConnect will stop the internally launched DNS. In other words, the only scene that allows automatic pop-ups to lead to the captive portal is when the ESP module is not transparent to the Internet.

    Instead, AutoConnect has options to restart the internal DNS server when the ESP module loses WiFi connectivity, allowing the device to auto-pop up a captive portal screen. If the sketch enables AutoConnectConfig::retainPotral and AutoConnectConfig::autoRise, then when the WiFi connection is lost (i.e. WiFi.status() != WL_CONNECTED), AutoConnect will initiate a trap by starting the SoftAP and the internal DNS server. At this time, the ESP module will transition to WIFI_AP_STA mode. The AutoConnect::handleClient function performs this restart sequence each time it is called, so the sketch can resume the captive portal automatic pop-up while the loop function is running.

    "},{"location":"faq.html#compile-error-due-to-file-system-header-file-not-found","title":"Compile error due to File system header file not found","text":"

    In PlatformIO, it may occur compilation error such as the bellows:

    In file included from C:\\Users\\<user>\\Documents\\Arduino\\libraries\\AutoConnect\\src\\AutoConnect.h:30:0,\nfrom src/main.cpp:28:\nC:\\Users\\<user>\\Documents\\Arduino\\libraries\\PageBuilder\\src\\PageBuilder.h:88:27:\nfatal error: SPIFFS.h: No such file or directory\n
    In file included from C:\\Users\\<user>\\Documents\\Arduino\\libraries\\AutoConnect\\src\\AutoConnect.h:30,\nfrom src\\main.cpp:28:\nC:\\Users\\<user>\\Documents\\Arduino\\libraries\\PageBuilder\\src\\PageBuilder.h:93:17:\nfatal error: LittleFS.h: No such file or directory\n

    This compilation error is due to PlatformIO's Library Dependency Finder not being able to detect #include with default mode chain. Chain mode does not recursively evaluate .cpp files. However, AutoConnect determines the default file system at compile time, depending on the platform. In order for LDF to detect it correctly, it is necessary to recursively scan #include of the header file, which depends on the file system used.

    To avoid compilation errors in PlatformIO, specify lib_ldf_mode in platformio.ini as follows:

    [env]\nlib_ldf_mode = deep+\n

    You should specify deep+ with lib_ldf_mode.

    Another option is to explicitly specify the file system to be applied to AutoConnect at build time. The compiler determines the file system to be applied to AutoConnect by preprocessor macro definitions defined in AutoConnectDefs.h. The directives defined as AC_USE_SPIFFS and AC_USE_LITTLEFS specify that the respective file systems apply. The chapter Using Filesystem details how to explicitly specify a file system for AutoConnect in PlatformIO.

    "},{"location":"faq.html#compile-error-occurs-due-to-the-text-section-exceeds","title":"Compile error occurs due to the text section exceeds","text":"

    When building the sketch, you may receive a compilation error message similar that the text section exceeds the available space on the board. This error occurs with ESP32 arduino core 2.0.0 or later. Since ESP32 arduino core 2.0.0, the object size of the library tends to be oversized, and the AutoConnect object size is also bloated. And also for some example sketches such as mqttRSSI, the BIN size after linkage does not fit in the default partition scheme.

    I'm aware of this issue1 and trying to reduce the size of the AutoConnect object, but for now, changing the partition table at build is the most effective workaround. See How much memory does AutoConnect consume? for information on how to change the partition table.

    "},{"location":"faq.html#compile-error-that-eeprom-was-not-declared-in-this-scope","title":"Compile error that 'EEPROM' was not declared in this scope","text":"

    If the user sketch includes the header file as EEPROM.h, this compilation error may occur depending on the order of the #include directives. AutoConnectCredentials.h including in succession linked from AutoConnect.h defines NO_GLOBAL_EEPROM internally, so if your sketch includes EEPROM.h after AutoConnect.h, the EEPROM global variable will be lost.

    If you use EEPROM with your sketch, declare #include <EEPROM.h> in front of #include <AutoConnect.h>.

    "},{"location":"faq.html#compile-error-that-esphttpupdate-was-not-declared-in-this-scope","title":"Compile error that 'ESPhttpUpdate' was not declared in this scope","text":"

    If the user sketch includes the header file as ESP8266httpUpdate.h, this compilation error may occur depending on the order of the #include directives. AutoConnectUpdate.h including in succession linked from AutoConnect.h defines NO_GLOBAL_HTTPUPDATE internally, so if your sketch includes ESP8266httpUpdate.h after AutoConnect.h, the ESPhttpUpdate global variable will be lost.

    You can avoid a compile error in one of two ways:

    1. Disable an AutoConnectUpdate feature if you don't need.

      You can disable the AutoConnectUpdate feature by commenting out the AUTOCONNECT_USE_UPDATE macro in the AutoConnectDefs.h header file. 

      #define AUTOCONNECT_USE_UPDATE\n

    2. Change the order of #include directives.

      With the Sketch, #include <ESP8266httpUpdate.h> before #include <AutoConnect.h>.

    "},{"location":"faq.html#connection-lost-immediately-after-establishment-with-ap","title":"Connection lost immediately after establishment with AP","text":"

    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.

    "},{"location":"faq.html#data-saved-to-eeprom-is-different-from-my-sketch-wrote","title":"Data saved to EEPROM is different from my sketch wrote.","text":"

    By default, AutoConnect saves the credentials of the established connection into EEPROM. The credential area of EEPROM used by AutoConnect will conflict with data owned by the user sketch if without measures taken. It will destroy the user sketch data and the data stored in EEPROM by AutoConnect with each other. You have the following two options to avoid this conflict:

    • Move the credential saving area of EEPROM. You can protect your data from corruption by notifying AutoConnect where to save credentials. Notification of the save location for the credentials uses AutoConnectConfig::boundaryOffset option. Refer to the chapter on Move the saving area of EEPROM for the credentials for details.

    • Suppresses the automatic save operation of credentials by AutoConnect. You can completely stop saving the credentials by AutoConnect. However, if you select this option, you lose the past credentials which were able to connect to the AP. Therefore, the effect of the automatic reconnection feature will be lost. If you want to stop the automatic saving of the credentials, uses AutoConnectConfig::autoSave option specifying AC_SAVECREDENTIAL_NEVER. Refer to the chapter on Advanced usage for details.

    "},{"location":"faq.html#does-not-appear-esp8266ap-in-smartphone","title":"Does not appear esp8266ap in smartphone.","text":"

    Maybe it is successfully connected at the 1st-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>\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  WiFi.mode(WIFI_STA);\n  delay(100);\n  WiFi.begin();\nif (WiFi.waitForConnectResult() == WL_CONNECTED) {\n    WiFi.disconnect();\nwhile (WiFi.status() == WL_CONNECTED)\n      delay(100);\n  }\n  Serial.println(\"WiFi disconnected.\");\n}\n\nvoid loop() {\n  delay(1000);\n}\n
    You can interactively check the WiFi state of ESP8266.

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

    "},{"location":"faq.html#does-not-response-from-_ac","title":"Does not response from /_ac.","text":"

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

    "},{"location":"faq.html#hang-up-after-reset","title":"Hang up after Reset?","text":"

    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 2

    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)\nets Jan  8 2013,rst cause:4, boot mode:(1,6) or (1,7)\nwdt reset\n

    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 on2: external reset4: 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)."},{"location":"faq.html#how-can-i-detect-the-captive-portal-starting","title":"How can I detect the captive portal starting?","text":"

    You can use the AutoConnect::onDetect exit routine. For more details and an implementation example of the onDetect exit routine, refer to the chapter Captive portal start detection.

    "},{"location":"faq.html#how-change-http-port","title":"How change HTTP port?","text":"

    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\n
    "},{"location":"faq.html#how-change-ssid-or-password-in-captive-portal","title":"How change SSID or Password in Captive portal?","text":"

    You can change both by using AutoConnectConfig::apid and AutoConnectConfig::psk. Refer to section Change SSID and Password for SoftAP in Settings and controls for network and WiFi.

    "},{"location":"faq.html#how-do-i-detach-the-ardunojson","title":"How do I detach the ArdunoJson?","text":"

    If you don't use ArduinoJson at all, you can detach it from the library. By detaching ArduinoJson, the binary size after compilation can be reduced. You can implement custom Web pages with your sketches without using ArduinoJson. Its method is described in Custom Web pages w/o JSON. To completely remove ArduinoJson at compile-time from the binary, you need to define a special #define directive for it. And if you define the directive, you will not be able to use the OTA update with the update server feature as well as AutoConnectAux described by JSON.

    To exclude ArduinoJson at compile-time, give the following #define directive as a compiler option such as the arduino-cli or PlatformIO.

    #define AUTOCONNECT_NOUSE_JSON\n

    For example, add the following description to the [env] section of the platformio.ini file with the build-flags.

    build-flags = -DAUTOCONNECT_NOUSE_JSON\n
    "},{"location":"faq.html#how-erase-the-credentials-saved-in-eeprom","title":"How erase the credentials saved in EEPROM?","text":"

    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. Refer to Saved credential access for details.

    Hint

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

    "},{"location":"faq.html#how-locate-the-link-button-to-the-autoconnect-menu","title":"How locate the link button to the AutoConnect menu?","text":"

    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>\n
    "},{"location":"faq.html#how-much-memory-does-autoconnect-consume","title":"How much memory does AutoConnect consume?","text":""},{"location":"faq.html#sketch-size","title":"Sketch size","text":"

    1. For ESP8266 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)

    2. For ESP32 The BIN size of the sketch grows to over 1M bytes. In the case of a sketch with many custom Web pages, when applying the partition table for the default scheme, the remaining flash size that can be utilized by the user application may be less than 200K bytes. Therefore, it is advisable to resize the partition to make more available space for the application. The ESP32 arduino core has various partition schemes, and you can choose it according to your Sketch feature. You can change the partition scheme from the Tools > Partition Scheme menu of Arduino IDE.

    Change the partition scheme with PlatformIO

    Use board_build.partitions directive with platformio.ini. 

    [env:esp32dev]\nboard_build.partitions = min_spiffs.csv\n
    Details for the PlatformIO documentation.

    "},{"location":"faq.html#heap-size","title":"Heap size","text":"

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

    Reducing Binary Size

    For sketches that do not require OTA feature or Custom Web pages, the build size can be reduced. See Reducing Binary Size in Basic Usage for details.

    "},{"location":"faq.html#how-placing-a-style-qualified-autoconnecttext-horizontally","title":"How placing a style-qualified AutoConnectText horizontally?","text":"

    When the style parameter is specified for AutoConnectText, it is always enclosed by the <div> tag, so the element placement direction is vertical and subsequent elements cannot be horizontal. If you want to place an element after AutoConnectText with the style, you can place the AutoConnectText horizontally by specifying the display CSS property with inline or inline-block in the style value. 

    {\n\"name\": \"text1\",\n\"type\": \"ACText\",\n\"value\": \"Hello,\",\n\"style\": \"display:inline;color:#f5ad42;font-weight:bold;margin-right:3px\"\n},\n{\n\"name\": \"text2\",\n\"type\": \"ACText\",\n\"value\": \"world\",\n\"posterior\": \"br\"\n}\n

    See also AutoConnectText chapter, CSS Flow Layout by MDN.

    "},{"location":"faq.html#how-placing-html-elements-undefined-in-autoconnectelements","title":"How placing HTML elements undefined in AutoConnectElements?","text":"

    AutoConnectElement can be applied in many cases when trying to place HTML elements that are undefined in AutoConnectElemets on custom Web pages. See Handling the custom Web Pages section.

    "},{"location":"faq.html#i-cannot-complete-to-wifi-login-from-smartphone","title":"I cannot complete to WiFi login from smartphone.","text":"

    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.

    "},{"location":"faq.html#i-cannot-see-the-custom-web-page","title":"I cannot see the custom Web page.","text":"

    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.

    "},{"location":"faq.html#nvs_open-failed-not_found-occurs","title":"nvs_open failed: NOT_FOUND occurs.","text":"

    In ESP32, NVS open failure may occur during execution of AutoConnect::begin with the following message on the Serial monitor.

    [E][Preferences.cpp:38] begin(): nvs_open failed: NOT_FOUND\n

    This is not a malfunction and expected behavior. AutoConnect will continue to execute normally.

    AutoConnect saves the credentials of the access point to which it was able to connect to the NVS of the ESP32 module as Preferences instances. The above error occurs when the area keyed for AutoConnect credentials does not exist in NVS. Usually, this error occurs immediately after erasing the ESP32 module flash or when running the AutoConnect sketch for the first time. If the AutoConnect credentials area does not exist in NVS, AutoConnect will automatically allocate it. Therefore, this error can be ignored and will not affect the execution of the sketch.

    "},{"location":"faq.html#request-handler-not-found-in-webserver","title":"Request handler not found in WebServer.","text":"

    It forms the following message as the most common form.

    request handler not found\n

    In ESP32, the above message has a detailed issuer.

    [WebServer.cpp:649] _handleRequest(): request handler not found\n

    If this message appears just by opening your custom web page or AutoConnect built-in page from a browser, it is probably the browser requesting a favicon for that html page. Please instead of prematurely assuming that the detection of this message indicates an implementation flaw, identify the URL from which the request originated. You can find it in the AutoConnect trace that outputs to the serial monitor by enabling AC_DEBUG macro.

    You can probably find the above message in the AC_DEBUG trace log. And if you can find the following trace just before that message, your sketch is working fine.

    [AC] Host:192.168.1.17,/favicon.ico,ignored\n

    It's just the browser asking for a favicon. Of course, your sketch doesn't have a favicon. That's what the \"request handler not found\" message means.

    The AC_DEBUG trace will record URL requests for which no request handler exists. If you find a [AC] Host: IP_ADDRESS, URL, ignored style message in the AC_DEBUG log, the request handler for that URL has not been registered with the WebServer. Even if your sketch has a custom web page with the said URL, it is probably causing a JSON syntax error and failing to deserialize. In such cases, the ArduinoJson Assistant can be helpful. It will find syntax errors in the JSON description for your custom web page.

    "},{"location":"faq.html#saved-credentials-are-wrong-or-lost","title":"Saved credentials are wrong or lost.","text":"

    A structure of AutoConnect saved credentials has changed two times throughout enhancement with v1.0.3 and v1.1.0. In particular, due to enhancements in v1.1.0, AutoConnectCredential data structure has lost the backward compatibility with previous versions. You must erase the flash of the ESP module using the esptool completely to save the credentials correctly with v1.1.0. 

    esptool -c esp8266 (or esp32) -p [COM_PORT] erase_flash\n

    "},{"location":"faq.html#some-autoconnect-page-is-cut-off","title":"Some AutoConnect page is cut off.","text":"

    It may be two possibilities as follows:

    1. Packet loss during transmission due to a too weak WiFi signal.
    2. Heap is insufficient memory. AutoConnect entrusts HTML generation to PageBuilder that makes heavy use the String::concatenate function and causes memory fragmentation. This is a structural problem with PageBuilder, but it is difficult to solve immediately.

    If this issue produces with your sketch, Reloading the page may recover. Also, you can check the memory running out status by rebuilding the Sketch with PageBuilder's debug log option turned on.

    If the heap memory is insufficient, the following message is displayed on the serial console.

    [PB] Failed building, free heap:<Size of free heap>\n
    "},{"location":"faq.html#submit-element-in-a-custom-web-page-does-not-react","title":"Submit element in a custom Web page does not react.","text":"

    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.

    "},{"location":"faq.html#unable-to-change-any-macro-definitions-by-the-sketch","title":"Unable to change any macro definitions by the Sketch.","text":"

    The various macro definitions that determine the configuration of AutoConnect cannot be redefined by hard-coding with Sketch. The compilation unit has a different AutoConnect library itself than the Sketch, and the configuration definitions in AutoConnectDefs.h are quoted in the compilation for AutoConnect only. For example, the following Sketch does not enable AC_DEBUG and does not change HTTP port also the menu background color:

    #define AC_DEBUG                                    // No effect\n#define AUTOCONNECT_HTTPPORT    8080                // No effect\n#define AUTOCONNECT_MENUCOLOR_BACKGROUND  \"#696969\" // No effect\n#include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect Portal;\n\nvoid setup() {\n  Portal.begin();\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    To enable them, edit AutoConnectDefs.h as the library source code directly, or supply them as the external parameters using a build system like PlatformIO with platformio.ini:

    platform = espressif8266\nboard = nodemcuv2\nboard_build.f_cpu = 160000000L\nboard_build.f_flash = 80000000L\nboard_build.flash_mode = dio\nboard_build.filesystem = littlefs\nbuild_flags =\n-DAC_DEBUG\n-DAUTOCONNECT_HTTPPORT=8080\n-DAUTOCONNECT_MENUCOLOR_BACKGROUND='\"#696969\"'\n
    "},{"location":"faq.html#unauthorize-error-without-prompting-the-login-dialog","title":"Unauthorize error without prompting the login dialog.","text":"

    The custom web pages that require authentication will occur unauthorized error always without prompting the login dialog under the captive portal state on some OS. This is a captive portal restriction and expected behavior. The captive portal web browser is almost a complete web browser, but while the captive portal session restricts the response to WWW-authenticate requests. (In intrinsically, the captive portal is a mechanism for authentication in itself)

    Once you exit from the captive portal session and connect SoftAP IP directly afresh, you can access custom web pages along with prompting a login dialog.

    "},{"location":"faq.html#uploaded-bin-via-ota-but-the-sketch-stopped-after-reboot","title":"Uploaded BIN via OTA, but the sketch stopped after reboot.","text":"

    Perhaps the current sketch as the uploader does not match the partition size of the BIN file to be uploaded. For example, if the current sketch (i.e. it performs OTA) is built with a partition table of Default.csv and the new BIN file to be updated is min_spiffs.csv.

    Also, the file system of the uploader sketch and the uploaded sketch must be the same. If the file system of the uploader sketch is SPIFFS while the uploaded BIN file is LITTLEFS, file system initialization will fail.

    "},{"location":"faq.html#still-not-stable-with-my-sketch","title":"Still, not stable with my sketch.","text":"

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

    "},{"location":"faq.html#1-change-wifi-channel","title":"1. Change WiFi channel","text":"

    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;\nAutoConnectConfig config;\n\nconfig.channel = 3;     // Specifies a channel number that matches the AP\nportal.config(config);  // Apply channel configuration\nportal.begin();         // Start the portal\n

    Channel selection guide

    Espressif Systems has released a channel selection guide.

    "},{"location":"faq.html#2-change-the-arduino-core-version","title":"2. Change the arduino core version","text":"

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

    "},{"location":"faq.html#with-esp8266-arduino-core","title":"with ESP8266 arduino core","text":"

    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.

    "},{"location":"faq.html#with-esp32-arduino-core","title":"with ESP32 arduino core","text":"

    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.

    "},{"location":"faq.html#3-turn-on-the-debug-log-options","title":"3. Turn on the debug log options","text":"

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

    AutoConnectDefs.h

    #define AC_DEBUG\n

    PageBuilder.h 3

    #define PB_DEBUG\n

    How to enable the AC_DEBUG, PB_DEBUG

    See Debug Print section, and one similarly too.

    "},{"location":"faq.html#4-reports-the-issue-to-autoconnect-github-repository","title":"4. Reports the issue to AutoConnect Github repository","text":"

    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:4

    • Hardware module
    • Arduino core version Including the upstream commit ID if necessary
    • Operating System which you use
    • Your smartphone OS and version (Especially for Android)
    • Your AP information (IP, channel) if related
    • lwIP variant
    • Problem description
    • If you have a STACK DUMP decoded result with formatted by the code block tag
    • the Sketch code with formatted by the code block tag (Reduce to the reproducible minimum code for the problem)
    • Debug messages output (Including arduino core)

    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.

    1. In this case, the underlying factor is mainly the bloat of ESP-IDF. This issue is also being discussed by many contributors of the Arduino core development community and efforts are underway to make a solution. Refs: espressif/arduino-esp32/issue#5630 \u21a9

    2. This issue has been resolved in ESP8266 core 2.5.0 and later.\u00a0\u21a9

    3. PageBuilder.h exists in the libraries/PageBuilder/src directory under your sketch folder.\u00a0\u21a9

    4. Without this information, the reproducibility of the problem is reduced, making diagnosis and analysis difficult.\u00a0\u21a9

    "},{"location":"filesystem.html","title":"Using Filesystem","text":""},{"location":"filesystem.html#selecting-appropriate-filesystem","title":"Selecting appropriate Filesystem","text":"

    There are two file systems for utilizing the onboard flash on the ESP8266 or the ESP32, SPIFFS and LittleFS. The file system to be applied is determined at the time of the sketch built. AutoConnect will determine as a file system to apply either SPIFFS or LittleFS according to the macro definition in AutoConnectDefs.h and has the following two definitions to include the file system.

    #define AC_USE_SPIFFS\n#define AC_USE_LITTLEFS\n

    The AC_USE_SPIFFS and AC_USE_LITTLEFS macros declare which file system to apply. Their definitions are contradictory to each other and you cannot activate both at the same time.

    Each platform supported by AutoConnect has a default file system, which is LittleFS for ESP8266 and SPIFFS for ESP32. Neither AC_USE_SPIFFS nor AC_USE_LITTLE_FS needs to be explicitly defined as long as you use the default file system. The default file system for each platform is assumed.

    SPIFFS has deprecated for ESP8266

    SPIFFS has deprecated on EP8266 core. AC_USE_SPIFFS flag indicates that the migration to LittleFS has not completed for the Sketch with ESP8266. You will get a warning message when you compile a sketch using SPIFFS. Also, LittleFS support on the ESP32 is expected to be in the future beyond Arduino ESP32 core v2. If you want to use the LittleFS library on your ESP32, you must use a third-party source provided externally.

    The file system intended by the sketch must match the file system applied to AutoConnect. (i.e. it is provided by the definitions of AC_USE_SPIFFS and AC_USE_LITTLEFS) For example, if the sketch includes LittleFS.h, but AC_USE_SPIFFS is defined, the sketch will not be able to sucessfully acces the built file system.

    "},{"location":"filesystem.html#filesystem-applied-to-pagebuilder-must-match-to-autoconnect","title":"Filesystem applied to PageBuilder must match to AutoConnect","text":"

    Also, PageBuilder has a definition of file system choices to use, similar to AutoConnect. It is the definition of PB_USE_SPIFFS and PB_USE_LITTLEFS in PageBuilder.h of PageBuilder library source, and its role is the same as these of AutoConnect. 

    #define PB_USE_SPIFFS\n#define PB_USE_LITTLEFS\n

    Note the version of each library

    Support for AC_USE_SPIFFS / AC_USE_LITTLEFS and PB_USE_SPIFFS / PB_USE_LITLTEFS is from AutoConnect 1.3.0 and PageBuilder 1.5.0 and later.

    "},{"location":"filesystem.html#to-determine-the-file-system-to-be-used","title":"To determine the file system to be used","text":"

    The most direct way is to edit the library source AutoConnectDefs.h directly and uncomment the definition of #define AC_USE_SPIFFS or #define AC_USE_LITTLES. In addition to that editing work, the definitions of PB_USE_SPIFFS and PB_USE_LITTLEFS in PageBuilder.h also need to be changed. Their definitions must match the AC_USE_SPIFFS and AC_USE_LITTLEFS definitions in AutoConnectDefs.h. PB_USE_SPIFFS enabled and AC_USE_LITTLEFS enabled state is not allowed, and vice-versa.

    However, this way makes the AutoConnect library inconsistent and may include your unintended file system on a project-by-project basis. By using PlatformIO, you can efficiently select a file system. That way, you can choose any file system for each project without polluting the library source.

    To apply a different file system for each project without modifying the library source code, add the following build_flags directive to platformio.ini as a project configuration file of each project.

    [env:esp_wroom_02]\nplatform = espressif8266\nboard = esp_wroom_02\nframework = arduino\nlib_extra_dirs = ~/Documents/Arduino/libraries\nlib_ldf_mode = deep+\nbuild_flags =\n-DAC_USE_SPIFFS\n-DPB_USE_SPIFFS\nupload_speed = 921600\nmonitor_speed = 115200\n

    The build_flags as build options allows PlatformIO can provide preprocessor macro definitions. -D name for build_flags, which specifies a predefined content, is treated as 1 equal to the #define directive.

    Library dependency search with PlatformIO

    If #include <LITTLEFS.h> becomes Not Found with PlatformIO built, try specifying lib_ldf_mode=deep+ with platformio.ini. Due to the deep nesting by preprocessor instructions, the include file cannot be detected by the chain mode (nested include search) of PlatformIO's Library Dependency Finder. See also FAQ.

    LittleFS for ESP8266 with PlatformIO

    The SPIFFS file system is used by default in order to keep legacy projects compatible. To choose LittleFS as the file system with ESP8266 platform, it should be explicitly specified using board_build.filesystem option in platformio.ini as follows: 

    [env:esp_wroom_02]\nplatform = espressif8266\nframework = arduino\nboard = esp_wroom_02\nboard_build.filesystem = littlefs\n...\n

    "},{"location":"filesystem.html#practical-situations-where-autoconnect-uses-a-file-system","title":"Practical situations where AutoConnect uses a file system","text":"

    AutoConnect has the ability to use the file system that is:

    • Place the custom web page defined in the JSON document in an external file and separate it from the sketch source code. This approach allows you to change the layout design of your custom web page by simply modifying the external file without recompiling the sketch.

    • Use the AutoConnectFile element to upload some parameters that control sketch execution to the file system on the ESP module. You can upload from the browser on the client PC via OTA.

    The following is an example of a scenario that embodies the combination of these facilities. The sketch below controls LED that blinks like heartbeat by PWM (Pulse-Width Modulation) from ESP8266. Custom web page contains an AutoConnectFile element that allows you to upload a parameter file to the ESP module from the browser on the client PC. And place the custom web page as a JSON document on the LittleFS of the ESP module.

    "},{"location":"filesystem.html#screenshot","title":"Screenshot","text":"

    The sketch UI of this scenario provides as shown by the screenshot below:

    It arranges in a very simple style to focus on how the sketch incorporating AutoConnect will handle the file system. This custom web page is loaded from LittleFS at the beginning of the sketch processing and has already been uploaded to LittleFS on the ESP8266.

    "},{"location":"filesystem.html#custom-web-page-json-definition","title":"Custom Web page JSON definition","text":"

    It has a file name as \"custom_pages.json\" and has two pages whose URI are \"/\" and \"/set\". An AutoConnectFile element named \"param\" is placed to upload a file from a client browser that contains the parameters to determine the behavior of this sketch. (ie. LED blinking cycle of the heartbeat)

    After selecting the parameter file to upload, click the AutoConnectSubmit element named \"set\". This will upload the selected file to LittleF on the ESP8266 module and start processing the sketch-coded \"/set\" page handler.

    [\n  {\n\"title\": \"Heartbeat\",\n\"uri\": \"/\",\n\"menu\": true,\n\"element\": [\n      {\n\"name\": \"param\",\n\"type\": \"ACFile\",\n\"label\": \"Parameter file:\",\n\"store\": \"fs\"\n      },\n      {\n\"name\": \"set\",\n\"type\": \"ACSubmit\",\n\"value\": \"SET\",\n\"uri\": \"/set\"\n      }\n    ]\n  },\n  {\n\"title\": \"Heartbeat\",\n\"uri\": \"/set\",\n\"menu\": false,\n\"element\": [\n      {\n\"name\": \"param\",\n\"type\": \"ACText\"\n      }\n    ]\n  }\n]\n
    "},{"location":"filesystem.html#parameter-file","title":"Parameter file","text":"

    You can make the parameters that determine the heartbeat cycle with the JSON definition using your favorite text editor as follows:

    {\n\"led\": 16,\n\"freq\": 1000,\n\"range\": 511,\n\"cycle\": 2\n}\n

    We use PWM to make the LED blinking gently repeat like a heartbeat. In addition, we also need the interval time to blink. We will put these values in the parameter file.

    • led : Blinking LED assignment pin (Depending on your ESP8266 module)
    • freq : PWM frequency [ms] (milliseconds unit)
    • range : PWM range (511 ~ 1023, 511 ~ 767 is recommended for smooth blinking)
    • cycle : Heartbeat cycle [s] (seconds unit. 4 seconds or less recommended)

    Save the text file with these settings as param.json on your PC. You can upload this file to the ESP8266 module using the AutoConnectFile element named param above. When executing a sketch, the settings described in this file will be read by the /set custom web page handler to control the analog output of the ESP8266 module.

    "},{"location":"filesystem.html#the-sketch","title":"The sketch","text":"

    Below is the final sketch that allows the LED to blink like a heartbeat according to the settings contained in the two external files custome_pages.json and param.json mentioned above.

    #include <Arduino.h>\n#include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <LittleFS.h>\n#include <AutoConnect.h>\n#include <ArduinoJson.h>\nAutoConnect portal;\nAutoConnectConfig config;\n\n// File names\nconst char* paramFile = \"param.json\";\nconst char* auxFile = \"custom_pages.json\";\n\n// Parameters for LED PWM control\nunsigned int  led = 0;\nunsigned long freq;\nunsigned long range;\nunsigned int  cycle;\nconst unsigned long reso = 10;\nint duty;\nint increase;\nunsigned long tmCycle;\nunsigned long tmStep;\n\nString onSet(AutoConnectAux& aux, PageArgument& args) {\n  StaticJsonDocument<128> doc;\n\n// Open uploaded parameter and parse parameters with JSON\n  File param = LittleFS.open(paramFile, \"r\");\nif (param) {\n    DeserializationError error = deserializeJson(doc, param);\nif (error) {\n      aux[\"param\"].value = \"JSON de-serialization failed: \" + String(error.c_str());\n    }\nelse {\n// Parsing the parameter JSON was successful.\n// Read the parameters as JSON document from the uploaded parameter file.\n      led = doc[\"led\"];\n      freq = doc[\"freq\"];\n      range = doc[\"range\"];\n      cycle = doc[\"cycle\"];\n\n// Set PWM conditions\n      analogWriteFreq(freq);\n      analogWriteRange(range);\n      increase = ((range / cycle) / reso) / 2;\n      duty = 0;\n      tmCycle = millis();\n      tmStep = tmCycle;\n\n// Echo back uploaded parameters to Custom web page\n      String  result;\n      serializeJson(doc, result);\n      aux[\"param\"].value = result;\n    }\n    param.close();\n  }\nelse\n    aux[\"param\"].value = String(paramFile) + String(\" open error\");\n\nreturn String();\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  LittleFS.begin();\n// Load Custom web pages from LittleFS\n  File aux = LittleFS.open(auxFile, \"r\");\nif (aux) {\n// Attach Custom web page and handler\n    portal.load(aux);\n    portal.on(\"/set\", onSet);\n\n// Exclude the HOME item from the menu as the custom web page will\n// be placed in the root path.\n    config.menuItems = 0x00ff & ~(AC_MENUITEM_HOME | AC_MENUITEM_DEVINFO);\n    config.ota = AC_OTA_BUILTIN;  // You can even update this sketch remotely\n    portal.config(config);\n\n// You can close the file once the custom web page has finished loading.\n    aux.close();\n  }\nelse {\n    Serial.print(auxFile);\n    Serial.println(\" open error\");\n  }\n\n  portal.begin();\n}\n\nvoid loop() {\nif (led) {  // The heartbeat begins after the led parameter will set.\nif (millis() - tmStep > abs(increase)) {\n      duty += increase;\nif (duty < 0)\n        duty = 0;\n      analogWrite(led, duty);\n      tmStep = millis();\n    }\nif (millis() - tmCycle > (cycle * 1000) / 2) {\n      increase *= -1;\n      tmCycle = millis();\n    }\n  }\n  portal.handleClient();\n}\n

    This final sketch consists of four components:

    • Include appropriate header files: Include the appropriate file system header files to operate the external files of the ESP8266 module by the sketch. For LitteleFS, it is #include <LittleFS.h>. Also, since we wrote the parameter setting file in JSON, we will deserialize it using ArduinoJson. The header required for the deserialization process is #include <ArduinoJson.h>.

    • setup: In the sketch setup phase, the procedure is similar to other sketches when using AutoConnect. In this case, the following steps are appended to apply the file system.

      • Start the file system as LittleFS. Then open the custom web page definition file. Upload this file as a LittleFS file on the ESP8266 module in advance.
      • Arduino can handle the opened file as a stream, so register the file stream with AutoConnect using the AutoConnect::load function. This procedure is also detailed in the documentation Loading & saving AutoConnectElements with JSON.

    • loop: In the loop, the duty is calculated and analog output is performed to the LED pin. Duty is a value for PWM. PWM is a modulation method that can adjust strength of electric power by turning the pulse train on and off at regular intervals and change the on-time width. In this sketch, the LED on-time is dynamically changed and supplied as the PWM duty to achieve the slow blinking like the heartbeat. The loop calculates this dynamic on-time change from the heartbeat cycle time (cycle setting of param.json) and executes analogWrite at the appropriate timing. The freq value in the parameter settings indicates the regular interval of the PWM.

      Do not use delay in a loop to create time variation for PWM

      It is a fault often found in careless sketches. An HTTP request is sent to the ESP8266 module each time you interact with the AutoConnect menu from the client browser. The request is properly answered by the AutoConnect::handleClient function. The delay function in the loop obstructs the flow of its processing. Remember that the sketching process will be suspended for the time period you specify by the delay.

    • /set custom web page handler: It is named onSet function in above sketch. The onSet handler retrieves PWM settings using ArduinoJson deserialization from the uploaded param.json file. Each fetched setting value is stored in each global variable. The loop function refers to that value to achieve PWM pulse control.

    "},{"location":"filesystem.html#adapts-the-sketch-to-the-selected-file-system-in-autoconnect","title":"Adapts the sketch to the selected file system in AutoConnect","text":"

    AutoConnect determines the appropriate file system instance according to the AC_USE_SPIFFS or AC_USE_LITTLEFS macro definition. This determination is made by the c++ preprocessor when the sketch is built. It then exports a macro definition that identifies the determined file system. Its macro definition allows the sketch to reference a valid file system after including the AutoConnect.h header file.

    The following two macro definitions, which can be referenced after including the AutoConnect.h header file, help the sketch choose the appropriate file system.

    • AUTOCONNECT_USE_SPIFFS: AutoConnect uses SPIFFS. The sketch should include SPIFFS.h. Also, the file system instance is SPIFFS.
    • AUTOCONNECT_USE_LITTLEFS: AutoConnect uses LITTLEFS. The sketch should include LittleFS.h. Also, the file system instance is LittleFS.

    Combining the c++ preprocessor directives with the two macro definitions above, you can write a common sketch code for both SPIFFS and LittleFS, as shown in the code as follows:

    #include <AutoConnect.h>\n\n#ifdef AUTOCONNECT_USE_LITTLEFS\n#include <LittleFS.h>\n#if defined(ARDUINO_ARCH_ESP8266)\nFS& FlashFS = LittleFS;\n#elif defined(ARDUINO_ARCH_ESP32)\nfs::LittleFSFS& FlashFS = LittleFS;\n#endif\n#else\n#include <FS.h>\n#include <SPIFFS.h>\nfs::SPIFFSFS& FlashFS = SPIFFS;\n#endif\n\nvoid setup() {\n  ...\n  FlashFS.begin();\n  ...\n}\n
    "},{"location":"gettingstarted.html","title":"Getting started","text":""},{"location":"gettingstarted.html#lets-do-the-most-simple-sketch","title":"Let's do the most simple sketch","text":"

    Open the Arduino IDE, write the following sketch and upload it. The feature of this sketch is that the SSID and Password are not coded.

    #include <ESP8266WiFi.h>          // Replace with WiFi.h for ESP32\n#include <ESP8266WebServer.h>     // Replace with WebServer.h for ESP32\n#include <AutoConnect.h>\n\nESP8266WebServer Server;          // Replace with WebServer for ESP32\nAutoConnect      Portal(Server);\n\nvoid rootPage() {\nchar content[] = \"Hello, world\";\n  Server.send(200, \"text/plain\", content);\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  Server.on(\"/\", rootPage);\nif (Portal.begin()) {\n    Serial.println(\"WiFi connected: \" + WiFi.localIP().toString());\n  }\n}\n\nvoid loop() {\n    Portal.handleClient();\n}\n

    The above code can be applied to ESP8266. To apply to ESP32, replace ESP8266WebServer class with WebServer and include WiFi.h and WebServer.h of arduino-esp32 appropriately.

    "},{"location":"gettingstarted.html#run-at-first","title":"Run at first","text":"

    After about 30 seconds, if the ESP8266 cannot connect to nearby Wi-Fi spot, you pull out your smartphone and open Wi-Fi settings from the Settings Apps. You can see the esp8266ap 1 in the list of \"CHOOSE A NETWORK...\". Then tap the esp8266ap and enter password 12345678, a something screen pops up automatically as shown below.

    This is the AutoConnect statistics screen. This screen displays the current status of the established connection, WiFi mode, IP address, free memory size, and etc. Also, the hamburger icon is the control menu of AutoConnect seems at the upper right. By tap the hamburger icon, the control menu appears as the below.

    "},{"location":"gettingstarted.html#join-to-the-new-access-point","title":"Join to the new access point","text":"

    Here, tap \"Configure new AP\" to connect the new access point then the SSID configuration screen would be shown. Enter the SSID and Passphrase and tap apply to start connecting the access point.

    Can be configured with static IP

    Since v1.1.0, Configure new AP menu can configure for WIFI_STA with static IP.

    "},{"location":"gettingstarted.html#connection-establishment","title":"Connection establishment","text":"

    After connection established, the current status screen will appear. It is already connected to WLAN with WiFi mode as WIFI_AP_STA and the IP connection status is displayed there including the SSID. Then at this screen, you have two options for the next step.

    For one, continues execution of the Sketch while keeping this connection. You can access ESP8266 via browser through the established IP address after cancel to \"Log in\" by upper right on the screen. Or, \"RESET\" can be selected. The ESP8266 resets and reboots. After that, immediately before the connection will be restored automatically with WIFI_STA mode.

    "},{"location":"gettingstarted.html#run-for-usually","title":"Run for usually","text":"

    The IP address of ESP8266 would be displayed on the serial monitor after connection restored. Please access its address from the browser. The \"Hello, world\" page will respond. It's the page that was handled by in the Sketch with \"on\" function of ESP8266WebServer.

    1. When applied to ESP32, SSID will appear as esp32ap.\u00a0\u21a9

    "},{"location":"howtoembed.html","title":"How to embed","text":""},{"location":"howtoembed.html#embed-the-autoconnect-to-the-sketch","title":"Embed the AutoConnect to the Sketch","text":"

    Here hold two case examples. Both examples perform the same function. Only how to incorporate the AutoConnect into the Sketch differs. Also included in the sample folder, HandlePortal.ino also shows how to use the PageBuilder library for HTML assemblies.

    "},{"location":"howtoembed.html#what-does-this-example-do","title":"What does this example do?","text":"

    Uses the web interface to light the LED connected to the D0 (sometimes called BUILTIN_LED) port of the NodeMCU module like the following animation.

    Access to the ESP8266 module connected WiFi from the browser then the page contains the current value of the D0 port would be displayed. The page has the buttons to switch the port value. The LED will blink according to the value with clicked by the button. This example is a typical sketch of manipulating ESP8266's GPIO via WLAN.

    Embed AutoConnect library into this sketch. There are few places to be changed. And you can use AutoConnect's captive portal function to establish a connection freely to other WiFi spots.

    "},{"location":"howtoembed.html#embed-autoconnect","title":"Embed AutoConnect","text":""},{"location":"howtoembed.html#pattern-a","title":"Pattern A.","text":"

    Bind to ESP8266WebServer, performs handleClient with handleRequest.

    In what situations should the handleRequest be used.

    It is something needs to be done immediately after the handle client. It is better to call only AutoConnect::handleClient whenever possible.

    "},{"location":"howtoembed.html#pattern-b","title":"Pattern B.","text":"

    Declare only AutoConnect, performs handleClient.

    "},{"location":"howtoembed.html#used-with-mqtt-as-a-client-application","title":"Used with MQTT as a client application","text":"

    The effect of AutoConnect is not only for ESP8266/ESP32 as the web server. It has advantages for something WiFi client as well. For example, AutoConnect is also convenient for publishing MQTT messages from various measurement points. Even if the SSID is different for each measurement point, it is not necessary to modify the Sketch.

    In this example, it is trying to publish a WiFi signal strength being received ESP8266 through the services on the cloud that can visualize the live data streams for IoT. Using the IoT platform provided by ThingSpeak\u2122, the ESP8266 publishes RSSI values to ThingSpeak MQTT broker channel via the MQTT client library.

    This example is a good indication of the usefulness of AutoConnect, as RSSI values can typically measure different intensities for each access point. By simply adding a few lines to the Sketch, you do not have to rewrite and upload the Sketch for each access point.

    "},{"location":"howtoembed.html#advance-procedures","title":"Advance procedures","text":"
    • Arduino Client for MQTT - It's the PubSubClient, install it to Arduino IDE. If you have the latest version already, this step does not need.
    • Create a channel on ThingSpeak.
    • Register the ESP module as an MQTT device to a ThingSpeak channel, allowing it to be published and subscribed to on that channel.
    • Get the Channel API Keys and MQTT device credentials from ThingSpeak, and put its keys to the Sketch.

    The ThingSpeak is the open IoT platform. It is capable of sending data privately to the cloud and analyzing, visualizing its data. If you do not have an account of ThingSpeak, you need that account to proceed further. ThingSpeak has the free plan for the account which uses within the scope of this example.1 You can sign up with the ThingSpeak sign-up page.

    Whether you should do sign-up or not.

    You are entrusted with the final judgment of account creation for ThingSpeak. Create an account at your own risk.

    "},{"location":"howtoembed.html#create-a-channel-on-thingspeak","title":"Create a channel on ThingSpeak","text":"

    Sign in ThingSpeak. Select Channels to show the My Channels, then click New Channel.

    At the New Channel screen, enter each field as a below. And click Save Channel at the bottom of the screen to save.

    • Name: ESP8266 Signal Strength
    • Description: ESP8266 RSSI publish
    • Field1: RSSI

    "},{"location":"howtoembed.html#get-channel-id-and-api-keys","title":"Get Channel ID and API Keys","text":"

    The channel successfully created, you can see the channel status screen as a below. Channel ID is displayed there.2

    Here, switch the channel status tab to API Keys. The API key required to publish the message is the Write API Key.

    The last key you need is the User API Key and can be confirmed it in the user profile. Pull down Account from the top menu, select My profile. Then you can see the ThingSpeak settings and the User API Key is displayed middle of this screen.

    "},{"location":"howtoembed.html#add-a-new-mqtt-device","title":"Add a new MQTT Device","text":"

    Since January 2022, the ThingSpeak channel authentication scheme has changed, and the following procedures are for the new authentication. You will need to obtain the credentials of the MQTT device by registering it with the channel you created in the previous step.

    Once you have defined your ThingSpeak channel, you can define devices: select MQTT from the Devices menu that appears in ThingSpeak's channel information to begin registering devices.

    Give the device a name on the next page that appears after you select the MQTT device. In this example, its device should be the ESP module that the ThingSpeak MQTT channel would identify. You then specify the channel and message type you want to allow for the device. (i.e., the ESP module)

    Upon successful registration of the MQTT device, Client ID, Username, and Password are issued as credentials for the device. You can retrieve the credentials and save them as JSON. After downloading the credential file, open it with a text editor and check the contents.

    "},{"location":"howtoembed.html#sketch-publishes-messages","title":"Sketch publishes messages","text":"

    The mqttRSSI.ino sketch in the AutoConnect repository is the complete code for publishing RSSI to the ThingSpeak channel. The sketch comes with an AutoConnectAux custom Web page to flexibly configure channel information created as a ThingSpeak channel.

    Parameters for the ThingSpeak MQTT channels

    Various settings of the MQTT Setting for the ThingSpeak channels via the above AutoConnectAux are following:

    • Server: mqtt3.thingspeak.com
    • User API Key: Specify the User API Key that can be confirmed with ThingSpeak My Profile page.
    • Channel ID: Specify the channel ID that can be confirmed with ThingSpeak My Channels page.
    • Write API Key: Specify the Write API Key that can be confirmed by following navigate to \"ThingSpeak My Channels > Your Channel Name > API Keys Tab > Write API Key\".
    • Client ID: Specify the client ID from the MQTT Devices page according to the previous step.
    • Username: Specify the user name from the MQTT Devices page according to the previous step.
    • Password: Specify the password from the MQTT Devices page according to the previous step.
    "},{"location":"howtoembed.html#publish-messages","title":"Publish messages","text":"

    After uploading the mqttRSSI.ino and restarting the ESP module, Messages will begin to be issued via the connected WiFi access point. The message will carry the RSSI value of the current WiFi signal strength; changes in signal strength due to RSSI will be displayed on the ThingSpeak Channel Stats page.

    "},{"location":"howtoembed.html#how-embed-to-your-sketches","title":"How embed to your sketches","text":"

    For the client sketches, the code required to connect to WiFi is the following four parts only.

    1. #include directive3

      Include AutoConnect.h header file behind the include of ESP8266WiFi.h.

    2. Declare AutoConnect

      The declaration of the AutoConnect variable is not accompanied by ESP8266WebServer.

    3. Invokes \"begin()\"

      Call AutoConnect::begin. If you need to assign a static IP address, executes AutoConnectConfig before that.

    4. Performs \"handleClent()\" in \"loop()\"

      Invokes AutoConnect::handleClient() at inside loop() to enable the AutoConnect menu.

    1. As of March 21, 2018.\u00a0\u21a9

    2. '454951' in the example above, but your channel ID should be different.\u00a0\u21a9

    3. #include <ESP8266WebServer.h> does not necessary for uses only client.\u00a0\u21a9

    "},{"location":"license.html","title":"License","text":"

    MIT License

    Copyright \u00a9 2018-2023 Hieromon Ikasamo

    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Acknowledgments

    Each of the following libraries used by AutoConnect is under its license:

    • The Luxbar is licensed under the MIT License. https://github.com/balzss/luxbar
    • ArduinoJson is licensed under the MIT License. https://arduinojson.org/
    "},{"location":"lsbegin.html","title":"Inside AutoConnect::begin","text":""},{"location":"lsbegin.html#autoconnectbegin-logic-sequence","title":"AutoConnect::begin logic sequence","text":"

    The following parameters of AutoConnectConfig affect the behavior and control a logic sequence of AutoConnect::begin function. These parameters are evaluated on a case-by-case basis and may not be valid in all situations. The Sketch must consider the role of these parameters and the conditions under which they will work as intended. You need to understand what happens when using these parameters in combination.

    • autoReconnect : Attempts re-connect with past SSID by saved credential.
    • autoRise : Controls starting the captive portal.
    • immediateStart : Starts the captive portal immediately, without the 1st-WiFi.begin.
    • portalTimeout : Time out limit for the portal.
    • retainPortal : Keep DNS server functioning for the captive portal.

    The following chart shows the AutoConnect::begin logic sequence that contains the control flow with each parameter takes effect.

    For example, AutoConnect::begin will not end without the portalTimeout while the connection not establishes, but WebServer will start to work. Also, the DNS server will start to make a series of the captive portal operation on the client device. The custom web pages now respond correctly by the two internally launched servers, and the Sketch looks like working. But AutoConnect::begin does not end yet. Especially when invoking AutoConnect::begin in the setup(), control flow does not pass to the loop().

    However, portalTimeout can be used effectively in various scenes in combination with immediateStart. Its combination is useful for implementing Sketches that can work in situations where WiFi is not always available. Namely, Sketch will support a running mode with both offline and online. If AutoConnect staying in the captive portal exceeds the time limit, Sketch can switch a process-mode to offline according to WiFi signal detection. Conversely, it can start a captive portal immediately with intentional control to shift the process-mode to online from offline. Especially, You can activate the process-mode shift manually by trigger via external switches.

    The retainPortal option allows continuing the captive portal operation even after exiting from AutoConnect::begin. This option allows the use of the automatic portal pop-ups on the smartphone devices etc. even after the ESP module has established a connection with some access point in STA mode. (Excepts blocking a series of portal processes via intentionally accessing a URL outside the scope of /_ac. eg., if you try to communicate with the mqtt server without connecting to the access point, its access will be redirected to /_ac caused by the trap of the captive portal detection)

    The AutoConnect::begin 3rd parameter

    Another parameter as the 3rd parameter of AutoConnect::begin related to timeout constrains the connection wait time after WiFi.begin. It is the CONNECTED judgment of the above chart that it has an effect.

    "},{"location":"menu.html","title":"AutoConnect menu","text":"

    Luxbar

    The AutoConnect menu is developed using the LuxBar which is licensed under the MIT License. See the License.

    "},{"location":"menu.html#where-the-from","title":"Where the from","text":"

    The following screen will appear as the AutoConnect menu when you access to AutoConnect root URL via http://{localIP}/_ac. (eg. http://172.217.28.1/_ac) It is a top page of AutoConnect which shows the current WiFi connection statistics. To invoke the AutoConnect menu, you can tap at right on top.

    AutoConnect root URL

    It is assigned \"/_ac\" located on the local IP address of ESP8266/ESP32 module by default and can be changed with the Sketch. A local IP means Local IP at connection established or SoftAP's IP.

    "},{"location":"menu.html#right-on-top","title":"Right on top","text":"

    Currently, AutoConnect supports six 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 the flash.
    • Disconnect: Disconnects current connection.
    • Reset...: Rest the ESP8266/ESP32 module.
    • Update: OTA updates. (Optional)
    • HOME: Return to user home page.

    "},{"location":"menu.html#configure-new-ap","title":"Configure new AP","text":"

    It scans all available access points in the vicinity and display it further the WiFi signal strength and security indicator as of the detected AP. Below that, the number of discovered hidden APs will be displayed. Enter SSID and Passphrase and tap \"Apply\" to start a WiFi connection.

    If you want to configure with static IP, uncheck \"Enable DHCP\". Once the WiFi connection is established, the entered static IP1 configuration will be stored to the credentials in the flash and restored to the station configuration via the Open SSIDs menu.

    "},{"location":"menu.html#open-ssids","title":"Open SSIDs","text":"

    After WiFi connected, AutoConnect will automatically save the established SSID and password to the flash on the ESP module. Open SSIDs menu reads the saved SSID credentials and lists them as below. Listed items are clickable buttons and can initiate a connection to its access point.

    Also, this menu allows you to interactively delete the stored credentials. icon will appear next to each SSID in the Open SSIDs menu when the credential removal feature is enabled with AutoConnectConfig::menuItems. Clicking the on this screen will delete the SSID. This feature is disabled by default.

    Saved credentials data structure has changed

    A structure of AutoConnect saved credentials has changed in v1.1.0 and was lost backward compatibility. Credentials saved by AutoConnect v1.0.3 (or earlier) will not display properly with AutoConnect v1.1.0. You need to erase the flash of the ESP module using the esptool before the Sketch uploading. 

    esptool -c esp8266 (or esp32) -p [COM_PORT] erase_flash\n

    "},{"location":"menu.html#disconnect","title":"Disconnect","text":"

    It disconnects ESP8266/ESP32 from the current connection. Also, ESP8266/ESP32 can be automatically reset after WiFi cutting by instructing with the Sketch using the AutoConnect API.

    After tapping the Disconnect, you will not be able to reach the AutoConnect menu. Once disconnected, you will need to set the SSID again for connecting to the WLAN.

    "},{"location":"menu.html#reset","title":"Reset...","text":"

    Resetting the ESP8266/ESP32 module will initiate a reboot. When the module restarting, the esp8266ap or esp32ap access point will disappear from the WLAN and the ESP8266/ESP32 module will begin to reconnect a previous access point with WIFI_STA mode.

    Not every ESP8266 module will be rebooted normally

    The Reset menu is using the ESP.reset() function for ESP8266. This is an almost hardware reset. In order to resume the Sketch normally, the state of GPIO0 is important. Since this depends on the circuit implementation for each module, not every module will be rebooted normally. See also FAQ.

    "},{"location":"menu.html#custom-menu-items","title":"Custom menu items","text":"

    If the Sketch has custom Web pages, the AutoConnect menu lines them up with the AutoConnect's items. Details for Custom Web pages in AutoConnect menu.

    "},{"location":"menu.html#update","title":"Update","text":"

    If you specify AutoConnectConfig::ota to import the OTA update feature into Sketch, an item will appear in the menu list as Update.

    The Update menu item will appear only AutoConnectOTA enabled

    The Update item is displayed automatically in the menu only when AutoConnectConfig::ota is specified with AC_OTA_BUILTIN or AutoConnectUpdate is attached.

    "},{"location":"menu.html#home","title":"HOME","text":"

    A HOME item at the bottom of the menu list is a link to the home path, and the default URI is / which is defined by AUTOCONNECT_HOMEURI in AutoConnectDefs.h header file.

    #define AUTOCONNECT_HOMEURI     \"/\"\n

    Also, you can change the HOME path using the AutoConnect API. The AutoConnect::home function sets the URI as a link of the HOME item in the AutoConnect menu.

    "},{"location":"menu.html#applying-the-active-menu-items","title":"Applying the active menu items","text":"

    Each of the above menu items can be configured with a Sketch. AutoConnectConfig::menuItems specifies the menu items that will be enabled at runtime. You can also adjust available menu items using AutoConnect::enableMenu and AutoConnect::disableMenu function. It is an alternative to AutoConnectConfig::menuItems and provides a shortcut to avoid using AutoConnectConfig. For example, by disabling the Configure new AP and Disconnect item, you can prevent the configuration for unknown access points.

    AutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  config.menuItems = AC_MENUITEM_OPENSSIDS | AC_MENUITEM_RESET | AC_MENUITEM_HOME;\n  portal.config(config);\n}\n

    The next is another way to achieve the same effect.

    AutoConnect portal;\n\nvoid setup() {\n  portal.disableMenu(AC_MENUITEM_CONFIGNEW | AC_MENUITEM_DISCONNECT);\n  portal.config(config);\n}\n

    The result of executing the above Sketch is as below:

    Details for AutoConnectConfig::menuItems.

    "},{"location":"menu.html#attaching-to-autoconnect-menu","title":"Attaching to AutoConnect menu","text":"

    The AutoConnect menu can contain your sketch's web pages as extra items as a custom. It works for HTML pages implemented by the ESP8266WebServer::on handler or the WebServer::on handler for ESP32. That is, you can make them invoke the legacy web pages from the AutoConnect menu. The below screen-shot is the result of adding an example sketch for the ESP8266WebServer library known as FSBrowser to the AutoConnect menu item. It can add Edit and List items with little modification to the legacy sketch code.

    AutoConnect allows capturing the extra pages handled with ESP8266WebServer or WebServer's legacy into the AutoConnect menu. See Section Advanced Usage for detailed instructions on how to add the extra pages into its menu.

    1. AutoConnect does not check the syntax and validity of the entered IP address. If the entered static IPs are incorrect, it cannot connect to the access point.\u00a0\u21a9

    "},{"location":"menuize.html","title":"Attach the menus","text":""},{"location":"menuize.html#the-feature-of-menu-attaching-using-autoconnect","title":"The feature of menu attaching using AutoConnect","text":"

    In this section, it presents numerous ways to customize the AutoConnect menu with your Sketch. AutoConnect dynamically materializes menu items at the Sketch run time with joined AutoConnectAux as a sourced configuration. Typically, it has AutoConnectElements for page rendering in its composition but can configure a Web page as a menu item without having AutoConnectElements. In other words, the AutoConnect Menu component allows you to easily embed a navigation menu with WiFi connection expansion in your Sketch, which has legacy pages for ESP8266WebServer or WebServer of ESP32.

    "},{"location":"menuize.html#the-basic-mechanism-for-menu-generation","title":"The basic mechanism for menu generation","text":"

    Sketch can equip the AutoConnect menu by using three patterns according to the appropriate usage of the AutoConnect API.

    Basic menu It is the most basic menu for a WiFi connection only. Sketch can automatically display it using the typical calling sequence of the AutoConnect API with AutoConnect::begin and AutoConnect::handleClient. Extra menu with custom Web pages which is consisted by AutoConnectElements It is an extended menu that appears when the Sketch consists of the custom Web pages with AutoConnectAux and AutoConnectElements. Refer to section Custom Web pages section. Extra menu which contains legacy pages It provides an item for including a legacy page in the AutoConnect menu that natively uses the page request handler attached by the ESP8266WebServer::on function. (Similarly, WebServer::on for ESP32)

    The mechanism by which AutoConnect dynamically generates the menu is simple. The member variables title and uri of AutoConnectAux will be transferred into <li> HTML tag as they are. Then all <li> elements are included in the form that makes up the menu. Therefore, the Sketch can register the legacy web pages to the menu by simply declaring the title and URI with AutoConnectAux and binding it to AutoConnect.

    "},{"location":"menuize.html#place-the-item-for-the-legacy-sketches-on-the-menu","title":"Place the item for the legacy sketches on the menu","text":"

    To implement this with your sketch, use only the AutoConnectAux constructed with the title and URI of that page. AutoConnectElements is not required.

    The AutoConnect library package contains an example sketch for ESP8266WebServer known as FSBrowser. Its example is a sample implementation that supports AutoConnect without changing the structure of the original FSBrowser and has the menu item for Edit and List.

    "},{"location":"menuize.html#slightly-changes-to-adapt-fsbrowser-to-autoconnect-menu","title":"Slightly changes to adapt FSBrowser to AutoConnect menu","text":"

    The changes I made to adapt the FSBrowser to the AutoConnect menu are slight as follows:

    1. Add AutoConnect declaration.
    2. Add AutoConnectConfig declaration to replace the menu title to FSBRowser.
    3. Set the menu title using AutoConnectConfig::title.
    4. Replace the destination of the not found handler (404 handler) from ESP8266WebServer to AutoConnect. 1IMPORTANT
    5. Add AutoConnectAux using AutoConnect::append and combine an item for Edit.
    6. Add AutoConnectAux using AutoConnect::append and combine an item for List.
    7. Establish a WiFi connection using AutoConnect::begin and execute AutoConnect::handleClient in the loop, as in the case of handling the basic menu.
    "},{"location":"menuize.html#fsbrowser-with-embedded-autoconnect","title":"FSBrowser with embedded AutoConnect","text":"

    Modification for FSBrowser as follows: (Excerpt of the sketch code)

    ... and embeds a hyperlink with an icon in the bottom of the body section of index.htm contained in the data folder to jump to the AutoConnect menu.

    <p style=\"padding-top:15px;text-align:center\">\n  <a href=\"/_ac\"><img src=\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAC2klEQVRIS61VvWsUQRSfmU2pon9BUIkQUaKFaCBKgooSb2d3NSSFKbQR/KrEIiIKBiGF2CgRxEpjQNHs7mwOUcghwUQ7g58IsbGxEBWsb2f8zR177s3t3S2cA8ftzPu993vzvoaSnMu2vRKlaqgKp74Q/tE8qjQPyHGcrUrRjwlWShmDbFMURd/a6TcQwNiYUmpFCPElUebcuQ2vz6aNATMVReHEPwzfSSntDcNwNo2rI+DcvQzhpAbA40VKyV0p1Q9snzBG1qYVcYufXV1sREraDcxpyHdXgkfpRBj6Uwm2RsC5dxxmZ9pdOY9cKTISRcHTCmGiUCh4fYyplTwG2mAUbtMTBMHXOgK9QfyXEZr+TkgQ1oUwDA40hEgfIAfj+HuQRaBzAs9eKyUZ5Htx+T3ZODKG8DzOJMANhmGomJVMXPll+hx9UUAlzZrJJ4QNCDG3VEfguu7mcpmcB/gkBOtShhQhchAlu5jlLUgc9ENgyP5gf9+y6LTv+58p5zySkgwzLNOIGc8sEoT1Lc53NMlbCQQuvMxeCME1NNPVVkmH/i3IzzXDtCSA0qQQwZWOCJDY50jsQRjJmkslEOxvTcDRO6zPxOh5xZglKkYLhWM9jMVnkIsTyMT6NBj7IbOCEjm6HxNVVTo2WXqEWJZ1T8rytB6GxizyDkPhWVpBqfiXUtbo/HywYJSpA9kMamNNPZ71R9Hcm+TMHHZNGw3EuraXEUldbfvw25UdOjqOt+JhMwJd7+jSTpZaEiIcaCDwPK83jtWnTkwnunFMtxeL/ge9r4XItt1RNNaj/0GAcV2bR3U5sG3nEh6M61US+Qrfd9Bs31GGulI2GOS/8dgcQZV1w+ApjIxB7TDwF9GcNzJzoA+rD0/8HvPnXQJCt2qFCwbBTfRI7UyXumWVt+HJ9NO4XI++bdsb0YyrqXmlh+AWOLHaLqS5CLQR5EggR3YlcVS9gKeH2hnX8r8Kmi1CAsl36QAAAABJRU5ErkJggg==\" border=\"0\" title=\"AutoConnect menu\" alt=\"AutoConnect menu\"/></a>\n</p>\n

    1. Missing this step, AutoConnect cannot handle the menu. Refs: 404 handler \u21a9

    "},{"location":"otabrowser.html","title":"OTA via Web Browser","text":""},{"location":"otabrowser.html#updates-with-the-web-browserupdated-wv115","title":"Updates with the Web Browser\u00a0UPDATED w/v1.1.5","text":"

    AutoConnect features a built-in OTA function to update ESP module firmware. You can easily make the Sketch that equips OTA and able to operate with the AutoConnect menu. As the AutoConnectOTA class, which is compliant with OTA updates using a web browser as described in the ESP8266 Arduino Core documentation.

    You will be able to import the AutoConnectOTA class into your sketch just by specifying AutoConnectConfig::ota. By incorporating the AutoConnectOTA class into your Sketch, you can have an OTA updating feature which able to updating binary sketch from the AutoConnect menu.

    The AutoConnectOTA feature is implemented based on the Updater class of the ESP8266 arduino core library. Its Updater class is also supported by the ESP32 Arduino core, so you can commonly import AutoConnectOTA into the Sketch without being aware of the differences between ESP8266 and ESP32 modules.

    Limitation of AutoConnectOTA with authentication

    AutoConnectOTA does not support authentication in v1.1.5 yet. It is planned for inclusion in AutoConnect v1.2.0, which will support HTTP authentication.

    "},{"location":"otabrowser.html#how-to-embed-autoconnectota-in-your-sketch","title":"How to embed AutoConnectOTA in your sketch","text":"

    To embed the AutoConnectOTA class into your sketch, basically follow these steps:

    1. Include ESP8266WiFi.h, ESP8266WebServer.h and AutoConnect.h as usual.1
    2. Declare an ESP8266WebServer object. It's optional. (as WebServer for ESP32)
    3. Declare an AutoConnect object, with an argument as ESP8266WebServer if separate the declarations.
    4. Declare an AutoConnectConfig object.
    5. Declare an AutoConnectAux object for your sketch own if needed.
    6. Perform the following procedure steps in the setup() function:
      1. Set AutoConnectConfig::ota to AC_OTA_BUILTIN and configure AutoConnect.
      2. Load the AutoConnectAux pages declared in step #4 for your application.
      3. Join these pages to AutoConnect.
      4. Invokes AutoConnect::begin function.
    7. Invokes AutoConnect::handleClient function in the loop().
    #include <ESP8266WiFi.h>            // Step #1\n#include <ESP8266WebServer.h>       // Step #1\n#include <AutoConnect.h>            // Step #1\n\nESP8266WebServer  server;           // Step #2\nAutoConnect       portal(server);   // Step #3\nAutoConnectConfig config;           // Step #4\nAutoConnectAux    hello;            // Step #5\n\nstatic const char HELLO_PAGE[] PROGMEM = R\"(\n{ \"title\": \"Hello world\", \"uri\": \"/\", \"menu\": true, \"element\": [\n    { \"name\": \"caption\", \"type\": \"ACText\", \"value\": \"<h2>Hello, world</h2>\",  \"style\": \"text-align:center;color:#2f4f4f;padding:10px;\" },\n    { \"name\": \"content\", \"type\": \"ACText\", \"value\": \"In this page, place the custom web page handled by the Sketch application.\" } ]\n}\n)\";                                 // Step #5\n\nvoid setup() {\n  config.ota = AC_OTA_BUILTIN;      // Step #6.a\n  portal.config(config);            // Step #6.a\n  hello.load(HELLO_PAGE);           // Step #6.b\n  portal.join({ hello });           // Step #6.c\n  portal.begin();                   // Step #6.d\n}\n\nvoid loop() {\n  portal.handleClient();            // Step #7\n}\n

    How LED ticking during updates

    AutoConnectOTA applies LED ticking during updates automatically. The destination LED port and ticker drive depends on AutoConnectConfig::tickerPort and AutoConnectConfig::tickerOn specifying.

    IMPORTANT The AutoConnectOTA activates the ticker constantly regardless of the AutoConnectConfig::ticker value. If you want to stop the ticker output to GPIO during updates, give 0xff to AutoConnectConfig::tickerPort.

    "},{"location":"otabrowser.html#autoconnectota-allocation-uri","title":"AutoConnectOTA allocation URI","text":"

    AutoConnectOTA has implemented using AutoConnectAUX. So it occupies two URIs by default. An update operation page is assigned to AUTOCONNECT_URI_UPDATE and the binary file uploader for the update is assigned to AUTOCONNECT_URI_UPDATE_ACT. These symbols are defined in the AutoConnectDefs.h header file as follows:

    #define AUTOCONNECT_URI             \"/_ac\"\n#define AUTOCONNECT_URI_UPDATE      AUTOCONNECT_URI \"/update\"\n#define AUTOCONNECT_URI_UPDATE_ACT  AUTOCONNECT_URI \"/update_act\"\n

    Therefore, the normal Sketch that imports AutoConnectOTA while keeping the default, you cannot use the two URIs /_ac/update and /_ac/update_act for your specific. If you want to use the URIs for any purpose other than AutoConnectOTA, you need to override the AutoConnectDefs.h definition at compile time. It can be overwritten by giving the build flags for platformio.ini as follows with the PlatformIO environment for example.

    build_flags = -DAUTOCONNECT_URI_UPDATE='\"/YOURURI\"'\n-DAUTOCONNECT_URI_UPDATE_ACT='\"/YOURURIACT\"'\n
    "},{"location":"otabrowser.html#timing-of-autoconnectota-instantiation","title":"Timing of AutoConnectOTA instantiation","text":"

    It will be born during AutoConnect::handleClient process. AutoConnect will evaluate the enabled state of AutoConnectConfig::ota each time the handleClient is executed, and if OTA is enabled then it creates an AutoConnectAux internally and assigns it to the update page. At this time, AutoConnectOTA is also instantiated together. The generated AUX page containing AutoConnectOTA is bound to AutoConnect inside the AutoConnect::handleClient process.

    If you want to attach AutoConnectOTA dynamically with an external trigger, you can sketch like this: This sketch imports the OTA update feature with an external switch assigned to the GPIO pin. While the trigger not occurs, AutoConnectOTA will not be imported into Sketch and will not appear on the menu list.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\n#define TRIGGER 4   // pin assigned to external trigger switch\n\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  pinMode(TRIGGER, INPUT);\n  portal.begin();\n}\n\nvoid loop() {\nif (digitalRead(TRIGGER) == HIGH) {\n    config.ota = AC_OTA_BUILTIN;\n    portal.config(config);\n  }\n  portal.handleClient();\n}\n

    AutoConnectOTA cannot detach dynamically

    Once imported, AutoConnectOTA cannot be removed from the Sketch. It can be only excluded from the menu by overriding AutoConnectConfig::menuItems. In this case, the AutoConnectOTA instance remains as a residue.

    "},{"location":"otabrowser.html#authentication-with-autoconnectota","title":"Authentication with AutoConnectOTA","text":"

    HTTP authentication of AutoConnect is also effective for OTA. Since the implementation of AutoConnectOTA is based on AutoConnectAux, the AutoConnectConfig::auth setting is valid for AutoConnectOTA as well. Also, it allows you to make authentication only on the OTA page while various custom Web pages coexist.

    The AC_AUTH_BASIC or AC_AUTH_DIGEST setting to the AutoConnectConfig::auth enables HTTP authentication. If it is in combination with AC_AUTHSCOPE_PARTIAL specified AutoConnectConfig::authScope setting, only an OTA page will be authenticated, excluding other custom Web pages that co-exist.

    AutoConnect portal;\nAutoConnectConfig config;\nAutoConnectAux aux(\"/aux\", \"AUX\");\n\nvoid setup() {\n// Join some custom web page\n  portal.join(aux);\n\n// Add OTA into the Sketch\n  config.ota = AC_OTA_BUILTIN;\n// Enable authentication on OTA page only\n  config.auth = AC_AUTH_DIGEST;\n  config.authScope = AC_AUTHSCOPE_PARTIAL;\n// Configure other settings\n  ...\n\n// Apply configuration settings\n  portal.config(config);\n  portal.begin();\n}\n
    "},{"location":"otabrowser.html#how-to-make-the-binary-sketch","title":"How to make the binary sketch","text":"

    Binary sketch files for updating can be retrieved using the Arduino IDE. Open the Sketch menu and select the Export compiled Binary, then starts compilation.

    When the compilation is complete, a binary sketch will save with the extension .bin in the same folder as the Sketch.

    "},{"location":"otabrowser.html#select-a-partition-scheme-to-enable-ota-wesp32","title":"Select a partition scheme to enable OTA w/ESP32","text":"

    To enable OTA on the ESP32, you need to build a sketch with a partition scheme that has reserved a binary sketch space for OTA. The ESP32 Arduino core comes with a variety of pre-configured partition schemes that can be selected from the Tools menu in the Arduino IDE.

    In most cases, this is simply a matter of selecting a built-in partition scheme with a reserved OTA area from the Tools menu in the Arduino IDE. However, Of the various ESP32-based modules, only a few have many partition schemes pre-configured. If you cannot find a partition scheme with reserved OTA space for your ESP32 module, you will need to modify boards.txt as the board configuration file included in the ESP32Arduino core distribution. The WebCamServer.ino example in the AutoConnect library shows the changes to boards.txt for esp32cam. But this modification is not recommended as it can inadvertently destroy the board configuration and will be overwritten and restored by the Arduino core version upstreams.

    Another way to choose a partition scheme is to use PlatformIO for your build system. You can easily select the reserved partition scheme for the OTA area using PlatformIO. When using PlatformIO, you can select a partition scheme with OTA reserved space by simply writing the following line in the platformio.ini file.

    board_build.partitions = min_spiffs.csv\n
    "},{"location":"otabrowser.html#ota-updates-wbrowser-without-using-autoconnectota","title":"OTA updates w/browser without using AutoConnectOTA","text":"

    The legacy OTA method based on ESP8266HTTPUpdateServer without AutoConnectOTA is still valid. To embed the ESP8266HTTPUpdateServer class with AutoConnect into your sketch, basically follow these steps:

    1. Include ESP8266HTTPUpdateServer.h, also WiFiClient.h, in addition to the usual directives as ESP8266WebServer.h and AutoConnect.h.2
    2. Declare an ESP8266WebServer object. (In ESP32, as WebServer)
    3. Declare an ESP8266HTTPUpdateServer object.
    4. Declare an AutoConnect object with an ESP8266WebServer object as an argument.
    5. Declare an AutoConnectAux object for the update operation page.
    6. Assign /update to the URI of the update dialog page.
    7. Assign any title as the AutoConnect menu for the update dialog page.
    8. Declare additional AutoConnectAux pages for your application intention if needed.
    9. Perform the following procedure steps in the setup() function:
      1. Invokes ESP8288HTTPUpdateServer::setup function, specifies the USERNAME and the PASSWORD as needed.
      2. Load the AutoConnectAux pages declared in step #8 for your application. (Except the update dialog page)
      3. Join these pages to AutoConnect along with the update dialog page declared in step #5.
      4. Invokes AutoConnect::begin function.
    10. Invokes AutoConnect::handleClient function in the loop(). 
    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <ESP8266HTTPUpdateServer.h>    // Step #1\n#include <WiFiClient.h>                 // Step #1\n#include <AutoConnect.h>\n\nstatic const char HELLO_PAGE[] PROGMEM = R\"(\n{ \"title\": \"Hello world\", \"uri\": \"/\", \"menu\": true, \"element\": [\n    { \"name\": \"caption\", \"type\": \"ACText\", \"value\": \"<h2>Hello, world</h2>\",  \"style\": \"text-align:center;color:#2f4f4f;padding:10px;\" },\n    { \"name\": \"content\", \"type\": \"ACText\", \"value\": \"In this page, place the custom web page handled by the Sketch application.\" } ]\n}\n)\";\n\nESP8266WebServer httpServer;                // Step #2\nESP8266HTTPUpdateServer httpUpdate;         // Step #3\nAutoConnect portal(httpServer);             // Step #4\nAutoConnectAux update(\"/update\", \"UPDATE\"); // Step #5, #6, #7\nAutoConnectAux hello;                       // Step #8\n\nvoid setup() {\n  httpUpdate.setup(&httpServer, \"USERNAME\", \"PASSWORD\"); // Step #9.a\n  hello.load(HELLO_PAGE);                   // Step #9.b\n  portal.join({ hello, update });           // Step #9.c\n  portal.begin();                           // Step #9.d\n}\n\nvoid loop() {\n  portal.handleClient();                    // Step #10\n}\n
    "},{"location":"otabrowser.html#regular-file-uploading-using-autoconnectotaenhanced-wv120","title":"Regular file uploading using AutoConnectOTA\u00a0ENHANCED w/v1.2.0","text":"

    The built-in OTA update feature can update the firmware as well as upload regular files placed in the file system on the ESP module. It allows a regular file is uploaded via OTA using the Update of AutoConnect menu without adding a particular custom Web page that contains AutoConnectFile. This utilization is useful for the operation of transferring the JSON document of the custom web page definition, the external parameter file of your sketch, and so on into the target ESP module via OTA.

    The built-in OTA update feature determines where to save the uploaded file according to the filename pattern. By default, a filename with ends a .bin extension is subject to firmware updates. A file that has another extensions will be saved as a regular to LittleFS (or SPIFFS) in the flash.

    The filename extension that should be treated as the firmware is defined as the AUTOCONNECT_UPLOAD_ASFIRMWARE macro in AutoConnectDefs.h header file of the library source code. When dealing with another extensions for the updating file as firmware change this macro definition.

    #define AUTOCONNECT_UPLOAD_ASFIRMWARE \".bin\"\n

    Specify with the PlatformIO

    AUTOCONNECT_UPLOAD_ASFIRMWARE pattern will be embedded into the binary sketch is determined at compile time. The PlatformIO build system allows you to change the pattern of the file extension for each project without modifying the library source code.

    build_flags=-DAUTOCONNECT_UPLOAD_ASFIRMWARE='\".bin\"'\n

    Use a regular expression to specify the file extension

    By default, you can specify only one file extension to be treated as firmware in OTA updates. However, you can specify the file extension as a regular expression, but it consumes a lot of memory.

    If the file extension pattern contains a regular expression, you need to enable the flag of AUTOCONNECT_UPLOAD_ASFIRMWARE_USE_REGEXP in AutoConnectDefs.h. Also, the AUTOCONNECT_UPLOAD_ASFIRMWARE definition as a regular expression is treated as a replacement string for the #define directive for C++ preprocessor, so the backslash must be escaped.

    "},{"location":"otabrowser.html#display-an-extra-string-on-the-update-screenenhanced-wv130","title":"Display an extra string on the update screen\u00a0ENHANCED w/v1.3.0","text":"

    You can add an extra string to the OTA update screen by the sketch. If an extra string is specified, it will be displayed on the right side of \"Updating firmware\" caption.

    The screenshot above shows an example of adding the current version of the sketch to the OTA caption.

    To display in the add an extra caption to the OTA update screen, sets the AutoConnectConfig::otaExtraCaption by your sketch. A type of the extra caption type to set in AutoConnectConfig::otaExtraCaption is the const char pointer. So, its string must remain in the memory area for the duration of OTA. (This string is not copied to the AutoConnectOTA class and expiration must be guaranteed by your sketch)

    #define FIRMWARE_VERSION  \"1.1.12-dev\"\n...\n#include <AutoConnect.h>\n...\nconst char* fw_ver = FIRMWARE_VERSION;\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  config.ota = AC_OTA_BUILTIN;\n  config.otaExtraCaption = fw_ver;\n  portal.config(config);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    Common mistakes about variable expiration

    Local variables are valid only within the function. The following code seems to work at first glance. But practically, *fw_ver is released at the end of the function. AutoConnectConfig::otaExtraCaption holds only a pointer to the extra caption string.

    #define FIRMWARE_VERSION  \"1.1.12-dev\"\n...\n#include <AutoConnect.h>\n...\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid setupConfig() {\nconst char* fw_ver = FIRMWARE_VERSION;\n  config.ota = AC_OTA_BUILTIN;\n  config.otaExtraCaption = fw_ver;  // This code doesn't work as intended.\n  portal.config(config);\n}\n\nvoid setup() {\n  setupConfig();\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"otabrowser.html#receive-the-autoconnectota-status-changeenhanced-wv130","title":"Receive the AutoConnectOTA status change\u00a0ENHANCED w/v1.3.0","text":"

    You can capture the change in the state of the OTA by registering the exit routine to AutoConnect. The exit routine for notifying the state change of AutoConnectOTA can execute the user's sketch function during specific stages of OTA or on an error. Also, these exit routines have the same interface as the similar exit functions included in the Arduino core.

    The following functions register the function in your sketch with AutoConnect to notify OTA state changes.

    • AutoConnect::onOTAStart : Register the on-start exit routine that is called only once when the OTA has been started.
    • AutoConnect::onOTAProgress : Register the exit routine that is called during the OTA progress.
    • AutoConnect::onOTAEnd : Register the on-end exit routine that is called only once when the OTA is finished.
    • AutoConnect::onOTAError : Register the exit routine that is called when some error occurred.
    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid OTAStart() {\n  Serial.println(\"Start OTA updating\");\n}\n\nvoid OTAEnd() {\n  Serial.println(\"\\nEnd\");\n}\nvoid OTAProgress(unsigned int amount, unsigned int size) {\n  Serial.printf(\"Progress: %u(%u)\\r\", amount, size);\n}\n\nvoid OTAError(uint8_t error) {\n  Serial.printf(\"Error[%u]: \", error);\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  config.ota = AC_OTA_BUILTIN;\n  portal.config(config);\n  portal.onOTAStart(OTAStart);\n  portal.onOTAEnd(OTAEnd);\n  portal.onOTAProgress(OTAProgress);\n  portal.onOTAError(OTAError);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    1. For ESP32, change the following items:

      • Change the include directives appropriately for the ESP32 environment.
      • Change ESP8266WebServer to WebServer.

      \u21a9

    2. The AutoConnect library provides an implementation of the HTTPUpdateServer class that ported from ESP8266HTTPUpdateServer class for ESP32 intention. It is contained the WebUpdate under the examples folder.\u00a0\u21a9

    "},{"location":"otaserver.html","title":"OTA using Update Server","text":""},{"location":"otaserver.html#updates-with-the-update-server","title":"Updates with the update server","text":"

    Since the v1.0.0 release, AutoConnect provides new feature for updating sketch firmware of ESP8266 or ESP32 modules via OTA using the AutoConnectUpdate class that is an implementation of the Sketch binary update by the HTTP server mentioned in the OTA update of the ESP8266 Arduino Core documentation, which inherits from the ESP8266HTTPUpdate class (as HTTPUpdate class in the case of ESP32). It acts as a client agent for a series of update operations.

    This method allows you to remotely update the ESP module's firmware beyond the network segments from the update server, as long as you can ensure proper routing and forwarding.

    If you choose this update method, you need to prepare the server process as a variant of the HTTP server that supplies the binary sketch files to the updating client agent. Its server requires to be able to handle the HTTP headers extended by ESP8266HTTPUpdate class as described in the ESP8266 Arduino Core documentation. There are various implementations of the update server that provide binary sketch files. For example, the ESP8266 Arduino Core documentation suggests an advanced updater php script that can be fully communicated with the client agent using the ESP8266HTTPUpdate class. That is, the update server for AutoConnect must work with the client agent, and its implementation should make the handshake well with the AutoConnectUpdate class which wraps an ESP8266HTTPUpdate class. The AutoConnect library provides an update server script implemented in Python that can combine with the AutoConnectUpdate class.

    "},{"location":"otaserver.html#how-to-embed-autoconnectupdate-to-your-sketch","title":"How to embed AutoConnectUpdate to your sketch","text":"

    To embed the AutoConnectUpdate class into your sketch, basically follow these steps:

    1. Declare an ESP8266WebServer object. (In ESP32, as WebServer)
    2. Declare an AutoConnect object with an ESP8266WebServer object.
    3. Declare an AutoConnectUpdate object with the update server address and the HTTP port as parameters.
    4. Invokes AutoConnect::begin function.
    5. Attach the AutoConnectUpdate object to AutoConnect using AutoConnectUpdate::attach function.
    6. Invokes AutoConnect::handleClient function in the loop().
    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nESP8266WebServer server;                          // Step #1\nAutoConnect portal;                               // Step #2\nAutoConnectUpdate update(\"192.168.0.100\", 8000);  // Step #3\n\nvoid setup() {\nif (portal.begin()) {     // Step #4\n    update.attach(portal);  // Step #5\n  }\n}\n\nvoid loop() {\n  portal.handleClient();    // Step #6\n}\n

    "},{"location":"otaserver.html#behavior-of-the-autoconnectupdate-class","title":"Behavior of the AutoConnectUpdate class","text":"

    A sketch incorporating the AutoConnectUpdate class has an extended menu item as UPDATE in the AutoConnect menu. UPDATE as menu item will be attached by the AutoConnectUpdate automatically.

    When an UPDATE item started, its first action is requesting a catalog list of updatable binary sketch files to the update server. Then the update server sends back the catalog list of stored binary sketch files to a client which is the ESP module. The AutoConnectUpdate class will display responded list to a custom Web page1 on the browser.

    The substance of Available firmware list is a custom Web page by AutoConnectAux, and you can select the target binary sketch file with the radio button (AutoConnectRadio). A progress bar will appear to notify the updating status once the update has begun. When the update finished, the ESP module will reset automatically to launch a new firmware.

    The AutoConnectUpdate class performs the above series of operations in conjunction with the update server. All you need to do is attach the AutoConnectUpdate class to AutoConnect and execute the AutoConnect::handleClient function in the loop().

    "},{"location":"otaserver.html#update-server-for-the-autoconnectupdate-class","title":"Update server for the AutoConnectUpdate class","text":"

    The above series of operations using AutoConnectUpdate class requires an update server that can work with it. AutoConnect provides an update server script implemented in Python. This server script conforms to a sketch that uses the AutoConnectUpdate class as an update client agent.2

    In the OTA platform, you can place the update server operated by the script in a location that is reachable from the ESP module on the network.

    updateserver.py [-h] [--port PORT] [--bind IP_ADDRESS] [--catalog CATALOG] [--log LOG_LEVEL]\n
    --help | -hShow help message and exit. --port | -pSpecifies PORT number (Default: 8000) --bind | -bSpecifies the IP address to which the update server binds. Usually, it is the host address of the update server. When multiple NICs configured, specify one of the IP addresses. (Default: HOST IP or 127.0.0.0) --catalog | -dSpecifies the directory path on the update server that contains the binary sketch files. (Default: The current directory) --log | -lSpecifies the level of logging output. It accepts the Logging Levels specified in the Python logging module.

    updateserver.py usage

    1. Python First, prepare a Python environment. It is also possible with a tiny single-board computer like the raspberry pi. Popular distributions such as Ubuntu for Linux include Python. You can easily set up a Python 2 or 3 environment. If you are using a Mac, you already have the Python 2 environment. macOS is equipped with Python 2.7 by default. In the case of Windows OS, it is necessary to install the Python environment intentionally. Please refer to the Python official page to install Python in your environment.

    2. Deploy the binary sketch files Use the Arduino IDE to output a binary file of sketches and deploy it3 under the update server. The path which specifies for the --catalog option of updateServer.py is the path of the binary sketch files you deployed.

    3. Start updateserver.py For example, to start the update server on the host with IP address 172.16.1.10 using 8080 port4, execute the following command: 

      python updateserver.py --port 8080 --bind 172.16.1.10 --catalog bin --log debug\n
      In this example assumes that the binary sketch files are deployed under the path bin from the current directory.

    Limitations of the updateserver.py

    The updateserver.py script equips only the minimum facility because it assumes a private small OTA platform without identifying individual modules and version restrictions etc. To operate a larger OTA platform, it is necessary to identify the individual ESP module and to consider version control and security.

    "},{"location":"otaserver.html#http-contents-and-the-sequence-for-the-autoconnectupdate-class","title":"HTTP contents and the sequence for the AutoConnectUpdate class","text":"

    You can also equip an update server that works with the AutoConnectUpdate class. It can be improved more widely applicable by adding extensions such as version control and authentication to the updateserver.py script. It is necessary to understand the specifications related to HTTP data streams and sequences to enhance the update server that the AutoConnectUpdate class assumes.

    This section describes the contents of the HTTP data stream required by the communication with AutoConnectUpdate class. To work correctly with the AutoConnectUpdate class, the update server must meet two requirements:

    • The update server notifies the catalog list of updatable binary files which stored in the update server to the client agent. 5
    • Send an updating binary file and MD5 hash to a client in response to URI request (HTTP GET). 6

    Above requirements will be implemented on along the HTTP protocol. The AutoConnectUpdate class requests an update server to notify the client for a catalog list of binary sketch files using an HTTP URL query string. The specifications of the HTTP query and the contents of the catalog list to be returned are as follows:

    "},{"location":"otaserver.html#1-http-url-query-for-the-catalog-list-of-the-updatable","title":"1. HTTP URL query for the catalog list of the updatable","text":"
    [address]/_catalog?op=list&path=[path]\n
    addressURL of the update server /_catalogRequest path, it is fixed. opOperation command for the update server. Currently, only 'list' occurs. pathPath containing the updatable binary files on the update server."},{"location":"otaserver.html#2-the-catalog-list-content","title":"2. The catalog list content","text":"

    The response (that is, the catalog list) to the above query from the server is the following specification in JSON format.

    {\n\"name\" : FILE_NAME,\n\"type\" : FILE_TYPE,\n\"date\" : FILE_TIMESTAMP_DATED,\n\"time\" : FILE_TIMESTAMP_TIMED,\n\"size\" : FILE_SIZE\n}\n
    nameBinary sketch file name for update (String) typeOne of 'bin', 'directory' or 'file'. AutoConnect Update recognizes only file types of 'bin' as update targets. (String) dateFile update date. AutoConnect v1.0.0 treats the file update date as an annotation and is not equip the version control feature yet. (String) timeFile update time. AutoConnect v1.0.0 treats the file update date as an annotation and is not equip the version control feature yet. (String) sizeFile byte count (Numeric)

    The above JSON object is one entry. The actual catalog list is an array of this entry since it assumes that an update server will provide multiple update binary files in production. The update server should respond with the MIME type specified as application/json for the catalog list.7

    "},{"location":"otaserver.html#3-the-binary-sketch-file-used-for-updating","title":"3. The binary sketch file used for updating","text":"

    The AutoConnectUpdate class issues a HTTP GET request with the specified host address and URI. The update server responds by sending back a binary sketch file with the following header:

    Content-Type: application/octet-stream\nContent-Disposition: attachment; filename=\"BINARY_SKETCH_FILE_NAME\"\nContent-Length: LENGTH_OF_CONTENT\nx-MD5: HEXDIGEST\n

    The header x-MD5 is a 128-bit hash value (digest in hexadecimal) that represents the checksum of the binary sketch file for updates required for the ESP8266HTTPUpdate class.

    1. You can scroll horizontally on the browser to see the timestamp and file size that the catalog list contains.\u00a0\u21a9

    2. The folders containing the script: For Python2: AUTOCONNECT_LIBRARY_PATH/src/updateserver/python2 For Python3: AUTOCONNECT_LIBRARY_PATH/src/updateserver/python3\u00a0\u21a9

    3. Deploying the binary sketch file output by Arduino IDE is usually just copying to the folder for deployment. However, its folder must be accessible from the updateserver.py script.\u00a0\u21a9

    4. The port of the update server and the port used by the AutoConnectUpdate class must be the same.\u00a0\u21a9

    5. The client agent is an instance of the AutoConnectUpdate class.\u00a0\u21a9

    6. The client agent will send its URI request to the update server.\u00a0\u21a9

    7. It should be represented as Content-Type: application/json in the HTTP response header.\u00a0\u21a9

    "},{"location":"otaupdate.html","title":"OTA Updates","text":"

    Only for AutoConnect

    AutoConnect OTA features are valid only for AutoConnect; they are not available for AutoConnectCore.

    "},{"location":"otaupdate.html#ota-updates-with-autoconnect","title":"OTA Updates with AutoConnect","text":"

    AutoConnect provides two type platforms for updating the binary sketch in the ESP8266 or ESP32 module via OTA. They correspond to the Web Browser Update and HTTP Server Update whiches mentioned in the ESP8266 Arduino Core documentation.

    The update behavior using a web browser as the client that supplies the binary sketch file for update follows the scenario assumed by the ESP8266 Arduino core. Therefore, the user sketch must meet the requirements described in the ESP8266 Arduino Core documentation, but you can easily embed the OTA update feature that able to operate via the web browser by AutoConnect menu. All you need to do is that specify AutoConnectConfig.

    It is for the only the same network

    This method can apply only if the client browser and the ESP module belong to the same network segment. It cannot work correctly across networks.

    Another update method using an update server can be applied more broadly than using a web browser. This method can also update the ESP module over the Internet if you can secure the correct route and transparency between the ESP module and the update server. To configure this platform, you need to have an update server along with using the AutoConnectUpdate class in your sketch.

    Security Disclaimer

    The security level of the OTA update platform provided by AutoConnect is very weak. No guarantees as to the level of security for your application by the AutoConnect OTA Update is implied.

    "},{"location":"wojson.html","title":"Custom Web pages w/o JSON","text":""},{"location":"wojson.html#suppress-increase-in-memory-consumption","title":"Suppress increase in memory consumption","text":"

    Custom Web page processing consumes a lot of memory. AutoConnect will take a whole string of the JSON document for the custom Web pages into memory. The required buffer size for the JSON document of example sketch mqttRSSI reaches approximately 3000 bytes. And actually, it needs twice the heap area. Especially this constraint will be a problem with the ESP8266 which has a heap size poor.

    AutoConnect can handle custom Web pages without using JSON. In that case, since the ArduinoJson library will not be bound, the Sketch size will also be reduced.

    "},{"location":"wojson.html#writing-the-custom-web-pages-without-json","title":"Writing the custom Web pages without JSON","text":"

    To handle the custom Web pages without using JSON, follow the steps below.

    1. Create or define AutoConnectAux for each page.
    2. Create or define AutoConnectElement(s).
    3. Add AutoConnectElement(s) to AutoConnectAux.
    4. Create more AutoConnectAux containing AutoConnectElement(s), if necessary.
    5. Register the request handlers for the custom Web pages.
    6. Join prepared AutoConnectAux(s) to AutoConnect.
    7. Invoke AutoConnect::begin().

    In addition to the above procedure, to completely cut off for binding with the ArduinoJson library, turn off the ArduinoJson use indicator which is declared by the AutoConnect definitions. Its declaration is in AutoConnectDefs.h file.1

    // Comment out the AUTOCONNECT_USE_JSON macro to detach the ArduinoJson.\n#define AUTOCONNECT_USE_JSON\n

    JSON processing will be disabled

    Commenting out the AUTOCONNECT_USE_JSON macro invalidates all functions related to JSON processing. If the Sketch is using the JSON function, it will result in a compile error.

    Exclude the ArduinoJson by each compile-time

    If you want to exclude ArduinoJson without changing the library code, specify the AUTOCONNECT_NOUSE_JSON directive as a compiler option according to the method described in the FAQ.

    "},{"location":"wojson.html#implementation-example-without-arduinojson","title":"Implementation example without ArduinoJson","text":"

    The code excluding JSON processing from the mqttRSSI sketch attached to the library is as follows. (It is a part of code. Refer to mqttRSSI_NA.ino for the whole sketch.)

    The JSON document for mqttRSSI

    [\n  {\n\"title\": \"MQTT Setting\",\n\"uri\": \"/mqtt_setting\",\n\"menu\": true,\n\"element\": [\n      {\n\"name\": \"header\",\n\"type\": \"ACText\",\n\"value\": \"<h2>MQTT broker settings</h2>\",\n\"style\": \"text-align:center;color:#2f4f4f;padding:10px;\"\n      },\n      {\n\"name\": \"caption\",\n\"type\": \"ACText\",\n\"value\": \"Publishing the WiFi signal strength to MQTT channel. RSSI value of ESP8266 to the channel created on ThingSpeak\",\n\"style\": \"font-family:serif;color:#4682b4;\"\n      },\n      {\n\"name\": \"mqttserver\",\n\"type\": \"ACInput\",\n\"value\": \"\",\n\"label\": \"Server\",\n\"pattern\": \"^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\\\-]*[a-zA-Z0-9])\\\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\\\-]*[A-Za-z0-9])$\",\n\"placeholder\": \"MQTT broker server\"\n      },\n      {\n\"name\": \"channelid\",\n\"type\": \"ACInput\",\n\"label\": \"Channel ID\",\n\"pattern\": \"^[0-9]{6}$\"\n      },\n      {\n\"name\": \"userkey\",\n\"type\": \"ACInput\",\n\"label\": \"User Key\"\n      },\n      {\n\"name\": \"apikey\",\n\"type\": \"ACInput\",\n\"label\": \"API Key\"\n      },\n      {\n\"name\": \"newline\",\n\"type\": \"ACElement\",\n\"value\": \"<hr>\"\n      },\n      {\n\"name\": \"uniqueid\",\n\"type\": \"ACCheckbox\",\n\"value\": \"unique\",\n\"label\": \"Use APID unique\",\n\"checked\": false\n      },\n      {\n\"name\": \"period\",\n\"type\": \"ACRadio\",\n\"value\": [\n\"30 sec.\",\n\"60 sec.\",\n\"180 sec.\"\n        ],\n\"label\": \"Update period\",\n\"arrange\": \"vertical\",\n\"checked\": 1\n      },\n      {\n\"name\": \"newline\",\n\"type\": \"ACElement\",\n\"value\": \"<hr>\"\n      },\n      {\n\"name\": \"hostname\",\n\"type\": \"ACInput\",\n\"value\": \"\",\n\"label\": \"ESP host name\",\n\"pattern\": \"^([a-zA-Z0-9]([a-zA-Z0-9-])*[a-zA-Z0-9]){1,32}$\"\n      },\n      {\n\"name\": \"save\",\n\"type\": \"ACSubmit\",\n\"value\": \"Save&amp;Start\",\n\"uri\": \"/mqtt_save\"\n      },\n      {\n\"name\": \"discard\",\n\"type\": \"ACSubmit\",\n\"value\": \"Discard\",\n\"uri\": \"/\"\n      }\n    ]\n  },\n  {\n\"title\": \"MQTT Setting\",\n\"uri\": \"/mqtt_save\",\n\"menu\": false,\n\"element\": [\n      {\n\"name\": \"caption\",\n\"type\": \"ACText\",\n\"value\": \"<h4>Parameters saved as:</h4>\",\n\"style\": \"text-align:center;color:#2f4f4f;padding:10px;\"\n      },\n      {\n\"name\": \"parameters\",\n\"type\": \"ACText\"\n      },\n      {\n\"name\": \"clear\",\n\"type\": \"ACSubmit\",\n\"value\": \"Clear channel\",\n\"uri\": \"/mqtt_clear\"\n      }\n    ]\n  }\n]\n
    Exclude the JSON and replace to the AutoConnectElements natively

    // In the declaration,\n// Declare AutoConnectElements for the page asf /mqtt_setting\nACText(header, \"<h2>MQTT broker settings</h2>\", \"text-align:center;color:#2f4f4f;padding:10px;\");\nACText(caption, \"Publishing the WiFi signal strength to MQTT channel. RSSI value of ESP8266 to the channel created on ThingSpeak\", \"font-family:serif;color:#4682b4;\");\nACInput(mqttserver, \"\", \"Server\", \"^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\\\-]*[a-zA-Z0-9])\\\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\\\-]*[A-Za-z0-9])$\", \"MQTT broker server\");\nACInput(channelid, \"\", \"Channel ID\", \"^[0-9]{6}$\");\nACInput(userkey, \"\", \"User Key\");\nACInput(apikey, \"\", \"API Key\");\nACElement(newline, \"<hr>\");\nACCheckbox(uniqueid, \"unique\", \"Use APID unique\");\nACRadio(period, { \"30 sec.\", \"60 sec.\", \"180 sec.\" }, \"Update period\", AC_Vertical, 1);\nACSubmit(save, \"Start\", \"mqtt_save\");\nACSubmit(discard, \"Discard\", \"/\");\n\n// Declare the custom Web page as /mqtt_setting and contains the AutoConnectElements\nAutoConnectAux mqtt_setting(\"/mqtt_setting\", \"MQTT Setting\", true, {\n  header,\n  caption,\n  mqttserver,\n  channelid,\n  userkey,\n  apikey,\n  newline,\n  uniqueid,\n  period,\n  newline,\n  save,\n  discard\n});\n\n// Declare AutoConnectElements for the page as /mqtt_save\nACText(caption2, \"<h4>Parameters available as:</h4>\", \"text-align:center;color:#2f4f4f;padding:10px;\");\nACText(parameters);\nACSubmit(clear, \"Clear channel\", \"/mqtt_clear\");\n\n// Declare the custom Web page as /mqtt_save and contains the AutoConnectElements\nAutoConnectAux mqtt_save(\"/mqtt_save\", \"MQTT Setting\", false, {\n  caption2,\n  parameters,\n  clear\n});\n\n// In the setup(),\n// Join the custom Web pages and performs begin\n  portal.join({ mqtt_setting, mqtt_save });\n  portal.begin();\n

    1. Detaching the ArduinoJson library reduces the Sketch size by approximately 10K bytes.\u00a0\u21a9

    "}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"index.html","title":"AutoConnect for ESP8266/ESP32","text":"

    An Arduino library for ESP8266/ESP32 WLAN configuration at run time with web interface.

    "},{"location":"index.html#overview","title":"Overview","text":"

    To the dynamic configuration for joining to WLAN with SSID and PSK accordingly. It an Arduino library united with ESP8266WebServer class for ESP8266 or WebServer class for ESP32. Easy implementing the Web interface constituting the WLAN for ESP8266/ESP32 WiFi connection. With this library to make a Sketch easily which connects from ESP8266/ESP32 to the access point at runtime by the web interface without hard-coded SSID and password.

    "},{"location":"index.html#no-need-pre-coded-ssid-password","title":"No need pre-coded SSID & password","text":"

    It is no needed hard-coding in advance the SSID and Password into the Sketch to connect between ESP8266/ESP32 and WLAN. You can input SSID & Password from a smartphone via the web interface at runtime.

    "},{"location":"index.html#simple-usage","title":"Simple usage","text":"

    AutoConnect control screen will be displayed automatically for establishing new connections. It aids by the captive portal when vested the connection cannot be detected.By using the AutoConnect menu, to manage the connections convenient.

    "},{"location":"index.html#store-the-established-connection","title":"Store the established connection","text":"

    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.

    "},{"location":"index.html#easy-to-embed-in","title":"Easy to embed in","text":"

    AutoConnect can be placed easily in your Sketch. It's \"begin\" and \"handleClient\" only.

    "},{"location":"index.html#lives-with-your-sketches","title":"Lives with your Sketches","text":"

    The Sketches which provide the web page using ESP8266WebServer there is, AutoConnect will not disturb it. AutoConnect can use an already instantiated ESP8266WebServer object, or itself can assign it. This effect also applies to ESP32. The corresponding class for ESP32 will be the WebServer.

    "},{"location":"index.html#easy-to-add-the-custom-web-pages-enhanced-wv097","title":"Easy to add the custom Web pages ENHANCED w/v0.9.7","text":"

    You can easily add your owned web pages that can consist of representative HTML elements and invoke them from the menu. Further it possible importing the custom Web pages declarations described with JSON which stored in PROGMEM, SPIFFS, or SD.

    "},{"location":"index.html#quick-and-easy-to-equip-the-ota-update-feature-updated-wv115","title":"Quick and easy to equip the OTA update feature UPDATED w/v1.1.5","text":"

    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.

    "},{"location":"index.html#installation","title":"Installation","text":""},{"location":"index.html#requirements","title":"Requirements","text":""},{"location":"index.html#supported-hardware","title":"Supported hardware","text":"
    • Generic ESP8266 modules (applying the ESP8266 Community's Arduino core)
    • Adafruit HUZZAH ESP8266 (ESP-12)
    • ESP-WROOM-02
    • Heltec WiFi Kit 8
    • NodeMCU 0.9 (ESP-12) / NodeMCU 1.0 (ESP-12E)
    • Olimex MOD-WIFI-ESP8266
    • SparkFun Thing
    • SweetPea ESP-210
    • ESP32Dev Board (applying the Espressif's arduino-esp32 core)
    • SparkFun ESP32 Thing
    • WEMOS LOLIN D32
    • Ai-Thinker NodeMCU-32S
    • Heltec WiFi Kit 32
    • M5Stack
    • And other ESP8266/ESP32 modules supported by the Additional Board Manager URLs of the Arduino-IDE.

    About flash size on the module

    The AutoConnect Sketch size is relatively large. Large flash capacity is necessary. 512Kbyte (4Mbits) flash inclusion module such as ESP-01 is not recommended.

    "},{"location":"index.html#required-libraries","title":"Required libraries","text":"

    AutoConnect requires the following environment and libraries.

    Arduino IDE

    The current upstream at the 1.8 level or later is needed. Please install from the official Arduino IDE download page. This step is not required if you already have a modern version.

    ESP8266 Arduino core

    AutoConnect targets Sketches made on the assumption of ESP8266 Community's Arduino core. Stable 2.4.0 or higher required and the latest release is recommended. Install third-party platform using the Boards Manager of Arduino IDE. Package URL is http://arduino.esp8266.com/stable/package_esp8266com_index.json

    ESP32 Arduino core

    Also, to apply AutoConnect to ESP32, the arduino-esp32 core provided by Espressif is needed. Stable 1.0.1 or required and the latest release 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.

    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 library to build HTML for ESP8266WebServer is needed. To install the PageBuilder library into your Arduino IDE, you can use the Library Manager. Select the board of ESP8266 series in the Arduino IDE, open the library manager and search keyword 'PageBuilder' with the topic 'Communication', then you can see the PageBuilder. The latest version is required 1.4.2 later.1

    Additional library (Optional)

    By adding the ArduinoJson library, AutoConnect will be able to handle the custom Web pages described with JSON. Since AutoConnect v0.9.7 you can insert user-owned web pages that can consist of representative HTML elements as styled TEXT, INPUT, BUTTON, CHECKBOX, SELECT, SUBMIT and invoke them from the AutoConnect menu. These HTML elements can be added by Sketches using the AutoConnect API. Further it possible importing the custom Web pages declarations described with JSON which stored in PROGMEM, SPIFFS, or SD. ArduinoJson is required to use this feature.2 AutoConnect can work with ArduinoJson both version 5 and version 6.

    "},{"location":"index.html#install-the-autoconnect","title":"Install the AutoConnect","text":"

    Clone or download from the AutoConnect GitHub repository.

    When you select Download, you can import it to Arduino IDE immediately. After downloaded, the AutoConnect-master.zip file will be saved in your download folder. Then in the Arduino IDE, navigate to \"Sketch > Include Library\". At the top of the drop down list, select the option to \"Add .ZIP Library...\". Details for Arduino official page.

    Supported by Library manager.

    AutoConnect was added to the Arduino IDE library manager. It can be used with the PlatformIO library also.

    1. Since AutoConnect v1.2.3, PageBuilder v1.5.0 later is required.\u00a0\u21a9

    2. Using the AutoConnect API natively allows you to Sketch custom Web pages without JSON.\u00a0\u21a9

    "},{"location":"acelements.html","title":"AutoConnectElements","text":""},{"location":"acelements.html#the-elements-for-the-custom-web-pages","title":"The elements for the custom Web pages","text":"

    Representative HTML elements for making the custom Web page are provided as AutoConnectElements.

    • AutoConnectButton: Labeled action button
    • AutoConnectCheckbox: Labeled checkbox
    • AutoConnectElement: General tag
    • AutoConnectFile: File uploader
    • AutoConnectInput: Labeled text input box
    • AutoConnectRadio: Labeled radio button
    • AutoConnectRange: Labeled range slider
    • AutoConnectSelect: Selection list
    • AutoConnectStyle: Custom CSS code
    • AutoConnectSubmit: Submit button
    • AutoConnectText: Style attributed text
    "},{"location":"acelements.html#layout-on-a-custom-web-page","title":"Layout on a custom Web page","text":"

    AutoConnect will not actively be involved in the layout of custom Web pages generated from AutoConnectElements. However, each element has an attribute to arrange placement on a custom web page by horizontally or vertically.

    "},{"location":"acelements.html#custom-css-for-a-custom-web-page","title":"Custom CSS for a custom Web page","text":"

    All custom Web page styles are limited to the built-in unique CSS embedded in the library code. Direct modification of the CSS affects AutoConnect behavior. You can use dedicated elements to relatively safely modify the style of your custom Web page. The AutoConnectStyle will insert the raw CSS code into the style block in HTML of the custom Web page.

    "},{"location":"acelements.html#form-and-autoconnectelements","title":"Form and AutoConnectElements","text":"

    All AutoConnectElements placed on custom web pages will be contained into one form. Its form is fixed and created by AutoConnect. The form value (usually the text or checkbox you entered) is sent by AutoConnectSubmit using the POST method with HTTP. The post method sends the actual form data which is a query string whose contents are the name and value of AutoConnectElements. You can retrieve the value for the parameter with the Sketch from the query string with ESP8266WebServer::arg function or PageArgument class of the AutoConnect::on handler when the form is submitted.

    "},{"location":"acelements.html#autoconnectelement-a-basic-class-of-elements","title":"AutoConnectElement - A basic class of elements","text":"

    AutoConnectElement is a base class for other element classes and has common attributes for all elements. It can also be used as a variant of each element. The following items are attributes that AutoConnectElement has and are common to other elements.

    Sample AutoConnectElement element(\"element\", \"<hr>\");

    On the page:

    "},{"location":"acelements.html#constructor","title":"Constructor","text":"
    AutoConnectElement(const char* name, const char* value, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name","title":"name","text":"

    Each element has a name. The name is the String data type. You can identify each element by the name to access it with sketches.

    "},{"location":"acelements.html#value","title":"value","text":"

    The value is the string which is a source to generate an HTML code. Characteristics of Value vary depending on the element. The value of AutoConnectElement is native HTML code. A string of value is output as HTML as it is.

    "},{"location":"acelements.html#post","title":"post","text":"

    The post specifies a tag to add behind the HTML code generated from the element. Its purpose is to place elements on the custom Web page as intended by the user sketch. AutoConnect will not actively be involved in the layout of custom Web pages generated from AutoConnectElements. Each element follows behind the previous one, with the exception of some elements. You can use the post value to arrange vertically or horizontal when the elements do not have the intended position on the custom Web Page specifying the following enumeration value as ACPosterior_t type for the post.

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.

    The default interpretation of the post value is specific to each element.

    AutoConnectElements Default interpretation of the post value AutoConnectElement AC_Tag_None AutoConnectButton AC_Tag_None AutoConnectCheckBox AC_Tag_BR AutoConnectFile AC_Tag_BR AutoConnectInput AC_Tag_BR AutoConnectRadio AC_Tag_BR AutoConnectRange AC_Tag_BR AutoConnectSelect AC_Tag_BR AutoConnectSubmit AC_Tag_None AutoConnectText AC_Tag_None

    A placement posterior of AutoConnectText

    A placement posterior for AutoConnectText has a slightly peculiar specification. AutoConnectText element without the style attribute will be drained to HTML as a raw value and is accompanied by <p>, <br> or <div> tags according to the post enumeration values. If the style attribute is specified, the post enumeration value will be ignored and always be enclosed in the <div> tag, and the style value will be inserted into style attribute of the <div> tag.

    "},{"location":"acelements.html#type","title":"type","text":"

    The type indicates the type of the element and represented as the ACElement_t enumeration type in the Sketch. Since AutoConnectElement also acts as a variant of other elements, it can be applied to handle elements collectively. At that time, the type can be referred to by the typeOf() function. The following example changes the font color of all AutoConnectText elements of a custom Web page to gray.

    AutoConnectAux  customPage;\n\nAutoConnectElementVT& elements = customPage.getElements();\nfor (AutoConnectElement& elm : elements) {\nif (elm.typeOf() == AC_Text) {\n    AutoConnectText& text = reinterpret_cast<AutoConnectText&>(elm);\n    text.style = \"color:gray;\";\n  }\n}\n

    The enumerators for ACElement_t are as follows:

    • AutoConnectButton: AC_Button
    • AutoConnectCheckbox: AC_Checkbox
    • AutoConnectElement: AC_Element
    • AutoConnectFile: AC_File
    • AutoConnectInput: AC_Input
    • AutoConnectRadio: AC_Radio
    • AutoConnectRange: AC_Range
    • AutoConnectSelect: AC_Select
    • AutoConnectStyle: AC_Style
    • AutoConnectSubmit: AC_Submit
    • AutoConnectText: AC_Text
    • Uninitialized element: AC_Unknown

    Furthermore, to convert an entity that is not an AutoConnectElement to its native type, you must re-interpret that type with c++. Or, you can be coding the Sketch more easily with using the as<T> function.

    AutoConnectAux  customPage;\n\nAutoConnectElementVT& elements = customPage.getElements();\nfor (AutoConnectElement& elm : elements) {\nif (elm.type() == AC_Text) {\n    AutoConnectText& text = customPage[elm.name].as<AutoConnectText>();\n    text.style = \"color:gray;\";\n// Or, it is also possible to write the code further reduced as follows.\n// customPage[elm.name].as<AutoConnectText>().style = \"color:gray;\";\n  }\n}\n
    "},{"location":"acelements.html#autoconnectbutton","title":"AutoConnectButton","text":"

    AutoConnectButton generates an HTML <button type=\"button\"> tag and locates a clickable button to a custom Web page. Currently AutoConnectButton corresponds only to name, value, an onclick attribute of HTML button tag. An onclick attribute is generated from an action member variable of the AutoConnectButton, which is mostly used with a JavaScript to activate a script.

    Sample AutoConnectButton button(\"button\", \"OK\", \"myFunction()\");

    On the page:

    "},{"location":"acelements.html#constructor_1","title":"Constructor","text":"
    AutoConnectButton(const char* name, const char* value, const String& action, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_1","title":"name","text":"

    It is the name of the AutoConnectButton element and matches the name attribute of the button tag. It also becomes the parameter name of the query string when submitted.

    "},{"location":"acelements.html#value_1","title":"value","text":"

    It becomes a value of the value attribute of an HTML button tag.

    "},{"location":"acelements.html#action","title":"action","text":"

    action is String data type and is an onclick attribute fire on a mouse click on the element. It is mostly used with a JavaScript to activate a script.1 For example, the following code defines a custom Web page that copies a content of Text1 to Text2 by clicking Button.

    const char* scCopyText = R\"(\n<script>\nfunction CopyText() {\n  document.getElementById(\"Text2\").value = document.getElementById(\"Text1\").value;\n}\n</script>\n)\";\nACInput(Text1, \"Text1\");\nACInput(Text2, \"Text2\");\nACButton(Button, \"COPY\", \"CopyText()\");\nACElement(TextCopy, scCopyText);\n
    "},{"location":"acelements.html#post_1","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_None.

    "},{"location":"acelements.html#autoconnectcheckbox","title":"AutoConnectCheckbox","text":"

    AutoConnectCheckbox generates an HTML <input type=\"checkbox\"> tag and a <label> tag. It places horizontally on a custom Web page by default.

    Sample AutoConnectCheckbox checkbox(\"checkbox\", \"uniqueapid\", \"Use APID unique\", false);

    On the page:

    "},{"location":"acelements.html#constructor_2","title":"Constructor","text":"
    AutoConnectCheckbox(const char* name, const char* value, const char* label, const bool checked, const ACPosition_t labelPosition, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_2","title":"name","text":"

    It is the name of the AutoConnectCheckbox element and matches the name attribute of the input tag. It also becomes the parameter name of the query string when submitted.

    "},{"location":"acelements.html#value_2","title":"value","text":"

    It becomes a value of the value attribute of an HTML <input type=\"checkbox\"> tag.

    "},{"location":"acelements.html#label","title":"label","text":"

    A label is an optional string. A label is always arranged on the right side of the checkbox. Specification of a label will generate an HTML <label> tag with an id attribute. The checkbox and the label are connected by the id attribute. Only will be displayed if a label is not specified.

    "},{"location":"acelements.html#checked","title":"checked","text":"

    A checked is a Boolean value and indicates the checked status of the checkbox. The value of the checked checkbox element is packed in the query string and sent.

    "},{"location":"acelements.html#labelposition","title":"labelPosition","text":"

    The position of the label belonging to the checkbox can be specified around the element. The labelPosition specifies the position of the label to generate with ACPostion_t enumeration value. The default value is AC_Behind.

    • AC_Infront : Place a label in front of the check box.
    • AC_Behind : Place a label behind the check box.
    "},{"location":"acelements.html#post_2","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#autoconnectfile","title":"AutoConnectFile","text":"

    AutoConnectFile generates an HTML <input type=\"file\"> tag and a <label> tag. AutoConnectFile enables file upload from the client through the web browser to ESP8266/ESP32 module. You can select the flash in the module, external SD device or any output destination as the storage of the uploaded file.

    Sample AutoConnectFile file(\"file\", \"\", \"Upload:\", AC_File_FS)

    On the page:

    "},{"location":"acelements.html#constructor_3","title":"Constructor","text":"
    AutoConnectFile(const char* name, const char* value, const char* label, const ACFile_t store, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_3","title":"name","text":"

    It is the name of the AutoConnectFile element and matches the name attribute of the input tag. It also becomes the parameter name of the query string when submitted.

    "},{"location":"acelements.html#value_3","title":"value","text":"

    File name to be upload. The value contains the value entered by the client browser to the <input type=\"file\"> tag and is read-only. Even If you give a value to the constructor, it does not affect as an initial value like a default file name.

    "},{"location":"acelements.html#label_1","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the input box. Specification of a label will generate an HTML <label> tag with an id attribute. The input box and the label are connected by the id attribute.

    "},{"location":"acelements.html#store","title":"store","text":"

    Specifies the destination to save the uploaded file. The destination can be specified the following values in the ACFile_t enumeration type.

    • AC_File_FS : Save as the SPIFFS file in flash of ESP8266/ESP32 module.
    • AC_File_SD : Save to an external SD device connected to ESP8266/ESP32 module.
    • AC_File_Extern : Pass the content of the uploaded file to the uploader which is declared by the Sketch individually. Its uploader must inherit AutoConnectUploadHandler class and implements _open, _write and _close function.

    Built-in uploader is ready.

    AutoConnect already equips the built-in uploader for saving to the SPIFFS as AC_File_FS and the external SD as AC_File_SD. It is already implemented inside AutoConnect and will store uploaded file automatically.

    "},{"location":"acelements.html#post_3","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#autoconnectinput","title":"AutoConnectInput","text":"

    AutoConnectInput generates an HTML <input type=\"text\">, <input type=\"number\"> or <input type=\"password\"> tag and a <label> tag. It can also have a placeholder. The value of the input box is passed to the destination in the query string and can be retrieved programmatically. You can also update from the Sketches.

    Sample AutoConnectInput input(\"input\", \"\", \"Server\", \"MQTT broker server\");

    On the page:

    "},{"location":"acelements.html#constructor_4","title":"Constructor","text":"
    AutoConnectInput(const char* name, const char* value, const char* label, const char* pattern, const char* placeholder, const ACPosterior_t post, const ACInput_t apply)\n
    "},{"location":"acelements.html#name_4","title":"name","text":"

    It is the name of the AutoConnectInput element and matches the name attribute, the id attribute of the input tag. It also becomes the parameter name of the query string when submitted.

    "},{"location":"acelements.html#value_4","title":"value","text":"

    It becomes a string value of the value attribute of an HTML <input type=\"text\"> tag. The text entered from the custom Web page will be grouped in the query string of the form submission and the string set before accessing the page will be displayed as the initial value.

    "},{"location":"acelements.html#label_2","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the input box. Specification of a label will generate an HTML <label> tag with an id attribute. The input box and the label are connected by the id attribute.

    "},{"location":"acelements.html#pattern","title":"pattern","text":"

    A pattern specifies a regular expression that the AutoConnectInput element's value is checked against on form submission. If it is invalid, the background color will change, but it will be sent even if the data format does not match. To check whether the entered value matches the pattern, use the isValid function.

    • The password that must contain 8 or more characters that are of at least one number, and one uppercase and lowercase letter:(?=.*\\d)(?=.*[a-z])(?=.*[A-Z]).{8,}

    • Email address as characters@characters.domain:[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}

    • IP address:(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])

    • Host name of Internet:(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\-]*[A-Za-z0-9])

    • Date (MM/DD/YYYY) as range 1900-2099:(0[1-9]|1[012])[- \\/.](0[1-9]|[12][0-9]|3[01])[- \\/.](19|20)\\d\\d

    • Twitter account:^@?(\\w){1,15}$

    "},{"location":"acelements.html#placeholder","title":"placeholder","text":"

    A placeholder is an option string. Specification of a placeholder will generate a placeholder attribute for the input tag.

    "},{"location":"acelements.html#post_4","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#apply","title":"apply","text":"

    Specifies the type of input that the text box accepts. AutoConnectInput will generate either a input type=\"text\", input type=\"password\", or input type=\"number\" tag based on the apply specifying as input type. The input type can be specified the following values in the ACInput_t enumeration type.

    • AC_Input_Text : input type=\"text\"
    • AC_Input_Password : input type=\"password\"
    • AC_Input_Number : input type=\"number\"

    Numerical keypad is different

    When the AutoConnectInput element with the AC_Input_Number applied is focused on the browser, the numeric keypad may be displayed automatically. For popular mobile OSes such as Android and iOS, the numeric keypad has the following styles and is different with each OS.

    "},{"location":"acelements.html#autoconnectradio","title":"AutoConnectRadio","text":"

    AutoConnectRadio generates several HTML <input type=\"radio\"> tags grouped together. It also assigns an equal number of <label> tags to each <input type=\"radio\"> tag and stores the values of the choices that make up a radio button as a String collection.

    Sample AutoConnectRadio radio(\"radio\", { \"30 sec.\", \"60 sec.\", \"180 sec.\" }, \"Update period\", AC_Vertical, 1);

    On the page:

    "},{"location":"acelements.html#constructor_5","title":"Constructor","text":"
    AutoConnectRadio(const char* name, std::vector<String> const& values, const char* label, const ACArrange_t order, const uint8_t checked, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_5","title":"name","text":"

    It is the name of the AutoConnectRadio element, which matches the name attribute of the input tag and defines the radio group by this name. It is also the name parameter in the query string during submission.

    "},{"location":"acelements.html#values","title":"values","text":"

    A group of radio buttons is a set of <input type=\"radio\"> tags with the same name; AutoConnectRadio defines a radio group based on an array of Strings specified as values. A values is an array of String, actually a std::vector. The sketch can allocate its String array using std::vector's List-initialization.

    "},{"location":"acelements.html#label_3","title":"label","text":"

    A label is an optional string. A label will be arranged in the left or top of the radio buttons according to the order. Specification of a label will generate an HTML <label> tag with an id attribute. The radio buttons and the label are connected by the id attribute.

    "},{"location":"acelements.html#order","title":"order","text":"

    A order specifies the direction to arrange the radio buttons. It is a value of type ACArrange_t and accepts one of the following:

    • AC_Horizontal : Horizontal arrangement.
    • AC_Vertical : Vertical arrangement.

    A label will place in the left or the top according to the order.

    "},{"location":"acelements.html#checked_1","title":"checked","text":"

    A checked specifies the index number (1-based) of the values to be checked. If this parameter is not specified neither item is checked.

    "},{"location":"acelements.html#post_5","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#autoconnectrange","title":"AutoConnectRange","text":"

    AutoConnectRange generates an HTML <input type=\"range\"> tag and a <label> tag.

    Sample AutoConnectRange range(\"bri\", 0, \"Brightness\", -2, 2, 1, AC_Infront);

    On the page:

    "},{"location":"acelements.html#constructor_6","title":"Constructor","text":"
    AutoConnectRange(const char* name, const int value, const char* label, const int min, const int max, const int step, const ACPosition_t magnify, const ACPosterior_t post, const char* style)\n
    "},{"location":"acelements.html#name_6","title":"name","text":"

    It is the name of the AutoConnectRange element and matches the name attribute, the id attribute of the input tag. It also becomes the parameter name of the query string when submitted.

    "},{"location":"acelements.html#value_5","title":"value","text":"

    It becomes a string value of the value attribute of an HTML <input type=\"range\"> tag, which indicates the default value of the range.

    "},{"location":"acelements.html#label_4","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the range slider. Specification of a label will generate an HTML <label> tag with an id attribute. The range slider and the label are connected by the id attribute.

    "},{"location":"acelements.html#min","title":"min","text":"

    Specifies the most negative value within the range of allowed values and must not be less than the value argument.

    "},{"location":"acelements.html#max","title":"max","text":"

    It defines the greatest value in the range of permitted values.

    "},{"location":"acelements.html#step","title":"step","text":"

    It is a number that specifies the granularity that the value must adhere to. The default is 1. As you move the slider, it increases or decreases the value according to the step in granularity.

    "},{"location":"acelements.html#magnify","title":"magnify","text":"

    Displays the current value of the range on the left or right side of the slider.

    • AC_Infront : Displays the current value on the left side.
    • AC_Behind : Displays the current value on the right side.
    • AC_Void : No display the current value. This is the default.
    "},{"location":"acelements.html#post_6","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#style","title":"style","text":"

    A style specifies the qualification style to give to the content and can use the style attribute format as it is.

    "},{"location":"acelements.html#autoconnectstyle","title":"AutoConnectStyle","text":"

    AutoConnectStyle inserts the string given by the value into the style block of a custom Web page as it is raw.

    The validity as CSS will not be checked

    AutoConnectStyle does not do syntax checking and semantic analysis of value. Insert the specified string into the style block of the custom Web page without processing it. Therefore, specifying the wrong CSS will modulate the behavior of the custom Web page.

    "},{"location":"acelements.html#constructor_7","title":"Constructor","text":"
    AutoConnectStyle(const char* name, const char* value)\n
    "},{"location":"acelements.html#name_7","title":"name","text":"

    It is the name of the AutoConnectStyle element and is useful only to access this element from the Sketch. It does not affect the generated HTML code.

    "},{"location":"acelements.html#value_6","title":"value","text":"

    The raw CSS code. It is not necessary to write <style> </style> tags.

    "},{"location":"acelements.html#autoconnectselect","title":"AutoConnectSelect","text":"

    AutoConnectSelect generates an HTML <select> tag (drop-down list) and few <option> tags.

    Sample AutoConnectSelect select(\"select\", { String(\"Europe/London\"), String(\"Europe/Berlin\"), String(\"Europe/Helsinki\"), String(\"Europe/Moscow\"), String(\"Asia/Dubai\") }, \"Select TZ name\");

    On the page:

    "},{"location":"acelements.html#constructor_8","title":"Constructor","text":"
    AutoConnectSelect(const char* name, std::vector<String> const& options, const char* label, const uint8_t selected, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_8","title":"name","text":"

    It is the name of the AutoConnectSelect element and matches the name attribute of the select tags.

    "},{"location":"acelements.html#options","title":"options","text":"

    An options is an array of String type for the options which as actually std::vector for an HTML <option> tag. It is an initialization list can be used. The option tags will be generated from each entry in the options, the amount of which is the same as the number of items in an options.

    "},{"location":"acelements.html#label_5","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the drop-down list. Specification of a label will generate an HTML <label> tag with an id attribute. The select tag and the label are connected by the id attribute.

    "},{"location":"acelements.html#selected","title":"selected","text":"

    A selected is an optional value. Specifies that an option should be pre-selected when the page loads.

    "},{"location":"acelements.html#post_7","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_BR.

    "},{"location":"acelements.html#autoconnectsubmit","title":"AutoConnectSubmit","text":"

    AutoConnectSubmit generates an HTML <input type=\"button\"> tag attached onclick attribute. The native code of the onclick attribute is the submission of the form with the POST method.

    Sample AutoConnectSubmit submit(\"submit\", \"Save\", \"/mqtt_save\");

    On the page:

    "},{"location":"acelements.html#constructor_9","title":"Constructor","text":"
    AutoConnectSubmit(const char* name, const char* value, const char* uri, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_9","title":"name","text":"

    It is the name of the AutoConnectSubmit element and matches the name attribute of the input tag.

    "},{"location":"acelements.html#value_7","title":"value","text":"

    It becomes a string of the value attribute of an HTML <input type=\"button\"> tag. The value will be displayed as a label of the button.

    "},{"location":"acelements.html#uri","title":"uri","text":"

    A uri specifies the URI to send form data when the button declared by AutoConnectSubmit is clicked.

    The query string of the form data sent with AutoConnectSubmit contains the URI of the page. Its parameter name is _acuri. In Sketch, you can know the called URI by referring to the _acuri parameter with the destination page handler. The actual query string is as follows:

    _acuri=CALLER_URI

    "},{"location":"acelements.html#post_8","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. The default values is AC_Tag_None.

    "},{"location":"acelements.html#autoconnecttext","title":"AutoConnectText","text":"

    AutoConnectText generates a text content enclosed in <div>, <p> or <span> tags; if the style parameter is provided, the style attributes is added. A kind of HTML tag applied depends on the value of the post parameter as follows:

    • AC_Tag_None: <span id='name' style='style'>value</span>
    • AC_Tag_BR: <span id='name' style='style'>value</span><br>
    • AC_Tag_P: <p id='name' style='style'>value</p>
    • AC_Tag_DIV: <div id='name' style='style'>value</div>

    Sample AutoConnectText text(\"text\", \"Publishing the WiFi signal strength to MQTT channel. RSSI value of ESP8266 to the channel created on ThingSpeak\", \"font-family:serif;color:#4682b4;\");

    On the page:

    "},{"location":"acelements.html#constructor_10","title":"Constructor","text":"
    AutoConnectText(const char* name, const char* value, const char* style, const char* format, const ACPosterior_t post)\n
    "},{"location":"acelements.html#name_10","title":"name","text":"

    A name does not exist in the generated HTML. It provides only a means of accessing elements with the Sketches.

    "},{"location":"acelements.html#value_8","title":"value","text":"

    It becomes content and also can contain the native HTML code, but remember that your written code is enclosed by the div tag.

    "},{"location":"acelements.html#style_1","title":"style","text":"

    A style specifies the qualification style to give to the content and can use the style attribute format as it is.

    "},{"location":"acelements.html#format","title":"format","text":"

    A format is a pointer to a null-terminated multi byte string specifying how to interpret the value. It specifies the conversion format when outputting values. The format string conforms to C-style printf library functions, but depends on the Espressif's SDK implementation. The conversion specification is valid only in %s format. (Left and Right justification, width are also valid.)

    "},{"location":"acelements.html#post_9","title":"post","text":"

    Specifies an HTML element that completes the text content. AutoConnectText's post parameter does not specify any behind-supplements, unlike when applied to other elements. A kind of HTML tag applied depends on the enumerated value of the post parameter as follows:

    • AC_Tag_None: <span id='name' style='style'>value</span>
    • AC_Tag_BR: <span id='name' style='style'>value</span><br>
    • AC_Tag_P: <p id='name' style='style'>value</p>
    • AC_Tag_DIV: <div id='name' style='style'>value</div>
    "},{"location":"acelements.html#how-to-coding-for-the-elements","title":"How to coding for the elements","text":""},{"location":"acelements.html#declaration-for-the-elements-in-sketches","title":"Declaration for the elements in Sketches","text":"

    Variables of each AutoConnetElement can be declared with macros. By using the macros, you can treat element name that is String type as variable in sketches.2

    ACElement ( name [ , value ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACButton ( name [ , value ] [ , action ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACCheckbox ( name [ , value ] [ , label ] [ , true | false ] [ , AC_Infront | AC_Behind ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACFile ( name [ , value ] [ , label ] [ , AC_File_FS | AC_File_SD | AC_File_Extern ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACInput ( name [ , value ] [ , label ] [ , pattern ] [ , placeholder ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] [ , AC_Input_Text | AC_Input_Password | AC_Input_Number ])

    ACRadio ( name [ , values ] [ , label ] [ , AC_Horizontal | AC_Vertical ] [ , checked ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACRange ( name [ , value ] [ , label ] [ , min ] [ , max ] [ , step ] [ , AC_Infront | AC_Behind | AC_Void ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] [ , style ] )

    ACSelect ( name [ , options ] [ , label ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACStyle ( name [ , value ] )

    ACSubmit ( name [ , value ] [ , uri ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    ACText ( name [ , value ] [ , style ] [ , format ] [ , AC_Tag_None | AC_Tag_BR | AC_Tag_P | AC_Tag_DIV ] )

    Declaration macro usage

    For example, AutoConnectText can be declared using macros. 

    AutoConnectText caption(\"caption\", \"hello, world\", \"color:blue;\")\n
    equals by using ACText macro. 
    ACText(caption, \"hello, world\", \"color:blue;\")\n

    "},{"location":"acelements.html#variant-for-autoconnectelements","title":"Variant for AutoConnectElements","text":"

    Some AutoConnectAux APIs specify AutoConnectElements as an argument. There are also functions that return a pointer to AutoConnectElements. AutoConnectElement behaves as a variant type of each element class to make these interfaces a single. Use reinterpret_cast to cast from a variant pointer to an Actual type pointer of AutoConnectElements.

    AutoConnectAux aux;\nACText(Text1, \"hello, world\");\naux.add(Text1);\nAutoConnectText* text_p = reinterpret_cast<AutoConnectText*>(aux.getElement(\"Text1\"));\nAutoConnectText& text = aux.getElement<AutoConnectText>(\"Text1\");\n

    1. JavaScript can be inserted into a custom Web page using AutoConnectElement.\u00a0\u21a9

    2. The square brackets in the syntax are optional parameters, the stroke is a selection parameter, the bold fonts are literal.\u00a0\u21a9

    "},{"location":"achandling.html","title":"Handling the custom Web pages","text":""},{"location":"achandling.html#page-container-component","title":"Page, Container, Component","text":"

    AutoConnectAux is the container for a custom Web page, AutoConnectElement is the component of a page. AutoConnectElements must be contained in AutoConnectAux object. (ie. they are the elements displayed on the custom Web page.) Then AutoConnect makes an AutoConnectAux to a page.

    AutoConnectElements declared in sketch must be programmed to add to AutoConnectAux one after another. Elements are automatically included in AutoConnectAux by AutoConnect if you load it from the JSON document. In either method, it is common to use the function of AutoConnectAux to access an element with a sketch.

    "},{"location":"achandling.html#custom-web-page-handler-programming-model","title":"Custom Web page handler programming model","text":"

    To handle Custom Web pages properly, the sketches need to implement to match the programming model. Custom Web page programming model is depicted as follows:

    Custom Web page handler acts as an event handler for processing the HTTP request captured by the WebServer class. The WebServer class parses the HTTP request and calls the registered uri handler appropriately. The custom web page uri (it should be specified by the JSON description for the custom web page, the AutoConnectAux constructor, or the AutoConnect::on function) is not registered directly with the WebServer class, and the Requests always go through the request dispatcher inside AutoConnect.

    When implementing the custom Web page handler, it is possible to give an appropriate function to the handler by understanding the above internal structure in advance. Custom web page handler can be sketched as regular function and has interface is as follows:

    String customWebpageHandler(AutoConnectAux& aux, PageArgument& args)\n
    "},{"location":"achandling.html#parameters-for-the-customwebagehandler","title":"Parameters for the customWebageHandler","text":"

    When the custom web page handler is called, AutoConnect passes the following two parameters:

    "},{"location":"achandling.html#1-reference-to-the-autoconnectaux-instance","title":"1. Reference to the AutoConnectAux instance","text":"

    Custom Web page handlers can access the AutoConnectElements owned by its page through a reference to the AutoConnectAux instance. It can use this access to update the AutoConnectElements value before the user views the page or get the value of AutoConnectElements owned by the page that triggered the transition.

    A list of commonly used functions to access AutoConnectElements with your Sketch via reference to an AutoConnectAux instance is following:

    • [] operator : Access to an AutoConnectElement by specified element name.
    • getElement function : Access to an AutoConnectElement by specified element name.
    • as<> function : Cast from a variant of AutoConnectElement type to an actual type such as AutoConnectText or AutoConnectInput etc. To access attributes that exist only in the actual type, it is necessary to convert from the AutoConnectElement type obtained with [] operator or getElement function.

    See the section Get AutoConnectElement from the AutoConnectAux and the section AutoConnectElements API for usage examples and API specifications for each above function.

    "},{"location":"achandling.html#2-reference-to-the-pageargument-instance","title":"2. Reference to the PageArgument instance","text":"

    The values of the AutoConnectCheckbox, AutoConnectFile, AutoConnectInput, AutoConnectRadio, and AutoConnectSelect elements are packed into the form data of the HTTP POST method by the page transition caused by AutoConnectSubmit. Use the PageArgument instance to retrieve the values of these transmitted AutoConnectElements with the customWebpageHandler. A list of commonly used functions to access PageArgment member variables with your Sketch via a reference to an PageArgument instance is following:

    • arg function : Get an element value by specified element name.
    • hasArg function : Checks for the existence of an element with the specified name.

    The method to get the form data attached to the HTTP request via PageArgument is described with the section How you can reach the values.

    "},{"location":"achandling.html#3-access-to-the-autoconnectelement-values","title":"3. Access to the AutoConnectElement values","text":"

    Here, you have one thing to note. The custom web page handler registered with AutoConnect::on function is called to respond to an HTTP request to the URL of its page. And, the AutoConnectAux instance then references the custom web page assigned to the requested URL. That is, the AutoConnectAux instance passed to the custom web page handler owns the AutoConnectElements for that page, while the PageArgument instance has the AutoConnectElements value of the custom web page that caused the page transition. You need to keep the difference between the two in mind when implementing the custom web page handler with your Sketch and access these values via the appropriate approach.

    You can access the AutoConnect Elements of the custom web page itself via the AutoConnectAux& argument by specifying the element name. You can also use the PageArgument& argument to get the value of AutoConnectElements for the page that caused the transition to that custom web page. (the URL that issued the HTTP request)

    The following screenshots are outputs of custom web pages that are based on a scenario to help you understand how to access AutoConnectElements properly with a custom web page handler. The requirements for this scenario are:

    • Calculate an addition simply, add B to A.
    • Perform the calculation with a customWebPageHandler.
    • Returns the calculated result in another custom web page with page transitions.

    The first thing to work on is defining two custom web pages. Here, Value A and Value B are easily defined by applying AutoConnectInput. Also, add an action button to perform the calculation with AutoConnectSubmit.

    {\n\"uri\": \"/add\",\n\"title\": \"Adder\",\n\"menu\": true,\n\"element\": [\n    {\n\"name\": \"valueA\",\n\"type\": \"ACInput\",\n\"label\": \"Value A\",\n\"apply\": \"number\"\n    },\n    {\n\"name\": \"valueB\",\n\"type\": \"ACInput\",\n\"label\": \"Value B\",\n\"apply\": \"number\"\n    },\n    {\n\"name\": \"add\",\n\"type\": \"ACSubmit\",\n\"value\": \"ADD\",\n\"uri\": \"/results\"\n    }\n  ]\n}\n

    Next, define an additional page to display the results. Here we use AutoConnectText to display the calculation as a representation string of the expression. There is one thing to watch out for here. That is, the transition destination of the action button as ADD that accept the operand (it is specified by the uri of the ACSubmit element named \"add\") and the uri of the page that displays the answer are the same.

    {\n\"uri\": \"/results\",\n\"title\": \"Adder\",\n\"menu\": false,\n\"element\": [\n    {\n\"name\": \"results\",\n\"type\": \"ACText\"\n    }\n  ]\n}\n

    When implementing a custom web page handler, it's usually a good idea to pre-determine the page design (which consists of the elements and layouts you want to use) for a better outlook when coding your Sketch. Especially when coding a custom web page handler, you need to specify the AutoConnectElements exactly, and it is recommended to implement it along the JSON defined earlier.

    After this, sketch the handlers for the above two custom web pages.

    First, the handler for the page allocated to /add. The role of this handler is to initialize the values respectively for the valueA and valueB input boxes. Both of these two input boxes are on the /add page, so the handler only references the AutoConnectAux& aux argument.

    You can use the [] operator with the element name like as aux[\"valueA\"] to get a reference to an AutoConnectElement by name. Then, once the reference is converted to AutoConnectInput, the value member of AutoConnectInput can be accessed. Use the as<AutoConnectInput>() function to convert from the AutoConnectElement type to the actual AutoConnectInput type.

    String onAdd(AutoConnectAux& aux, PageArgument& args) {\n  aux[\"valueA\"].as<AutoConnectInput>().value = \"0\";\n  aux[\"valueB\"].as<AutoConnectInput>().value = \"0\";\nreturn String();\n}\n

    Next, the handler for the page allocated to /results. The role of this handler is to add the value B to A for the calculation. The /results page does not have an element that contains the operands Value A and Value B to calculate. Only the /add page has them. The /results page handler is called when ACSubmit on the /add page works, so valueA and valueB are included in the form data of the HTTP POST request to the /results page. That is, the handler for the /results page will get valueA and valueB from the PageArgument& args argument.

    String onResults(AutoConnectAux& aux, PageArgument& args) {\nint valueA = args.arg(\"valueA\").toInt();\nint valueB = args.arg(\"valueB\").toInt();\n\n  aux[\"results\"].as<AutoConnectText>().value = String(valueA) + \" + \" + String(valueB) + \" = \" + String(valueA + valueB);\nreturn String();\n}\n

    PageArgument is a built-in class in the PageBuilder library. You can use the PageArgument::arg function to retrieve the parameters of the form data contained in the POST request by name. Since the PageArgument::arg function returns the parameters of the POSTed form data as a string, it converts Value A and Value B to the operand integer value of the addition via the String::toInt() function.

    int valueA = args.arg(\"valueA\").toInt();\nint valueB = args.arg(\"valueB\").toInt();\n

    In this scenario, in addition to the calculation result, the calculation formula is also displayed on the result page.

    aux[\"results\"].as<AutoConnectText>().value = String(valueA) + \" + \" + String(valueB) + \" = \" + String(valueA + valueB);\n
    "},{"location":"achandling.html#the-customwebpagehandler-return-value","title":"The customWebpageHandler return value","text":"

    The customWebpageHandler returns a string. The returned string is used internally by AutoConnect to temporarily qualify the HTML generating of the custom web page. AutoConnect typically calls a custom web page handler before HTML generation.

    When the customWebpageHandler returns an HTML string for qualification, it applies to the drawing area for the elements of AutoConnectElements. Additionally, you can then specify where the modifier HTML will be inserted. The second parameter of the AutoConnectAux::on function, which allows the registration of custom web page handlers, indicates where to insert the modifier HTML.

    The Sketch can specify the following three values for the second parameter of AutoConnectAux::on function:

    • AC_EXIT_AHEAD : Modifiers HTML returned by the custom Web page handler is inserted into the front of the list expansion of AutoConnectElements.

    • AC_EXIT_LATER : Modifiers HTML returned by the custom Web page handler is inserted into the back of the list expansion of AutoConnectElements.

    • AC_EXIT_BOTH : The customWebpageHandle will be called twice before and after list expansion of AutoConnectElements.

    A detailed description of the AutoConnectAux::on function can be found in Section AutoConnectAux API.

    The actual sketch code implemented following these steps above would look like this (case of ESP8266):

    #include <Arduino.h>\n#include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nconst char PAGE_ADD[] PROGMEM = R\"(\n{\n  \"uri\": \"/add\",\n  \"title\": \"Adder\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"valueA\",\n      \"type\": \"ACInput\",\n      \"label\": \"Value A\",\n      \"apply\": \"number\"\n    },\n    {\n      \"name\": \"valueB\",\n      \"type\": \"ACInput\",\n      \"label\": \"Value B\",\n      \"apply\": \"number\"\n    },\n    {\n      \"name\": \"add\",\n      \"type\": \"ACSubmit\",\n      \"value\": \"ADD\",\n      \"uri\": \"/results\"\n    }\n  ]\n}\n)\";\n\nconst char PAGE_RESULTS[] PROGMEM = R\"(\n{\n  \"uri\": \"/results\",\n  \"title\": \"Adder\",\n  \"menu\": false,\n  \"element\": [\n    {\n      \"name\": \"results\",\n      \"type\": \"ACText\"\n    }\n  ]\n}\n)\";\n\nAutoConnect portal;\nAutoConnectAux  page_add;\nAutoConnectAux  page_results;\n\nString onAdd(AutoConnectAux& aux, PageArgument& args) {\n  aux[\"valueA\"].as<AutoConnectInput>().value = \"0\";\n  aux[\"valueB\"].as<AutoConnectInput>().value = \"0\";\nreturn String();\n}\n\nString onResults(AutoConnectAux& aux, PageArgument& args) {\nint valueA = args.arg(\"valueA\").toInt();\nint valueB = args.arg(\"valueB\").toInt();\n\n  aux[\"results\"].as<AutoConnectText>().value = String(valueA) + \" + \" + String(valueB) + \" = \" + String(valueA + valueB);\nreturn String();\n}\n\nvoid setup() {\n  delay(1000);\n  page_add.load(PAGE_ADD);\n  page_results.load(PAGE_RESULTS);\n  portal.join({ page_add, page_results });\n  portal.on(\"/add\", onAdd);\n  portal.on(\"/results\", onResults);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"achandling.html#handing-autoconnectelements-with-the-sketches","title":"Handing AutoConnectElements with the Sketches","text":"

    The AutoConnectAux class has several functions to manipulate AutoConnectElements. The functions can add, delete, retrieve elements, and get and set values.

    "},{"location":"achandling.html#add-autoconnectelements-to-the-autoconnectaux-object","title":"Add AutoConnectElements to the AutoConnectAux object","text":"

    To add AutoConnectElment(s) to an AutoConnectAux object, use the add function.

    void AutoConnectAux::add(AutoConnectElement& addon)\n
    void AutoConnectAux::add(AutoConnectElementVT addons)\n

    The add function adds the specified AutoConnectElement to AutoConnectAux. The AutoConnectElementVT type is the std::vector of the reference wrapper to AutoConnectElements, and you can add these elements in bulk by using the list initialization with the Sketch.

    typedef std::vector<std::reference_wrapper<AutoConnectElement>> AutoConnectElementVT;\n

    AutoConnectElements contained in AutoConnectAux object are uniquely identified by name. When adding an AutoConnectElement, if an element with the same name already exists in the AutoConnectAux, checking the type, and if it is the same, the value will be replaced. If another type of AutoConnectElement exists with the same name, that add operation will be invalid.1 In the following example, AutoConnectButton button addition will invalid because hello with the same name already exists as AutoConnectText.

    AutoConnectAux  aux;\nAutoConnectText text(\"hello\", \"hello, world\");\nAutoConnectButton button(\"hello\", \"hello, world\", \"alert('Hello world!')\");  // This is invalid.\naux.add({ text, button });\n

    Similarly this, the uniqueness of the name is also necessary within the JSON document

    {\n\"name\" : \"aux\",\n\"uri\" : \"/aux\",\n\"menu\" : true,\n\"element\" : [\n    {\n\"name\": \"hello\",\n\"type\": \"ACText\",\n\"value\": \"hello, world\"\n    },\n    {\n\"name\": \"hello\",\n\"type\": \"ACButton\",\n\"value\": \"hello, world\",\n\"action\": \"alert('Hello world!')\"\n    }\n  ]\n}\n

    Load all elements from JSON document

    If you load all AutoConnectElements from JSON document into AutoConnect, you do not need to sketch the population process of the AutoConnectElements. It is managed by the AutoConnect library automatically.

    "},{"location":"achandling.html#get-autoconnectelement-from-the-autoconnectaux","title":"Get AutoConnectElement from the AutoConnectAux","text":"

    To retrieve an element from AutoConnectAux, use the getElement or getElements function. Normally, the getElement is needed when accessing the value of AutoConnectElement in the Sketch.

    AutoConnectElement* AutoConnectAux::getElement(const char* name)\n
    AutoConnectElement* AutoConnectAux::getElement(const __FlashStringHelper* name)\n
    AutoConnectElement* AutoConnectAux::getElement(const String& name)\n
    T& AutoConnectAux::getElement<T>(const String& name)\n
    AutoConnectElementVT* AutoConnectAux::getElements(void)\n

    The getElement function returns an AutoConnectElement with the specified name as a key. When you use this function, you need to know the type of AutoConnectElement in advance and specify its type <T> to an argument of the getElement. A type of <T> can be specified as follows.

    AutoConnectButton& AutoConnectAux::getElement<AutoConnectButton>(const String& name)\nAutoConnectCheckbox& AutoConnectAux::getElement<AutoConnectCheckbox>(const String& name)\nAutoConnectElement& AutoConnectAux::getElement<AutoConnectElement>(const String& name)\nAutoConnectFile& AutoConnectAux::getElement<AutoConnectFile>(const String& name)\nAutoConnectInput& AutoConnectAux::getElement<AutoConnectInput>(const String& name)\nAutoConnectRadio& AutoConnectAux::getElement<AutoConnectRadio>(const String& name)\nAutoConnectSelect& AutoConnectAux::getElement<AutoConnectSelect>(const String& name)\nAutoConnectSubmit& AutoConnectAux::getElement<AutoConnectSubmit>(const String& name)\nAutoConnectText& AutoConnectAux::getElement<AutoConnectText>(const String& name)\n

    To retrieve an AutoConnectElement by specifying its type, use the following method.

    AutoConnectAux  aux;\naux.load(\"SOME_JSON_DOCUMENT\");\n\n// Retrieve the pointer of the AutoConnectText\nAutoConnectText* text = reinterpret_cast<AutoConnectText*>(aux.getElement(\"TEXT_ELEMENT_NAME\"));\n\n// Retrieve the reference of the AutoConnectText\nAutoConnectText& text = aux.getElement<AutoConnectText>(\"TEXT_ELEMENT_NAME\");\n

    The AutoConnectElement type behaves as a variant of other element types. Therefore use cast or template to convert to actual type as above. In the Sketch, you access the real type of AutoConnectElement after casting it and storing into the variable.

    const String auxJson = String(\"{\\\"title\\\":\\\"Page 1 title\\\",\\\"uri\\\":\\\"/page1\\\",\\\"menu\\\":true,\\\"element\\\":[{\\\"name\\\":\\\"caption\\\",\\\"type\\\":\\\"ACText\\\",\\\"value\\\":\\\"hello, world\\\"}]}\");\nAutoConnect portal;\nportal.load(auxJson);\nAutoConnectAux* aux = portal.aux(\"/page1\");  // Identify the AutoConnectAux instance with uri\nAutoConnectText& text = aux->getElement<AutoConnectText>(\"caption\");  // Cast to real type and access members\nSerial.println(text.value);\n

    You can also use the operator [] of AutoConnectAux as another way to get the desired element. An operator [] is a shortcut for getElement function with the reference casting and makes simplify the Sketch code and treats like an array with the elements placed on a custom Web page. Its argument is the name of the element to be acquired similarly to getElement function. In the Sketch, by combining the AutoConnectElement::as<T> function with the operator [], you can access the AutoConnectElements reference according to its actual type. For example, the following sketch code returns the same as a reference of AutoConnectText element as the caption.

    AutoConnect portal;\nportal.load(auxJson);\nAutoConnectAux&  aux = *portal.aux(\"/page1\");\nAutoConnectText& text1 = aux.getElement<AutoConnectElement>(\"caption\");\nAutoConnectText& text2 = aux[\"caption\"].as<AutoConnectText>();\n

    Need cast to convert to the actual type

    An operator [] returns a reference of an AutoConnectElement. It is necessary to convert the type according to the actual element type with AutoConnectElement::as<T> function. 

    AutoConnectButton& AutoConnectElement::as<AutoConnectButton>()\nAutoConnectCheckbox& AutoConnectElement::as<AutoConnectCheckbox>()\nAutoConnectElement& AutoConnectElement::as<AutoConnectElement>()\nAutoConnectFile& AutoConnectElement::as<AutoConnectFile>()\nAutoConnectInput& AutoConnectElement::as<AutoConnectInput>()\nAutoConnectRadio& AutoConnectElement::as<AutoConnectRadio>()\nAutoConnectSelect& AutoConnectElement::as<AutoConnectSelect>()\nAutoConnectSubmit& AutoConnectElement::as<AutoConnectSubmit>()\nAutoConnectText& AutoConnectElement::as<AutoConnectText>()\n

    To get all the AutoConnectElements in an AutoConnectAux object use the getElements function. This function returns the vector of the reference wrapper as AutoConnectElementVT to all AutoConnectElements registered in the AutoConnectAux.

    AutoConnectElementVT& AutoConnectAux::getElements(void)\n
    "},{"location":"achandling.html#enable-autoconnectelements-during-the-sketch-execution","title":"Enable AutoConnectElements during the Sketch execution","text":"

    AutoConnectElemets have an enable attribute to activate its own HTML generation. Sketches can change the HTMLization of their elements dynamically by setting or resetting the enable value. An element whose the enable attribute is true will generate itself HTML and place on the custom Web page. And conversely, it will not generate the HTML when the value is false.

    For example, to enable the submit button only when the ESP module is connected to the access point in STA mode, you can sketch the following:

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char AUX[] PROGMEM = R(\"\n{\n\"name\" : \"aux\",\n\"uri\" : \"/aux\",\n\"menu\" : true,\n\"element\" : [\n    {\n\"name\": \"input\",\n\"type\": \"ACInput\",\n\"label\": \"Input\"\n    },\n    {\n\"name\": \"send\",\n\"type\": \"ACSubmit\",\n\"uri\": \"/send\"\n    }\n  ]\n}\n\");\n\nAutoConnect    portal;\nAutoConnectAux page;\n\nString onPage(AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectSubmit& send = aux[\"send\"].as<AutoConnectSubmit>();\nif (WiFi.isConnected())\n    send.enable = (WiFi.getMode() == WIFI_STA);\nelse\n    send.enable = false;\nreturn String();\n}\n\nvoid setup() {\n  page.load(AUX);\n  page.on(onPage);\n  portal.join(page);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    Desirable to set or reset the enable attribute in the page handler

    The enable attribute can be set at any time during the Sketch execution. The page handler with the AC_EXIT_AHEAD option is sure to handle it.

    "},{"location":"achandling.html#loading-saving-autoconnectelements-with-json","title":"Loading & saving AutoConnectElements with JSON","text":"

    AutoConnect supports reading the custom Web page definitions written in JSON and also supports loading and saving of AutoConnectAux or AutoConnectElements. In both cases, the target object is a JSON document for AutoConnect. However, it can not save all AutoConnectElements contained in the page as a custom Web page. (ie. AutoConnectAux)

    "},{"location":"achandling.html#loading-autoconnectaux-autoconnectelements-with-json","title":"Loading AutoConnectAux & AutoConnectElements with JSON","text":"

    To load a JSON document as AutoConnectAux use the AutoConnect::load function and load the JSON document of each AutoConnectElement using the AutoConnectAux::loadElement function. Although the functions of both are similar, the structure of the target JSON document is different.

    The AutoConnect::load function loads the entire AutoConnectAux and creates both the AutoConnectAux instance and each AutoConnectElement instance. A single JSON document can contain multiple custom Web pages. If you write JSON of AutoConnectAux as an array, the load function generates all the pages contained in that array. Therefore, it is necessary to supply the JSON document of AutoConnectAux as an input of the load function and must contain the elements described section JSON document structure for AutoConnectAux.

    The AutoConnectAux::loadElement function loads the elements individually into an AutoConnectAux object. The structure of its supplying JSON document is not AutoConnectAux. It must be a JSON structure for AutoConnectElement, but you can specify an array.

    // AutoConnectAux as a custom Web page.\nconst char page[] PROGMEM = R\"raw(\n{\n  \"title\": \"Settings\",\n  \"uri\": \"/settings\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"server\",\n      \"type\": \"ACInput\",\n      \"label\": \"Server\"\n    },\n    {\n      \"name\": \"set\",\n      \"type\": \"ACSubmit\",\n      \"value\": \"SET\",\n      \"uri\" : \"/set\"\n    }\n  ]\n}\n)raw\";\n\n// Additional AutoConnectElements.\nconst char addons[] PROGMEM = R\"raw(\n[\n  {\n    \"name\": \"notes\",\n    \"type\": \"ACText\",\n    \"value\": \"An update period as the below optionally.\"\n  },\n  {\n    \"name\": \"period\",\n    \"type\": \"ACRadio\",\n    \"value\": [\n      \"30 sec.\",\n      \"60 sec.\",\n      \"180 sec.\"\n    ],\n    \"arrange\": \"vertical\",\n    \"checked\": 1\n  }\n]\n)raw\";\n\nAutoConnect     portal;\nAutoConnectAux* auxPage;\n\n// Load a custom Web page.\nportal.load(page);\n// Get a '/settings' page\nauxPage = portal.aux(\"/settings\");\n\n// Also, load only AutoConnectRadio named the period.\nauxPage->loadElement(addons, \"period\");\n// Retrieve a server name from an AutoConnectText value.\nAutoConnectText& serverName = auxPage->getElement<AutoConnectText>(\"server\");\nSerial.println(serverName.value);\n
    "},{"location":"achandling.html#saving-autoconnectelements-with-json","title":"Saving AutoConnectElements with JSON","text":"

    To save the AutoConnectAux or the AutoConnectElement as a JSON document, use the AutoConnectAux::saveElement function. It serializes the contents of the object based on the type of the AutoConnectElement. You can persist a serialized AutoConnectElements as a JSON document to a stream.

    // Open a parameter file on the SPIFFS.\nSPIFFS.begin();\nFILE param = SPIFFS.open(\"/param\", \"w\");\n\n// Save elements as the parameters.\nauxPage->saveElement(param, { \"server\", \"period\" });\n\n// Close a parameter file.\nparam.close();\nSPIFFS.end();\n

    The example above saves server and period elements from the AutoConnectAux object as mentioned above to the /param file on SPIFFS. Its JSON document of AutoConnectElements saved by its code looks like this:

    [\n  {\n\"name\": \"server\",\n\"type\": \"ACInput\",\n\"value\": \"An inputted server name\",\n\"label\": \"Server\",\n\"placeholder\": \"\"\n  },\n  {\n\"name\": \"period\",\n\"type\": \"ACRadio\",\n\"value\": [\n\"30 sec.\",\n\"60 sec.\",\n\"180 sec.\"\n    ],\n\"arrange\": \"vertical\",\n\"checked\": 2\n  }\n]\n

    Above JSON document can be loaded as it is into a custom Web page using the loadElement function. The loadElement function also loads the value of the element, so the saved value can be restored on the custom Web page.

    "},{"location":"achandling.html#custom-field-data-handling","title":"Custom field data handling","text":"

    A sketch can access variables of AutoConnectElements in the custom Web page. The value entered into the AutoConnectElements on the page is stored in the member variable of each element by AutoConnect whenever GET/POST transmission occurs.

    The following diagram shows the flow of the input values of a custom Web page into a sketch and is the basis for actions to manipulate the values of custom Web pages using sketches.

    "},{"location":"achandling.html#where-to-pick-up-the-values","title":"Where to pick up the values","text":"

    A sketch composed of handlers can receive the value of AutoConnectElements entered in a custom Web page after sending, but that handler is different from the page where the value was entered. It is necessary to be aware that can accept the entered values by the next page handler after the transition.

    Usually, two ways to retrieve entered values we have. One is to use the ESP8266WebServer::arg (or WebServer::arg for ESP32) function in the on handler attached by ESP8266WebServer (WebServer w/ESP32 also).

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char addonJson[] PROGMEM = R\"raw(\n{\n  \"title\": \"Hello\",\n  \"uri\": \"/hello\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"feels\",\n      \"type\": \"ACInput\",\n      \"label\": \"What's up?\"\n    },\n    {\n      \"name\": \"send\",\n      \"type\": \"ACSubmit\",\n      \"value\": \"Just it!\",\n      \"uri\": \"/feels\"\n    }\n  ]\n}\n)raw\";\n\nESP8266WebServer webServer;\nAutoConnect portal(webServer);\n\n// Here, /feels handler\nvoid feelsOn() {\n\n// Retrieve the value of a input-box named \"feels\"\n  String feel = webServer.arg(\"feels\");\n// Echo back the value\n  String echo = \"<html><p style=\\\"color:blue;font-family:verdana;font-size:300%;\\\">\" + feel + String(\" and a bold world!</p></html>\");\n  webServer.send(200, \"text/html\", echo);\n}\n\nvoid setup() {\n  delay(1000);\n  webServer.on(\"/feels\", feelsOn);  // Register /feels handler\n  portal.load(addonJson);           // Load a custom Web page\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    An above example is the most simple sketch of handling values entered into a custom Web page. This sketch obtains the string entered in the AutoConnectInput named feels with the /feels handler after page transition, and the AutoConnectInput is an <input type=\"text\" name=\"feels\"> element wrapped in the form as the actual HTML code.

    Should be accessed /_ac first

    When you actually try the above sketch, there is no a root handler. So the URL that should be accessed first is /_ac concatenated with the local IP address of the esp8266 module.

    Another method is effective when custom Web pages have complicated page transitions. It is a way to straight access the AutoConnectElements member value. You can get the AutoConnectElement with the specified name using the getElement function. The following sketch executes the above example with AutoConnect only, without using the function of ESP8266WebServer.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nconst static char addonJson[] PROGMEM = R\"raw(\n[\n  {\n    \"title\": \"Hello\",\n    \"uri\": \"/hello\",\n    \"menu\": true,\n    \"element\": [\n      {\n        \"name\": \"feels\",\n        \"type\": \"ACInput\",\n        \"label\": \"What's up?\"\n      },\n      {\n        \"name\": \"send\",\n        \"type\": \"ACSubmit\",\n        \"value\": \"Just it!\",\n        \"uri\": \"/feels\"\n      }\n    ]\n  },\n  {\n    \"title\": \"Hello\",\n    \"uri\": \"/feels\",\n    \"menu\": false,\n    \"element\": [\n      {\n        \"name\": \"echo\",\n        \"type\": \"ACText\",\n        \"style\": \"color:blue;font-family:verdana;font-size:300%;\"\n      }\n    ]\n  }\n]\n)raw\";\n\nAutoConnect portal;\n\n// Here, /feels handler\nString feelsOn(AutoConnectAux& aux, PageArgument& args) {\n\n// Get the AutoConnectInput named \"feels\".\n// The where() function returns an uri string of the AutoConnectAux that triggered this handler.\n  AutoConnectAux* hello = portal.aux(portal.where());\n  AutoConnectInput& feels = hello->getElement<AutoConnectInput>(\"feels\");\n// Get the AutoConnectText named \"echo\".\n  AutoConnectText&  echo = aux.getElement<AutoConnectText>(\"echo\");\n// Echo back from input-box to /feels page.\n  echo.value = feels.value +  String(\" and a bold world!\");\nreturn String(\"\");\n}\n\nvoid setup() {\n  delay(1000);\n  portal.load(addonJson);                       // Load custom Web pages\n  portal.on(\"/feels\", feelsOn, AC_EXIT_AHEAD);  // Register /feels handler\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    The above example handles in the handler for the values of a custom Web page. An AutoConnect::on function registers a handler for the AutoConnectAux page of the specified uri. The argument of the custom Web page handler is an AutoConnectAux of the page itself and the PageArgument object.

    To retrieve the values entered in a custom Web page you need to access the AutoConnectElement of the page that caused the request to this page and to do this, you use the AutoConnect::where function. The AutoConnect::where function returns an uri string of the AutoConnectAux object of the custom Web page that caused the HTTP request.

    The where() function is available for only AutoConnectAux.

    The AutoConnect::where function is available only for the AutoConnectAux object. It is invalid for HTTP requests from individual pages registered with the on handler of ESP8266WebServer/WebServer for ESP32. In other words, the AutoConnect::where function only returns the last AutoConnecAux page called.

    "},{"location":"achandling.html#when-setting-the-initial-values","title":"When setting the initial values","text":"

    An AutoConnectAux page is dynamically created by AutoConnect when its uri is requested. The initial value of AutoConnectElements can be set before its page request. It is also possible during loop(). To set the initial value when the page is accessed it needs by the handler of its page.

    The AutoConnect::on and AutoConnectAux::on functions register a handler for a custom Web page and also specify when to call that handler. The behavior of the two on functions is the same, only the class and arguments are different.

    bool AutoConnect::on(const String& uri, const AuxHandlerFunctionT handler, AutoConnectExitOrder_t order)\n
    void AutoConnectAux::on(const AuxHandlerFunctionT handler, const AutoConnectExitOrder_t order)\n

    Parameter uri specifies an URI of the custom Web page, but an AutoConnectAux object with its URI must be registered with AutoConnect via the AutoConnect::join function beforehand.

    AutoConnect::on/AutoConnectAux::on is not ESP8266WebServer::on

    The on function for AutoConnect is different from the on function of Arduino core ESP8266WebServer (WebServer for ESP32). You can share the same handler via wrapper, but access to AutoConnectElements is valid only for handlers registered with on function for AutoConnect.

    AuxHandlerFunctionT type is a handler declaration using with std::function.

    String handler(AutoConnectAux& aux, PageArgument& args)\n

    The handler of the custom Web page has two arguments by a reference of AutoConnectAux and a reference of PageArgument, it returns String. AutoConnect appends the string returned from the handler to the generated HTML. This allows you to add an HTML part before displaying the page.

    AutoConnectExitOrder_t specifies when the handler is called with the following enumeration value.
    • AC_EXIT_AHEAD : Called before AutoConnect generates the HTML of the page. You set the value of AutoConnectElements in the handler then its value will be displayed on the page.
    • AC_EXIT_LATER : Called after AutoConnect generates the HTML of the page. You can append to HTML generated by AutoConnect.
    • AC_EXIT_BOTH : Called even before generating HTML and after generated.

    The following example is a part of sketch contained the handlers. 

    // AutoConnect object declarations\nACInput(input1);\nAutoConnectAux aux(\"/aux\", { input1 });\nAutoConnect portal;\n// Pre-declare handlers\nString initialize(AutoConnectAux&, PageArgument&);\nString append(AutoConnectAux&, PageArgument&);\n\n// Register handlers and launch the portal.\naux.on(initialize, AC_AHEAD);\naux.on(append, AC_LATER);\nportal.join(aux);\nportal.begin();\n\n// Some code here...\n\n// The handler called before HTML generating\nString initialize(AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectInput& input1 = aux.getElement<AutoConnectInput>(\"input1\");\n// Set initial value for the input box in a custom Web page.\n  input1.value = \"Initial value\";\n// Nothing appendix for a generated HTML.\nreturn String();\n}\n\n// The handler called after HTML generated\nString append(AutoConnectAux& aux, PageArgument& args) {\n// Append an HTML\nreturn String(\"<p>This text has been added.</p>\");\n}\n
    "},{"location":"achandling.html#how-you-can-reach-the-values","title":"How you can reach the values","text":"

    AutoConnectSubmit uses the POST method to send HTTP requests. A value of AutoConnectInput sent to the ESP8266 or ESP32 with POST is stored in the request body of the HTTP request: 

    POST /feels HTTP/1.1\nHost: ESP8266_IP_ADDRESS\nname1=value1&name2=value2&name3=value3\n
    ESP8266WebServer class will parse the query string and rebuilds its arguments when the above request arrives. A custom page handler registered with the ESP8266WebServer::on function can access the value of AutoConnectElements with ESP8266WebServe::arg function. It reaches the values of AutoConnectElements without the intermediation of AutoConnect. Therefore, its handler will not be AutoConnectAux and can send a response to the client directly. The following example is part of a server sketch which has two web pages. The /hello page is a custom Web page of AutoConnectAux which has an input box named \"input1\". Another /echo page is a page handler for ESP8266WebServer, which uses the ESP8266WebServer::send function to echo back the value of an input1 as an http response.

    ESP8266WebServer server;\nAutoConnect      portal(server);\nACInput(input1, \"\", \"INPUT\");\nACSubmit(send, \"HELLO\", \"/echo\");\nAutoConnectAux  aux(\"/hello\", { input1, send });\n\nserver.on(\"/echo\", []() {\n  String echo = server.arg(\"input1\");\n  Serial.println(echo);\n  server.send(200, \"text/plain\", echo);\n});\n\nportal.join(aux);\nportal.begin();\n

    Also, you can choose another way to access arguments without going through the ESP8266WebServer class. The PageArgument object of the custom Web page handler argument is a copy of the arg object of the ESP8266WebServer class. Either of these methods is a simple and easy way to access parameters in custom Web page handlers. However, if you need to access from outside of the handler to the value of AutoConnectElements, you need to accomplish it using with the AutoConnectAux::getElement function. The following sketch code replaces the above example with JSON and PageArgument, and its behaves is equivalent basically to the above sketch.

    const static char auxPage[] PROGMEM = R\"raw(\n[\n  { \"title\":\"Hello\", \"uri\":\"/hello\", \"menu\":true, \"element\":[\n    { \"name\":\"input1\", \"type\": \"ACInput\", \"label\": \"INPUT\" },\n    { \"name\":\"send\", \"type\":\"ACSubmit\", \"value\":\"HELLO\", \"uri\":\"/echo\" }]\n  },\n  { \"title\":\"Echo\", \"uri\":\"/echo\", \"menu\":false, \"element\":[\n    { \"name\":\"echo\", \"type\":\"ACText\" }]\n  }\n]\n)raw\";\n\nAutoConnect portal;\n\nportal.load(auxPage);\nportal.on(\"/echo\", [](AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectText& ac_echo = aux.getElement<AutoConnectText>(\"echo\");\n  ac_echo.value = args.arg(\"input1\");\nreturn String();  \n});\n\nportal.begin();\n
    "},{"location":"achandling.html#get-autoconnectelement-values-from-the-transition-source","title":"Get AutoConnectElement values from the transition source","text":"

    Usually, the page transition called by the custom web page handler will have an HTTP request directed to the destination URL. Its HTTP request has parameters enclosed by the POST method, all of which are AutoConnectElements placed on the transition source page. On the other hand, the custom web page handler's first argument points to AutoConnectAux after the transition, so the handler cannot access the AutoConnectElement values placed at the transition source using the first argument.

    Custom Web paga handler has two ways to access AutoConnectElements placed on the transition source page: combining the AutoConnect::where and AutoConnect::aux functions or using the AutoConnectAux::referer function. The following code snippet shows the difference between the two methods of identifying the input1 AutoConnectInput with the /echo page handler after the transition based on the /hello page described above.

    portal.on(\"/echo\", [](AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectAux&   ac_hello = *portal.aux(portal.where());\n  AutoConnectInput& ac_input1 = ac_hello[\"input1\"].as<AutoConnectInput>();\n  Serial.println(ac_input1.value);\nreturn String();  \n});\n
    portal.on(\"/echo\", [](AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectAux&   ac_hello = portal.referer();\n  AutoConnectInput& ac_input1 = ac_hello[\"input1\"].as<AutoConnectInput>();\n  Serial.println(ac_input1.value);\nreturn String();  \n});\n
    "},{"location":"achandling.html#transfer-of-input-values-across-pages","title":"Transfer of input values across pages","text":"

    Since v1.0.0, AutoConnect supports a new attribute with each element that allows automatic transfer of input values across pages without sketching. AutoConnect will copy the input value of the elements declared as global to the same-named global elements on a different custom Web pages at the page transition timing.

    The global attribute will be useful for echoing input values back to another custom Web pages. This copy operation can be performed between different types. (eg., copy value from AutoConnectInput to AutoConnectText) The following example reflects the input value of PAGE1 to the AutoConnectText field of PAGE2 without sketch code.

    static const char PAGE1[] PROGMEM = R\"(\n{\n  \"title\": \"PAGE1\",\n  \"uri\": \"/page1\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"input1\",\n      \"type\": \"ACInput\",\n      \"global\": true\n    },\n    {\n      \"name\": \"send\",\n      \"type\": \"ACSubmit\",\n      \"value\": \"OK\",\n      \"uri\": \"/page2\"\n    }\n  ]\n}\n)\";\nstatic const char PAGE2[] PROGMEM = R\"(\n{\n  \"title\": \"PAGE2\",\n  \"uri\": \"/page2\",\n  \"menu\": false,\n  \"element\": [\n    {\n      \"name\": \"input1\",\n      \"type\": \"ACText\",\n      \"global\": true\n    }\n  ]\n}\n)\";\n\nAutoConnect portal;\nAutoConnectAux page1;\nAutoConnectAux page2;\n\nvoid setup() {\n  page1.load(PAGE1);\n  page2.load(PAGE2);\n  portal.join( { page1, page2 });\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    The value entered in input1 declared in PAGE1 is reflected in input1 of PAGE2 as an AutoConnectText value even if there is no sketch code to transfer it to PAGE2. It's shown as like:

    Copy only for same-named and the global

    The input value will be copied only if the global attribute of the destination element is true. If an element with the same name is declared non-global, the value is not copied.

    "},{"location":"achandling.html#retrieve-the-values-with-webserveron-handler","title":"Retrieve the values with WebServer::on handler","text":"

    ESP8266WebServer class and the WebServer class assume that the implementation of the ReqestHandler class contained in the WebServer library will handle the URL requests. Usually, it is sketch code registered by ESP8266WebServer::on function.

    When a page transition from a custom Web page created by AutoConnectAux to a handler registered with ESP2866WebServer::on function, a little trick is needed to retrieve the values of AutoConnectElements. (i.e. the URI of the ESP8266WebServer::on handler is specified in the uri attribute of AutoConnectSubmit) AutoConnect cannot intervene in the procedure in which the ESP8266WebServer class calls the on-page handler coded with the Sketch. Therefore, it is necessary to retrieve preliminary the values of AutoConnectElements using the AutoConnectAux::fetchElement function for value processing with the on-page handler.

    The following sketch is an example of extracting values inputted on a custom web page with an on-page handler and then processing it.

    ESP8266WebServer server;\nAutoConnect portal(server);\nAutoConnectAux Input;\n\nconst static char InputPage[] PROGMEM = R\"r(\n{\n  \"title\": \"Input\", \"uri\": \"/input\", \"menu\": true, \"element\": [\n    { \"name\": \"input\", \"type\": \"ACInput\", \"label\": \"INPUT\" },\n    {\n      \"name\": \"save\",\n      \"type\": \"ACSubmit\",\n      \"value\": \"SAVE\",\n      \"uri\": \"/\"\n    }\n  ]\n}\n)r\";\n\n// An on-page handler for '/' access\nvoid onRoot() {\n  String  content =\n\"<html>\"\n\"<head><meta name='viewport' content='width=device-width, initial-scale=1'></head>\"\n\"<body><div>INPUT: {{value}}</div></body>\"\n\"</html>\";\n\n  Input.fetchElement();    // Preliminary acquisition\n// For this steps to work, need to call fetchElement function beforehand.\n  String value = Input[\"input\"].value;\n  content.replace(\"{{value}}\", value);\n  server.send(200, \"text/html\", content);\n}\n\nvoid setup() {\n  Input.load(InputPage);\n  portal.join(Input);\n  server.on(\"/\", onRoot);  // Register the on-page handler\n  portal.begin();  \n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"achandling.html#overwrite-the-autoconnectelements","title":"Overwrite the AutoConnectElements","text":"

    Sketches can update the attributes of AutoConnectElements with two approaches. A one is to assign directly to the attributes of a member variable of its element. The other is to overwrite them with loading the element by AutoConnectAux::loadElement.

    The elements for attributes described in the JSON document for AutoConnectElements overwrites the member variables of the target AutoConnectElements. However, AutoConnectAux::loadElement keeps the member variables unchanged if there is no element in the JSON document. This overwriting behavior is the same for the AutoConnect::load function.

    For example, the combination of the Sketch and JSON document as follows updates only the style while keeping Caption (ie. \"Hello, world\") as AutoConnectText value.

    External JSON document for the below sketch to modify the text style. 

    {\n\"name\" : \"Caption\",\n\"type\" : \"ACText\",\n\"style\": \"text-align:center;font-size:24px;font-family:'Impact','Futura',sans-serif;color:tomato;\"\n}\n

    the Sketch (a part of code), load above JSON. 

    ACText(Caption, \"Hello, world\");\nAutoConnectAux helloPage(\"/hello\", \"Hello\", true, { Caption });\nAutoConnect portal;\n\nString onHello(AutoConnectAux& aux, PageArgument& args) {\n  aux.loadElement(JSON);\nreturn String();\n}\n\nvoid setup() {\n  helloPage.on(onHello);\n  portal.join(helloPage);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    It's shown as like:

    "},{"location":"achandling.html#check-data-against-on-submission","title":"Check data against on submission","text":"

    By giving a pattern to AutoConnectInput, you can find errors in data styles while typing in custom Web pages. The pattern is specified with regular expression.2 If the value during input of AutoConnectInput does not match the regular expression specified in the pattern, its background color changes to pink. The following example shows the behavior when checking the IP address in the AutoConnectInput field.

    {\n\"title\" : \"Page-1\",\n\"uri\" : \"/page1\",\n\"menu\" : true,\n\"element\" : [\n    {\n\"name\" : \"Server\",\n\"type\" : \"ACInput\",\n\"label\": \"Server address\",\n\"pattern\": \"^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$\"\n    }\n  ]\n}\n

    It's shown as like:

    If you are not familiar with regular expressions, you may feel that description very strange. Matter of fact, it's a strange description for those who are unfamiliar with the formal languages. If your regular expression can not interpret the intended syntax and semantics, you can use an online tester. The regex101 is an exceptional online tool for testing and debugging regular expressions.

    "},{"location":"achandling.html#input-data-validation","title":"Input data validation","text":"

    The pattern attribute of AutoConnectInput only determines the data consistency on the web browser based on the given regular expression. In order to guarantee the validity of input data, it is necessary to verify it before actually using it.

    You can validate input data from AutoConnectInput using the isValid function before actually processing it. The isValid function determines whether the value currently stored in AutoConnectInput matches the pattern.

    You can also use the AutoConnectAux::isValid function to verify the data input to all AutoConnectInput elements on the custom Web page at once. The two sketches below show the difference between using AutoConnectInput::isValid and using AutoConnectAux::isValid. In both cases, it verifies the input data of the same AutoConnectInput, but in the case of using AutoConnectAux::isValid, the amount of sketch coding is small.

    "},{"location":"achandling.html#common-declaration","title":"Common declaration","text":"
    const char PAGE[] PROGMEM = R\"(\n{\n  \"title\": \"Custom page\",\n  \"uri\": \"/page\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"input1\",\n      \"type\": \"ACInput\",\n      \"pattern\": \"^[0-9]{4}$\"\n    },\n    {\n      \"name\": \"input2\",\n      \"type\": \"ACInput\",\n      \"pattern\": \"^[a-zA-Z]{4}$\"\n    }\n  ]\n}\n)\";\nAutoConnectAux page;\npage.load(PAGE);\n
    "},{"location":"achandling.html#using-autoconnectinputisvalid","title":"Using AutoConnectInput::isValid","text":"
    AutoConnectInput& input1 = page[\"input1\"].as<AutoConnectInput>();\nAutoConnectInput& input2 = page[\"input2\"].as<AutoConnectInput>();\nif (!input1.isValid() || !input2.isValid())\n  Serial.println(\"Validation error\");\n
    "},{"location":"achandling.html#using-autoconnectauxisvalid","title":"Using AutoConnectAux::isValid","text":"
    if (!page.isValid())\n  Serial.println(\"Validation error\");\n
    "},{"location":"achandling.html#convert-data-to-actually-type","title":"Convert data to actually type","text":"

    The values in the AutoConnectElements field of the custom Web page are all typed as String. A sketch needs to be converted to an actual data type if the data type required for sketch processing is not a String type. For the typical data type conversion method, refer to section Tips for data conversion.

    "},{"location":"achandling.html#place-html-elements-undefined-in-autoconnectelements","title":"Place HTML elements undefined in AutoConnectElements","text":"

    Of the many HTML elements for markup, AutoConnet can only support a limited number. If you are designing a custom web page and the elements you want are not in AutoConnectElements, consider using an AutoConnectElement. AutoConnectElement can be applied in many cases when trying to place HTML tag elements that are undefined in AutoConnectElemets on custom web pages.

    Not all of them work

    The strongest constraint is the heap size required to generate HTML for the entire custom Web page. AutoConnect creates a custom web page as a chunk of String. It's not a stream. Therefore, it may not be possible to generate long HTML pages. See also FAQ.

    "},{"location":"achandling.html#place-a-markup-or-a-styled-html-tag","title":"Place a markup or a styled HTML tag","text":"

    If the HTML element you want to place is just the tag that makes up the appearance of the web page, assign the tag element directly to the value member of AutoConnectElement. If the tag you are trying to place is for static markup effects, just write the value as follows:

    {\n\"name\": \"headline\",\n\"type\": \"ACElement\",\n\"value\": \"<hr style='height:1px;border-width:0;color:gray;background-color:#52a6ed'>\"\n}\n

    If the element has a hierarchy like a <table> ~ </table>, describe the entire element in the value:

    {\n\"name\": \"table\",\n\"type\": \"ACElement\",\n\"value\": \"<table><tr><th>Board</th><th>Platform</th></tr><tr><td>NodeMCU</td><td>Espressif8266</td></tr><tr><td>ESP32-DevKitC</td><td>Espressif32</td></tr></table>\"\n}\n

    Also, using AutoConnectStyle combined, you can give the style effect of only that element.

    {\n\"name\": \"tablestyle\",\n\"type\": \"ACStyle\",\n\"value\": \"table.style{font-family:arial,sans-serif;border-collapse:collapse;width:100%;color:black;}table.style td,table.style th{border:1px solid #dddddd;text-align:center;padding:8px;}table.style tr:nth-child(even){background-color:#dddddd;}\"\n},\n{\n\"name\": \"table\",\n\"type\": \"ACElement\",\n\"value\": \"<table class='style'><tr><th>Board</th><th>Platform</th></tr><tr><td>NodeMCU</td><td>Espressif8266</td></tr><tr><td>ESP32-DevKitC</td><td>Espressif32</td></tr></table>\"\n}\n

    As you see it: Board Platform NodeMCU Espressif8266 ESP32-DevKitC Espressif32

    "},{"location":"achandling.html#place-the-input-elements-within-a-form","title":"Place the input elements within a form","text":"

    There is still no dedicated AutoConnectElement for entering other than equivalent to checkbox, file, number, password, radio and text for <input type=\"...\"> HTML element. But you can substitute them with the AutoConnectElement.

    For example, if you use the <input> element of type=\"date\" to place a field where you can enter a date, the AutoConnectElement would look like this:

    {\n\"name\": \"date\",\n\"type\": \"ACElement\",\n\"value\": \"<label for='picker'>Date:</label><input type='date' id='picker' name='date'>\"\n}\n

    And it becomes a textbox that validates the input or a special date picker interface. Then, instead of accessing that AutoConnectElement directly, obtains entered date value from the POST body included in the HTTP request from the hosted ESP8266WebServer class. Its process carries out with the AutoConnectAux page handler following:

    String aux_page_handler(AutoConnectAux &aux, PageArgument &arg) {\n  Serial.println(arg.arg(\"date\"));  // Obtain a date value entered\nreturn \"\";\n}\n

    AutoConnect passes a PageArgument to the AutoConnectAux page handler. The handler can use the PageArgument::arg function to get the parameters contained in the HTTP request for the page. Also, the equivalent can also be implemented using ESP8266WebServer::arg function with the ESP8266WebServer client request handler.

    "},{"location":"achandling.html#using-javascript","title":"Using JavaScript","text":"

    What is described in this section belongs to the tips of what effectiveness a web page can have using AutoConnectElement, rather than the correct usage for AutoConnect. You can use AutoConnectElement to embed JavaScript into the custom Web page as with HTML elements for markup. The reason for embedding JavaScript on a page depends on your requirements, but One of the most common requirements is the need to access elements of a web page. You can implement the requirements by having the AutoConnectElement have JavaScript that contains DOM access.

    The following screenshot shows an example of accessing AutoConnectText via the DOM using an AutoConnectElement with JavaScript. This web page is a very simple example and returns the result of multiplying the multiplier entered in an AutoConnectInput field.

    This custom Web page is generated from the following JSON document:

    {\n\"uri\": \"/jselement\",\n\"title\": \"Multiply\",\n\"menu\": true,\n\"element\": [\n    {\n\"name\": \"multiplier\",\n\"type\": \"ACInput\",\n\"label\": \"3 &times; \",\n\"apply\": \"number\",\n\"posterior\": \"none\"\n    },\n    {\n\"name\": \"op\",\n\"type\": \"ACButton\",\n\"value\": \" = \",\n\"action\": \"multi()\",\n\"posterior\": \"none\"\n    },\n    {\n\"name\": \"answer\",\n\"type\": \"ACText\"\n    },\n    {\n\"name\": \"js\",\n\"type\": \"ACElement\",\n\"value\": \"<script type='text/javascript'>function multi() {document.getElementById('answer').innerHTML=3*document.getElementById('multiplier').value;}</script>\"\n    }\n  ]\n}  \n

    An input field for a multiplier is defined by AutoConnectInput. The field for displaying the results exists with the name answer. The multiplication function is what AutoConnectElement has as JavaScript and it has the following content:

    function multi() {\n  document.getElementById('answer').innerHTML = 3 * document.getElementById('multiplier').value;\n}\n

    And the action for calling the multi() function is the = labeled button as the AutoConnectButton element. AutoConnect generates the name attribute of each AutoConnectElement as the Id of the HTML tag. The Id should be useful for DOM access.

    JavaScript that is too long can cause insufficient memory

    If it reaches thousands of bytes, AutoConnect will not be able to complete the HTML generation for the page.

    "},{"location":"achandling.html#custom-web-pages-communication-without-page-transitions","title":"Custom Web pages communication without page transitions","text":"

    The request-response form typically provided by AutoConnectAux is based on stateless HTTP page transitions. Its communication between custom Web pages and sketches involves page transitions in the client browser via the request-response form. However, major Web browsers support HTTP asynchronous communication without page transitions. By embedding those Web APIs in your custom Web pages, you can implement sketches that do not disrupt the user working flow with page transitions.

    There are two types of Web APIs that allow asynchronous communication that can be used with AutoConnectAux:

    • XMLHttpRequest

      JavaScript embedded in a custom web page uses the XMLHttpRequest (XHR) objects to communicate with the request handler on the sketch side. A sketch typically embeds its JavaScript coded as a string value with AutoConnectElement into a custom web page JSON description.

      The request handler that is communication partner with the above JavaScript should be implemented in the sketch as the Client request handlers of the ESP8266WebServer (WebServer for ESP32) class.

      The procedure for implementing a sketch in this manner is described in a subsequent section.

    • Fetch API

      The Fetch API supported by AutoConnectAux is even easy to implement than XHR. AutoConnectElements can execute Fetch API-driven JavaScript that can communicate with the server sketch. Its script will be triggered by expected events and automatically be embedded into the HTML source of your custom web page by AutoConnect.

      Also, the sketch process with which the above Fetch API script communicates can access and update the values and properties of each AutoConnectElement. Updated AutoConnectElement contents are immediately reflected on the custom web page by sending a response.

      The Fetch API-driven approach based on AutoConnectElements event firing is described in the section of Interact with sketches by AutoConnectElements event.

    "},{"location":"achandling.html#communicate-with-the-sketch-using-xhr","title":"Communicate with the Sketch using XHR","text":"

    AutoConnectElement allows having scripts that make HTTP sessions based on XHR. XHR (XMLHttpRequest) is a JavaScript API to create AJAX requests. Its methods allow sending network requests between the browser and a server. The sketch implements the server-side process as a response handler to a standard HTTP request and can equip it with a dynamic custom Web page. This technique is tricky but is useful when implementing dynamic pages because it does not cause page transitions. As a matter of fact, AutoConnectOTA class is implemented with this technique and is a custom web page by AutoConnectAux using XHR.

    Here's a simple example of JavaScript-based on XHR and a server-side request handler. It's like a clock that displays the time in real-time on an AutoConnect custom web page. The sketch in the following example is roughly divided into two structures. The AutoConnectElement defined with the name js gets the server time with XHR and updates the response via the DOM with the AutoConnectText named time and substance is the following JavaScript:

    var xhr;\n\nfunction clock() {\nxhr.open('GET', '/clock');\nxhr.responseType = 'text';\nxhr.send();\n}\n\nwindow.onclose = function() {\nxhr.abort();\n};\n\nwindow.onload = function() {\nxhr = new XMLHttpRequest();\nxhr.onreadystatechange = function() {\nif (this.readyState == 4 && xhr.status == 200) {\n      document.getElementById('time').innerHTML = this.responseText;\n    }\n  };\nsetInterval(clock, 1000);\n};\n

    This script issues a GET request to /clock every second and updates the element of Id=time with the text content of its response. As this script shows, it will issue a send request using the XMLHttpRequest object.

    The other component is located on the AutoConnect-hosted ESP8266WebServer server. This component gets the current time from the NTP server and sends the value as text to the client.

    void auxClock() {\ntime_t  t;\nstruct tm *tm;\nchar    dateTime[24];\n\n  t = time(NULL);\n  tm = localtime(&t);\n  sprintf(dateTime, \"%04d/%02d/%02d %02d:%02d:%02d.\",\n                    tm->tm_year + 1900, tm->tm_mon + 1, tm->tm_mday,\n                    tm->tm_hour, tm->tm_min, tm->tm_sec);\n  server.send(200, \"text/plain\", dateTime);\n}\n

    Then just register the auxClock function as a /clock URL handler with the hosted ESP8266Server instance.

    server.on(\"/clock\", auxClock);\n

    As you can see from the above two components, AutoConnect does not intervene in those communications and no page transitions occur. A complete sketch that integrates the above components and includes a custom Web page declaration for time display looks like this:

    #include <Arduino.h>\n#include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n#include <time.h>\n\nstatic const char JSPAGE[] PROGMEM = R\"'(\n{\n  \"uri\": \"/jselement\",\n  \"title\": \"Clock\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"time\",\n      \"type\": \"ACText\"\n    },\n    {\n      \"name\": \"js\",\n      \"type\": \"ACElement\",\n      \"value\": \"<script type='text/javascript'>var xhr;function clock(){xhr.open('GET', '/clock');xhr.responseType='text';xhr.send();}window.onclose=function(){xhr.abort();};window.onload=function(){xhr=new XMLHttpRequest();xhr.onreadystatechange=function(){if(this.readyState==4&&xhr.status==200){document.getElementById('time').innerHTML=this.responseText;}};setInterval(clock,1000);};</script>\"\n    }\n  ]\n}  \n)'\";\n\nESP8266WebServer  server;\nAutoConnect portal(server);\n\nvoid auxClock() {\ntime_t  t;\nstruct tm *tm;\nchar    dateTime[24];\n\n  t = time(NULL);\n  tm = localtime(&t);\n  sprintf(dateTime, \"%04d/%02d/%02d %02d:%02d:%02d.\",\n                    tm->tm_year + 1900, tm->tm_mon + 1, tm->tm_mday,\n                    tm->tm_hour, tm->tm_min, tm->tm_sec);\n  server.send(200, \"text/plain\", dateTime);\n}\n\nvoid setup() {\n  delay(1000);\n  portal.load(FPSTR(JSPAGE));\nif (portal.begin()) {\n    server.on(\"/clock\", auxClock);\n    configTime(0, 0, \"europe.pool.ntp.org\");\n  }\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"achandling.html#interact-with-sketches-by-autoconnectelements-event","title":"Interact with sketches by AutoConnectElements event","text":"

    AutoConnectAux supports Fetch API besides XMLHttpRequest for communication between the client browser and the ESP module. This allows your sketches to get and change values and properties of AutoConnectElements without a page transition on the browser. The changed values and properties are immediately reflected in the page currently being viewed in the browser.

    The following screenshot shows that a custom web page using the Fetch API can blink the LED on the ESP module without any page transitions. And it allows the custom web page changes the text color and button caption in sync with the LED flashing.

    The sketch implemented for the above demonstration does not need to write JavaScript code to handle the Fetch API. Its Fetch API script will automatically be embedded in the HTML source of your custom web page by AutoConnect. All you need to do is describe your custom web page in JSON and write AutoConnectElements event handlers to apply to user interaction.

    How to sketch with the AutoConnectElements events is covered in detail in chapter Interact with Sketch and AutoConnectElements.

    "},{"location":"achandling.html#transitions-of-the-custom-web-pages","title":"Transitions of the custom Web pages","text":""},{"location":"achandling.html#scope-lifetime-of-autoconnectaux","title":"Scope & Lifetime of AutoConnectAux","text":"

    AutoConnectAux and AutoConnectElements must live while the custom Web pages are available. The implementation of the custom Web page inherits from requestHandler driven from ESP8266WebServer (WebServer for ESP32), so the instance of AutoConnectAux and AutoConnectElements must exist for the duration of effect of handleClient. The following example is incorrect for manipulating custom Web pages. Its AutoConnectAux instance will be destructed at the exit of the setup().

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const auxPage[] PROGMEM = R\"raw(\n{\n  \"title\": \"Page-1\",\n  \"uri\": \"/page1\",\n  \"menu\": true,\n  \"element\": [\n    { \"name\":\"Server\", \"type\":\"ACText\", \"label\":\"Server address\" }\n  ]\n}\n)raw\";\n\nAutoConnect  portal;\n\nvoid setup() {\n// This declaration is wrong.\n  AutoConnectAux aux;\n  aux.load(auxPage);\n  portal.join(aux);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"achandling.html#the-uri-of-the-custom-web-pages","title":"The URI of the custom Web pages","text":"

    The transition of the custom Web page follows the URI of the page, but the ESP8266WebServer class does not know the URI of an AutoConnectAux page. (Registering a custom Web page does not use the ESP8266WebServer::on/WebServer::on function.) Therefore ESP8266WebServer class does not detect its URI access. If you want to detect an http request to AutoConnectAux's custom Web page, you need to register its URI with the AutoConnectAux::on function.

    In addition to this, there are restrictions in the handler for the custom Web page as shown in the following section.

    "},{"location":"achandling.html#an-http-response-from-the-custom-web-page-handler","title":"An HTTP response from the custom Web page handler","text":"

    Normally, a custom web page handler does not need to respond to a request from the client. Its HTTP response will be sent by AutoConnect when it returns from the custom web page handler. In that case, the HTTP response code is 200.

    However, this structure requires AutoConnectAux to always respond with the page content. If AutoConnectAux does not have page content as an HTTP response, then the custom web page handler can respond with its own HTTP response by following the steps:

    1. Declare an AutoConnectAux with the responsive argument set to false, or describe \"response\":false with JSON:

      AutoConnectAux aux(\"/aux\", \"AUX\", false, {}, false);\n
      {\n\"title\": \"AUX\",\n\"uri\": \"/aux\",\n\"response\": false,\n\"menu\": false\n}\n

    2. Send an HTTP response from a custom web page handler (Case of ESP32):

      WebServer   server;\nAutoConnect portal(server);\n\nString handleAux(AutoConnectAux& aux, PageArgument& args) {\n  server.send(202, \"text/plain\", \"Accepted\");\nreturn String();\n}\n\nportal.on(\"/aux\", handleAux);\n
      If you want to respond with a 302 from a custom web page handler, you can use the AutoConnectAux::redirect function. 
      String handleAux(AutoConnectAux& aux, PageArgument& args) {\n  aux.redirect(\"http://redirect.url:port/?query\");\nreturn String();\n}\n

    "},{"location":"achandling.html#limitations","title":"Limitations","text":"

    The custom Web pages handler has the following limitations.

    • Do not send HTTP responses from the handler.

      If the handler returns its own response, the custom Web page will be lost.

    • Use AutoConnectSubmit whenever possible.

      AutoConnect will hold the values of a custom Web Page is sent by AutoConnectSubmit.

    • Can not handle the custom Web pages during a connection is not established yet.

      During the connection attempt, the web browser of the client will send a probe for a captive portal. Its request will cause unintended custom Web page transitions.

    • Can not place URI of the custom Web pages to AUTOCONNECT_URI.

      AutoConnect will not work if you place a custom Web page to AUTOCONNECT_URI.

    • Can not use the element named SUBMIT.

      You can not use 'SUBMIT' as the element name of AutoConnectElements in a custom Web page that declares the AutoConnectSubmit element. (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.

    Do not handle for the same page

    Do not duplicate AutoConnect::on with ESP8266WebServer::on (also WebServer::on) for the same custom web page.

    1. The valid scope of the name is within an AutoConnectAux.\u00a0\u21a9

    2. Regular expression specification as a pattern of AutoConnectInput is JavaScript compliant.\u00a0\u21a9

    "},{"location":"acinteract.html","title":"Interact between Sketch and AutoConnectElements","text":""},{"location":"acinteract.html#interaction-with-autoconnectelements-wo-page-transition","title":"Interaction with AutoConnectElements w/o page transition","text":"

    The substance of the custom web page deployed by AutoConnectAux is just HTML content; AutoConnectAux is just a request handler conforming to the RequestHandler class of the ESP8266 and ESP32 Arduino core's WebServer library.

    Therefore, the request-response form typically provided by AutoConnectAux is based on stateless HTTP page transitions. Its communication between custom Web pages and sketches involves page transitions in the client browser via the request-response form.

    However, major Web browsers support HTTP asynchronous communication without page transitions. By embedding those Web APIs in your custom web pages, you can implement sketches that do not disrupt the user working flow with page transitions.

    AutoConnectAux allows the custom web page to use two types of Web APIs for asynchronous communication with the sketch. Both methods can be accomplished by having JavaScript inherent in the custom web page to communicate with the server sketch (i.e., the AutoConnectAux event handler).

    • XMLHttpRequest

      JavaScript embedded in a custom web page uses the XMLHttpRequest (XHR) objects to communicate with the request handler on the sketch side. A sketch typically embeds its JavaScript coded as a string value with AutoConnectElement into a custom web page JSON description.

      The request handler that is communication partner with the JavaScript should be implemented in the sketch as the Client request handlers of the ESP8266WebServer (WebServer for ESP32) class.

      The procedure for implementing a sketch in this manner is covered in Communicate with the Sketch using XHR section.

    • Fetch API

      The Fetch API supported by AutoConnectAux is even easy to implement than XHR. AutoConnectElements can execute Fetch API-driven JavaScript that can communicate with the server sketch. Its script will be triggered by expected events and automatically be embedded into the HTML source of your custom web page by AutoConnect.

      Also, the sketch process with which the Fetch API scripts communicates can access and update the values and properties of each AutoConnectElement. Updated AutoConnectElement contents are immediately reflected on the custom web page by sending a response.

      This section describes a Fetch API-driven approach based on AutoConnectElements event firing and the specific API for the sketch implementation.

      No retries around Fetch API handling

      The JavaScript containing the Fetch API that AutoConnect automatically embeds in custom web pages does not include retry handling. If the connection with the ESP module is unstable, the request will be reset by the client browser without completing the HTTP transmission/reception. However, the state may be difficult to understand at first glance, and the user may not be able to immediately determine what has happened.

      When applying the Fetch API on the AutoConnect custom web page, it is recommended to keep the amount of communication as low as possible.

    "},{"location":"acinteract.html#interact-with-sketches-by-autoconnectelements-event","title":"Interact with sketches by AutoConnectElements event","text":"

    Interaction between AutoConnectElements and sketch without page transitions is very smooth. It allows you to complete data exchange with ESP modules on the same page without interrupting your work.

    The figure below illustrates what a custom web page without page transitions looks like in action. It's a screen capture of a custom web page behavior that controls a simple LED blink (like \"hello, world\\n\" for The C Programming Language), and contains only a caption as AutoConnectText and a button as AutoConnectButton to turn on or off LED.

    The LED ON/OFF button as AutoConnectButton used in this sketch handles the HTML element click event to send the current value to the ESP module. The receiver sketch changes the LED signal level according to the received value and responds to the client with the button's display text and caption color. These send-and-receive exchanges are attribute names and values for AutoConnectButton and AutoConnectText. This sketch handles these actions with the standard HTTP POST method without causing a page transition.

    The following sections describe APIs and programming methods for interacting with custom web pages with no page transitions, following the sketch structure that implements the above figure.

    "},{"location":"acinteract.html#associate-events-with-autoconnectelements","title":"Associate events with AutoConnectElements","text":"

    Custom web pages derived by AutoConnectAux are regular HTML, so it can contain JavaScript that responds to DOM events. The reason why the sketch above figure does not cause a page transition is that the click event with the AutoConnectButton is trigged to send an HTTP POST to the sketch running in the ESP module using the Fetch API.

    AutoConnect automatically inserts JavaScript that communicates via the Fetch API in response to events if AutoConnectElements with registered an event handler is present on the custom web page. The following code is the JSON description of the custom web page shown above. It is no different from the page description with no event handling.

    const char LED_ONOFF[] PROGMEM = R\"(\n{\n  \"uri\": \"/led\",\n  \"title\": \"LED\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"caption\",\n      \"type\": \"ACText\",\n      \"value\": \"BUILT-IN LED\",\n      \"style\": \"font-weight:bold;font-size:25px;text-align:center;\",\n      \"posterior\": \"div\"\n    },\n    {\n      \"name\": \"onoff\",\n      \"type\": \"ACButton\",\n      \"value\": \"ON\"\n    }\n  ]\n}\n)\";\n

    All you need to do is write your custom web page in JSON and write event handlers for AutoConnectElements that apply to user interactions.

    "},{"location":"acinteract.html#allow-autoconnectelements-to-have-event-processing","title":"Allow AutoConnectElements to have event processing","text":"

    AutoConnect will automatically embed the JavaScript into the HTML that communicates with a server-side sketch using the Fetch API if the custom web page has AutoConnectElements with an event handler. Use the on function to allow the event-handling capability to elements used for the interaction with the user.

    To give your custom web page the ability to handle events using Fetch API, roughly follow these steps:

    1. Declare AutoConnectElements for user interaction. It can be declared directly using the constructor of each element or embedded in the JSON description. This procedure is no different from the definition in custom web pages.

    2. Identify elements that allow events after loading a custom web page. Usually, you use the AutoConnectAux::getElement function (or override operator []) accompanied by the AutoConnect::aux or AutoConnect::locate for this. This function takes the element name as an argument and returns a reference to an instance of AutoConnectElements.

      AutoConnect portal;\n\nportal.load(FPSTR(LED_ONOFF));\nAutoConnectAux& led = portal.locate(\"/led\");\nAutoConnectButton& onOff = led[\"onoff\"].as<AutoConnectButton>();\n

    3. Register the event handler with the AutoConnectElement::on function.

      onOff.on(ledOnOff);\n

    4. Write an event handler with the sketch. The event handler will be passed a reference to the instance of AutoConnectElements where the event occurred and a reference to AutoConnectAux. The event handler can use these parameters to receive the element's value of the event occurrence and perform processing according to that value. You can also give attributes such as new values and styles of other elements as return values. Use the AutoConnectElement::response function to set the return values.

      // Event handler that attaches to an AutoConnectButton named `led`.\n// This event handler receives a reference to AutoConnectButton as `led`\n// and a reference to the AutoConnectAux of the page rendered in the client\n// browser.\nvoid ledOnOff(AutoConnectButton& me, AutoConnectAux& ledOnOff) {\nif (me.value == \"ON\") {\n// Since \"ON\" has been passed from the AutoConnectButton as `led`. Let the\n// LED turns on.\n    digitalWrite(LED_BUILTIN, HIGH);\n// Direct assignment to AutoConnectElement values is not reflected on the\n// web page; use the `response` function to update the value of the element\n// on the web page.\n    me.response(\"OFF\");\n// The `on` event handler attached to AutoConnectElements can override the\n// value and attributes of other elements placed on that AutoConnectAux page.\n// For example, a following statement changes the font color of the `caption`\n// element along with a LED blinking.\n    ledOnOff[\"caption\"].response(\"style\", \"{\\\"color\\\":\\\"red\\\"}\");\n  }\nif (me.value == \"OFF\") {\n// Since a value \"OFF\" has been passed from the AutoConnectButton as `led`.\n// Let the LED turns off.\n    digitalWrite(LED_BUILTIN, LOW);\n    me.response(\"ON\");\n    ledOnOff[\"caption\"].response(\"style\", \"{\\\"color\\\":\\\"black\\\"}\");\n  }\n}\n
    "},{"location":"acinteract.html#register-event-handling-for-autoconnectelements","title":"Register Event handling for AutoConnectElements","text":"

    The on function catches different events for each AutoConnectElements1. There are also types of AutoConnectElements for which event handling cannot be registered. The syntax of the on function is as follows:

    void AutoConnectElements::on(eventHandler)

    AutoConnectElements that can catch events and the types of events are as follows:

    Available elements for Event Event type The moment the event occurs AutoConnectButton click Mouse click (only primary button) AutoConnectCheckbox change When an element is checked or unchecked AutoConnectInput change When the element loses focus after its value was changed AutoConnectRadio change When an element is checked (but not when unchecked) AutoConnectSelect change When the user commits the change explicitly

    The eventHandler parameter specifies the function that handles the event.

    "},{"location":"acinteract.html#event-handling-for-autoconnectelements","title":"Event handling for AutoConnectElements","text":""},{"location":"acinteract.html#event-handler-function","title":"Event handler function","text":"

    void eventHandler(AutoConnectElements& me, AutoConnectAux& aux)

    AutoConnectElements1 is actually one of the types listed in the table above for which the event is available. A reference to the element itself and to the AutoConnectAux to which it belongs is passed to the event handler. For example, to receive an event when an AutoConnectRadio named radio changes its checked state by mouse clicking, declare a function like onChangeRadio as follows:

    void onChangeRadio(AutoConnectRadio& me, AutoConnectAux& aux)\n

    Then use the AutoConnectRadio::on function to register the onChangeRadio handler function with the radio instance of AutoConnectRadio.

    AutoConnectRadio radio(\"radio\", {\"Huey\", \"Dewey\", \"Louie\"}, \"Select one\");\n...\nradio.on(onChangeRadio);\n

    AutoConnectElements1 will handle events if an event handler is registered with the on function. AutoConnect automatically inserts a script containing the Fetch API in the HTML generation of your custom web page when an element with an event handler function is registered.

    A type of event source and type of event handler argument is always the same

    The first argument of the event handler will contain a reference to an instance of an actual AutoConnectElements that is source of the event. So, the type of AutoConnectElements that registers the event handler and the type passed to the event handler are always the same. For example, the type of the first argument of the handler that receives the change event of AutoConnectText is the type of AutoConnectText itself.

    "},{"location":"acinteract.html#data-sent-with-the-event","title":"Data sent with the event","text":"

    When the custom web page catches the event, the script inserted by AutoConnect uses the Fetch API to send the value of each AutoConnectElements on the page to the ESP module. This script sends the value of each element as form data via HTTP POST.

    The data sent in this behavior is the same as the data transmission form with page transitions with AutoConnectSubmit. Then AutoConnect will store the transmitted data in the actual instance of AutoConnectElements before control is passed to the user sketch. Details of this behavior are covered in the section Custom field data handling.

    So in your sketch, you can unconsciously access the value of each AutoConnectElements of the custom web page where the event occurred in the event handler function. A reference to the element where the event originated is passed as the first argument, and a reference to the custom web page where the event triggered as the second argument.

    "},{"location":"acinteract.html#make-responses","title":"Make responses","text":"

    Responses to an HTTP POST request triggered by the event will be returned by AutoConnect at the end of the event handler function. The event handler continues processing until it exits, depending on the situation. For example, the event handler that controls the LED on/off described above (i.e., ledOnOff function) responds to the requested HTTP POST by setting the signal level to the LED_BUILTIN port to conform to the sent value of the AutoConnectButton by the event. It then rewrites the button's label with the new value.

    Use the response function for this. The response function has the effect of communicating the contents of AutoConnectElements updated by the event handler to the client browser. In the actual event handler, you should call the response as a member function of AutoConnectElements and specifies the instance of the element that will return the response. For example, to update the value of an AutoConnectText named caption on a page according to the LED ON/OFF control above, the code would look like this:

    ...\n\nACButton(onoff, \"ON\");\nACText(caption, \"LED OFF\");\n...\n\nvoid eventHandler(AutoConnectButton& me, AutoConnectAux& aux) {\n\n...\n\nif (me.value == \"OFF\") {\n    digitalWrite(LED_BUILTIN, LOW);\n    me.response(\"ON\");\n    caption.response(\"LED OFF\");\n  }\nif (me.value == \"ON\") {\n    digitalWrite(LED_BUILTIN, HIGH);\n    me.response(\"OFF\");\n    caption.response(\"LED ON\");\n  }\n\n...\n\n}\n

    The AutoConnectButton::response function rewrites the value attribute and innerHTML property of the onoff element (i.e. button type=\"button id=\"onoff\" node) on the page, while the AutoConnectText::response function rewrites only the innerHTML property of the div or span DOM node on the page. In this way, the value returned by response differs depending on the type of AutoConnectElements that generated the event. The following table shows which attributes of elements on the page the response(const char*) function affects.

    Available AutoConnectElement::response functions Attributes to rewrite AutoConnectButton::response value for the HTMLButtonElementinnerHTML for the HTMLButtonElement node AutoConnectCheckbox::response checked for <input type=\"checkbox\"> AutoConnectInput::response value for the HTMLInputElement AutoConnectText::response innerHTML for the <div> or <span> node

    When the response function updates the value of AutoConnectElements

    The response function also updates the value of the element's instance. For example, AutoConnectText::response function, in addition to sending the text to be updated to the client browser, also updates the value member of the sketch's AutoConnectText variable. However, that update process is done by AutoConnect at the exit of the event handler function.

    So, in the event handler function, even if you execute the response function, the value of AutoConnectElements will be kept as it was before the event occurred.

    Each AutoConnectElements has another response function that takes two arguments. The response(const char*) function updates the value of that element, while the response(const char*, const char*) function with two arguments updates the specified attribute or property and is used to change attributes of an element other than its value. For example, citing the LED ON/OFF example above, you can change the button background color according to the LED lighting state using the response function that takes two arguments.

    To change the button background color via an event handler when an event fires, specifies a String of a response form that allows direct access to the inline styles property of the button element using the CSSStyleDeclaration object.

    In this case, specify the property name of the HTML element to be changed in the first argument of the response function and the value to be changed in the second argument. This specification format conforms to object literals in JavaScript and can be expressed in JSON as follows:

    { style: { backgroundColor: 'red' }}\n

    So, specify style as the property part of the above syntax to the first argument of the response function and the nested {backGroundColor:\"red\"} part to the second argument.

    response(\"style\", \"{backGroundColor:\\\"red\\\"}\");\n

    If the property to be changed is not a nested object property like an inline style, the second argument can be the property value as it is. For example:

    response(\"placeholder\", \"Enter name\");\n

    Also, even if you give a boolean value, specify it as a string in the argument to the response function. AutoConnect automatically converts \"true\"/\"false\" as strings to booleans. For example:

    response(\"hidden\", \"true\");\n
    "},{"location":"acinteract.html#overall-the-led-control-sketch","title":"Overall the LED control sketch","text":"

    Based on the explanation so far, the following sketch is the implementation of the custom web page shown in the opening figure.

    #include <Arduino.h>\n#include <WiFi.h>\n#include <WebServer.h>\n#include <AutoConnect.h>\n\nconst char LED_ONOFF[] PROGMEM = R\"(\n{\n  \"uri\": \"/led\",\n  \"title\": \"LED\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"caption\",\n      \"type\": \"ACText\",\n      \"value\": \"BUILT-IN LED\",\n      \"style\": \"font-weight:bold;font-size:25px;text-align:center;\",\n      \"posterior\": \"div\"\n    },\n    {\n      \"name\": \"onoff\",\n      \"type\": \"ACButton\",\n      \"value\": \"ON\"\n    }\n  ]\n}\n)\";\n\nAutoConnect portal;\nAutoConnectConfig config;\n\n// Event handler that attaches to an AutoConnectButton named `led`.\n// This event handler receives a reference to AutoConnectButton as `led`\n// and a reference to the AutoConnectAux of the page rendered in the client\n// browser.\nvoid ledOnOff(AutoConnectButton& me, AutoConnectAux& ledOnOff) {\nif (me.value == \"ON\") {\n\n// Since \"ON\" has been passed from the AutoConnectButton as `led`. Let the\n// LED turns on.\n    digitalWrite(LED_BUILTIN, HIGH);\n\n// Direct assignment to AutoConnectElement values is not reflected on the\n// web page; use the `response` function to update the value of the element\n// on the web page.\n    me.response(\"OFF\");\n// The `on` event handler attached to AutoConnectElements can override the\n// value and attributes of other elements placed on that AutoConnectAux page.\n// For example, a following statement changes the font color of the `caption`\n// element along with a LED blinking.\n    ledOnOff[\"caption\"].response(\"style\", \"{\\\"color\\\":\\\"red\\\", \\\"font-weight\\\":\\\"bold\\\"}\");\n  }\nif (me.value == \"OFF\") {\n// Since a value \"OFF\" has been passed from the AutoConnectButton as `led`.\n// Let the LED turns off.\n    digitalWrite(LED_BUILTIN, LOW);\n    me.response(\"ON\");\n    ledOnOff[\"caption\"].response(\"style\", \"{\\\"color\\\":\\\"black\\\", \\\"font-weight\\\":\\\"normal\\\"}\");\n  }\n}\n\nvoid setup() {\n  delay(500);\n  Serial.begin(115200);\n  Serial.println();\n\n// Built-in LED port setting up\n  pinMode(LED_BUILTIN, OUTPUT);\n  digitalWrite(LED_BUILTIN, LOW);\n\n// Configure AutoConnect connection behavior.\n// Various configurations depending on the demands of your situation.\n  config.autoReconnect = true;\n  portal.config(config);\n\n// Load the AutoConnectAux page with the LED ON/OFF button into AutoConnect.\n// The sketch can get its instance using the AutoConnect::locate function\n// after AutoConnectAux is loaded.\n  portal.load(FPSTR(LED_ONOFF));\n  AutoConnectAux& led = portal.locate(\"/led\");\n\n// The AutoConnectElement::on function allows the sketch to register an event\n// handler that interacts with the element individually.\n  AutoConnectButton& onOff = led[\"onoff\"].as<AutoConnectButton>();\n  onOff.on(ledOnOff);\n// Start a portal\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    Above custom web page features two major AutoConnectElements:

    • caption: AutoConnectText

      Shows the current LED lighting state. The font color also reflects this status. To change the font color, use the response function for the caption element according to the value of the AutoConnectButton named onoff in the event handler.

      ledOnOff[\"caption\"].response(\"style\", \"{\\\"color\\\":\\\"red\\\", \\\"font-weight\\\":\\\"bold\\\"}\");\n

    • onoff: AutoConnectButton

      LED lighting switch placed on the custom web page. Interact with an event handler of the server sketch by catching click events on the browser. The event handler function name is ledOnOff. Register an event handler with the AutoConnectButton::on function to catch a click event on the onoff element as an AutoConnectButton.

      AutoConnectButton& onOff = led[\"onoff\"].as<AutoConnectButton>();\nonOff.on(ledOnOff);\n

      In the event handler, you can get the current value of the onoff through the reference to AutoConnectButton, which is the first argument as me.

      if (me.value == \"ON\") {\n  digitalWrite(LED_BUILTIN, HIGH);\n}\n

      The label on the onoff button indicates the instruction to turn the LED signal. So the content will be the opposite of the LED lighting state. Use the AutoConnectButton::response function to rewrite the label.

      me.response(\"OFF\");\n

    1. AutoConnectElements is a generic term for elements handled by custom web pages. They are actually replaced by types such as AutoConnectInput or AutoConnectText etc.\u00a0\u21a9\u21a9\u21a9

    "},{"location":"acintro.html","title":"Custom Web pages with AutoConnect","text":""},{"location":"acintro.html#what-it-is","title":"What it is","text":"

    AutoConnect can handle custom Web pages prepared by user sketches individually. Custom Web pages can be integrated into the AutoConnect menu and executed as menu items and can have input-output parameters and handle them.

    For example, you can program some sketches that publish messages by entering the URI or unique ID of the MQTT broker on a custom page. You do not need to code the processing to handle the web page. It retrieves the input parameters and passes to the MQTT broker connection API is only.

    "},{"location":"acintro.html#how-it-works","title":"How it works","text":"

    AutoConnect creates the custom Web pages dynamically at runtime. Sketch describes the custom Web pages using classes and APIs necessary for dynamic creation which are AutoConnectAux and the variant of AutoConnectElements. AutoConnectAux is an object dependent on AutoConnect, which provides an easy way to incorporate custom Web pages into AutoConnect like the one on the right figure. The elements make up a custom Web page are provided as an AutoConnectElement class.

    Furthermore, an input box, a check box, a submit button, etc. are implemented by classes derived from AutoConnectElement.

    AutoConnectAux is a container for AutoConnectElements. To make a custom Web page, create elements that make up the page and put it in the AutoConnectAux object. Joining its AutoConnectAux object to AutoConnect will integrate the custom Web page into the AutoConnect menu.

    The above figure shows a code sequence that declares AutoConnectElements and put in the AutoConnectAux container and integrates those into AutoConnect. It declares two text elements named header and caption, adds them to the AutoConnectAux object as aux, binds to an AutoConnect object named portal. This sequence is the basic procedure for creating custom Web pages with the Sketch. The further explanation is available in section AutoConnectElements also.

    "},{"location":"acintro.html#custom-web-pages-in-autoconnect-menu","title":"Custom Web pages in AutoConnect menu","text":"
    • AutoConnect integrates custom Web page objects into menus as AutoConnectAux. The AutoConnectAux object contains URI and title as member variables and has an indicator to display in the AutoConnect menu.You give the title and URI of the custom Web page to the AutoConnectAux object with Sketch. Then the title of the custom Web page would be displayed in the AutoConnect menu as the left figure.1 It is a hyperlink to a custom Web page which will be displayed tapped it.
    "},{"location":"acintro.html#multiple-custom-web-pages","title":"Multiple custom Web pages","text":"

    You can create multiple custom Web pages and specify pages that can be called from the menu. The following sketch shows a code sequence for integrating three custom Web pages into one and embedding them in a menu.

    • In the above code, the third parameter of aux2 is false. The third parameter of the AutoConnectAux constructor is an indicator for whether it's shown to the AutoConnect menu. Right animation is an execution result of the above code. You will see that the menu applies only two items for three custom Web pages. the Sketch of this animation is written to transition to aux2 by the utility of the AutoConnectSubmit element owned by aux1.2The aux2 page transitions only from the aux1 page. As shown in mqttRSSI in the library example, its page replies the saving result for the parameters entered on the previous page. It can not be invoked directly from the menu and want to hide them with AutoConnect menu items. The utility of the third parameter of the AutoConnectAux constructor is that.

    "},{"location":"acintro.html#basic-steps-to-use-custom-web-pages","title":"Basic steps to use custom Web pages","text":"

    So, the basic procedure for handling of the custom Web pages is as follows:

    1. Create or define AutoConnectAux.
    2. Create or define AutoConnectElement(s).
    3. Add AutoConnectElement(s) to AutoConnectAux.
    4. Create more AutoConnectAux containing AutoConnectElement(s), if necessary.
    5. Register the request handlers for the custom Web pages.
    6. Join prepared AutoConnectAux(s) to AutoConnect.
    7. Invoke AutoConnect::begin().
    8. Perform AutoConnect::handleClient().
    "},{"location":"acintro.html#write-the-custom-web-page-with-json","title":"Write the custom Web page with JSON","text":"

    You can write the custom Web page in JSON without using sketch codes.3 It is possible to describe the entire page in JSON and can be described for each element also. The JSON document can be saved in SPIFFS or SD and read using AutoConnect's load function. you can reduce the steps of the basic procedure with this approach, but this way consumes a lot of memory. The following JSON code and sketch will execute the custom Web page as an example in the above figure. That is, the Sketch of this code and footnote2 is equivalent.

    custom_page.json 

    [\n  {\n\"title\": \"MQTT Setting\",\n\"uri\": \"/mqtt_setting\",\n\"menu\": true,\n\"element\": [\n      {\n\"name\": \"header\",\n\"type\": \"ACText\",\n\"value\": \"MQTT broker settings\"\n      },\n      {\n\"name\": \"caption1\",\n\"type\": \"ACText\",\n\"value\": \"Publishing the WiFi...\"\n      },\n      {\n\"name\": \"save\",\n\"type\": \"ACSubmit\",\n\"value\": \"SAVE\",\n\"uri\": \"/mqtt_save\"\n      }\n    ]\n  },\n  {\n\"title\": \"MQTT Setting\",\n\"uri\": \"/mqtt_save\",\n\"menu\": false,\n\"element\": [\n      {\n\"name\": \"caption2\",\n\"type\": \"ACText\",\n\"value\": \"Save parameters\"\n      },\n      {\n\"name\": \"start\",\n\"type\": \"ACSubmit\",\n\"value\": \"START\",\n\"uri\": \"/mqtt_start\"\n      }\n    ]\n  },\n  {\n\"title\": \"MQTT Start\",\n\"uri\": \"/mqtt_start\",\n\"menu\": true,\n\"element\": []\n  }\n]\n

    the Sketch 

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <FS.h>\n#include <AutoConnect.h>\n\nAutoConnect  portal;\n\nvoid setup() {\n  SPIFFS.begin();\n\n  File page = SPIFFS.open(\"/custom_page.json\", \"r\");\n  portal.load(page);\n  page.close();\n  SPIFFS.end();\n\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    "},{"location":"acintro.html#passing-parameters-with-sketches-and-custom-web-pages","title":"Passing parameters with sketches and custom Web pages","text":"

    A sketch can access variables of AutoConnectElements on the custom Web page. The value entered into the AutoConnectElements is stored to the member variables of the element by AutoConnect whenever GET / POST transmission occurs. Your sketches can get these values with the request handler which will be registered by AutoConnect::on function. And if you assign a value to an element before a request to the page occurs, its value will appear as the initial value when the page is displayed. The details are explained in section Custom field data handling.

    1. There is no overlay in the actual menu.\u00a0\u21a9

    2. the Sketch is actually this: 

      #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect     portal;\n\nACText(header, \"MQTT broker settings\");\nACText(caption1, \"Publishing the WiFi...\");\nACSubmit(save, \"SAVE\", \"/mqtt_save\");\nAutoConnectAux  aux1(\"/mqtt_setting\", \"MQTT Setting\", true, { header, caption1, save });\n\nACText(caption2, \"Save parameters\");\nACSubmit(start, \"START\", \"/mqtt_start\"); \nAutoConnectAux  aux2(\"/mqtt_save\", \"MQTT Setting\", false, { caption2, start });\n\nAutoConnectAux  aux3(\"/mqtt_start\", \"MQTT Start\");\n\nvoid setup() {\n  portal.join({ aux1, aux2, aux3 });\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
      \u21a9

    3. Installation of the ArduinoJson as the latest release of version 5 series is required.\u00a0\u21a9

    "},{"location":"acjson.html","title":"Custom Web pages with JSON","text":"

    You can embed custom Web pages written in JSON into AutoConnect without AutoConnectAux & AutoConnectElements declaration. Custom Web page declaration by JSON can embed in the Sketch as a fixed string or can store in the external file such as SPIFFS for stream loading. Also, you can also load and save AutoConnectElements objects individually.1

    By providing the following JSON document to AutoConnect, you can include the custom Web page like the below:

    A JSON document for AutoConnect can contain the custom Web page multiple. You can further reduce the Sketch process by loading multiple pages of JSON document at once.

    Adopt ArduinoJson v5 or v6

    To handle AutoConnectAux and AutoConnectElements written in JSON, you need to install the ArduinoJson library. You can adopt either version 5 or version 6 for the ArduinoJson. AutoConnect supports both versions.

    "},{"location":"acjson.html#json-objects-elements-for-the-custom-web-page","title":"JSON objects & elements for the custom Web page","text":""},{"location":"acjson.html#json-document-structure-for-autoconnectaux","title":"JSON document structure for AutoConnectAux","text":"

    AutoConnectAux will configure custom Web pages with JSON objects. The elements that make up the object are as follows:

    {\n\"title\" : title,\n\"uri\" : uri,\n\"menu\" : true | false,\n\"response\" : true | false,\n\"auth\": authentication,\n\"element\" : element_array\n}\n
    "},{"location":"acjson.html#title","title":"title","text":"A title of the custom Web page. This is string value and specifies the title will be displayed in the AutoConnection menu."},{"location":"acjson.html#uri","title":"uri","text":"String of URI path that specifies where to place the custom Web page. It needs to be a location from the root path including '/'."},{"location":"acjson.html#menu","title":"menu","text":"This is a Boolean value indicating whether to include the custom Web page in the AutoConnect menu. If the page only responds to another page and you want to prevent the direct use from the menu, you can exclude from the AutoConnect menu. If this key is false, it will not appear in the menu."},{"location":"acjson.html#response","title":"response","text":"This is a Boolean value indicating whether to respond to HTTP responses independently in its custom web page handler. Normally, AutoConnect will respond with a response code of 200 after its custom web page has processed the request from the client. However, depending on the processing status of the handler, it may be necessary to return a response other than 200. For example, it might respond with a 302 redirect. In such situations, the custom web page handler can apply the sendHeader, sendContent, and send functions of the WebServer library to respond with its own response. If the response is false, AutoConnect will not respond with an HTTP response when it returns from the custom web page handler. The custom web page handler needs to perform the HTTP response by itself."},{"location":"acjson.html#auth","title":"auth","text":"It allows that this page requires authentication. An authentication specifies the following string that represents the authentication scheme.
    • NONE: No authentication. This is default.
    • BASIC: Apply Basic scheme.
    • DIGEST: Apply Digest scheme.
    "},{"location":"acjson.html#element","title":"element","text":"Describe an array of JSON objects as element_array. It is a JSON object array of the AutoConnectElements that make up the custom Web page.

    Order of elements on a custom Web page

    The order in which AutoConnectElements are placed on a custom Web page is the order in the JSON document.

    "},{"location":"acjson.html#multiple-custom-web-pages-declaration-in-json-document","title":"Multiple custom Web pages declaration in JSON document","text":"

    You can put declarations of multiple custom Web pages in one JSON document. In that case, declare an array of each custom Web page with JSON. The following JSON document contains three custom Web pages:

    [\n  {\n\"title\" : \"Page 1 title\",\n\"uri\" : \"/page1\",\n\"menu\" : true,\n\"element\" : [\n      {\n\"name\" : \"caption\",\n\"type\" : \"ACText\",\n\"value\" : \"hello, world\"\n      },\n      {\n\"name\" : \"send\",\n\"type\" : \"ACSubmit\",\n\"uri\" : \"/page2\"\n      }\n    ]\n  },\n  {\n\"title\" : \"Page 1 title\",\n\"uri\" : \"/page2\",\n\"menu\" : false,\n\"element\" : [\n      {\n\"name\" : \"responds\",\n\"type\" : \"ACText\",\n\"value\" : \"Good day\"\n      },\n      {\n\"name\" : \"send\",\n\"type\" : \"ACSubmit\",\n\"uri\" : \"/page3\"\n      }\n    ]\n  },\n  {\n\"title\" : \"Page 3 title\",\n\"uri\" : \"/page3\",\n\"menu\" : true,\n\"element\" : [\n      {\n\"name\" : \"responds\",\n\"type\" : \"ACText\",\n\"value\" : \"bye\"\n      }\n    ]\n  }\n]\n

    The above custom Web page definitions can be loaded in a batch using the AutoConnect::load function.

    "},{"location":"acjson.html#json-object-for-autoconnectelements","title":"JSON object for AutoConnectElements","text":"

    JSON description for AutoConnectElements describes as an array in the element with arguments of each constructor.

    {\n\"name\" : name,\n\"type\" : type,\n\"posterior\" : posterior,\nkey_according_to_type : the_value | array_of_value,\n  [ key_according_to_type : the_value | array_of_value ]\n}\n
    "},{"location":"acjson.html#name","title":"name","text":"A string of the name for the element."},{"location":"acjson.html#type","title":"type","text":"A string of the type for the element. For this type, specify the following string corresponding to each element.
    • AutoConnectButton: ACButton
    • AutoConnectCheckbox: ACCheckbox
    • AutoConnectElement: ACElement
    • AutoConnectFile: ACFile
    • AutoConnectInput: ACInput
    • AutoConnectRadio: ACRadio
    • AutoConnectRange: ACRange
    • AutoConnectSelect: ACSelect
    • AutoConnectStyle: ACStyle
    • AutoConnectSubmit: ACSubmit
    • AutoConnectText: ACText
    "},{"location":"acjson.html#posterior","title":"posterior","text":"Specifies a tag to add behind the HTML code generated from the element. Its purpose is to place elements on the custom Web page as intended by the user sketch. You can use the posterior key with the following values to arrange vertically or horizontal when the elements do not have the intended position on the custom Web Page specifying the following:
    • none : No generate additional tags.
    • br : Add a <br> tag to the end of the element.
    • par : Include the element in the <p> ~ </p> tag.
    • div : Include the element in the <div> ~ </div> tag.
    "},{"location":"acjson.html#key_according_to_type","title":"key_according_to_type","text":"

    This is different for each AutoConnectElements, and the key that can be specified by the type of AutoConnectElements is determined.

    "},{"location":"acjson.html#acbutton","title":"ACButton","text":"
    • value : Specifies the button label. This value also applies to the value attribute of an HTML button tag.
    • action : Specifies an action to be fire on a mouse click on the button. It is mostly used with a JavaScript to activate a script, or it directly describes a JavaScript.
    "},{"location":"acjson.html#accheckbox","title":"ACCheckbox","text":"
    • value : Specifies the value to be supplied to the checkbox. It will be packed in the query string as name=value when the checkbox is ticked.
    • label : Specifies a label of the checkbox. Its placement is always to the right of the checkbox.
    • checked : Specifies checking status as a boolean value. The value of the checked checkbox element is packed in the query string and sent.
    "},{"location":"acjson.html#acelement","title":"ACElement","text":"
    • value : Specifies the source code of generating HTML. The value is native HTML code and is output as HTML as it is.
    "},{"location":"acjson.html#acfile","title":"ACFile","text":"
    • value : The file name of the upload file will be stored. The value is read-only and will be ignored if specified.
    • label : Specifies a label of the file selection box. Its placement is always to the left of the file selection box.
    • store : Specifies the destination to save the uploaded file. Its value accepts one of the following:
      • fs : Save as the SPIFFS file in flash of ESP8266/ESP32 module. If the valid file system of the ESP8266 module incorporating the Sketch is LittleFS, AutoConnect assumes the file system to be LittleFS. However, it does not sense the actual file system, so If the Sketch implementation does not match the file system on the ESP8266 depends, a file writing error will occur.
      • sd : Save to an external SD device connected to ESP8266/ESP32 module.
      • extern : Pass the content of the uploaded file to the uploader which is declared by the Sketch individually. Its uploader must inherit AutoConnectUploadHandler class and implements _open, _write and _close function.

    A valid filesystem of ESP8266 on board flash

    AutoConnect has assumed LittleFS as a valid file system since v1.2.0 enhancement. On the other hand, the ESP8266 arduino core has supported LittleFS officially since a release 2.7.0. LittleFS support in AutoConnect relies on the FS instance declared by the arduino core used at compile-time per project, and its FS instance will acquire by either the SPIFFS class or the LittleFS class. That is, you need to choose which file system will be available in the actual Sketch and make consistent it with AutoConnect assumed file system. So, you can choose which one uses the file systems per project via adjustment the AC_USE_SPIFFS macro enable or disable. AutoConnect determines the available file system by the AC_USE_SPIFFS macro which defined in AutoConnectDefs.h header file.

    "},{"location":"acjson.html#acinput","title":"ACInput","text":"
    • value : Specifies the initial text string of the input box. If this value is omitted, placeholder is displayed as the initial string.
    • label : Specifies a label of the input box. Its placement is always to the left of the input box.
    • placeholder : Specifies short hint of the input box.
    • apply : Specifies the type of input that the text box accepts. Its value accepts one of the following:
      • text : A text.
      • password : Password input field. The text is obscured so that it cannot be read, usually by replacing each character with a symbol such as the asterisk (\"*\") or a dot (\"\u2022\").
      • number : A field let the user enter number characters only.

    Numerical keypad is different

    When the AutoConnectInput element with the number applied is focused on the browser, the numeric keypad may be displayed automatically. For popular mobile OSes such as Android and iOS, the numeric keypad has the following styles and is different with each OS.

    "},{"location":"acjson.html#acradio","title":"ACRadio","text":"
    • value : Specifies the collection of radio buttons as an array element.
    • label : Specifies a label of the collection of radio buttons, not for each button. The arrangement will be the top or left side according to the arrange.
    • arrange : Specifies the orientation of the radio buttons. Its value accepts one of the following:
      • horizontal : Horizontal arrangement.
      • vertical : Vertical arrangement.
    • checked : Specifies the index number (1-based) of the radio buttons collection to be checked.
    "},{"location":"acjson.html#acrange","title":"ACRange","text":"
    • value : Specifies the initial value in the range. If the value is not specified, the default value is determined by the following algorithm:value = (max < min) ? min : min + (max - min)/2;
    • label : Specifies a label of the range slider. Its placement is always to the left of the input box.
    • min : Specifies the most negative value within the range of allowed values and must not be less than the value.
    • max : Specifies the greatest value in the range of permitted values.
    • step : Specifies the granularity that the value must adhere to. The default is 1. As you move the slider, it increases or decreases the value according to the step in granularity.
    • magnify : Displays the current value of the range on the left or right side of the slider. The magnify accepts one of the following:
      • infront : Displays the current value on the left side.
      • behind : Displays the current value on the right side.
      • void : No display the current value. This is the default.
    • style : Specifies the qualification style to give to the content and can use the style attribute format as it is.
    "},{"location":"acjson.html#acselect","title":"ACSelect","text":"
    • label : Specifies a label of the drop-down list. Its placement is always to the left of the drop-down list.
    • option : Specifies the initial value collection of the drop-down list as an array element.
    "},{"location":"acjson.html#acstyle","title":"ACStyle","text":"
    • value : Specifies the custom CSS code.
    "},{"location":"acjson.html#acsubmit","title":"ACSubmit","text":"
    • value : Specifies a label of the submit button.
    • uri : Specifies the URI to send form data when the button is clicked.
    "},{"location":"acjson.html#actext","title":"ACText","text":"
    • value : Specifies a content and also can contain the native HTML code, but remember that your written code is enclosed by the div tag.
    • style : Specifies the qualification style to give to the content and can use the style attribute format as it is.
    • format : Specifies how to interpret the value. It specifies the conversion format when outputting values. The format string conforms to the C-style printf library functions, but depends on the espressif SDK implementation. The conversion specification is valid only for %s format. (Left and Right justification, width are also valid.)

    AutoConnect JSON parsing process is not perfect

    It is based on analysis by ArduinoJson, but the semantic analysis is simplified to save memory. Consequently, it is not an error that a custom Web page JSON document to have unnecessary keys. It will be ignored.

    "},{"location":"acjson.html#loading-json-document","title":"Loading JSON document","text":""},{"location":"acjson.html#loading-to-autoconnect","title":"Loading to AutoConnect","text":"

    There are two main ways to load the custom Web pages into AutoConnect.

    1. Load directly into AutoConnect

      This way does not require an explicit declaration of AutoConnectAux objects with sketches and is also useful when importing the custom Web pages JSON document from an external file such as SPIFFS because the page definition and sketch coding structure can be separated.

      Using the AutoCoonnect::load function, AutoConnect dynamically generates the necessary AutoConnectAux objects internally based on the custom Web page definition of the imported JSON document content. In the Sketch, the generated AutoConnectAux object can be referenced using the AutoConnect::aux function. You can reach the AutoConnectElements you desired using the AutoConnectAux::getElement function of its AutoConnectAux.

      In the following example, it loads in a batch a JSON document of custom Web pages stored in SPIFFS and accesses to the AutoConnectInput element.

      [\n  {\n\"title\": \"page1\",\n\"uri\": \"/page1\",\n\"menu\": true,\n\"element\": [\n      {\n\"name\": \"input1\",\n\"type\": \"ACInput\"\n      }\n    ]\n  },\n  {\n\"title\": \"page2\",\n\"uri\": \"/page2\",\n\"menu\": true,\n\"element\": [\n      {\n\"name\": \"input2\",\n\"type\": \"ACInput\"\n      }\n    ]\n  }\n]\n
      AutoConnect portal;\nFile page = SPIFFS.open(\"/custom_page.json\", \"r\");\nportal.load(page);\npage.close();\nAutoConnectAux* aux = portal.aux(\"/page1\");\nAutoConnectInput& input1 = aux->getElement<AutoConnectInput>(\"input1\");\n

    2. Load to AutoConnectAux and join to AutoConnect

      This way declares AutoConnectAux in the Sketch and loads the custom Web pages JSON document there. It has an advantage for if you want to define each page of a custom Web page individually or allocate AutoConnectAux objects dynamically on the Sketch side.

      After loading a JSON document using the AutoConnectAux::load function by each, integrate those into AutoConnect using the AutoConnect::join function.

      In the following example, you can see the difference between two sketches in a sketch modified using the AutoConnectAux::load.

      {\n\"title\": \"page1\",\n\"uri\": \"/page1\",\n\"menu\": true,\n\"element\": [\n    {\n\"name\": \"input1\",\n\"type\": \"ACInput\"\n    }\n  ]\n}\n
      {\n\"title\": \"page2\",\n\"uri\": \"/page2\",\n\"menu\": true,\n\"element\": [\n    {\n\"name\": \"input2\",\n\"type\": \"ACInput\"\n    }\n  ]\n}\n
      AutoConnect portal;\nAutoConnectAux page1;\nAutoConnectAux page2;\nFile page = SPIFFS.open(\"/custom_page1.json\", \"r\");\npage1.load(page);\npage.close();\npage = SPIFFS.open(\"/custom_page2.json\", \"r\");\npage2.load(page);\npage.close();\nportal.join( { page1, page2 } );\nAutoConnectInput& input1 = page1.getElement<AutoConnectInput>(\"input1\");\n

    "},{"location":"acjson.html#loading-from-the-streamed-file","title":"Loading from the streamed file","text":"

    AutoConnect supports loading of JSON document from the following instances:

    • String
    • PROGMEM
    • Stream

    To load custom Web pages JSON document into AutoConnect, use the load function of the AutoConnect class. Its JSON document can read must be completed as a description interpretable by the ArduinoJson library. It cannot import custom Web pages if there are syntax errors for the JSON. If you can not see the custom Web page prepared by JSON, you can check the syntax with ArduinoJson Assistant. It is useful for pre-checking.

    bool AutoConnect::load(const String& aux)\n
    bool AutoConnect::load(const __FlashStringHelper* aux)\n
    bool AutoConnect::load(Stream& aux)\n
    An example of using each function is as follows. 
    AutoConnect  portal;\n\n// Loading from String\nconst String aux = String(\"{\\\"title\\\":\\\"Page 1 title\\\",\\\"uri\\\":\\\"/page1\\\",\\\"menu\\\":true,\\\"element\\\":[{\\\"name\\\":\\\"caption\\\",\\\"type\\\":\\\"ACText\\\",\\\"value\\\":\\\"hello, world\\\"}]}\");\nportal.load(aux);\n\n// Loading from PROGMEM\nconst char aux[] PROGMEM = R\"raw(\n{\n  \"title\" : \"Page 1 title\",\n  \"uri\" : \"/page1\",\n  \"menu\" : true,\n  \"element\" : [\n    {\n      \"name\" : \"caption\",\n      \"type\" : \"ACText\",\n      \"value\" : \"hello, world\"\n    }\n  ]\n}\n)raw\";\nportal.load(FPSTR(aux));\n\n// Loading from Stream assumes \"aux.json\" file should be store in SPIFFS.\nFile aux = SPIFFS.open(\"aux.json\", \"r\");\nportal.load(aux);\naux.close();\n

    AutoConnect passes the given JSON document directly to the parseObject() function of the ArduinoJson library for parsing. Therefore, the constraint of the parseObject() function is applied as it is in the parsing of the JSON document for the AutoConnect. That is, if the JSON string is read-only, duplicating the input string occurs and consumes more memory.

    "},{"location":"acjson.html#adjust-the-json-document-buffer-size","title":"Adjust the JSON document buffer size","text":"

    AutoConnect uses ArduinoJson library's dynamic buffer to parse JSON documents. Its dynamic buffer allocation scheme depends on the version 5 or version 6 of ArduinoJson library. Either version must have enough buffer to parse the custom web page's JSON document successfully. AutoConnect has the following three constants internally to complete the parsing as much as possible in both ArduinoJson version. These constants are macro defined in AutoConnectDefs.h.

    If memory insufficiency occurs during JSON document parsing, you can adjust these constants to avoid insufficiency by using the JsonAssistant with deriving the required buffer size in advance.

    #define AUTOCONNECT_JSONBUFFER_SIZE     256\n#define AUTOCONNECT_JSONDOCUMENT_SIZE   (8 * 1024)\n#define AUTOCONNECT_JSONPSRAM_SIZE      (16* 1024)\n
    "},{"location":"acjson.html#autoconnect_jsonbuffer_size","title":"AUTOCONNECT_JSONBUFFER_SIZE","text":"

    This is a unit size constant of DynamicJsonBuffer and works when the library used is ArduinoJson version 5. A buffer size of the JSON document increases with this unit. This value relates to the impact of the fragmented heap area. If it is too large, may occur run-out of memory.

    "},{"location":"acjson.html#autoconnect_jsondocument_size","title":"AUTOCONNECT_JSONDOCUMENT_SIZE","text":"

    This is a size of DynamicJsonDocument for ArduinoJson version 6. This buffer is not automatically expanding, and the size determines the limit.

    "},{"location":"acjson.html#autoconnect_jsonpsram_size","title":"AUTOCONNECT_JSONPSRAM_SIZE","text":"

    For ESP32 module equips with PSRAM, you can allocate the JSON document buffer to PSRAM. Buffer allocation to PSRAM will enable when PSRAM:Enabled option selected in the Arduino IDE's Board Manager menu. It is available since ArduinoJson 6.10.0.

    "},{"location":"acjson.html#saving-json-document","title":"Saving JSON document","text":"

    the Sketch can persist AutoConnectElements as a JSON document and also uses this function to save the values entered on the custom Web page. And you can reload the saved JSON document into AutoConnectElements as the field in a custom Web page using the load function.

    1. Loading and saving AutoConnect parameters adopt this method.\u00a0\u21a9

    "},{"location":"acupload.html","title":"File upload handler","text":""},{"location":"acupload.html#uploading-file-from-web-browser","title":"Uploading file from Web Browser","text":"

    If you have to write some data individually to the ESP8266/ESP32 module for the Sketch behavior, the AutoConnectFile element will assist with your wants implementation. The AutoConnectFile element produces an HTML <input type=\"file\"> tag and can save uploaded file to the flash or external SD of the ESP8266/ESP32 module. The handler for saving is built into AutoConnect. You can use it to inject any sketch data such as the initial values for the custom Web page into the ESP module via OTA without using the Sketch data upload tool of Arduino-IDE.

    "},{"location":"acupload.html#basic-steps-of-the-file-upload-sketch","title":"Basic steps of the file upload sketch","text":"

    Here is the basic procedure of the Sketch which can upload files from the client browser using AutoConnectFile:1

    1. Place AutoConnectFile on a custom Web page by writing JSON or constructor code directly with the Sketch.
    2. Place other AutoConnectElements as needed.
    3. Place AutoConnectSubmit on the same custom Web page.
    4. Perform the following process in the on-handler of submitting destination:
      • Retrieve the AutoConnectFile instance from the custom Web page where you placed the AutoConnectFile element using the AutoConnectAux::getElement function or the operator [].
      • Start access to the device specified as the upload destination. In usually, it depends on the file system's begin function. For example, if you specified Flash's SPIFFS as the upload destination, invokes SPIFFS.begin().
      • The value member of AutoConnectFile contains the file name of the upload file. Use its file name to access the uploaded file on the device.
      • Invokes the end function associated with the begin to close the device. It is the SPIFFS.end()* if the flash on the ESP module has been begun for SPIFFS.

    The following sketch is an example that implements the above basic steps. The postUpload function is the on-handler and retrieves the AutoConnectFile as named upload_file. You should note that this handler is not for a custom Web page placed with its AutoConnectFile element. The uploaded file should be processed by the handler for the transition destination page from the AutoConnectFile element placed page. AutoConnect built-in upload handler will save the uploaded file to the specified device before invoking the postUpload function.

    However, If you use uploaded files in different situations, it may be more appropriate to place the actual handling process outside the handler. It applies for the parameter file, etc. The important thing is that you do not have to sketch file reception and storing logic by using the AutoConnectFile element and the upload handler built into the AutoConnect.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <FS.h>\n#include <AutoConnect.h>\n\n// Upload request custom Web page\nstatic const char PAGE_UPLOAD[] PROGMEM = R\"(\n{\n  \"uri\": \"/\",\n  \"title\": \"Upload\",\n  \"menu\": true,\n  \"element\": [\n    { \"name\":\"caption\", \"type\":\"ACText\", \"value\":\"<h2>File uploading platform<h2>\" },\n    { \"name\":\"upload_file\", \"type\":\"ACFile\", \"label\":\"Select file: \", \"store\":\"fs\" },\n    { \"name\":\"upload\", \"type\":\"ACSubmit\", \"value\":\"UPLOAD\", \"uri\":\"/upload\" }\n  ]\n}\n)\";\n\n// Upload result display\nstatic const char PAGE_BROWSE[] PROGMEM = R\"(\n{\n  \"uri\": \"/upload\",\n  \"title\": \"Upload\",\n  \"menu\": false,\n  \"element\": [\n    { \"name\":\"caption\", \"type\":\"ACText\", \"value\":\"<h2>Uploading ended<h2>\" },\n    { \"name\":\"filename\", \"type\":\"ACText\" },\n    { \"name\":\"size\", \"type\":\"ACText\", \"format\":\"%s bytes uploaded\" },\n    { \"name\":\"content_type\", \"type\":\"ACText\", \"format\":\"Content: %s\" }\n  ]\n}\n)\";\n\nESP8266WebServer server;\nAutoConnect portal(server);\n// Declare AutoConnectAux separately as a custom web page to access\n// easily for each page in the post-upload handler.\nAutoConnectAux auxUpload;\nAutoConnectAux auxBrowse;\n\n/**\n * Post uploading, AutoConnectFile's built-in upload handler reads the\n * file saved in SPIFFS and displays the file contents on /upload custom\n * web page. However, only files with mime type uploaded as text are\n * displayed. A custom web page handler is called after upload.\n * @param  aux  AutoConnectAux(/upload)\n * @param  args PageArgument\n * @return Uploaded text content\n */\nString postUpload(AutoConnectAux& aux, PageArgument& args) {\n  String  content;\n  AutoConnectFile&  upload = auxUpload[\"upload_file\"].as<AutoConnectFile>();\n  AutoConnectText&  aux_filename = aux[\"filename\"].as<AutoConnectText>();\n  AutoConnectText&  aux_size = aux[\"size\"].as<AutoConnectText>();\n  AutoConnectText&  aux_contentType = aux[\"content_type\"].as<AutoConnectText>();\n// Assignment operator can be used for the element attribute.\n  aux_filename.value = upload.value;\n  aux_size.value = String(upload.size);\n  aux_contentType.value = upload.mimeType;\n// The file saved by the AutoConnect upload handler is read from\n// the EEPROM and echoed to a custom web page.\n  SPIFFS.begin();\n  File uploadFile = SPIFFS.open(String(\"/\" + upload.value).c_str(), \"r\");\nif (uploadFile) {\nwhile (uploadFile.available()) {\nchar c = uploadFile.read();\n      Serial.print(c);\n    }\n    uploadFile.close();\n  }\nelse\n    content = \"Not saved\";\n  SPIFFS.end();\nreturn String();\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  auxUpload.load(PAGE_UPLOAD);\n  auxBrowse.load(PAGE_BROWSE);\n  portal.join({ auxUpload, auxBrowse });\n  auxBrowse.on(postUpload);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"acupload.html#where-will-the-file-upload","title":"Where will the file upload","text":"

    The AutoConnect built-in upload handler can save the upload file to three locations:

    1. Flash memory embedded in the ESP8266/ESP32 module
    2. SD device externally connected to the ESP8266/ESP32 module
    3. Other character devices

    You can specify the device type to save with the store attribute of AutoConnectFile, and it accepts the following values:

    • Flash : AC_File_FS for the API parameter or fs for the JSON document
    • SD : AC_File_SD for the API parameter or sd for the JSON document
    • Other : AC_File_Extern for the API parameter or extern for the JSON document

    The substance of AC_File_FS (fs) is a SPIFFS file system implemented by the ESP8266/ESP32 core, and then AutoConnect uses the Global Instance SPIFFS to access SPIFFS.

    Also, the substance of AC_File_SD (sd) is a FAT file of Arduino SD library ported to the ESP8266/ESP32 core, and then AutoConnect uses the Global Instance SD to access SD. When saving to an external SD device, there are additional required parameters for the connection interface and is defined as the macro in AutoConnectDefs.h.

    #define AUTOCONNECT_SD_CS       SS\n#define AUTOCONNECT_SD_SPEED    4000000\n

    AUTOCONNECT_SD_CS defines which GPIO for the CS (Chip Select, or SS as Slave Select) pin. This definition is derived from pins_arduino.h, which is included in the Arduino core distribution. If you want to assign the CS pin to another GPIO, you need to change the macro definition of AutoConnectDefs.h.

    AUTOCONNECT_SD_SPEED defines SPI clock speed depending on the connected device.

    Involves both the begin() and the end()

    The built-in uploader executes the begin and end functions regardless of the Sketch whence the file system of the device will terminate with the uploader termination. Therefore, to use the device in the Sketch after uploading, you need to restart it with the begin function.

    "},{"location":"acupload.html#when-it-will-be-uploaded","title":"When it will be uploaded","text":"

    Upload handler will be launched by ESP8266WebServer/WebServer(as ESP32) library which is triggered by receiving an HTTP stream of POST BODY including file content. Its launching occurs before invoking the page handler.

    The following diagram illustrates the file uploading sequence:

    At the time of the page handler behaves, the uploaded file already saved to the device, and the member variables of AutoConnectFile reflects the file name and transfer size.

    "},{"location":"acupload.html#the-file-name-for-the-uploaded-file","title":"The file name for the uploaded file","text":"

    AutoConnetFile saves the uploaded file with the file name you selected by <input type=\"file\"> tag on the browser. The file name used for uploading is stored in the AutoConnetFile's value member, which you can access after uploading. (i.e. In the handler of the destination page by the AutoConnectSubmit element.) You can not save it with a different name. It can be renamed after upload if you need to change the name.

    "},{"location":"acupload.html#upload-to-a-device-other-than-flash-or-sd","title":"Upload to a device other than Flash or SD","text":"

    You can output the file to any device using a custom uploader by specifying extern with the store attribute of AutoConnectFile (or specifying AC_File_Extern for the store member variable) and can customize the uploader according to the need to upload files to other than Flash or SD. Implements your own uploader with inheriting the AutoConnectUploadHandler class which is the base class of the upload handler.

    It's not so difficult

    Implementing the custom uploader requires a little knowledge of the c++ language. If you are less attuned to programming c++, you may find it difficult. But don't worry. You can make it in various situations by just modifying the Sketch skeleton that appears at the end of this page.

    "},{"location":"acupload.html#upload-handler-base-class","title":"Upload handler base class","text":"

    AutoConnectUploadHandler is a base class of upload handler and It has one public member function and three protected functions.

    "},{"location":"acupload.html#constructor","title":"Constructor","text":"
    AutoConnectUploadHandler()\n
    "},{"location":"acupload.html#member-functions","title":"Member functions","text":"

    The upload public function is an entry point, the ESP8266WebServer (WebServer as ESP32) library will invoke the upload with each time of uploading content divided into chunks.

    Also, the _open, _write and _close protected functions are actually responsible for saving files and are declared as pure virtual functions. A custom uploader class that inherits from the AutoConnectUploadHandler class need to implement these functions.

    The actual upload process is handled by the three private functions above, and then upload only invokes three functions according to the upload situation. In usually, there is no need to override the upload function in an inherited class.

    public virtual void upload(const String& requestUri, const HTTPUpload& upload)\n
    Parameters requestUriURI of upload request source. uploadA data structure of the upload file as HTTPUpload. It is defined in the ESP8266WebServer (WebServer as ESP32) library as follows: 
    typedef struct {\n  HTTPUploadStatus status;\n  String  filename;\n  String  name;\n  String  type;\nsize_t  totalSize;\nsize_t  currentSize;\nsize_t  contentLength;\nuint8_t buf[HTTP_UPLOAD_BUFLEN];\n} HTTPUpload;\n

    An upload handler needs to implement a procedure corresponding with HTTPUploadStatus enum value indicated by the uploading process of ESP8266WebServer class, which contained in HTTPUpload.status as following values:

    • UPLOAD_FILE_START : Invokes to the _open.
    • UPLOAD_FILE_WRITE : Invokes to the _write.
    • UPLOAD_FILE_END : Invokes to the _close.
    • UPLOAD_FILE_ABORTED : Invokes to the _close.

    The _open function will be invoked when HTTPUploadStatus is UPLOAD_FILE_START. Usually, the implementation of an inherited class will open the file.

    protected virtual bool _open(const char* filename, const char* mode) = 0\n
    Parameters filenameUploading file name. modeAn indicator for the file access mode, a \"w\" for writing. Return value trueFile open successful. falseFailed to open.

    The _write function will be invoked when HTTPUploadStatus is UPLOAD_FILE_WRITE. The content of the upload file is divided and the _write will be invoked in multiple times. Usually, the implementation of an inherited class will write data.

    protected virtual size_t _write(const uint8_t *buf, const size_t size) = 0\n
    Parameters bufFile content block. sizeFile block size to write. Return value Size written.

    The _close function will be invoked when HTTPUploadStatus is UPLOAD_FILE_END or UPLOAD_FILE_ABORTED. Usually, the implementation of an inherited class will close the file.

    protected virtual void _close(void) = 0\n

    For reference, the following AutoConnectUploadFS class is an implementation of AutoConnect built-in uploader and inherits from AutoConnectUploadHandler.

    class AutoConnectUploadFS : public AutoConnectUploadHandler {\npublic:\nexplicit AutoConnectUploadFS(SPIFFST& media) : _media(&media) {}\n~AutoConnectUploadFS() { _close(); }\n\nprotected:\nbool _open(const char* filename, const char* mode) override {\nif (_media->begin()) {\n      _file = _media->open(filename, mode);\nreturn _file != false;      \n    }\nreturn false;\n  }\n\nsize_t _write(const uint8_t* buf, const size_t size) override {\nif (_file)\nreturn _file.write(buf, size);\nelse\nreturn -1;\n  }\n\nvoid _close(void) override {\nif (_file)\n      _file.close();\n    _media->end();\n  }\n\nprivate:\n  SPIFFST*  _media;\n  SPIFileT  _file; \n};\n
    "},{"location":"acupload.html#register-custom-upload-handler","title":"Register custom upload handler","text":"

    In order to upload a file by the custom uploader, it is necessary to register it to the custom Web page beforehand. To register a custom uploader, specify the custom uploader class name in the template argument of the AutoConnectAux::onUpload function and invokes it.

    void AutoConnectAux::onUpload<T>(T& uploadClass)\n
    Parameters TSpecifies a class name of the custom uploader. This class name is a class that you implemented by inheriting AutoConnectUploadHandler for custom upload. uploadClassSpecifies the custom upload class instance.

    The rough structure of the Sketches that completed these implementations will be as follows:

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char PAGE_UPLOAD[] PROGMEM = R\"(\n{\n  \"uri\": \"/\",\n  \"title\": \"Upload\",\n  \"menu\": true,\n  \"element\": [\n    { \"name\":\"caption\", \"type\":\"ACText\", \"value\":\"<h2>File uploading platform<h2>\" },\n    { \"name\":\"upload_file\", \"type\":\"ACFile\", \"label\":\"Select file: \", \"store\":\"extern\" },\n    { \"name\":\"upload\", \"type\":\"ACSubmit\", \"value\":\"UPLOAD\", \"uri\":\"/upload\" }\n  ]\n}\n)\";\n\nstatic const char PAGE_RECEIVED[] PROGMEM = R\"(\n{\n  \"uri\": \"/upload\",\n  \"title\": \"Upload ended\",\n  \"menu\": false,\n  \"element\": [\n    { \"name\":\"caption\", \"type\":\"ACText\", \"value\":\"<h2>File uploading ended<h2>\" }\n  ]\n}\n)\";\n\n// Custom upload handler class\nclass CustomUploader : public AutoConnectUploadHandler {\npublic:\n  CustomUploader() {}\n~CustomUploader() {}\n\nprotected:\nbool   _open(const char* filename, const char* mode) override;\nsize_t _write(const uint8_t *buf, const size_t size) override;\nvoid   _close(void) override;\n};\n\n// _open for custom open\nbool CustomUploader::_open(const char* filename, const char* mode) {\n// Here, an implementation for the open file.\n}\n\n// _open for custom write\nsize_t CustomUploader::_write(const uint8_t *buf, const size_t size) {\n// Here, an implementation for the writing the file data.\n}\n\n// _open for custom close\nvoid CustomUploader::_close(void) {\n// Here, an implementation for the close file.\n}\n\nAutoConnect     portal;\nAutoConnectAux  uploadPage;\nAutoConnectAux  receivePage;\nCustomUploader  uploader;   // Declare the custom uploader\n\nvoid setup() {\n  uploadPage.load(PAGE_UPLOAD);\n  receivePage.load(PAGE_RECEIVED);\n  portal.join({ uploadPage, receivePage });\n  receivePage.onUpload<CustomUploader>(uploader);  // Register the custom uploader\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    Don't forget to specify the store

    When using a custom uploader, remember to specify the extern for the store attribute of AutoConnectFile.

    1. The AutoConnectFile element can be used with other AutoConnectElements on the same page.\u00a0\u21a9

    "},{"location":"adauthentication.html","title":"Authentication settings","text":"

    The Sketch may use authentication to protect custom Web pages and prevent unauthorized access. AutoConnect has implemented HTTP authentication feature that can be applied to multiple scopes using the authentication methods provided by the platform's WebServer library for ESP8266 or ESP32.1

    • Applying HTTP authentication
    • Applying HTTP authentication for Built-in OTA
    • Authentication within the captive portal state
    "},{"location":"adauthentication.html#applying-http-authentication","title":"Applying HTTP authentication","text":"

    AutoConnectConfig::auth setting allows the Sketch to HTTP authenticate with \"BASIC\" or \"DIGEST\" scheme. AutoConnectConfig::authScope specifies the scope covered by authentication which is the whole range for all pages of the Sketch, custom web pages, or AutoConnect pages. AutoConnectConfig::username and AutoConnectConfig::password specifies credential as user-id/password pairs.

    The Sketch enables HTTP authentication with the AutoConnectConfig::auth setting, also specifies the authentication scheme:

    • AC_AUTH_NONE AutoConnect pages and custom Web pages do not require authentication. Not protected from all HTTP access. This is the default.
    • AC_AUTH_DIGEST Protect AutoConnect pages and custom Web pages with DIGEST authentication.
    • AC_AUTH_BASIC Protect AutoConnect pages and custom Web pages with BASIC authentication.

    Note that the authentication scope specified in AutoConnectConfig::authScope is different from the protection space shown by Realm for HTTP authentication. AutoConnect assumes only one Realm and defines it as AUTOCONNECT_AUTH_REALM in AutoConnectDefs.h header file. Instead, the Sketch will be able to expand or narrow the range of authentication by AutoConnectConfig::authScope setting, which can be either as follows:

    • AC_AUTHSCOPE_PORTAL Require authentication to access for all AutoConnect pages, including custom Web pages.
    • AC_AUTHSCOPE_AUX Require authentication to access for all custom Web pages, excepting AutoConnect pages. This is the Default.
    • AC_AUTHSCOPE_PARTIAL Authenticate only specific custom Web pages which are specified by AutoConnectAux::authentication function or JSON.

    Also, a credential used for authentication is specified in the Sketch using the AutoConnectConfig::username and AutoConnectConfig::password settings.2

    Here's a minimal Sketch with HTTP authentication for the custom Web page:

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char PAGE_AUTH[] PROGMEM = R\"(\n{\n  \"uri\": \"/auth\",\n  \"title\": \"Auth\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"text\",\n      \"type\": \"ACText\",\n      \"value\": \"AutoConnect has authorized\",\n      \"style\": \"font-family:Arial;font-size:18px;font-weight:400;color:#191970\"\n    }\n  ]\n}\n)\";\n\nWebServerClass    server;\nAutoConnect       portal(server);\nAutoConnectConfig config;\n\nvoid setup() {\n  config.auth = AC_AUTH_DIGEST;\n  config.authScope = AC_AUTHSCOPE_AUX;\n  config.username = \"user\";\n  config.password = \"password\";\n  portal.config(config);\n  portal.load(FPSTR(PAGE_AUTH));\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    If you want to authenticate only specific pages in a Sketch that handles multiple custom Web pages, set AC_AUTHSCOPE_PARTIAL to AutoConnectConfig::authScope. Then, it specifies the authentication scheme with the auth key in the JSON description of the page should be authenticated.

    AutoConnect determines which authentication method to use for custom Web pages (such as AutoConnectAux) based on its association with AutoConnectConfig::authScope setting. The table below shows which authentication scheme will be finally adopted. As shown in this table, the final authentication scheme depends on the AutoConnectConfig::authScope setting, and if AC_AUTHSCOPE_PARTIAL is specified it, AutoConnectAux's authentication setting takes precedence over the AutoConnectConfig::auth setting.

    AutoConnectConfig::authScope Authentication scheme for the custom Web page AC_AUTHSCOPE_PORTAL Specified by AutoConnectConfig::auth AC_AUTHSCOPE_AUX Specified by AutoConnectConfig::auth AC_AUTHSCOPE_PARTIAL Specified by AutoConnectAux::authentication, The default values is AC_AUTH_NONE.

    Authentication designation for AutoConnectAux can also be specified by giving the following value to the auth key by the JSON description:

    • \"auth\" : \"basic\"
    • \"auth\" : \"digest\"
    • \"auth\" : \"none\"

    The following example Sketch has two custom Web pages, Hello and Auth. It applies authentication only to the Auth page by setting AC_AUTHSCOPE_PARTIAL to AutoConnectConfig::authScope.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char PAGE_HELLO[] PROGMEM = R\"(\n{\n  \"uri\": \"/hello\",\n  \"title\": \"Hello\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"text\",\n      \"type\": \"ACText\",\n      \"value\": \"Hello, word\",\n      \"style\": \"font-family:Arial;font-size:18px;font-weight:400;color:#191970\"\n    }\n  ]\n}\n)\";\n\nstatic const char PAGE_AUTH[] PROGMEM = R\"(\n{\n  \"uri\": \"/auth\",\n  \"title\": \"Auth\",\n  \"menu\": true,\n  \"auth\": \"digest\",\n  \"element\": [\n    {\n      \"name\": \"text\",\n      \"type\": \"ACText\",\n      \"value\": \"AutoConnect has authorized\",\n      \"style\": \"font-family:Arial;font-size:18px;font-weight:400;color:#191970\"\n    }\n  ]\n}\n)\";\n\nWebServerClass    server;\nAutoConnect       portal(server);\nAutoConnectConfig config;\n\nvoid setup() {\n// It's a default value but has no meaning in the AC_AUTHSCOPE_PARTIAL setting.\n// config.auth = AC_AUTH_NONE;\n  config.authScope = AC_AUTHSCOPE_PARTIAL;\n  config.username = \"user\";\n  config.password = \"password\";\n  portal.config(config);\n  portal.load(FPSTR(PAGE_HELLO));\n  portal.load(FPSTR(PAGE_AUTH));\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    PageBuilder v1.4.0 or later needed

    PageBuilder v1.4.0 or later is required to use HTTP authentication with AutoConnect. Also, v1.4.2 or later is required to eliminate SPIFFS, which is deprecated as a file system for ESP8266 module.

    Can not use DIGEST authentication for ESP32 arduino core 1.0.4 stable release

    For ESP32, Arduino core 1.0.4 stable has a bug for DIGEST authentication. The upstream of the master is recommended. (or use BASIC authentication)

    "},{"location":"adauthentication.html#applying-http-authentication-for-built-in-ota","title":"Applying HTTP authentication for Built-in OTA","text":"

    AutoConnectConfig::auth setting also affects the built-in OTA feature. AC_AUTH_BASIC or AC_AUTH_DIGEST setting allows Built-in OTA to authenticate with the UPDATE page. This setting is valid even if AutoConnectConfig::authScope is AC_AUTHSCOPE_PARTIAL. That is if the AutoConnectConfig::auth setting is BASIC or DIGEST, authentication will be required for Built-in OTA. See also Authentication with AutoconnectOTA.

    "},{"location":"adauthentication.html#authentication-within-the-captive-portal-state","title":"Authentication within the captive portal state","text":"

    When accessing the ESP module from an iOS or Android device in the captive portal state, the HTTP authentication framework is disabled in the OS of the client device. Even if the ESP module responds with a 401 unauthorized with WWW-Authenticate, those client device OSs under the captive portal do not display the login dialog and deprive the user of the opportunity to enter their credentials. There will always be an unauthorized error.

    AutoConnect's authentication operation based on HTTP (not HTTPS) depends on the OS of the client device, so in the captive portal state, most devices will unconditionally result in an authentication error. Therefore, the default authentication behavior of AutoConnect does not apply authentication in the captive portal state. (It will be ignored even if the AutoConnect setting is not AC_AUTH_NONE)

    However, if you want to deny unauthorized access to the protected page even in the captive portal state, you can use the extension bit of AutoConnectConfig::authScope. The AC_AUTHSCOPE_WITHCP flag allows AutoConnect to authentication in the captive portal state. It is set using a logical OR operator for the AutoConnectConfig::authScope setting and AutoConnect will enable authentication at the captive portal if the AC_AUTHSCOPE_WITHCP is ON.

    AutoConnectConfig config;\n...\nconfig.auth = AC_AUTH_DIGEST;\nconfig.authScope = AC_AUTHSCOPE_AUX | AC_AUTHSCOPE_WITHCP;\n...\n

    1. ESP32 Arduino core has the authenticate method provided by the WebServer library, similar to that of the ESP8266.\u00a0\u21a9

    2. The default user name and password for authentication inherits the setting of AutoConnectConfig::apid and AutoConnectConfig::psk.\u00a0\u21a9

    "},{"location":"adconnection.html","title":"AutoConnect WiFi connection control","text":"

    AutoConnect aims to connect the ESP module as a station to a WiFi access point and equips with various APIs to maintain a WiFi connection as possible while sketch running. The main APIs are AutoConnect::begin and AutoConnect::handleClient. You can make sketches with flexible WiFi connection capability by properly using these two APIs and the settings by AutoConnectConfig.

    • Automatic reconnect
    • Automatic reconnect (Background)
    • Configure WiFi channel
    • Connects depending on the WiFi signal strength
    • Detects connection establishment to AP
    • Match with known access points by SSID
    • Preserve AP mode
    • Timeout settings for a connection attempt
    • Verify the WiFi connection conditions
    "},{"location":"adconnection.html#automatic-reconnect","title":"Automatic reconnect","text":"

    AutoConnect will change the WiFi mode depending on the situation. The AutoConnect::begin function starts the Web Server with WIFI_STA mode when the connection is successful with 1st-WiFi.begin. If the connection with the last access point fails, AutoConnect will switch the WiFi mode to WIFI_AP_STA, launching a DNS server and allowing the ESP module to launch the captive portal.

    The captive portal launches SoftAP at its start and disconnects the STA. At this time, the ESP module discards its stored station configuration data (known as the SDK's station_config structure). This is the default behavior of AutoConnect.

    On the other hand, AutoConnect can connect to an access point again that has disconnected once, and its control is allowed by AutoConnectConfig::autoReconnect that option specifies to attempt to reconnect to the past established access point using the saved credentials. If the autoReconnect is enabled, AutoConnect will not launch SoftAP immediately even if 1st-WiFi.begin fails. When AutoConnect fails WiFi connection, it will scan the WiFi signal and try to find the access point that the ESP module has connected to in the past. If AutoConnect finds one of the saved credentials from the broadcast with BSSID, it will explicitly apply the matching credential and attempt to reconnect while in WIFI_STA mode. (AutoReconnect works well even with hidden SSID access points)

    AutoConnect       Portal;\nAutoConnectConfig Config;\nConfig.autoReconnect = true;\nPortal.config(Config);\nPortal.begin();\n

    The autoReconnect option is only available for AutoConnect::begin without SSID and PASSWORD parameter. If you use AutoConnect::begin with an SSID and PASSWORD, no reconnection attempt will be made if the 1st-WiFi.begin fails to connect to that SSID.

    The autoReconnect is not autoreconnect

    The WiFiSTAClass::disconnect 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 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 the arduino-esp32 core. AutoConnect's automatic reconnection is a mechanism independent from the automatic reconnection of the arduino-esp32 core.

    "},{"location":"adconnection.html#automatic-reconnect-background","title":"Automatic reconnect (Background)","text":"

    Combining autoReconnect with AutoConnectConfig::reconnectInterval allows you to periodically repeat connection attempts to known access points within AutoConnect::handleClient. This process is pseudo-asynchronous and does not block the Sketch process in the loop() function.

    The reconnectInterval specifies the interval time to seek for known access points with saved credentials during the handleClient loop and attempt to connect to the AP.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  Config.autoReconnect = true;    // Attempt automatic reconnection.\n  Config.reconnectInterval = 6;   // Seek interval time is 180[s].\n  Portal.config(Config);\n  Portal.begin();\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n// Here to do when WiFi is connected.\n  }\nelse {\n// Here to do when WiFi is not connected.\n  }\n\n  Portal.handleClient();\n}\n

    Above Sketch shows a configuration example that you want to keep connecting to known access points as long as possible. When the WiFi connection is lost, it will start seeking the WiFi network every 30 seconds during the handleClient loop.

    Limitation for automatic reconnection to a specific access point

    An access point that ESP module to reconnect automatically depends on whether the SSID and password argument existence with AutoConnect::begin. If the Sketch calls AutoConnect::begin without specifying an SSID or password, the autoReconnect will connect to one of the detected access points and cannot be pre-determined. The other one, the case of the Sketch specifies SSID and password with AutoConnect::begin, the autoReconnect will try to reconnect to a specified access point periodically during the handleClient loop.

    Also, you can combine the background automatic reconnect performing inside the loop function by handleClient with AutoConnectConfig::retainPortal and AutoConnectConfig::autoReset, to enable pop up the captive portal automatically on the client device each time the ESP module disconnects from the access point.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  Config.autoReset = false;     // Not reset the module even by intentional disconnection using AutoConnect menu.\n  Config.autoReconnect = true;  // Reconnect to known access points.\n  Config.reconnectInterval = 6; // Reconnection attempting interval is 3[min].\n  Config.retainPortal = true;   // Keep the captive portal open.\n  Portal.config(Config);\n  Portal.begin();\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n// Here to do when WiFi is connected.\n  }\nelse {\n// Here to do when WiFi is not connected.\n  }\n}\n

    The effective range of the reconnectInterval depending on the setting value

    The range of values that reconnectInterval can take is 0 to 255. (Actual seconds are from 0 to 255\u00d7AUTOCONNECT_UNITTIME) Reconnect behavior depends on the setting value. If it is 0, reconnection will work if the 1st-WiFi.begin in AutoConnect::begin fails and will suspend during the handleClient loop. If reconnectInterval is greater than 0, AutoConnect will attempt to reconnect both in AutoConnect::begin and during the handleClient loop.

    "},{"location":"adconnection.html#configure-wifi-channel","title":"Configure WiFi channel","text":"

    Appropriately specifying the WiFi channel to use for ESP8266 and ESP32 is essential for a stable connection with the access point. AutoConnect remembers the WiFi channel with a credential of the access point once connected and reuses it.

    The default channel when a captive portal starts and AutoConnect itself becomes an access point is the AutoConnectConfig::channel member. If this channel is different from the channel of the access point you will attempt to connect, WiFi.begin may fail. The cause is that the ESP module shares the same channel in AP mode and STA mode. If the connection attempt is not stable, specifying a proper channel using AutoConnectConfig::channel may result in a stable connection.

    "},{"location":"adconnection.html#connects-depending-on-the-wifi-signal-strength","title":"Connects depending on the WiFi signal strength","text":"

    When the ESP module found the multiple available access points (i.e. AutoConnect has connected in the past), the default behavior AutoConnect will attempt to connect to the least recent one. However, If the ESP module can operate properly with any access point, it is advantageous to establish a connection with the best one of the reception sensitivity.

    The AutoConnectConfig::principle parameter has the connection disposition, and specifying AC_PRINCIPLE_RSSI will attempt to connect to one of the highest RSSI value among multiple available access points. Also You can expect stable WiFi connection by specifying the lower limit of signal strength using AutoConnectConfig::minRSSI. Combining these two parameters allows you to filter the destination AP when multiple available access points are found.

    AutoConnectConfig::principle affects the behavior of both 1st-WiFi.begin and autoReconnect. If you specify AC_PRINCIPLE_RECENT for the principle, it will try according to the conventional connection rules, but if you specify AC_PRINCIPLE_RSSI, it will try to connect to the access point that is sending the strongest WiFi signal at that time instead of the last accessed AP. Also, the static IPs will be restored from a saved credential instead of AutoConnectConfig. (The values specified by AutoConnectConfig is ignored)

    SSID &Password AutoConnectConfig::principle Which credentials would be selected Static IPs AutoConnect::begin NULL specified AC_PRINCIPLE_RECENT Nothing, depends on SDK saves Use the specified value of AutoConnectConfig AC_PRINCIPLE_RSSI Auto-selected credentials with max RSSI Restoring static IPs suitable for the SSID from saved credentials Specified with the Sketch Not effective By AutoConnect::begin parameters Use the specified value of AutoConnectConfig AutoReconnect Load fromsaved credential AC_PRINCIPLE_RECENT Recently saved SSID would be chosen Restoring static IPs suitable for the SSID from saved credentials AC_PRINCIPLE_RSSI Auto-selected credentials with max RSSI

    In ESP32, the difference between the AutoConnectConfig::principle and WIFI_ALL_CHANNEL_SCAN in WiFi.begin

    In ESP32, if there are multiple access points with the same SSID and PW within reach, WiFi.begin with the SSID and PW explicitly specified will scan all radio channels and connect to the AP which has the highest signal strength. This feature has been enabled since ESP32 Arduino Release 1.0.6. The principle setting is slightly different from this feature. AutoConnect does not specify the SSID and PW in the 1st-WiFi.begin. It leaves that to the contents stored in the SDK. Even if there is an AP with a stronger signal nearby, it will try to connect to an AP with a smaller channel number. However, in the case where autoReconnect setting will attempt to reconnect, AutoConnect will read the SSID and PW from the saved credentials and explicitly pass them to WiFi.begin. Therefore, in this case, the connection will be made to the AP with the highest signal strength by WIFI_ALL_CHANNEL_SCAN. But it is only valid across multiple APs with the same SSID and PW. On the other hand, AC_PRINCIPLE_RSSI tries to connect the AP with the strongest signal from the connection candidates after selecting the SSID when multiple APs with different SSIDs are mixed in the reachable range.

    "},{"location":"adconnection.html#detects-connection-establishment-to-ap","title":"Detects connection establishment to AP","text":"

    The Sketch can detect that the ESP module has established a WiFi connection as a station to the access point. The AutoConnect::begin or AutoConnect::handleClient will transit the control temporarily to the function in the Sketch registered by AutoConnect::onConnect when the ESP module establish a WiFi connection. The ConnectExit function registered with AutoConnect::onConnect should have the following types and arguments:

    void ConnectExit(IPAddress& ip)\n

    The ConnectExit function is of type void. The argument ip is the IP address assigned to the ESP module by the connected AP. AutoConnect::onConnect allows the Sketch registers a ConnectExit function to AutoConnect. Also, you can make the function using a lambda expression.

    AutoConnect Portal;\n\nvoid onConnect(IPAddress& ipaddr) {\n  Serial.print(\"WiFi connected with \");\n  Serial.print(WiFi.SSID());\n  Serial.print(\", IP:\");\n  Serial.println(ipaddr.toString());\n}\nvoid setup() {\n  Serial.begin(115200);\n  Portal.onConnect(onConnect);  // Register the ConnectExit function\n  Portal.begin();\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    In addition, a sketch that shuts down SoftAP when the ESP module connects to the access point can be described using a lambda expression as follows:

    AutoConnect Portal;\n\nvoid setup() {\n  Serial.begin(115200);\n  Portal.onConnect([](IPAddress& ipaddr){\n    Serial.printf(\"WiiFi connected with %s, IP:%s\\n\", WiFi.SSID().c_str(), ipaddr.toString().c_str());\nif (WiFi.getMode() & WIFI_AP) {\n      WiFi.softAPdisconnect(true);\n      WiFi.enableAP(false);\n      Serial.printf(\"SoftAP:%s shut down\\n\", WiFi.softAPSSID().c_str());\n    }\n  });\n  Portal.begin();\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    It is not an event

    AutoConnect::onConnect has the same effect on the Sketch as the WiFi.onStationModeConnected, but AutoConnect does not use the event. Sketch can use WiFi.onEvent independently of AutoConnect.

    "},{"location":"adconnection.html#match-with-known-access-points-by-ssid","title":"Match with known access points by SSID","text":"

    By default, AutoConnect uses the BSSID to search for known access points. (Usually, it's the MAC address of the device) By using BSSID as the key to finding the WiFi network, AutoConnect can find even if the access point is hidden. However BSSIDs can change on some mobile hotspots, the BSSID-keyed searches may not be able to find known access points. If you operate inconvenience in aiming at the access point by BSSID, you can change the collation key from BSSID to SSID by uncommenting AUTOCONNECT_APKEY_SSID macro definition in AutoConnectDefs.h library source code.

    #define AUTOCONNECT_APKEY_SSID\n

    Allow you to use PlatformIO as a build system and give the following description to the platformio.ini, you can enable AUTOCONNECT_APKEY_SSID each build without modifying the library source code:

    build_flags=-DAUTOCONNECT_APKEY_SSID\n

    Can't be found hidden APs in SSID-keyed

    The hidden access point's SSID will be blank on the broadcast. So if the seek key is an SSID, AutoConnect will not find it.

    "},{"location":"adconnection.html#preserve-ap-mode","title":"Preserve AP mode","text":"

    Sketch using AutoConnect can open a gateway to the Internet by connecting to a WiFi router even through use Espressif's peculiar WiFi protocol (e.g. ESP-MESH or ESP-NOW). These specific communication protocols require to keeps AP + STA as the WiFi mode. That is, to apply these protocols, it needs to launch SoftAP by a sketch itself and then call AutoConnect::begin. But the default behavior of AutoConnect::begin will turn off SoftAP always then it will unable to open a connection.

    AutoConnectConfig::preserveAPMode setting maintains WIFI_AP mode without disabling SoftAP inside AutoConnect::begin. The Sketch can utilize the WiFi connection via AutoConnect with ESP-MESH and ESP-NOW protocol by enabling this option.

    The following diagram quoted from the ESP-MESH documentation that illustrates the typical topology of the MESH network. The module located at the Root Node bridges between the mesh network and the router by an application that handles two protocols, TCP/IP and ESP-MESH. Its SoftAP communicates with the internal mesh network as an interface of the mesh layer. On the other hand, STA performs station communication with the WiFi router as an interface of the TCP/IP layer. AutoConnect allows assists the connection between the router and the STA of the Root Node using AutoConnectConfig::preserveAPMode and starting the SoftAP via Sketch separately.

    Also in general, the Sketch should set false to AutoConnectConfig::autoRise, true to AutoConnectConfig::immediateStart when applying to those protocols.

    "},{"location":"adconnection.html#timeout-settings-for-a-connection-attempt","title":"Timeout settings for a connection attempt","text":"

    AutoConnect uses AutoConnectConfig::beginTimeout value to limit time to attempt when connecting the ESP module to the access point as a WiFi station. The default value is AUTOCONNECT_TIMEOUT defined in AutoConnectDefs.h and the initial value is 30 seconds. (actually specified in milliseconds) For example, the following sketch sets the connection timeout to 15 seconds:

    AutoConnect Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  Config.beginTimeout = 15000; // Timeout sets to 15[s]\n  Portal.config(Config);\n  Portal.begin();\n}\n\nvoid loop () {\n  Portal.handleClient();\n}\n

    In addition, the limit of the waiting time for connection attempts can be specified by the AutoConnect::begin parameter too. The timeout parameter specified in AutoConnect::begin takes precedence over AutoConnectConfig::beginTimeout.

    The beginTimeout has an effect on handleClient

    The beginTimeout value will be applied with handleClient when requesting a connection from the captive portal and when attempting to reconnect with autoReconnect.

    "},{"location":"adconnection.html#verify-the-wifi-connection-conditions","title":"Verify the WiFi connection conditions","text":"

    AutoConnect has the following indicators regarding WiFi connection attempts. These states are indicated as bitwise values and are the logical disjunction of multiple states. For example, if the 1st-WiFi.begin fails and the connection is restored by the AutoConnectConfig::autoReconnect setting, this status value will indicate both AC_AUTORECONNECT and AC_ESTABLISHED.

    A sketch can get this status value using the AutoConnect::portalStatus function. AutoConnect::portalStatus returns a value of type uint8_t. The return value is a bitwise value that indicates each status in the table below. In the sketch, the WiFi connection status is detected by taking the AND of the return value and the enum value shown in the following table:

    Values of the status indication WiFi connection situations AutoConnect::AC_IDLE Initial state: This is the initial state, AutoConnect is not making any WiFi connection attempts. This state is reached immediately after AutoConnect::begin starts. AutoConnect::AC_ESTABLISHED Connection successful: Successfully connected to the WiFi access point. AutoConnect::AC_AUTORECONNECT The autoReconnect was applied: AutoConnectConfig::autoReconnect setting was applied during the WiFi connection attempt process. This flag does not indicate a successful connection. It only shows that a condition that triggers autoReconnect has occurred. Whether the connection was actually successful should be determined by WiFi.status()==WL_CONNECTED. AutoConnect::AC_TIMEOUT Connection timeout: WiFi connection attempt timed out. Or, the captive portal was shut down by the AutoConnectConfig::portalTimeout setting. AutoConnect::AC_INTERRUPT Connection interrupted due to an indication with the exit: The whileConnecting exit routine returned false. or the whileCaptivePortal exit routine returned false. AutoConnect aborted the WiFi connection attempt with those indications. AutoConnect::AC_CAPTIVEPORTAL Captive portal is available: SoftAP mode is enabled, and the DNS server is available. AutoConnect will redirect connection requests to SoftAP from client devices to a captive portal site within AutoConnect. The state of this flag is equivalent to the return value of AutoConnect::isPortalAvailable function.NOTE: AC_CAPTIVEPORTAL is false if only SoftAP is available and no DNS server is enabled. AutoConnect::AC_INPROGRESS WiFi.begin in progress: AutoConnect requests WiFi.begin and is waiting for the connection to succeed or times out; this state will reset when terminating WiFi.begin attempts. 
    AutoConnect portal;\nAutoConnectConfig config;\n\nuint8_t state;\n\nvoid setup() {\n// Configure automatic reconnection and captive portal retention, then start\n// AutoConnect. In subsequent steps, it will use the portalStatus function to\n// detect the WiFi connection status in this configuration.\n  config.portalTimeout = 180000;\n  config.autoReconnect = true;\n  config.reconnectInterval = 1;\n  config.retainPortal = true;\n  portal.config(config);\n\n  portal.begin();\n\n  state = portal.portalStatus();\nif (WiFi.status() == WL_CONNECTED) {\nif (state & AutoConnect::AC_AUTORECONNECT)\n      Serial.println(\"Auto reconnection applied\");\n  }\nelse {\nif (state & AutoConnect::AC_TIMEOUT)\n      Serial.println(\"Connection timeout\");\n  }\n\nif (state & AutoConnect::AC_CAPTIVEPORTAL)\n    Serial.println(\"Captive portal is still alive\");\nelse\n    Serial.println(\"Captive portal is not available\");\n}\n\nvoid loop() {\n  portal.handleClient();\nuint8_t transition = portal.portalStatus();\n\nif (transition != state) {\nif (transition & AutoConnect::AC_CAPTIVEPORTAL)\n      Serial.println(\"Captive portal activated\");\nif (transition & AutoConnect::AC_AUTORECONNECT)\n      Serial.println(\"Auto reconnection applied\");\nif (!(transition & AutoConnect::AC_ESTABLISHED))\n      Serial.println(\"WiFi connection lost\");\n\n    state = transition;\n  }\n}\n

    AutoConnect::portalStatus within the loop of AutoConnect::handleClient

    AutoConnect::portalStatus function is also valid during the AutoConnect::handleClient loop inside the loop function. With the background reconnection enabled using the AutoConnectConfig::autoReconnect and AutoConnectConfig::reconnectInterval settings, the AutoConnect::portalStatus function will return a value indicating the reconnection status at every time AutoConnect::handleClient in the loop().

    "},{"location":"adcpcontrol.html","title":"Captive portal control","text":"

    The default behavior of AutoConnect is to launch the captive portal if 1st-WiFi.begin attempting inside AutoConnect::begin fails. You can change this default behavior through the AutoConnectConfig settings join together with Sketch code that implements to control the WiFi connection attempting.

    • Captive portal start control
    • Captive portal start detection
    • Captive portal state identification
    • Captive portal timeout control
    • Disable the captive portal
    • Launch the captive portal on demand by external trigger
    • Launch the captive portal on-demand at losing WiFi
    • Shutdown the captive portal
    • Sketch execution during the captive portal loop
    "},{"location":"adcpcontrol.html#captive-portal-start-control","title":"Captive portal start control","text":"

    AutoConnect will launch the captive portal based on the AutoConnectConfig settings when the WiFi connection status will become to certain conditions. AutoConnectConfig::autoRise and AutoConnectConfig::immediateStart are concern the conditions to launch the captive portal. Also, the AutoConnectConfig::retainPortal controls the continuity of the captive portal state and allows the Sketch to launch the captive portal dynamically even while in a handleClient loop.

    The autoRise allows or disallows the launch of the captive portal. AutoConnect launches the captive portal only if the autoRise is true. If the autoRise is false, the captive portal will not start even if the WiFi connection is lost.

    Basically, the captive portal initiation is triggered by the result of 1st-WiFi.begin, but Sketch can control it according to direct the following four actions by configuring AutoConnectConfig with two parameters, the immediateStart and the autoRise.

    AutoConnectConfig::immediateStart AutoConnectConfig::autoRise true false true Skip *1st-WiFi.begin*ESP module becomes SoftAP and the captive portal starts immediately. Not attempt WiFi connection.Only WebServer will start in STA mode. false Attempts WiFi connection in STA mode.In some cases, the autoReconnect may restore the connection even if 1st-WiFiBeing fails.If the connection is completely lost, the captive portal will be launched.This is the default. Attempts WiFi connection in STA mode.In some cases, the autoReconnect may restore the connection even if 1st-WiFiBeing fails.ESP module stays in STA mode and WebServer will start.

    The retainPortal specifies the continuity of the captive portal after AutoConnect::begin, allowing the captive portal would be launched after the Sketch execution has transitioned into the loop function. When AutoConnect establishes a WiFi connection while in the captive portal within AutoConnect::begin, it stops the DNS server to close the captive portal with SoftAP still running. In this situation, if the Sketch loses the established WiFi connection while executing the loop function, it can reopen the captive portal.

    However, this behavior can be redundant depending on the Sketch characteristics. In such a case, you can prevent to starting the captive portal during the loop() by autoRise setting to false.

    "},{"location":"adcpcontrol.html#captive-portal-start-detection","title":"Captive portal start detection","text":"

    The captive portal will only be activated if 1st-WiFi::begin fails. Sketch can detect with the AutoConnect::onDetect function that the captive portal has started. For example, the Sketch can be written like as follows that turns on the LED at the start captive portal.

    AutoConnect Portal;\n\nbool startCP(IPAddress& ip) {\n  digitalWrite(BUILTIN_LED, HIGH);\n  Serial.println(\"C.P. started, IP:\" + ip.toString());\nreturn true;\n}\n\nvoid setup() {\n  Serial.begin(115200);\n  pinMode(BUILTIN_LED, OUTPUT);\n  digitalWrite(BUILTIN_LED, LOW);\n  Portal.onDetect(startCP);\nif (Portal.begin()) {\n    digitalWrite(BUILTIN_LED, LOW);\n  }\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n
    "},{"location":"adcpcontrol.html#captive-portal-state-identification","title":"Captive portal state identification","text":"

    You can use the AutoConnect::isPortalAvailable function to identify if AutoConnect is in a captive portal state.

    Captive-Portal - i.e., just a spoofed response to a DNS lookup for Internet connection verification that occurs on a new connection attempt from the client device; it needs a DNS server and SoftAP to work. AutoConnect implements it with HTTP redirection. The AutoConnect::isPortalAvailable function returns true if all of the following conditions are met.

    • ESP module is in WIFI_AP mode and enable SoftAP.
    • IP address assigned to SoftAP is the equivalent of AutoConnectConfig::apip.
    • AutoConnect is running a DNS server for directing to the captive portal. Through its action, DNS lookups issued by client devices for Internet transparency validation are directed to the ESP module SoftAP.

    A similar utility is AutoConnect::portalStatus

    See Verify the WiFi connection conditions and AutoConnect::portalStatus function.

    "},{"location":"adcpcontrol.html#captive-portal-timeout-control","title":"Captive portal timeout control","text":"

    Once AutoConnect has entered the captive portal state due to the above conditions, the default behavior is that AutoConnect::begin will not exit until a WiFi connection is established. Captive portal timeout control prevents AutoConnect from blocking the Sketch progress. It allows Sketch to abort AutoConnect::begin and returns control to Sketch.

    AutoConnect has two parameters for timeout control. The first is the timeout value used when trying to connect to the specified AP. It works like a typical timeout control for connection attempts with WiFi.begin. This setting is specified by the AutoConnectConfig::beginTimeout or third argument of the AutoConnect::begin function. The default value is the macro defined by AUTOCONNECT_TIMEOUT in the AutoConnectDefs.h header file.

    Another timeout control is for the captive portal itself. It is useful if you want to keep the Sketch offline running even if a WiFi connection is not possible. You can also combine its setting with the immediateStart option to create highly mobile sketches. The timeout of the captive portal is specified by the AutoConnectConfig::portalTimeout as follows.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect  portal;\nAutoConnectConfig  config;\n\nvoid setup() {\n  config.portalTimeout = 60000;  // It will time out in 60 seconds\n  portal.config(config);\n  portal.begin();\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n// Some sketch code for the connected scene is here.\n  }\nelse {\n// Some sketch code for not connected scene is here.\n  }\n  portal.handleClient();\n}\n

    Also, if you want to stop AutoConnect completely when the captive portal is timed out, you need to call the AutoConnect::end function. It looks like the following code:

    bool acEnable;\n\nvoid setup() {\n  config.portalTimeout = 60000;  // It will time out in 60 seconds\n  portal.config(config);\n  acEnable = portal.begin();\nif (!acEnable) {\n    portal.end();\n  }\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n// Some sketch code for the connected scene is here.\n  }\nelse {\n// Some sketch code for not connected scene is here.\n  }\nif (acEnable) {\n    portal.handleClient();\n  }\n}\n

    AutoConnectConfig has another option related to timeouts that you can enable to take advantage of the captive portal feature after a timeout occurrence. The AutoConnectConfig::retainPortal option will not shut down SoftAP and the internal DNS server even though AutoConnect::begin has aborted due to a timeout occurrence. Even after the captive portal times out, you can always try to connect to the AP while keeping the Sketch running offline.

    The following sample code is the Sketch above with the retainPortal setting added. As you can see, the implementation for captive portal continuation does not affect the main logic of the Sketch.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect  portal;\nAutoConnectConfig  config;\n\nvoid setup() {\n  config.portalTimeout = 60000;  // It will time out in 60 seconds\n  config.retainPortal = true;\n  portal.config(config);\n  portal.begin();\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n// Some sketch code for the connected scene is here.\n  }\nelse {\n// Some sketch code for not connected scene is here.\n  }\n  portal.handleClient();\n}\n
    "},{"location":"adcpcontrol.html#disable-the-captive-portal","title":"Disable the captive portal","text":"

    It can also prevent the captive portal from starting even if the connection at the 1st-WiFi.begin fails. In this case, AutoConnect::begin behaves same as WiFi.begin.

    For disabling the captive portal, autoRise sets to false with AutoConnectConfig.

    AutoConnect       portal;\nAutoConnectConfig acConfig;\n\nacConfig.autoRise = false;\nportal.config(acConfig);\nportal.begin();\n
    "},{"location":"adcpcontrol.html#launch-the-captive-portal-on-demand-by-external-trigger","title":"Launch the captive portal on demand by external trigger","text":"

    The default behavior of AutoConnect::begin gives priority to connect to the least recently established access point. In general, We expect this behavior in most situations, but will intentionally launch the captive portal on some occasion.

    Here section describes how to launch on demand the captive portal, and suggests two templates that you can use to implement it.

    1. Offline for usual operation, connect to WiFi with an external switch

      You can use this template if the ESP module does not connect to WiFi at an ordinal situation and need to establish by a manual trigger. In this case, it is desirable that AutoConnect not start until an external switch fires. This behavior is similar to the WiFiManager's startConfigPortal function. AutoConnectConfig::immediateStart is an option to launch the portal by the SoftAP immediately without attempting 1st-WiFi.begin. Also, by setting the AutoConnectConfig::autoRise option to false, it is possible to suppress unintended automatic pop-ups of the portal screen when connecting to an ESP module SSID. To implement this, execute AutoConnect::config within the setup() function as usual, and handle AutoConnect::begin inside the loop() function.

      #define TRIGGER_PIN 5     // Trigger switch should be LOW active.\n#define HOLD_TIMER  3000\n\nAutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  pinMode(5, INPUT_PULLUP);\n  Config.immediateStart = true;\n// Config.autoRise = false;   // If you don't need to automatically pop-up the portal when connected to the ESP module's SSID.\n  Portal.config(Config);\n}\n\nvoid loop() {\nif (digitalRead(TRIGGER_PIN) == LOW) {\nunsigned long tm = millis();\nwhile (digitalRead(TRIGGER_PIN) == LOW) {\n      yield();\n    }\n// Hold the switch while HOLD_TIMER time to start connect.\nif (millis() - tm > HOLD_TIMER)\n      Portal.begin();\n  }\n\nif (WiFi.status() == WL_CONNECTED) {\n// Here, what to do if the module has connected to a WiFi access point\n  }\n\n// Main process of your sketch\n\n  Portal.handleClient();  // If WiFi is not connected, handleClient will do nothing.\n}\n

      It will not be automatic reconnect

      The above example does not connect to WiFi until TRIGGER_PIN goes LOW. When TRIGGER_PIN goes LOW, the captive portal starts and you can connect to WiFi. Even if you reset the module, it will not automatically reconnect.

    2. Register new access points on demand

      The following template is useful for controlling the registration of unknown access points. In this case, the ESP module establishes a WiFi connection using WiFi.begin natively without relying on AutoConnect. Known access point credentials are saved by AutoConnect, to the ESP module can use the saved credentials to handle WiFi.begin natively. This means that you can explicitly register available access points when needed, and the ESP module will not use unknown access points under normal situations.

      AutoConnect* portal = nullptr;\n\nbool detectSwitch() {\n/*\n  Returns true if an external switch to configure is active.\n  */\n}\n\nbool connectWiFi(const char* ssid, const char* password, unsigned long timeout) {\n  WiFi.mode(WIFI_STA);\n  delay(100);\n  WiFi.begin(ssid, password);\nunsigned long tm = millis();\nwhile (WiFi.status() != WL_CONNECTED) {\nif (millis() - tm > timeout)\nreturn false;\n  }\nreturn true;\n}\n\nvoid setup() {\n  AutoConnectCredential credt;\n  station_config_t  config;\nfor (int8_t e = 0; e < credt.entries(); e++) {\n    credt.load(e, &config);\nif (connectWiFi(config.ssid, config.password, 30000))\nbreak;\n  }\nif (WiFi.status() != WL_CONNECTED) {\n// Here, do something when WiFi cannot reach.\n  }\n}\n\nvoid loop() {\nif (detectSwitch()) {\n    AutoConnectConfig config;\n    config.immediateStart= true;\nif (!portal) {\n      portal = new AutoConnect;\n    }\n    portal->config(config);\nif (portal->begin()) {\n      portal->end();\ndelete portal;\n      portal = nullptr;\n    }\n  }\n// Here, ordinary sketch logic.\n}\n
    "},{"location":"adcpcontrol.html#launch-the-captive-portal-on-demand-at-losing-wifi","title":"Launch the captive portal on-demand at losing WiFi","text":"

    If the ESP module loses the established WiFi connection during the loop of handleClient, you can prevent the ESP module from going absolutely standalone by launching the captive portal on demand.

    When retainPortal and autoRise settings are enabled, AutoConnect will launch SoftAP and start DNS when it detects a WiFi disconnect with the router during a handleClient loop. This behavior will occur caused by a WiFi disconnect detection even if the WiFi mode is STA.

    Since AutoConnect v1.2.0, An improved retainPortal option allows the captive portal to be restarted during a handleClient loop even if it is closed once in AutoConnect::begin. In this case, the Sketch execution stage has already transitioned into the loop function, so the Sketch process seems running concurrently with the captive portal loop. Its captive portal launched from inside handleClient does not block the execution of the Sketch, unlike that launched from AutoConnect::begin.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  Config.autoRise = true; // It's the default, no setting is needed explicitly.\n  Config.retainPortal = true;\n  Portal.config(Config);\n  Portal.begin();\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    Need autoRise enabled

    Need AutoConnectConfig::autoRise setting enabled to start the captive portal on demand during a handleClient loop.

    Although the Sketch above specifies the retainPortal, it does not instruct starts the captive portal always. AutoConnect will try WiFi.begin once in AutoConnect::begin unless the immediateStart option is specified. If AutoConnect fails the 1st-WiFi.begin, the captive portal will be launched at that point and the Sketch execution will stay within the AutoConnect::begin function.

    There is also a way to avoid starting the captive portal inside AutoConnect::begin and start the captive portal according to the WiFi connection status after the Sketch execution transitions to a handleClient loop. Adjusting the timing of autoRise activation will allow the captive portal to start only from inside AutoConnect::handleClient function.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n  Config.retainPortal = true;\n  Config.autoRise = false;  // Suppresses the launch of the captive portal from AutoConnect::begin.\n  Portal.config(Config);    // Don't forget it.\n  Portal.begin();\n  Config.autoRise = true;   // Enable the launch of the captive portal.\n  Portal.config(Config);    // Don't forget it.\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    The retainPortal option will keep SoftAP even if WiFi has established a connection as a client with the router. Since it has the effect of stopping the DNS server, the phenomenon that the portal screen will not pop up automatically even though SoftAP is in action occur. This is a legacy behavior to ensure backward compatibility with up to AutoConnect v1.1.7. To stop SoftAP on escape from the on-demand captive portal, you need to explicitly call WiFi.softAPdisconnect(true) and WiFi.enableAP(false) in the Sketch.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nbool  Connected;\nunsigned long Elapsed;\n\nvoid onConnect(IPAddress& clientIP) {\n  Connected = true;\n  Elapsed = millis();\n}\n\nvoid setup() {\n  Config.retainPortal = true;\n  Portal.config(Config);\n  Portal.onConnect(onConnect);\n  Portal.begin();\n}\n\nvoid loop() {\nif (WiFi.status() != WL_CONNECTED) {\n    connected = false;\n    Elapsed = millis();\n  }\n\nif ((WiFi.getMode() & WIFI_AP) && Connected) {\nif (millis() - Elapsed > 30000) {\n      WiFi.softAPdisconnect(true);\n      WiFi.enableAP(false);\n    }\n  }\n// Actual sketch process is here.\n\n  Portal.handleClient();\n}\n

    The above sketch will shutdown the SoftAP after elapsed time exceeds 30 seconds since the connection was re-established. Its logic is a bit tricky and does not stop SoftAP immediately after the connection established, which has several seconds delay. Doing it ensures that AutoConnect can send the HTML response.

    Stopped SoftAP is still displayed

    After SoftAP stopped, there is a time lag before it disappears from the detected access points list on the client device.

    "},{"location":"adcpcontrol.html#shutdown-the-captive-portal","title":"Shutdown the captive portal","text":"

    There is some complexity in the conditions under which AutoConnect shuts down the captive portal. Making a sketch that activates SoftAP only when needed can seem tedious. But there is a reason why. Even if AutoConnect could establish a connection using a captive portal, your cell phone as a client device would still have to keep connected to the ESP module-generated SoftAP in order to send the page for notifying the connection successful to a user. At that point, your client device that opened the captive portal still needs a connection with SoftAP.

    What happens, after all, is as follows:

    1. You made a connection to the access point such as WiFi router using the captive portal and took a successful page.
    2. Your sketch will rush into the loop function and starts to works well, hooray!
    3. Oops. Don't celebrate yet. I can see SoftAP ID on my cell phone. But the AutoConnect page never pops up automatically. Why?

    Because, for the above reasons, we can not promptly shut down the SoftAP. (However, DNS will stop)

    So, If you want to stop SoftAP after connecting to the access point using the captive portal, you need to implement the shutdown process with Sketch explicitly. A template of the basic sketch that can stop the SoftAP after the connection is the following:

    AutoConnect Portal;\n\nvoid setup() {\nif (Portal.begin()) {\nif (WiFi.getMode() & WIFI_AP) {\n      WiFi.softAPdisconnect(true);\n      WiFi.enableAP(false);\n    }\n  }\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    If you stop SoftAP, the connection will be lost

    If you stop SoftAP immediately after the AutoConnect::begin successful, will part with the connection and cannot see the result notifying on your client device. You can expect to receive result notifications if you run handleClient before stopping SoftAP. (although you may not always succeed; it will not work if the WiFi radio signal is weak)

    "},{"location":"adcpcontrol.html#sketch-execution-during-the-captive-portal-loop","title":"Sketch execution during the captive portal loop","text":"

    With AutoConnect::begin, once the captive portal is started without being able to connect to a known WiFi access point, control will not return to sketch until the WiFi connection is established or times out. This behavior helps to pin the ESP module's network participation as a WiFi client (that is, AutoConnect::begin is an alternative to WiFi.begin) but it can not rush into the loop function of the Sketch. Therefore, while the ESP module is in the captive portal state and waiting for a connection operation to the access point, the behavior of the Sketch will be restrained by the escape conditions from AutoConnect::begin.

    The whileCaptivePortal exit allows the Sketch to continue the process temporarily while the ESP module remains standalone and the captive portal is open. AutConnect::whileCaptivePortal function registers the user's sketch function to be called by AutoConnect::begin or AutoConnect::handleClient during the execution of the captive portal session loop.

    The whileCaptivePortal exit can be registered by following: 

    AutoConnect portal;\n\nbool whileCP(void) {\nbool  rc;\n// Here, something to process while the captive portal is open.\n// To escape from the captive portal loop, this exit function returns false.\n// rc = true;, or rc = false;\nreturn rc;\n}\n\nvoid setup() {\n  ...\n  portal.whileCaptivePortal(whileCP);\n  portal.begin();\n  ...\n}\n

    AutoConnect will open the captive portal in the AutoConnect::begin and AutoConnect::handleClient scenes, but the whileCaptive portal exit will be called repeatedly from AutoConnect::begin until exits from it. The whileCaptivePortal exit will be called repeatedly while the captive portal is open until WiFi connected or times out occurs. In the Sketch, returning a FALSE value from the whileCaptivePortal function allows the control to escape from the captive portal loop even before the session elapsed time exceeds the limits.

    "},{"location":"adcredential.html","title":"Credential accesses","text":"

    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
    "},{"location":"adcredential.html#access-to-saved-credentials","title":"Access to saved credentials","text":"

    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.

    "},{"location":"adcredential.html#autosave-credential","title":"Autosave Credential","text":"

    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;\nAutoConnectConfig Config;\nConfig.autoSave = AC_SAVECREDENTIAL_NEVER;\nPortal.config(Config);\nPortal.begin();\n

    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 corefor ESP8266 Arduino core for ESP32 1.0.2 earlier 1.0.3 later v0.9.12 earlier EEPROM EEPROM (partition) Not supported v1.0.0 later Preferences (nvs)

    (Can be used EEPROM with turning off AUTOCONNECT_USE_PREFERENCES macro)

    Preferences (nvs)"},{"location":"adcredential.html#move-the-saving-area-of-eeprom-for-the-credentials","title":"Move the saving area of EEPROM for the credentials","text":"

    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:

    |--------------|-------|---------------|--|--|--|--|--|\n^              ^       ^               ^     ^\nSketch    OTA update   File system   EEPROM  WiFi config (SDK)\n

    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;\nAutoConnectConfig config;\n\n// Defines the custom data should be stored in EEPROM.\ntypedef struct {\nchar  data1[8];\nchar  data2[8];\nchar  data3[8];\n} EEPROM_CONFIG_t;\nEEPROM_CONFIG_t eepromConfig;\n...\n// Declares to reserve the EEPROM_CONFIG_t area for a Sketch using.\nconfig.boundaryOffset = sizeof(eepromConfig);\nportal.config(config);\n...\nstrcpy(eepromComfig.data1, \"data1\");\nstrcpy(eepromComfig.data2, \"data2\");\nstrcpy(eepromComfig.data3, \"data3\");\n\n// Use getEEPROMUsedSize to access the EEPROM with the appropriate region size.\nEEPROM.begin(portal.getEEPROMUsedSize());\nEEPROM.put<EEPROM_CONFIG_t>(0, eepromConfig);\nEEPROM.commit();\nEEPROM.end();\n...\n
    "},{"location":"adcredential.html#save-and-restore-credentials","title":"Save and restore credentials","text":"

    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>\n#include <LittleFS.h>\n\n...\n\nAutoConnect portal;\n\nvoid setup() {\n  LittleFS.begin(true);\n\nif (portal.begin()) {\n    portal.saveCredential(\"/cred\", LittleFS);\n  }\n}\n
    #include <FS.h>\n#include <LittleFS.h>\n\n...\n\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  LittleFS.begin();\n\n  config.autoReconnect = true;\n  portal.config(config);\n  portal.restoreCredential(\"/cred\", LittleFS);\n  portal.begin();\n}\n

    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>\n#include <SD.h>\n\n...\n\nAutoConnect portal;\n\nvoid setup() {\n  SD.begin();\n\nif (portal.begin()) {\n    portal.saveCredential<SDClass>(\"/cred\", SDFS);   // For ESP8266\n// portal.saveCredential<fs::SDFS>(\"/credentials\", SDFS);  // For ESP32\n  }\n}\n
    #include <SPI.h>\n#include <SD.h>\n\n...\n\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  SD.begin();\n\n  config.autoReconnect = true;\n  portal.config(config);\n  portal.restoreCredential<SDClass>(\"/cred\", SDFS);  // For ESP8266\n// portal.restoreCredential<fs::SDFS>(\"/credentials\", SDFS);  // For ESP32\n\n  portal.begin();\n}\n
    "},{"location":"adexterior.html","title":"Customizing page appearance","text":"

    The design of various AutoConnect web pages is basically inflexible. Its appearance and layout don't have many customizable visual aspects but nevertheless, you can customize the following appearances of your AutoConnect web pages:

    • AutoConnect menu colorize (See Appendix)
    • Make different menu labels
    • Make different menu title
    • Capture the legacy web pages as items into the menu
    "},{"location":"adexterior.html#make-different-menu-labels","title":"Make different menu labels","text":"

    You can change the label text for each menu item but cannot change them at run time. There are two ways to change the label text, both of which require coding the label literal.

    1. Overwrite the label literal of library source code directly.

      You can change the label of the AutoConnect menu item by rewriting the default label literal in AutoConnectLabels.h macros. However, changing menu items literal influences all the Sketch's build scenes.

      #define AUTOCONNECT_MENULABEL_CONFIGNEW   \"Configure new AP\"\n#define AUTOCONNECT_MENULABEL_OPENSSIDS   \"Open SSIDs\"\n#define AUTOCONNECT_MENULABEL_DISCONNECT  \"Disconnect\"\n#define AUTOCONNECT_MENULABEL_RESET       \"Reset...\"\n#define AUTOCONNECT_MENULABEL_UPDATE      \"Update\"\n#define AUTOCONNECT_MENULABEL_HOME        \"HOME\"\n#define AUTOCONNECT_MENULABEL_DEVINFO     \"Device info\"\n#define AUTOCONNECT_BUTTONLABEL_RESET     \"RESET\"\n#define AUTOCONNECT_BUTTONLABEL_UPDATE    \"UPDATE\"\n

      build_flags with PlatformIO will no effect

      The mistake that many people make is to use PlatformIO's build_flags to try to redefine any literal at compile time. The AutoConnect library statically contains the label literals which are embedded as binary data when compiling the library code. The label literals will not change without compiling the library source. And PlatformIO is a build system. Library sources will not be compiled unless AutoConnectLabels.h is updated.

    2. Change the label literals for each Arduino project

      Another way to change the label literal is to provide a header file that defines the label literals, as mentioned in Appendix. You can also use this method to display label text and fixed text in the local language on the AutoConnect page. See Change the item's label text section for details.

    "},{"location":"adexterior.html#make-different-menu-title","title":"Make different menu title","text":"

    Although the default menu title is AutoConnect, you can change the title by setting AutoConnectConfig::title. To set the menu title properly, you must set before calling AutoConnect::begin.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nvoid setup() {\n// Set menu title\n  Config.title = \"FSBrowser\";\n  Portal.config(Config);\n  Portal.begin();\n}\n

    Executing the above sketch will rewrite the menu title for the FSBrowser as the below.

    "},{"location":"adexterior.html#capture-the-legacy-web-pages-as-items-into-the-menu","title":"Capture the legacy web pages as items into the menu","text":"

    You can embed the ordinary page processed by the ESP8266WebServer request handler as an item into the AutoConnect menu. AutoConnect can capture the legacy web pages for ESP8266WebServer or WebServer of ESP32 and extends the menu containing these items. In ordinary, the Sketch registers the request handler for the page depending on URI using the ESP8266WebServer::on function. AutoConnect allows Sketch to bundle the registered legacy page into a menu. the Sketch is able to include its URI to a menu item using AutoConnect::append function that creates internally an AutoConnectAux depended on its URI and integrates into the menu.

    The following code has a mixture of both AutoConnectAux and the legacy web page. An AutoConnectAux page is menued automatically with the AutoConnect::join or AutoConnect::load function. Similarly, a legacy page is integrated by the AutoConnect::append function.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nESP8266WebServer server;\nAutoConnect      portal(server);\n\n// Definitions of AutoConnectAux page\nstatic const char PAGE[] PROGMEM = R\"(\n{\n  \"title\": \"PAGE\",\n  \"uri\": \"/page\",\n  \"menu\": true,\n  \"element\": [\n    {\n      \"name\": \"cap\",\n      \"type\": \"ACText\",\n      \"value\": \"This is a custom web page.\"\n    }\n  ]\n}\n)\";\n\nvoid setup() {\n// The Web page handler located to /hello\n  server.on(\"/hello\", [](){\n    server.send(200, \"text/html\", String(F(\n\"<html>\"\n\"<head><meta name='viewport' content='width=device-width,initial-scale=1.0'></head>\"\n\"<body><h2>Hello, world</h2></body>\"\n\"</html>\"\n    )));\n  });\n\n  portal.append(\"/hello\", \"HELLO\");  // Adds an item as HELLO into the menu\n  portal.load(FPSTR(PAGE));               // Load AutoConnectAux custom web page\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    The AutoConnect::append function also has the third parameter that directly specifies the request handler. It has similar efficacy to calling the append and ESP8266WebSever::on at once. 1

    portal.append(\"/hello\", \"HELLO\", [](){\n  server.send(200, \"text/html\", String(F(\n\"<html>\"\n\"<head><meta name='viewport' content='width=device-width,initial-scale=1.0'></head>\"\n\"<body><h2>Hello, world</h2></body>\"\n\"</html>\"\n  )));\n});\n

    For more details, see section Attach the menus of Examples page.

    An instance of ESP8266WebServer/WebServer is needed

    When calling the append function with request handler parameters, an instance of the WebServer as the registration destination must exist. AutoConnect can instantiate and host a WebServer internally, but in that case, the point in time to call the AutoConnect::append function with a request handler parameter must be after AutoConnect::begin.

    1. However, the pages registered this way remain legacy. Therefore, the AutoConnect menu bar is not appeared.\u00a0\u21a9

    "},{"location":"adnetwork.html","title":"Settings and controls for network and WiFi","text":"

    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
    • Assign user sketch's home path
    • Change SSID and Password for SoftAP
    • Combination with mDNS
    • Make SSID of SoftAP unique
    • Relocate the AutoConnect home path
    • SoftAP access point IP settings
    • Static IP assignment as a client
    • Static IP preservation
    • Station hostname
    "},{"location":"adnetwork.html#404-handler","title":"404 handler","text":"

    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.

    "},{"location":"adnetwork.html#assign-user-sketchs-home-path","title":"Assign user sketch's home path","text":"

    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:

    • AUTOCONNECT_URI The ROOT URI of AutoConnect. It is defined in AutoConnectDefs.h file and is assigned to AutoConnect statistics screen by default.
    • AutoConnectConfig::homeUri It is the hyperlink of listed on the AutoConnect menu as HOME.
    • AutoConnectConfig::bootUri Which page appears at the captive portal, AUTOCONNECT_URI, or the homeUri. Its page will pop up automatically when you visit the captive portal.
    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 HOMEAlso, 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"},{"location":"adnetwork.html#change-ssid-and-password-for-softap","title":"Change SSID and Password for SoftAP","text":"

    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;\nAutoConnectConfig config;\n\nvoid setup() {\n config.apid = \"ap_portal\";\n  config.psk  = \"new_password\";\n  portal.config(config);\n  portal.begin();\n}\n

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

    AutoConnect portal;\nAutoConnectConfig config(\"ap_portal\", \"new_password\");\nvoid setup() {\n  portal.config(config);\n  portal.begin();\n}\n

    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.

    "},{"location":"adnetwork.html#combination-with-mdns","title":"Combination with mDNS","text":"

    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>\n#include <ESP8266mDNS.h>\n#include <ESP8266WebServer.h>\nAutoConnect Portal;\nvoid setup() {\nif (Portal.begin()) {\nif (MDNS.begin(\"esp8266\")) {\n      MDNS.addService(\"http\", \"tcp\", 80);\n    }\n  }\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n
    "},{"location":"adnetwork.html#make-ssid-of-softap-unique","title":"Make SSID of SoftAP unique","text":"

    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;\nAutoConnectConfig acConfig;\n\nacConfig.apid = \"ESP-\" + String(ESP.getChipId(), HEX);\naConfig.psk = YOUR_PASSWORD;\nportal.config(acConfig);\nportal.begin();\n

    Obtaining chip ID for ESP32

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

    "},{"location":"adnetwork.html#relocate-the-autoconnect-home-path","title":"Relocate the AutoConnect home path","text":"

    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\"\n
    "},{"location":"adnetwork.html#softap-access-point-ip-settings","title":"SoftAP access point IP settings","text":"

    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"},{"location":"adnetwork.html#static-ip-assignment-as-a-client","title":"Static IP assignment as a client","text":"

    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;\nAutoConnectConfig  Config;\nConfig.staip = IPAddress(192, 168, 1, 10);\nConfig.staGateway = IPAddress(192, 168, 1, 1);\nConfig.staNetmask = IPAddress(255, 255, 255, 0);\nConfig.dns1 = IPAddress(192,168,1,1);\nportal.config(Config);\nportal.begin();\n
    "},{"location":"adnetwork.html#static-ip-preservation","title":"Static IP preservation","text":"

    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;\nAutoConnectConfig config;\n\nvoid setup() {\n// If the connection to the last established AP fails, attempt to\n// connect to the nearest AP using known credentials.\n  config.autoReconnect = true;\n\n// Apply the following static IP configuration to reconnect.\n  config.staip = IPAddress(192, 168, 1, 10);\n  config.staGateway = IPAddress(192, 168, 1, 1);\n  config.staNetmask = IPAddress(255, 255, 255, 0);\n  config.dns1 = IPAddress(192, 168, 1, 1);\n\n// The above settings take precedence over the IP settings of the\n// stored credentials.\n// If this value is left false, the station IP configuration contained\n// in the stored credentials takes precedence.\n  config.preserveIP = true;\n  portal.config(config);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    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.

    "},{"location":"adnetwork.html#station-hostname","title":"Station hostname","text":"

    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.\u00a0\u21a9

    "},{"location":"adothers.html","title":"Other operation settings and controls","text":"

    AutoConnect also has features that are not directly related to WiFi connection abilities. They're mostly like a little accessory but can reduce the amount of sketch code.

    • Built-in OTA update
    • Choice of the filesystem for ESP8266
    • Debug Print
    • File uploading via built-in OTA feature
    • Refers the hosted ESP8266WebServer/WebServer
    • Reset the ESP module after disconnecting from WLAN
    • Ticker for WiFi status
    • Usage for automatically instantiated ESP8266WebServer/WebServer
    • Use with the PageBuilder library
    "},{"location":"adothers.html#built-in-ota-update-feature","title":"Built-in OTA update feature","text":"

    AutoConnect features a built-in OTA function to update ESP module firmware. You can easily make the Sketch that equips OTA and able to operate with the AutoConnect menu.

    AutoConnectConfig::ota specifies to import the built-in OTA update class into the Sketch. See the Updates with the Web Browser chapter for details.

    "},{"location":"adothers.html#choice-of-the-filesystem-for-esp8266","title":"Choice of the filesystem for ESP8266","text":"

    For ESP8266, since the Arduino core v2.7.0, SPIFFS has deprecated and the migration to LittleFS is being promoted currently. AutoConnect has adopted LittleFS as the default filesystem to follow the core standard.

    However, SPIFFS is still valid. AutoConnect can correctly compile and execute sketches made with SPIFFS assumed. When you make an AutoConnect sketch with SPIFFS enabled, you need to change the macro definition that AutoConnectDefs.h has. AC_USE_SPIFFS definition will enable SPIFFS as the filesystem.

    #define AC_USE_SPIFFS\n

    See also the FAQ to help you enable AC_USE_SPIFFS correctly. Note that refers to the Using Filesystem chapter to know the utilization capabilities of the file system with AutoConnect.

    "},{"location":"adothers.html#debug-print","title":"Debug Print","text":"

    You can output AutoConnect monitor messages to the Serial. A monitor message activation switch is in an include header file AutoConnectDefs.h of library source. Define AC_DEBUG macro to output the monitor messages.1

    #define AC_DEBUG\n

    AutoConnect does not automatically start the Serial even if AC_DEBUG is activated. The Sketch should start the Serial during its setup phase using Serial.begin(BAUDRATE).

    How to enable AC_DEBUG

    The #define is a C++ preprocessor directive. The build process of the Sketch by the Arduino IDE is processed independently of the subsequent C++ compilation unit. Writing the #define directive for AC_DEBUG in the Sketch has no effect on the AutoConnect library. To compile the AutoConnect library with the AC_DEBUG directive, you can either edit the library source code directly (usually it is located in ~/Arduino/libraries/AutoConnect/src) or use a build system which can configure the preprocessor directives externally such as PlatformIO. To enable AC_DEBUG using PlatformIO without modifying the library source, specify the build_flags directive in the platformio.ini file with each project. 

    build_flags = -DAC_DEBUG\n

    "},{"location":"adothers.html#file-uploading-via-built-in-ota-feature","title":"File uploading via built-in OTA feature","text":"

    The built-in OTA update feature can update the firmware as well as upload regular files placed in the file system on the ESP module. It allows a regular file is uploaded via OTA using the Update of AutoConnect menu without adding a particular custom Web page that contains AutoConnectFile. This ability is useful for transferring the JSON document of the custom web page definition, the external parameter file of your sketch, and so on into the target ESP module via OTA.

    The built-in OTA update feature determines where to save the uploaded file according to the filename pattern. By default, a filename with ends a .bin extension is subject to firmware updates. A file that has the other extension will be saved as a regular to the filesystem in the flash. The file extension that should be treated as the firmware is defined as the AUTOCONNECT_UPLOAD_ASFIRMWARE macro in AutoConnectDefs.h header file of the library source code. When dealing with another extension for the updating file as firmware change this macro definition.

    #define AUTOCONNECT_UPLOAD_ASFIRMWARE \".bin\"\n

    Specify with the PlatformIO

    AUTOCONNECT_UPLOAD_ASFIRMWARE pattern will be embedded into the binary sketch is determined at compile time. The PlatformIO build system allows you to change the pattern expression for each project without modifying the library source code.

    build_flags=-DAUTOCONNECT_UPLOAD_ASFIRMWARE='\".bin\"'\n
    "},{"location":"adothers.html#refers-the-hosted-esp8266webserverwebserver","title":"Refers the hosted ESP8266WebServer/WebServer","text":"

    Constructing an AutoConnect object variable without parameters then creates and starts an ESP8266WebServer/WebServer inside the AutoConnect. This object variable could be referred by AutoConnect::host function to access ESP8266WebServer/WebServer instance as like below.

    AutoConnect Portal;\n\nPortal.begin();\nESP8266WebServer& server = Portal.host();\nserver.send(200, \"text/plain\", \"Hello, world\");\n

    When host() is valid

    The host() can be referred at after AutoConnect::begin.

    "},{"location":"adothers.html#reset-the-esp-module-after-disconnecting-from-wlan","title":"Reset the ESP module after disconnecting from WLAN","text":"

    Disconnect by menu operation allows the ESP8266/ESP32 module to reset automatically after disconnecting from WLAN. This behavior is enabled by default and can be disabled by AutoConnectConfig::autoReset settings.

    AutoConnect       Portal;\nAutoConnectConfig Config;\nConfig.autoReset = false; // Continue sketch processing even after disconnecting from by AutoConnect menu.\nPortal.config(Config);\nPortal.begin();\n

    The autoReset setting will automatically reset the ESP module when disconnecting WiFi only if you intentionally navigate the menu. And it does not participate in passive disconnection conditions such as disconnection due to sketch processing or loss of WiFi signal.

    You can combine autoReset with autoReconnect to disconnect from WiFi and automatically reconnect to another AP while continuing the Sketch operation.

    The Sketch below shows an example of a meaningful combination of autoReset and autoReconnect. It can connect to the access point once with the captive portal but assumes that it can be disconnected from the WLAN by intentional menu navigation. In that case, the Sketch will continue processing without resetting the module. Then an external switch allows to start automatic reconnecting. In this situation, if known access points appear nearby, the ESP module will automatically reconnect to them in the handleClient loop. In this state transition, the module continues the Sketch process without resetting.

    AutoConnect       Portal;\nAutoConnectConfig Config;\n\nconst int reconnectSwitch = 14; // Assign the reconnect switch to GPIO14\n\nICACHE_RAM_ATTR void detectsReconnect() {\nif (!Config.autoReconnect) {  // Chattering elimination\n// autoReconnect is enabled by interrupt of the GPIO trigger,\n    Config.autoReconnect = true;  // Activate reconnection\n    Config.reconnectInterval = 2; // Attempt to reconnect at 60 seconds intervals.\n    Portal.config(Config);\n    Serial.printf(\"Turn on autoReconnect, interval %d[s]\\n\", Config.reconnectInterval * AUTOCONNECT_UNITTIME);\n  }\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  Config.ticker = true;   // Setting up WiFi connection indicator\n  Portal.config(Config);  \n\nif (Portal.begin()) {\n    Config.autoReset = false;\n    Portal.config(Config);\n\n// Set external switch pin to reconnect as interrupt, assign interrupt function and set RISING mode\n    pinMode(reconnectSwitch, INPUT_PULLUP);\n    attachInterrupt(digitalPinToInterrupt(reconnectSwitch), detectsReconnect, RISING);\n  }\n}\n\nvoid loop() {\nif (WiFi.status() == WL_CONNECTED) {\n/*\n    Here, your sketch process with WiFi connection\n    */\n  }\nelse {\n/*\n    Here, your sketch process without WiFi connection\n    */\n  }\n\n// Post process, turn to initial state of autoReconnect.\nif (Config.autoReconnect) {\nif (WiFi.status() == WL_CONNECTED) {\n      Config.autoReconnect = false;\n      Portal.config(Config);\n    }\n  }\n\n// The actual reconnection takes place within handleClient.\n  Portal.handleClient();\n}\n

    An external switch wiring to GPIO

    The wiring for the above Sketch assumes a momentary effects switch that connects the GPIO pin 14 to GND. You can experience it with easily wire on a breadboard using a NodeMCU as like:

    "},{"location":"adothers.html#ticker-for-wifi-status","title":"Ticker for WiFi status","text":"

    Flicker signal can be output from the ESP8266/ESP32 module according to WiFi connection status. By wiring the LED to the signal output pin with the appropriate limiting resistor, you can know the WiFi connection status through the LED blink during the inside behavior of AutoConnect::begin and loop of AutoConnect::handleClient.

    AutoConnectConfig::ticker option specifies flicker signal output. The following sketch is an example of blinking the active-low LED connected to GPIO16 depending on the WiFi connection status.2

    AutoConnect        portal;\nAutoConnectConfig  Config;\nConfig.ticker = true;\nconfig.tickerPort = 16;\nConfig.tickerOn = LOW;\nportal.config(Config);\nportal.begin();\n

    The AutoConnect ticker indicates the WiFi connection status in the following three flicker patterns:

    • Short blink: The ESP module stays in AP_STA mode.
    • Short-on and long-off: No STA connection state. (i.e. WiFi.status != WL_CONNECTED)
    • No blink: WiFi connection with access point established and data link enabled. (i.e. WiFi.status = WL_CONNECTED)

    The flicker cycle length is defined by some macros in AutoConnectDefs.h header file.

    #define AUTOCONNECT_FLICKER_PERIODAP  1000 // [ms]\n#define AUTOCONNECT_FLICKER_PERIODDC  (AUTOCONNECT_FLICKER_PERIODAP << 1) // [ms]\n#define AUTOCONNECT_FLICKER_WIDTHAP   96  // (8 bit resolution)\n#define AUTOCONNECT_FLICKER_WIDTHDC   16  // (8 bit resolution)\n
    • AUTOCONNECT_FLICKER_PERIODAP: Assigns a flicker period when the ESP module stays in AP_STA mode.
    • AUTOCONNECT_FLICKER_PERIODDC: Assigns a flicker period when WiFi is disconnected.
    • AUTOCONNECT_FLICKER_WIDTHAP and AUTOCONNECT_FLICKER_WIDTHDC: Specify the duty rate for each period [ms] in 8-bit resolution.

    Ticker during OTA

    The LED blinking will always be a short blinking during the update via OTA, regardless of the definition of the flicker cycle.

    AutoConnectConfig::tickerPort specifies a port that outputs the flicker signal. If you are using an LED-equipped ESP module board, you can assign a LED pin to the tick-port for the WiFi connection monitoring without the external LED. The default pin is arduino valiant's LED_BUILTIN. You can refer to the Arduino IDE's variant information to find out which pin actually on the module assign to LED_BUILTIN.3

    AutoConnectConfig::tickerOn specifies the active logic level of the flicker signal. This value indicates the active signal level when driving the ticker. For example, if the LED connected to tickPort lights by LOW, the tickerOn is LOW. The logic level of LED_BUILTIN for popular modules are as follows:

    module Logic level LED_BUILTIN Pin Arduino alias NodeMCU V1.0 Active-low 16 D0 WEMOS D1 mini Active-low 2 D4 SparkFun ESP8266 Thing Active-high 5 Adafruit Feather HUZZAH ESP8266 Active-low 0 NodeMCU 32s Active-high 2 T2 LOLIN32 Pro Active-low 5 SS SparkFun ESP32 Thing Active-high 5 Adafruit Feather HUZZAH32 Active-high 13 A12"},{"location":"adothers.html#usage-for-automatically-instantiated-esp8266webserverwebserver","title":"Usage for automatically instantiated ESP8266WebServer/WebServer","text":"

    The Sketch can handle URL requests using ESP8266WebServer or WebServer that AutoConnect started internally. ESP8266WebServer/WebServer instantiated dynamically by AutoConnect can be referred to by AutoConnect::host function. The Sketch can use the 'on' function, 'send' function, 'client' function and others by ESP8266WebServer/WebServer reference of its return value.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect       Portal;\n\nvoid handleRoot() {\n  ESP8266WebServer& IntServer = Portal.host();\n  IntServer.send(200, \"text/html\", \"Hello, world\");\n}\n\nvoid handleNotFound() {\n  ESP8266WebServer& IntServer = Portal.host();\n  IntServer.send(404, \"text/html\", \"Unknown.\");\n}\n\nvoid setup() {\nbool r = Portal.begin();\nif (r) {\n    ESP8266WebServer& IntServer = Portal.host();\n    IntServer.on(\"/\", handleRoot);\n    Portal.onNotFound(handleNotFound);    // For only onNotFound.\n  }\n}\n\nvoid loop() {\n  Portal.host().handleClient();\n  Portal.handleRequest();\n/* or following one line code is equ.\n  Portal.handleClient();\n  */\n}\n

    ESP8266WebServer/WebServer function should be called after AutoConnect::begin

    The Sketch cannot refer to an instance of ESP8266WebServer/WebServer until AutoConnect::begin completes successfully.

    Do not use with ESP8266WebServer::begin or WebServer::begin

    ESP8266WebServer/WebServer is already running inside the AutoConnect.

    "},{"location":"adothers.html#use-with-the-pagebuilder-library","title":"Use with the PageBuilder library","text":"

    In ordinary, the URL handler will respond to the request from the client by sending some HTML. It will dynamically generate the HTML to respond to based on the sensing data etc. for the changing scene, but it contains elements of variable values in the middle of the HTML fixed string. Therefore, sketches tend to be in a tangled that repeats the logic for data handling and string splicing in turn, which tends to be less readable and maintainable.

    PageBuilder library is an HTML assembly aid. it can handle predefined HTML like the template and simplify an HTML string assemble logic, and also the generated HTML send automatically.

    An example sketch used with the PageBuilder as follows and it explains how it aids for the HTML generating. Details for GitHub repository.

    1. The source code placement of common macros for AutoConnect since v0.9.7 has changed.\u00a0\u21a9

    2. The ESP module pin mapping is different for each breakout. Definitions for assigning pin numbers to pin names usually exist in the variant definition program of Arduino core packages. (e.g. esp8266/arduino core, arduino-esp32 core) You may find the definition as pins_arduino.h.\u00a0\u21a9

    3. It's defined in the pins_arduino.h file, located in the sub-folder named variants wherein Arduino IDE installed folder.\u00a0\u21a9

    "},{"location":"advancedusage.html","title":"Advanced usage","text":""},{"location":"advancedusage.html#summary","title":"Summary","text":"

    To make sketches work as you intended with AutoConnect, make sure you understand the implications of the setting parameters and configure AutoConnect. AutoConnectConfig allows you to incorporate settings into AutoConnect that coordinate control over WiFi connectivity and captive portal behavior. For advanced usages, the configuration settings and the Sketch examples are followings:

    • AutoConnect WiFi connection control
    • Captive portal control
    • Authentication settings
    • Credential accesses
    • Settings for customizing the page exterior
    • Settings and controls for network and WiFi
    • Other operation settings and controls

    Don't forget AutoConnect::config

    The configuration cannot be reflected by only changing the member variables of AutoConnectConfig settings. It will be reflected in the actual ones by AutoConnect::config function. Don't forget to run the AutoConnect::config after changing the AutoConnectConfig member variables.

    AutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  config.autoReconnect = true;\n  portal.config(config);  // Don't forget.\n  portal.begin();\n}\n
    "},{"location":"api.html","title":"AutoConnect API","text":""},{"location":"api.html#include-headers","title":"Include headers","text":"

    The AutoConnect class is limited in its available APIs by the AutoConnect component it contains. The AutoConnect.h header file makes all AutoConnect features available. On the other hand, the AutoConnectCore.h header file does not include extensions such as custom web pages or OTAs; AutoConnectCore.h reduces memory consumption by limiting functionality to WiFi connectivity utilities only. See the Reducing Binary Size chapter for details.

    "},{"location":"api.html#autoconnecth","title":"AutoConnect.h","text":"
    #include <AutoConnect.h>\n

    AutoConnect.h header file provides all AutoConnect features.

    "},{"location":"api.html#autoconnectcoreh","title":"AutoConnectCore.h","text":"
    #include <AutoConnectCore.h>\n

    AutoConnectCore.h header file provides the AutoConnect class that excludes Custom Web pages and OTA-related components of the AutoConnect features. When you include this header in your sketch, you cannot use the AutoConnectAux, AutoConnectElements, AutoConnectOTA, and AutoConnectUpdate classes.

    "},{"location":"api.html#defined-macros","title":"Defined macros","text":"

    They contain in AutoConnectDefs.h.

    #define AC_USE_SPIFFS                           // Use SPIFFS for the file system on the onboard flash\n#define AC_USE_LITTLEFS                         // Use LittleFS for the file system on the onboard fash\n#define AC_DEBUG                                // Monitor message output activation\n#define AC_DEBUG_PORT           Serial          // Default message output device\n#define AUTOCONNECT_AP_IP       0x011CD9AC      // Default SoftAP IP\n#define AUTOCONNECT_AP_GW       0x011CD9AC      // Default SoftAP Gateway IP\n#define AUTOCONNECT_AP_NM       0x00FFFFFF      // Default subnet mask\n#define AUTOCONNECT_DNSPORT     53              // Default DNS port at captive portal\n#define AUTOCONNECT_HTTPPORT    80              // Default HTTP\n#define AUTOCONNECT_MENU_TITLE  \"AutoConnect\"   // Default AutoConnect menu title\n#define AUTOCONNECT_URI         \"/_ac\"          // Default AutoConnect root path\n#define AUTOCONNECT_TIMEOUT     30000           // Default connection timeout[ms]\n#define AUTOCONNECT_CAPTIVEPORTAL_TIMEOUT  0    // Captive portal timeout value\n#define AUTOCONNECT_STARTUPTIME 30              // Default waiting time[s] for after reset\n#define AUTOCONNECT_USE_JSON                    // Allow AutoConnect elements to be handled by JSON format\n#define AUTOCONNECT_USE_UPDATE                  // Indicator of whether to use the AutoConnectUpdate feature.\n#define AUTOCONNECT_UPDATE_PORT 8000            // Available HTTP port number for the update\n#define AUTOCONNECT_UPDATE_TIMEOUT  8000        // HTTP client timeout limitation for the update [ms]\n#define AUTOCONNECT_TICKER_PORT LED_BUILTIN     // Ticker port\n#endif\n

    Macros placement moved

    Source code placement of the above macros provided for user sketch changed from v0.9.7. The new code is in AutoConnectDefs.h.

    "},{"location":"api.html#constructors","title":"Constructors","text":""},{"location":"api.html#autoconnect","title":"AutoConnect","text":"
    AutoConnect()\n

    AutoConnect default constructor. This entry internally allocates the ESP8266WebServer for ESP8266 or WebServer for ESP32 and is activated internally.

    AutoConnect will call the user added handler to respond to the HTTP request using the ESP8266WebServer::on (WebServer::on for ESP32) funtion. This call will be made from during the handleClient of AutoConnect function. Therefore, in the use case of assigning AutoConnect in this constructor, it is necessary to know the instance of ESP8266WebServer in order to register the request handler. Sketch can use host functions to obtain a reference to an ESP8266WebServer instance that is internally hosted by AutoConnect.

    • For ESP8266
    AutoConnect(ESP8266WebServer& webServer)\n
    • For ESP32
    AutoConnect(WebServer& webServer)\n

    Run the AutoConnect site using the externally ensured ESP8266WebServer for ESP8266 or WebServer for ESP32. Parameter webServerA reference of ESP8266WebServer or WebServer instance.

    "},{"location":"api.html#public-member-functions","title":"Public member functions","text":""},{"location":"api.html#append","title":"append","text":"
    • ESP8266/ESP32 Common
    AutoConnectAux* append(const String& uri, const String& title)\n
    • For ESP8266
    AutoConnectAux* append(const String& uri, const String& title, ESP8266WebServer::THandlerFunction handler)\n
    • For ESP32
    AutoConnectAux* append(const String& uri, const String& title, WebServer::THandlerFunction handler)\n

    Creates an AutoConnectAux dynamically with the specified URI and integrates it into the menu. Calls with a request handler parameter can use this function as menu registration for a legacy page of ESP8266WebServer/WebServer. If the handler parameter specified, also it will register the request handler for the ESP8266WebServer/WebServer. AutoConnect manages the menu items using a sequence list, and this function always adds the item to the end of the list. Therefore, the order of the menu items is the additional order. Returns the pointer to created AutoConnectAux instance, the nullptr if an AutoConnectAux with the same URI already exists. Parameter uriA string of the URI. titleTitle for menu item. handlerRequest handler function as type of ESP8266WebServer::THandlerFunction/WebServer::THandlerFunction. Return value A Pointer to a created AutoConnectAux instance.

    An instance of ESP8266WebServer/WebServer is needed

    The WebServer must have instantiated for calling with a request handler parameter. AutoConnect can instantiate and host a WebServer internally, but in that case, the point in time to call the append function with a request handler parameter must be after AutoConnect::begin.

    "},{"location":"api.html#aux","title":"aux","text":"
    AutoConnectAux* aux(const String& uri) const\n

    Returns a pointer to AutoConnectAux with the URI specified by uri. If AutoConnectAux with that URI is not bound, it returns nullptr. Parameter uriA string of the URI. Return value A Pointer of the AutoConnectAux instance.

    "},{"location":"api.html#begin","title":"begin","text":"
    bool begin()\n
    bool begin(const char* ssid, const char* passphrase)\n
    bool begin(const char* ssid, const char* passphrase, unsigned long timeout)\n

    Starts establishing the WiFi connection. The WiFi mode at this time is WIFI_STA. AutoConnect first invokes WiFi.begin. If the ssid and the passphrase are missing, its WiFi.begin has no SSID and Password. Regardless of the result, ESP8266WebServer/WebServer will start immediately after the first WiFi.begin. The captive portal will not be started if the connection has been established with first WiFi.begin. If the connection cannot establish, switch to WIFI_AP_STA mode and activate SoftAP. Then DNS server starts. Parameters ssidSSID to be connected. passphrasePassword for connection. timeoutA time out value in milliseconds for waiting connection. Return value trueConnection established, AutoConnect service started with WIFI_STA mode. falseCould not connected, Captive portal started with WIFI_AP_STA mode.

    "},{"location":"api.html#config","title":"config","text":"
    bool config(AutoConnectConfig& config)\n
    bool config(const char* ap, const char* password = nullptr)\n

    Set AutoConnect configuration settings. Parameters configReference to AutoConnectConfig containing SoftAP's parameters and static IP parameters. apSSID for SoftAP. The default value is esp8266ap for ESP8266, esp32ap for ESP32. passwordPassword for SodtAP. The default value is 12345678. Return value trueSuccessfully configured. falseConfiguration parameter is invalid, some values out of range.

    "},{"location":"api.html#detach","title":"detach","text":"
    bool detach(const String& uri)\n

    Detach the AutoConnectAux with the specified URI from the management of AutoConnect. An unmanaged AutoConnectAux will no longer appear in menu items, and its page handler will no longer respond even if the URI is accessed directly. Parameter uriURI of AutoConnectAux to be detached. Return value trueSuccessfully detached. falseAn AutoConnectAux with the specified URI does not exist.

    If the request handler registered in the detaching AutoConnectAux is for a legacy page of the ESP8266WebServer/WebServer, the URI is still valid after detaching. AutoConnect does not delete the request handler registered to ESP8266WebServer/WebServer with the on function. (It cannot be removed)

    Deleting the AutoConnectAux

    If the AutoConnectAux to detach was added by AutoConnect::append, it will be automatically removed and freed from memory.

    "},{"location":"api.html#disablemenu","title":"disableMenu","text":"
    void disableMenu(const uint16_t items)\n

    Disable the AutoConnect menu items specified by the items parameter with logical OR value using AC_MENUITEM_t constant. This function only works for AutoConnect primary menu items. It has no effect on disable for AutoConnectAux items. To disable the items by AutoConnectAux, use the AutoConnectAux::menu function. Parameter itemsSpecify 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 about AC_MENUITEM_t.

    "},{"location":"api.html#enablemenu","title":"enableMenu","text":"
    void enableMenu(const uint16_t items)\n
    Enable the AutoConnect menu items specified by the items parameter with logical OR value using AC_MENUITEM_t constant. This function only works for AutoConnect primary menu items. It has no effect on enable for AutoConnectAux items. To enable the items by AutoConnectAux, use the AutoConnectAux::menu function. Parameter itemsSpecify the combined value of AC_MENUITEM_t of the items applying to the AutoConnect menu. It provides the value calculated from the logical OR by the AC_MENUITEM_t value of each item applied as a menu. AC_MENUITEM_t is enumeration type to identify each menu item and it has the below values.
    • AC_MENUITEM_CONFIGNEW : Configure new AP
    • AC_MENUITEM_OPENSSIDS : Open SSIDs
    • AC_MENUITEM_DISCONNECT : Disconnect
    • AC_MENUITEM_RESET : Reset...
    • AC_MENUITEM_HOME : HOME
    • AC_MENUITEM_UPDATE : Update
    • AC_MENUITEM_DEVINFO : Device statistics as AutoConnect root page
    • AC_MENUITEM_DELETESSID : Enable to delete credentials on Open SSIDs.

    It is added, not replaced.

    The initial configuration of the AutoConnect menu items: AC_MENUITEM_CONFIGNEW | AC_MENUITEM_OPENSSIDS | AC_MENUITEM_DISCONNECT | AC_MENUITEM_RESET | AC_MENUITEM_HOME The enableMenu function adds an indication of the specified items to the current. Therefore, use the disableMenu to remove the specified item from the initial menu.

    "},{"location":"api.html#end","title":"end","text":"
    void end(void)\n

    Stops AutoConnect captive portal service. Release ESP8266WebServer/WebServer and DNSServer.

    Attention to end

    The end function releases the instance of ESP8266WebServer/WebServer and DNSServer. It can not process them after the end function.

    "},{"location":"api.html#getconfig","title":"getConfig","text":"
    AutoConnectConfig& getConfig(void)\n

    Get the current AutoConnectConfig values held by AutoConnect. Return value A reference to an AutoConnectConfig instance retained by AutoConnect. This reference reflects the actual values captured by the AutoConnect::config function, unlike the AutoConnectConfig value declared in the sketch.

    "},{"location":"api.html#geteepromusedsize","title":"getEEPROMUsedSize","text":"
    uint16_t getEEPROMUsedSize(void)\n

    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. Return value Total amount size of saved AutoConnect credentials and custom data.

    The getEEPROMUsedSize is available for only ESP8266 use

    It is available for only ESP8266 use and will return 0 when used with ESP32.

    "},{"location":"api.html#handleclient","title":"handleClient","text":"
    void handleClient(void)\n

    Process the AutoConnect menu interface. The ESP8266WebServer::handleClient1 function hosted by AutoConnect is also called from within AutoConnect to handle the request handlers contained in Sketch.

    Enhanced AutoConnect::handleClient

    The handleClient function enhanced since AutoConnect 1.2.0 can start the captive portal according to the WiFi connection status. By properly specifying AutoConnectConfig::retainPortal and AutoConnectConfig::autoRise, when handleClient detects WiFi disconnection, it shifts WiFi mode to WIFI_AP_STA and starts the DNS server together with SoftAP dynamically. Then trapping for incoming HTTP requests from client devices will be started by AutoConnect. Thus it will open the captive portal behind the execution of the sketch loop() function. The captive portal launched by enhanced handleClient does not interfere with sketch execution except waiting for the result of WiFi.begin. Also, AutoConnectConfig::autoReconnect has improved. The Sketch can specify the AutoConnectConfig::reconnectInterval to continue retrying the reconnection with enhanced handleClient.

    "},{"location":"api.html#handlerequest","title":"handleRequest","text":"
    void handleRequest(void)\n

    Handling for the AutoConnect menu request.

    About used in combination with handleClient

    The handleRequest function is not supposed to use with AutoConnect::handleClient. It should be used following ESP8266WebServer::handleClient or WebServer::handleClient.

    "},{"location":"api.html#home","title":"home","text":"
    void home(String& uri)\n

    Put a user site's home URI. The URI specified by home is linked from \"HOME\" in the AutoConnect menu. Parameter uriA URI string of user site's home path.

    "},{"location":"api.html#host","title":"host","text":"
    • For ESP8266
    ESP8266WebServer& host(void)\n
    • For ESP32
    WebServer& host(void)\n

    Returns the reference of the ESP8266WebServer/WebServer which is allocated in AutoConnect automatically. Return value A reference of the ESP8266WebServer/WebServer.

    &reference is not a pointer

    A reference cannot be re-assigned, and must be assigned at initialization. It's like as bind as alias. 

    ESP8266WebServer& server = portal.host();\nserver.handleClient();\n
    or 
    portal.host().handleClient();\n

    "},{"location":"api.html#isportalavailable","title":"isPortalAvailable","text":"
    bool isPortalAvailable(void)\n

    Returns a boolean value indicating whether a captive portal is available. Return value trueCaptive portal is available. It has SoftAP enabled and is spoofing DNS lookup responses by AutoConnect. Usually, in this state, requests from client devices for Internet transparency validation are redirected to the ESP module. falseAutoConnect is not in captive portal state.

    void join(std::vector<std::reference_wrapper<AutoConnectAux>> aux)\n
    "},{"location":"api.html#join","title":"join","text":"
    void join(AutoConnectAux& aux)\n
    void join(std::vector<std::reference_wrapper<AutoConnectAux>> aux)\n

    Join the AutoConnectAux object to AutoConnect. AutoConnectAux objects can be joined one by one, or joined altogether. The AutoConnectAux object joined by the join function can be handled from the AutoConnect menu. Parameter auxReference to AutoConnectAux. It can be std::vector of std::reference_wrapper of AutoConnectAux with list initialization.

    "},{"location":"api.html#load","title":"load","text":"
    bool load(const String& aux)\n
    bool load(PGM_P aux)\n
    bool load(const __FlashStringHelper* aux)\n
    bool load(Stream& aux)\n

    Load JSON document of AutoConnectAux which contains AutoConnectElements. If there is a syntax error in the JSON document, false is returned. Parameter auxThe input string to be loaded. Return value trueThe JSON document as AutoConnectAux successfully loaded. falseLoading JSON document unsuccessful, probably syntax errors have occurred or insufficient memory. You can diagnose the cause of loading failure using the ArduinoJson Assistant.

    "},{"location":"api.html#locate","title":"locate","text":"
    AutoConnectAux& locate(const String& uri)\n

    Returns a reference to the AutoConnectAux assigned to the uri passed in the argument. Parameter uriURI string of the custom web page to be located. Return value A reference to the AutoConnectAux that has a specified URI.

    AutoConnectAux for the specified uri must exist

    If the AutoConnectAux for the uri specified to the locate function does not exist, the function returns a reference to an empty AutoConnectAux. It's just a frame without any AutoConnectElements. No processing can continue using that AutoConnectAux. (causes an exception) A common cause of exceptions for the locate function is syntax errors in the JSON description of a custom web page.

    "},{"location":"api.html#on","title":"on","text":"
    bool on(const String& uri, const AuxHandlerFunctionT handler, AutoConnectExitOrder_t order = AC_EXIT_AHEAD)\n
    Register the handler function of the AutoConnectAux. Parameters uriA string of the URI assigned to the AutoConnectAux page. handlerA function that behaves when a request to the AutoConnectAux page occurs. AuxHandlerFunctionT type is defined by the following declaration.

    String handler(AutoConnectAux&, PageArgument&)

    orderSpecifies when the handler is called with the following enumeration value.
    • AC_EXIT_AHEAD : Called before AutoConnect generates the HTML of the page. You set the value of AutoConnectElements in the handler then its value will be displayed on the page.
    • AC_EXIT_LATER : Called after AutoConnect generates the HTML of the page. You can append to HTML generated by AutoConnect.
    • AC_EXIT_BOTH : Called even before generating HTML and after generated.

    It is not ESP8266WebServer::on, not WebServer::on for ESP32.

    This function effects to AutoConnectAux only. However, it coexists with that of ESP8266WebServer::on or WebServer::on of ESP32.

    "},{"location":"api.html#onconnect","title":"onConnect","text":"
    void onConnect(ConnectExit_ft fn)\n

    Register the function which will call from AutoConnect at the WiFi connection established. Parameter fnA function called at the WiFi connected.

    An fn specifies the function called when the WiFi connected. Its prototype declaration is defined as ConnectExit_ft.

    typedef std::function<void(IPAddress& localIP)> ConnectExit_ft\n
    Parameter localIPAn IP address of the ESP module as STA."},{"location":"api.html#ondetect","title":"onDetect","text":"
    void onDetect(DetectExit_ft fn)\n

    Register the function which will call from AutoConnect at the start of the captive portal. Parameter fnA function called at the captive portal start.

    An fn specifies the function called when the captive portal starts. Its prototype declaration is defined as DetectExit_ft.

    typedef std::function<bool(IPAddress& softapIP)>  DetectExit_ft\n
    Parameter softapIPAn IP address of SoftAP for the captive portal. Return value trueContinues captive portal handling. falseCancel the captive portal. AutoConnect::begin function will return with a false."},{"location":"api.html#onnotfound","title":"onNotFound","text":"
    • For ESP8266
    void onNotFound(ESP8266WebServer::THandlerFunction fn)\n
    • For ESP32
    void onNotFound(WebServer::THandlerFunction fn)\n

    Register the handler function for undefined URL request detected. Parameter fnA function of the \"not found\" handler.

    "},{"location":"api.html#onotaend","title":"onOTAEnd","text":"
    void onOTAEnd(OTAEndExit_ft fn)\n

    Register the on-end exit routine that is called only once when the OTA is finished. Parameter fnA function called when the OTA has been finished.

    An fn specifies the function called when the OTA has been finished. Its prototype declaration is defined as OTAEndExit_ft.

    typedef std::function<void(void)> OTAEndExit_ft\n
    "},{"location":"api.html#onotaerror","title":"onOTAError","text":"
    void onOTAError(OTAErrorExit_ft fn)\n

    Register the exit routine that is called when some error occurred. Parameter fnA function called when some OTA error occurs.

    An fn specifies the function called when the some error occurred. Its prototype declaration is defined as OTAErrorExit_ft.

    typedef std::function<void(uint8_t error)> OTAErrorExit_ft\n
    Parameter errorError code of OTA. It is defined in the Updater class or the Update class of the Arduino core for each platform."},{"location":"api.html#onotaprogress","title":"onOTAProgress","text":"
    void onOTAProgress(OTAProgressExit_ft fn)\n

    Register the exit routine that is called during the OTA progress. Parameter fnA function called during the OTA progress.

    An fn specifies the function called during the OTA progress. Its prototype declaration is defined as OTAProgressExit_ft.

    typedef std::function<void(unsigned int amount, unsigned int size)> OTAProgressExit_ft\n
    Parameters amountTotal amount of bytes received. sizeBlock size of current send."},{"location":"api.html#onotastart","title":"onOTAStart","text":"
    void onOTAStart(OTAStartExit_ft fn)\n

    Register the on-start exit routine that is called only once when the OTA has been started. Parameter fnA function called at the OTA start.

    An fn specifies the function called when the OTA starts. Its prototype declaration is defined as OTAStartExit_ft.

    typedef std::function<void(void)> OTAStartExit_ft\n
    "},{"location":"api.html#portalstatus","title":"portalStatus","text":"
    uint8_t portalStatus(void)\n
    Returns the status of the portal inside AutoConnect::begin and AutoConnect::handleClient. Return value A bitwise value that indicates each status and is the logical disjunction of multiple states.
    • AutoConnect::AC_IDLE: Initial state. AutoConnect is not making any WiFi connection attempts. This state is reached immediately after AutoConnect::begin starts.
    • AutoConnect::AC_ESTABLISHED: Successfully connected to the WiFi access point.
    • AutoConnect::AC_AUTORECONNECT: AutoConnectConfig::autoReconnect setting was applied during the WiFi connection attempt process. This flag does not indicate a successful connection. It only shows that a condition that triggers autoReconnect has occurred. Whether the connection was actually successful should be determined by WiFi.status()==WL_CONNECTED.
    • AutoConnect::AC_TIMEOUT: WiFi connection attempt timed out. Or, the captive portal was shut down by the AutoConnectConfig::portalTimeout setting.
    • AutoConnect::AC_INTERRUPT: Connection interrupted due to an indication with the exit. The whileConnecting exit routine returned false. or the whileCaptivePortal exit routine returned false. AutoConnect aborted the WiFi connection attempt with those indications.
    • AutoConnect::AC_CAPTIVEPORTAL: Captive portal is available. It means that SoftAP mode is enabled, and the DNS server is available. The state of this flag is equivalent to the return value of AutoConnect::isPortalAvailable function.
    • AutoConnect::AC_INPROGRESS: WiFi.begin in progress. AutoConnect is waiting for the connection to succeed or times out; this state will reset when terminating WiFi.begin attempts.
    "},{"location":"api.html#restorecredential","title":"restoreCredential","text":"
    • For ESP8266
    bool restoreCredential(const char* filename = \"/ac_credt\", fs::FS& fs = FS)\n
    • For ESP32
    bool restoreCredential(const char* filename = \"/ac_credt\", fs::SPIFFSFS& fs = SPIFFS)\n
    bool restoreCredential(const char* filename = \"/ac_credt\", fs::LittleFSFS& fs = LittleFS)\n
    • For using SD
    bool restoreCredential<fs::SDFS>(const char* filename, fs::SDFS& fs)\n

    Restore credentials from the file as named filename with specified fs file system. The file containing the credentials of the restore source must have been saved with the AutoConnect::saveCredential function. Parameter filenameSpecify the file from which to restore the credentials. The filename must include /, the root directory. If this parameter is not specified, ac_credt is assumed. fsSpecifies the file system of the source file to be restored. It must be mounted by the begin function of the file system concerned. Return value trueCredentials has been restored. falseFailed to restore the credentials. Current credentials may have been lost.

    "},{"location":"api.html#savecredential","title":"saveCredential","text":"
    • For ESP8266
    bool saveCredential(const char* filename = \"/ac_credt\", fs::FS& fs = FS)\n
    • For ESP32
    bool saveCredential(const char* filename = \"/ac_credt\", fs::SPIFFSFS& fs)\n
    bool saveCredential(const char* filename = \"/ac_credt\", fs::LittleFSFS& fs)\n
    • For using SD
    bool saveCredential<fs::SDFS>(const char* filename, fs::SDFS& fs)\n

    Saves the current credentials stored by AutoConnect to the specified file. A credential file saved with this function can be treated as input to the AutoConnect::restoreCredential function. Parameter filenameSpecify the file from which to save the credentials. The filename must include /, the root directory. If this parameter is not specified, ac_credt is assumed. fsSpecifies the file system of the destination file to be saved. It must be mounted by the begin function of the file system concerned. Return value trueCredentials has been saved. falseFailed to save the credentials.

    "},{"location":"api.html#where","title":"where","text":"
    String where(void)\n

    Returns an uri string of the AutoConnectAux uri object of the custom Web page that caused the request to the page. AutoConnect identifies the URI (ie. the referrer URI) that caused the request each time from the client occurs and will save the URI If the request source is a custom Web page of AutoConnectAux. The where function returns a pointer of AutoConnectAux which is a URI of a least recent request from the custom Web page. This function is provided to access the fields (ie. the AutoConnectElements) with a custom Web page handler of a page and is available only for request source that is the custom Web pages. It is invalid for HTTP requests from individual pages registered with the on handler of ESP8266WebServer/WebServer for ESP32. In other words, this function only returns the AutoConnecAux page which is a least recently displayed. Return value An uri string of the AutoConnectAux that caused the request the page.

    The where function usage is described in the section Where to pick up the values.

    "},{"location":"api.html#whilecaptiveportal","title":"whileCaptivePortal","text":"
    void whileCaptivePortal(WhileCaptivePortalExit_ft fn)\n

    Register the function which will call from AutoConnect during a stay in the captive portal. Parameter fnFunction called at the captive portal start.

    An fn specifies the function called while staying in the captive portal. Its prototype declaration is defined as WhileCaptivePortalExit_ft.

    typedef std::function<bool(void)>   WhileCaptivePortalExit_ft\n
    Return value trueContinues captive portal handling. falseCancel the captive portal. AutoConnect::begin function will return with a false."},{"location":"api.html#whileconnecting","title":"whileConnecting","text":"
    void whileConnecting(WhileConnectingExit_ft fn)\n

    Register the function that will call from AutoConnect while waiting for connection after WiFi.begin. Parameter fnFunction that will call from AutoConnect while waiting for connection.

    An fn specifies the a function called while waiting for a WiFi connection. Its prototype declaration is defined as WhileConnectingExit_ft.

    typedef std::function<bool(String&)>    WhileConnectingExit_ft\n
    Parameter ssidSSID of an access point to which connection is being attempted. Return value trueContinue attempts to connect to WiFi. falseCancel the WiFi connection attempt.

    1. Equivalent to the WebServer::handleClient function on the ESP32 platform.\u00a0\u21a9

    "},{"location":"apiaux.html","title":"AutoConnectAux API","text":"

    Only for AutoConnect

    The following AutoConnectAux API are valid only for AutoConnect; they are not available for AutoConnectCore.

    "},{"location":"apiaux.html#constructor","title":"Constructor","text":""},{"location":"apiaux.html#autoconnectaux","title":"AutoConnectAux","text":"
    AutoConnectAux(const String& uri = String(\"\"), const String& title = String(\"\"), const bool menu = true, const AutoConnectElementVT addons = AutoConnectElementVT(), const bool responsive = true, const bool CORS = false)\n
    Parameters uriURI of this custom Web Page. titlePage title of this custom Web page. It will appear on the auto connection menu and at the top of that page. menuSpecifies whether to display this page on menu. addonsReference to AutoConnectElement collection. responsiveSpecifies whether to make HTTP response or not. CORSInclude Access-Control-Allow-Origin:* in the HTTP response headers of the custom web page. This indicates that the response can be shared."},{"location":"apiaux.html#public-member-functions","title":"Public member functions","text":""},{"location":"apiaux.html#operator","title":"operator [ ]","text":"
    AutoConnectElement& operator[](const char* name)\n
    AutoConnectElement& operator[](const __FlashStringHelper* name)\n

    AutoConnectElement& operator[](const String& name)\n
    Returns a reference to the element specified by name. An operator [] is a shortcut for getElement function with the reference casting. Unlike getElement, which returns a pointer to that element, an operator [] returns a reference to that element. You also need to cast the return value to the actual type, just like the getElement function. Parameter nameName of the AutoConnectElements to be retrieved. Return valueA reference to AutoConnectElement. It is different from the actual element type.

    "},{"location":"apiaux.html#add","title":"add","text":"
    void add(AutoConnectElement& addon)\n
    void add(AutoConnectElementVT addons)\n

    Add an element to the AutoConnectAux. An added element is displayed on the custom Web page invoked from the AutoConnect menu. Parameters addonReference of AutoConnectElements. Specifies one of the AutoConnectElements classes. addonsAn array list of reference of AutoConnectElements. The list initialization with braced-init-list of the std::vector can be used for the addons parameter cause the actual definition of type AutoConnectElementVT is std::vector<std::reference_wrapper<AutoConnectElement>>.

    "},{"location":"apiaux.html#authentication","title":"authentication","text":"
    void authentication(const AC_AUTH_t auth)\n

    Set to require authentication with access to a page. When you access a page that requires authentication, HTTP authentication will be performed according to the scheme specified with the auth parameter. Parameters authSpecifies authentication scheme with the following enumeration value.

    • AC_AUTH_BASIC : Basic scheme.
    • AC_AUTH_DIGEST : Digest scheme.
    "},{"location":"apiaux.html#content","title":"content","text":"
    size_t content(void)\n

    Returns the number of AutoConnectElements the AutoConnectAux contains. Return valueA number of the registered AutoConnectElements.

    "},{"location":"apiaux.html#fetchelement","title":"fetchElement","text":"

    void fetchElement(void)\n
    Retrieve the values of the AutoConnectElements on the custom Web page. Refer to how to use the fetchElement.

    "},{"location":"apiaux.html#getelement","title":"getElement","text":"
    T& getElement<T>(const String& name)\n
    AutoConnectElement* getElement(const char* name)\n
    AutoConnectElement* getElement(const __FlashStringHelper* name)\n
    AutoConnectElement* getElement(const String& name)\n

    Get a registered AutoConnectElement as specified name. If T is specified as an actual type of AutoConnectElements, it returns a reference to that instance. Parameters TActual type name of AutoConnectElements as AutoConnectButton, AutoConnectCheckbox, AutoConnectElement, AutoConnectFile, AutoConnectInput, AutoConnectRadio, AutoConnectSelect, AutoConnectSubmit, AutoConnectText. nameName of the AutoConnectElements to be retrieved. Return valueA reference of the AutoConnectElements. If a type is not specified returns a pointer.

    "},{"location":"apiaux.html#getelements","title":"getElements","text":"
    AutoConnectElementVT& getElements(void)\n

    Get vector of reference of all elements. Return value A reference to std::vector of reference to AutoConnecctElements.

    The getElements returns a reference to std::vector of reference to AutoConnecctElements. This function is provided to handle AutoConnectElemets owned by AutoConnectAux in bulk, and you can use each method of std::vector for a return value.

    // An example of getting type and name of all AutoConnectElements registered in AutoConnectAux.\nAutoConnectAux aux;\n// some code here...\nAutoConnectElementVt& elements = aux.getElements();\nfor (AutoConnectElement& elm : elements) {\n    Serial.printf(\"name<%s> as type %d\\n\", elm.name.c_str(), (int)elm.typeOf());\n}\n
    "},{"location":"apiaux.html#ismenu","title":"isMenu","text":"
    bool isMenu(void)\n

    Returns whether embedded in the menu or not. The isMenu is a function that complements the menu function. Return value trueThe custom Web page has been incorporated into the AutoConnect menu as a menu item. falseThis custom Web page is not currently a menu item.

    "},{"location":"apiaux.html#isvalid","title":"isValid","text":"
    bool isValid(void)\n

    Performs validation of all AutoConnectInput elements owned by AutoConnectAux and returns the result. The isValid function will return the true even if the AutoConnectAux does not own AutoConnectInputs. Return value trueValidation is successful. A value of all AutoConnectInputs match with each pattern. falseSome elements failed validation.

    "},{"location":"apiaux.html#load","title":"load","text":"
    bool load(const String& in)\n
    bool load(PGM_P in)\n
    bool load(const __FlashStringHelper* in)\n
    bool load(Stream& in)\n

    Load all AutoConnectElements elements from JSON document into AutoConnectAux as custom Web pages. The JSON document specified by the load function must be the document structure of AutoConnectAux. Its JSON document can describe multiple pages as an array. Parameter inSpecifies the JSON document to be load. The load function can input the following objects.

    • String : Read-only String
    • PROGMEM : Character array contained in the flash
    • Stream : An entity that inherits stream class, generally SPIFFS or SD. Return value trueJSON document as the custom Web pages successfully loaded. falseJSON document loading failed.

    Load multiple custom Web pages separately

    Multiple custom Web pages can be loaded at once with JSON as an array. But it will consume a lot of memory. By loading a JSON document by page as much as possible, you can reduce memory consumption.

    "},{"location":"apiaux.html#loadelement","title":"loadElement","text":"
    bool loadElement(const String& in, const String& name = String(\"\"))\n
    bool loadElement(const String& in, std::vector<String> const& names)\n
    bool loadElement(PGM_P in, const String& name = String(\"\"))\n
    bool loadElement(PGM_P in, std::vector<String> const& names)\n
    bool loadElement(const __FlashStringHelper* in, const String& name = String(\"\"))\n
    bool loadElement(const __FlashStringHelper* in, std::vector<String> const& names)\n
    bool loadElement(Stream& in, const String& name = String(\"\"))\n
    bool loadElement(Stream& in, std::vector<String> const& names)\n

    Load specified element from JSON document into AutoConnectAux. The JSON document specified by the loadElement function must be the AutoConnectElement document structure. When loading from a JSON document that describes multiple elements, its description must be an array syntax. Parameters inSpecifies the JSON document to be load. The load function can input the following objects.

    • String : Read-only String
    • PROGMEM : Character array contained in the flash
    • Stream : An entity that inherits stream class, generally SPIFFS or SD. nameSpecifies the name to be load. If the name is not specified, the loadElement function will load all elements contained in the JSON document. names Specifies an array list of String indicating the name of the element to be loaded. The list initialization with braced-init-list of the std::vector can be used. Return value trueSpecified AutoConnectElements successfully loaded. falseJSON document loading failed.

    Maybe it is an array

    Please note that the JSON document that is the input for loadElement is an array syntax of AutoConnectElements when there are multiple elements. For example, the following JSON document has a syntax error:

    {\n\"name\": \"Caption\",\n\"type\": \"ACText\",\n\"value\": \"Hello, world\"\n},\n{\n\"name\": \"Server\",\n\"type\": \"ACInput\",\n\"label\": \"Server address\"\n}\n
    The outermost [, ] is missing.

    "},{"location":"apiaux.html#menu","title":"menu","text":"
    void menu(const bool post)\n

    Set or reset the display as menu item for this AutoConnectAux. This function programmatically manipulates the menu parameter of the AutoConnectAux constructor. Parameter trueShow on the menu. falseHidden on the menu.

    AutoConnectAux::menu and isMenu have no effect on AutoConnect built-in menu items

    Some of AutoConnect's built-in pages make use of AutoConnectAux class. You can use the AutoConnect::aux or AutoConnect::locate function with those URLs to retrieve the AutoConnectAux for built-in pages, but the menu function does not show/hide the built-in items of the menu list. Also, it is not recommended to use AutoConnect::aux or locate functions to get AutoConnect's built-in pages. Instructions on how to show/hide AutoConnect's built-in menu items can be found in the Applying the active menu items section.

    "},{"location":"apiaux.html#on","title":"on","text":"
    void on(const AuxHandlerFunctionT handler, const AutoConnectExitOrder_t order = AC_EXIT_AHEAD)\n
    Register the handler function of the AutoConnectAux. Parameters handlerA function that behaves when a request to the AutoConnectAux page occurs. AuxHandlerFunctionT type is defined by the following declaration.

    String handler(AutoConnectAux&, PageArgument&)

    orderSpecifies when the handler is called with the following enumeration value.
    • AC_EXIT_AHEAD : Called before AutoConnect generates the HTML of the page. You set the value of AutoConnectElements in the handler then its value will be displayed on the page.
    • AC_EXIT_LATER : Called after AutoConnect generates the HTML of the page. You can append to HTML generated by AutoConnect.
    • AC_EXIT_BOTH : Called even before generating HTML and after generated.
    "},{"location":"apiaux.html#onupload","title":"onUpload","text":"
    void onUpload<T&>(T handler)\n
    void onUpload(PageBuilder::UploadFuncT uploadFunc)\n

    Register the upload handler of the AutoConnectAux. Parameters TSpecifies a class name of the custom uploader inherited from AutoConnectUploadHandler class. Refer to the appendix for details. handlerSpecifies the custom uploader inherited from AutoConnectUploadHandler class. Refer to the appendix for details. uploadFuncA function that behaves when request to upload with the AutoConnectAux page. UploadFuncT type is defined by the following declaration.

    void(const String&, const HTTPUpload&)

    A data structure of the upload file as HTTPUpload. It is defined in the ESP8266WebServer (the WebServer for ESP32) library as follows:

    typedef struct {\n  HTTPUploadStatus status;\n  String  filename;\n  String  name;\n  String  type;\nsize_t  totalSize;\nsize_t  currentSize;\nsize_t  contentLength;\nuint8_t buf[HTTP_UPLOAD_BUFLEN];\n} HTTPUpload;\n

    Refer to 'To upload to a device other than Flash or SD' in section appendix for details.

    "},{"location":"apiaux.html#redirect","title":"redirect","text":"
    void redirect(const char* url)\n

    Generate a Location header field with the specified url and responds with a 302 response code to the client. This function is intended to be used from within the Custom Web Page handler. If the AutoConnectAux is going to redirect to another page without responding with page content, declare the responsive argument false in the AutoConnectAux constructor. With this construction, AutoConnectAux will not respond to HTTP responses. The redirect function can be useful in this situation to respond to a 302 redirect. Parameter urlSpecifies the URL to redirect a page to.

    "},{"location":"apiaux.html#referer","title":"referer","text":"
    AutoConnectAux& referer(void)\n

    Returns a reference to the AutoConnectAux from which this AutoConnectAux was called. Return value A reference to the AutoConnectAux from which this AutoConnectAux was called. If the source of the transition is not an AutoConnectAux page, it returns a reference to itself.

    "},{"location":"apiaux.html#release","title":"release","text":"
    bool release(const String& name)\n

    Release a specified AutoConnectElement from AutoConnectAux. The release function is provided to dynamically change the structure of the custom Web pages with the Sketch. By combining the release function and the add function or the loadElement function, the Sketch can change the style of the custom Web page according to its behavior. Parameter nameSpecifies the name of AutoConnectElements to be released. Return value trueThe AutoConnectElement successfully released. falseThe AutoConnectElement can not be released.

    "},{"location":"apiaux.html#saveelement","title":"saveElement","text":"
    size_t saveElement(Stream& out, std::vector<String> const& names = {})\n

    Write elements of AutoConnectAux to the stream. The saveElement function outputs the specified AutoConnectElements as a JSON document using the prettyPrintTo function of the ArduinoJson library. Parameters outOutput stream to be output. SPIFFS, SD also Serial can be specified generally. namesThe array of the name of AutoConnectElements to be output. If the names parameter is not specified, all AutoConnectElements registered in AutoConnectAux are output. Return value The number of bytes written.

    The output format is pretty

    The saveElement function outputs a prettified JSON document.

    It is not complementary with loadElement

    The saveElement function which missing the names parameter without name list to be saved that saves an entire AutoConnectAux element, not just AutoConnectElements. Its saved JSON document is not a complementary input to the loadElement function. The JSON document describing AutoConnectAux saved without the names parameter must be loaded by the AutoConnectAux::load function or AutoConnect::load function.

    "},{"location":"apiaux.html#setelementvalue","title":"setElementValue","text":"
    bool setElementValue(const String& name, const String value)\n
    bool setElementValue(const String& name, std::vector<String> const& values)\n

    Sets the value of the specified AutoConnectElement. If values is specified as a std::vector of String, the element that can set the values is the AutoConnectRadio or the AutoConnectSelect. Parameters nameSpecifies the name of the AutoConnectElements that you want to set the value. valueSpecifies the value to be set. valuesSpecifies a reference of a std::vector of String. It contains the values of the AutoConnectRadio or the AutoConnectSelect. Return value trueThe value has been set. falseAutoConnectElements with the specified name are not registered. Or the type of the value is not consistent with the specified AutoConnectElements.

    You can directly access the value member variable.

    If you are gripping with the Sketch to the AutoConnectElements of the target that sets the value, you can access the value member variable directly. The following sketch code has the same effect. 

    AutoConnectAux aux;\n// ... Griping the AutoConnectText here.\naux.setElementValue(\"TEXT_FIELD\", \"New value\");\n
    AutoConnectAux aux;\n// ... Griping the AutoConnectText here.\nAutoConnectText& text = aux.getElement<AutoConnectText>(\"TEXT_FIELD\");\ntext.value = \"New value\";\n
    The difference between the setElementValue and the value access with the getElement is the certainty of the registration state for the element. The getElement returns an empty object if the element is not registered then a sketch assigns the value to it. May occur unexpected results and crashes. You should use the setElementValue if its registration is unsettled.

    "},{"location":"apiaux.html#settitle","title":"setTitle","text":"
    void setTitle(const String& title)\n

    Set the title string of the custom Web page. This title will be displayed as the menu title of the custom Web page. Parameter titleTitle string to be display.

    Not the menu title

    The setTitle function is not set for the AutoConnect menu title. The effect of this function is that custom Web page only. To change the AutoConnect menu title use AutoConnectConfig::title.

    "},{"location":"apiconfig.html","title":"AutoConnectConfig API","text":"

    The AutoConnectConfig class does not present some members regarding custom web page features due to differences in the AutoConnect component used in the sketch.

    Sketch allows by including either AutoConnect.h or AutoConnectCore.h header file to use the AutoConnect library. If you include the AutoConnectCore.h with the sketch, AutoConnect will drop the functions involved custom web page facility. And correspondingly, some members that depend on custom web page functions will omit from the AutoConnectConfig class. See the Reducing Binary Size chapter for details.

    "},{"location":"apiconfig.html#constructor","title":"Constructor","text":""},{"location":"apiconfig.html#autoconnectconfig","title":"AutoConnectConfig","text":"
    AutoConnectConfig()\n
    AutoConnectConfig(const char* ap, const char* password)\n
    AutoConnectConfig(const char* ap, const char* password, const unsigned long timeout)\n
    AutoConnectConfig(const char* ap, const char* password, const unsigned long timeout, const uint8_t channel)\n
    Parameters apSSID for SoftAP. The length should be up to 31. The default value is esp8266ap for ESP8266, esp32ap for ESP32. passwordPassword for SoftAP. The length should be from 8 to up to 63. The default value is 12345678. timeoutThe timeout value of the captive portal in [ms] units. The default value is 0. channelThe channel number of WIFi when SoftAP starts. The default values is 1."},{"location":"apiconfig.html#public-member-variables","title":"Public member variables","text":""},{"location":"apiconfig.html#apid","title":"apid","text":"

    SoftAP's SSID. Type StringThe default value is esp8266ap for ESP8266, esp32ap for ESP32.

    "},{"location":"apiconfig.html#apip","title":"apip","text":"

    Sets IP address for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this. Type IPAddressThe default value is 172.217.28.1

    "},{"location":"apiconfig.html#auth","title":"auth","text":"

    Apply HTTP authentication with the AutoConnect web page. This This setting allows the Sketch to authenticate with \"BASIC\" or \"DIGEST\" scheme. It is given as an enumeration value of AC_AUTH_t that indicates the authentication scheme. This setting determines the default scheme for HTTP authentication with AutoConnect. When the AutoConnectConfig::authScope is AC_AUTHSCOPE_PARTIAL, each AutoConnectAux authentication scheme has priority. Type AC_AUTH_t Value AC_AUTH_NONE No authentication. This is the default. AC_AUTH_DIGEST Use the digest scheme. AC_AUTH_BASIC Use the basic scheme.

    "},{"location":"apiconfig.html#authscope","title":"authScope","text":"

    Specifies the authentication scope of AutoConnect Web pages. The Sketch will be able to expand or narrow the range of authentication by this setting, which can be either as AC_AUTHSCOPE_t enumeration value. Type AC_AUTHSCOPE_t Value AC_AUTHSCOPE_AUX Require authentication to access for all custom Web pages, excepting AutoConnect's pages. This is the Default. AC_AUTHSCOPE_PARTIAL Authenticate only specific custom Web pages which are specified by AutoConnectAux::authentication function or JSON description. AC_AUTHSCOPE_PORTAL Require authentication to access for all AutoConnect's pages, including custom Web pages.

    This setting is available only when AutoConnectConfig::auth is other than AC_AUTH_NONE. Ignored if it is AC_AUTH_NONE.

    Also, the authScope setting has another bit that indicates to allow authentication in the captive portal state. Its enum value cannot be used alone and is always for qualifying the above three enum values. Value AC_AUTHSCOPE_WITHCP Allow authentication with the captive portal state. This value cannot be used alone to declare an authentication scope. It indicates to enable authentication in the captive portal by the logical OR operator with one of the AC_AUTHSCOPE_t values above.

    "},{"location":"apiconfig.html#autoreconnect","title":"autoReconnect","text":"

    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 bool Value trueReconnect automatically. falseStarts Captive Portal in SoftAP + STA mode without trying to reconnect. This is the default.

    When the autoReconnect option is enabled, an automatic connection will behave if the following conditions are satisfied.

    • Invokes AutoConnect::begin without user name and password parameter as begin().
    • If one of the saved credentials matches the BSSID (or SSID) detected by the network scan.

    Either BSSID or SSID to aim the access point

    Whether or not it points to the target access point is determined by matching the SSID or BSSID. The default key to collate is BSSID. The BSSID is usually fixed to the MAC address unique to its access point device, but when using some mobile hotspots, the BSSID may change even for the same access point. If you operate inconvenience in aiming at the access point by BSSID, you can change the collation key to SSID by uncomment the below line in AutoConnectDefs.h:

    #define AUTOCONNECT_APKEY_SSID\n

    If AUTOCONNECT_APKEY_SSID macro is defined when the library is compiled, the access points are collated by the SSID.

    "},{"location":"apiconfig.html#autoreset","title":"autoReset","text":"

    Reset ESP8266 module automatically after WLAN disconnected. Type bool Value trueReset after WiFi disconnected automatically. falseNo reset.

    "},{"location":"apiconfig.html#autorise","title":"autoRise","text":"

    Captive portal activation switch. False for disabling the captive portal. It prevents starting the captive portal even if the connection at the 1st-WiFi.begin fails. Type bool Value trueEnable the captive portal. This is the default. falseDisable the captive portal.

    "},{"location":"apiconfig.html#autosave","title":"autoSave","text":"

    The credential saved automatically at the connection establishment. Type AC_SAVECREDENTIAL_t Value AC_SAVECREDENTIAL_AUTO The credential saved automatically. This is the default. AC_SAVECREDENTIAL_ALWAYS Save specified SSID and Password always even if a specified credential has been rejected. AC_SAVECREDENTIAL_NEVER The credential no saved.

    "},{"location":"apiconfig.html#begintimeout","title":"beginTimeout","text":"

    Specify the limit time to attempt WiFi connection to the access point. AutoConnect uses this value to abort the connection attempt at WiFi.begin. Its actual value specified in milliseconds unit. The default value is AUTOCONNECT_TIMEOUT defined in AutoConnectDefs.h and the initial value is 30 seconds. Type unsigned long

    "},{"location":"apiconfig.html#booturi","title":"bootUri","text":"

    Specify the location to be redirected after module reset in the AutoConnect menu. It is given as an enumeration value of AC_ONBOOTURI_t indicating either the AutoConnect root path or the user screen home path. Type AC_ONBOOTURI_t Value AC_ONBOOTURI_ROOT Resetting the module redirects it to the AutoConnect root path. The root path is assumed to be AUTOCONNECT_URI defined in AutoConnectDefs.h. AC_ONBOOTURI_HOME It is redirected to the URI specified by AutoConnectConfig::homeUri.

    "},{"location":"apiconfig.html#boundaryoffset","title":"boundaryOffset","text":"

    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. This option is valid only for ESP8266 or ESP32 arduino core 1.0.2 earlier. Type uint16_t

    It will conflict with user data.

    If the Sketch leaves this offset at zero, it will conflict the storage area of credentials with the user sketch owned data. It needs to use the behind of credential area.

    "},{"location":"apiconfig.html#channel","title":"channel","text":"

    The channel number of WIFi when SoftAP starts. Type uint8_t Value 1 ~ 14. The default value is 1.

    How do I choose Channel

    Espressif Systems had announced the application note about Wi-Fi channel selection.

    "},{"location":"apiconfig.html#dns1","title":"dns1","text":"

    Set primary DNS server address when using static IP address. Type IPAddress

    "},{"location":"apiconfig.html#dns2","title":"dns2","text":"

    Set secondary DNS server address when using static IP address. Type IPAddress

    "},{"location":"apiconfig.html#gateway","title":"gateway","text":"

    Sets gateway address for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this. Type IPAddressThe default value is 172.217.28.1

    "},{"location":"apiconfig.html#hidden","title":"hidden","text":"

    Sets SoftAP to hidden SSID. Type uint8_t Value 0SSID will be appeared. This is the default. 1SSID will be hidden.

    "},{"location":"apiconfig.html#homeuri","title":"homeUri","text":"

    Sets the home path of user sketch. This path would be linked from 'HOME' in the AutoConnect menu. The default for homeUri is \"/\". Type String

    "},{"location":"apiconfig.html#hostname","title":"hostName","text":"

    Sets the station host name of ESP8266/ESP32. Type String

    "},{"location":"apiconfig.html#immediatestart","title":"immediateStart","text":"

    Disable the 1st-WiFi.begin and start the captive portal. If this option is enabled, the module will be in AP_STA mode and the captive portal. The evaluation rank of this parameter is lower than the AutoConnectConfig::autoRise. Even if immediateStart is true, the captive portal will not launch if autoRise is false. Type bool Value trueStart the captive portal with AutoConnect::begin. falseEnable the 1st-WiFi.begin and it will start captive portal when connection failed. This is default.

    "},{"location":"apiconfig.html#menuitems","title":"menuItems","text":"

    Configure applying items of the AutoConnect menu. You can arbitrarily combine valid menus by coordinating the menuItems value. Type uint16_tIt provides the combined AC_MENUITEM_t value of the item to apply to the AutoConnect menu.Specify the value calculated from the logical OR by the AC_MENUITEM_t value of each item applied as a menu. It affects not only disappear the items from the menu also invalidates the URI they have. As a consequence, even if it accesses the URL directly will occur a 404 error.The default value is logical OR of AC_MENUITEM_CONFIGNEW, AC_MENUITEM_OPENSSIDS, AC_MENUITEM_DISCONNECT, AC_MENUITEM_RESET, AC_MENUITEM_UPDATE and AC_MENUITEM_HOME. Value AC_MENUITEM_NONE No assign items except for the AutoConnectAux page item. AC_MENUITEM_CONFIGNEW Appends Configure new AP item. AC_MENUITEM_OPENSSIDS Appends Open SSIDs item. AC_MENUITEM_DISCONNECT Appends Disconnect item. AC_MENUITEM_RESET Appends Reset... item. AC_MENUITEM_UPDATE Appends Update item. This value is valid only for AutoConnect; it is not available for AutoConnectCore. AC_MENUITEM_HOME Appends HOME item. AC_MENUITEM_DEVINFO Appends the Device info item which links to AutoConnect statistics page. AC_MENUITEM_DELETESSID Enables the ability to interactively delete credentials on the Open SSIDs menu screen.

    How to specify the value of the menu items

    An menuItems accepts the logical OR of AC_MENUITEM_t type value. For example, to enable only Open SSIDs and HOME items, specify: 

    AutoConnect portal;\nAutoConnectConfig config;\n\nconfig.menuItems = AC_MENUITEM_OPENSSIDS | AC_MENUITEM_HOME;\nportal.config(config);\n
    Also, to enable the credentials removal feature, follow these settings procedures. 
    AutoConnect portal;\nAutoConnectConfig config;\n\nconfig.menuItems = config.menuItems | AC_MENUITEM_DELETESSID;\nportal.config(config);\n
    However, even if you specify like the above, the AutoConnectAux page items still display on the menu. To remove the AutoConnectAux items, use the AutoConnectAux::menu function.

    "},{"location":"apiconfig.html#minrssi","title":"minRSSI","text":"

    Specify the lower limit of the WiFi signal strength allowed to use as an access point. This value should be greater than -120 as RSSI. Generally, a data link will not be established unless it exceeds -90 dBm. Also, packet transmission is not reliable below -70 dBm to -80 dBm. Type int16_tThe default value is -120

    "},{"location":"apiconfig.html#netmask","title":"netmask","text":"

    Sets subnet mask for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this. Type IPAddressThe default value is 255.255.255.0

    "},{"location":"apiconfig.html#ota","title":"ota","text":"

    Specifies to import the built-in OTA update class into the Sketch. When this option is enabled, an Update item will appear in the AutoConnect menu, and the OTA update via Web browser will be automatically embedded to the Sketch. Type AC_OTA_t Value AC_OTA_EXTRA AutoConnect does not import AutoConnectOTA. This is the default. AC_OTA_BUILTIN Specifies to include AutoConnectOTA in the Sketch.

    "},{"location":"apiconfig.html#otaextracaption","title":"otaExtraCaption","text":"

    Specifies the caption to be displayed as an extra on the OTA update screen. The extra caption you specified will be displayed in the upper right corner of the OTA update screen. Also, you can only specify the caption string, and you cannot specify the style individually. An extra caption will draw up with the default style of AutoConnect. Type const char* An extra caption string pointer.

    "},{"location":"apiconfig.html#password","title":"password","text":"

    Set the password for authentication. Type String The default value is same as psk.

    "},{"location":"apiconfig.html#portaltimeout","title":"portalTimeout","text":"

    Specify the timeout value of the captive portal in [ms] units. It is valid when the station is not connected and does not time out if the station is connected to the ESP module in SoftAP mode (i.e. Attempting WiFi connection with the portal function). If 0, the captive portal will not be timed-out. Type unsigned longCaptive portal timeout value. The default value is 0.

    "},{"location":"apiconfig.html#preserveapmode","title":"preserveAPMode","text":"

    Specifies starting the STA while maintaining the state of the SoftAP mode in the AutoConnect::begin. This setting only applies when the AutoConnectConfig::autoRise is false. Type bool Value trueAutoConnect::begin keeps AP mode. falseAutoConnect::begin will stop SoftAP at the beginning of the process.

    Note that this option is not for starting the SoftAP forcibly in AutoConnect::begin and only keeps AP mode, SoftAP initiation is left to the Sketch.

    "},{"location":"apiconfig.html#preserveip","title":"preserveIP","text":"

    When using existing credentials to connect WiFi, the station IP configuration specified with the AutoConnectConfig::staip, AutoConnectConfig::staGateway, and AutoConnectConfig::staNetmask are preferred over the IP settings of the stored credentials. If this value is set to true, IP configurations stored with credentials will not be restored. Type bool Value trueUse IP addresses specified with the AutoConnectConfig::staip, AutoConnectConfig::staGateway, and AutoConnectConfig::staNetmask as the station IP configuration. falseWhen reconnecting, the station IP configuration specified with AutoConnectConfig is ignored and the saved credential values are used.

    "},{"location":"apiconfig.html#principle","title":"principle","text":"

    Specify the connection order will attempt to connect to one of the highest RSSI values among multiple available access points. It is given as an enumeration value of AC_PRINCIPLE_t indicating. Type AC_PRINCIPLE_t Value AC_PRINCIPLE_RECENT Attempts to connect in the order of the saved credentials entries. The entry order is generally a time series connected in the past. AC_PRINCIPLE_RSSI Attempts to connect to one of the highest RSSI values among multiple available access points.

    "},{"location":"apiconfig.html#psk","title":"psk","text":"

    Sets password for SoftAP. The length should be from 8 to up to 63. The default value is 12345678. Type String

    "},{"location":"apiconfig.html#reconnectinterval","title":"reconnectInterval","text":"

    Specifies the number of units for interval time to attempt automatic reconnection when AutoConnectConfig::autoReconnect is enabled. This value is specified by the number of unit times from 0 to 255, and one unit time is macro-defined as AUTOCONNECT_UNITTIME in AutoConnectDefs.h file of library source code, and its initial value is 30[s]. Type uint8_t

    WiFi connection retry is repeated inside AutoConnect::handleClient after the number of seconds that the reconnectInterval value is multiplied by AUTOCONNECT_UNITTIME from the previous attempt. Then, when the connection with one of the saved credentials is established, the automatic reconnection will stop. And while AutoConnectConfig::autoReconnect is enabled, if the WiFi connection is lost, it will start to auto-reconnect again inside AutoConnect::handleClient.

    If 0 is specified for the reconnectInterval, background reconnection attempt repeatedly will not be made, and only once at the 1st-WiFi.begin failure in AutoConnect::begin. (Only when AutoConnectConfig::autoReconnect is enabled) The default value is 0.

    AUTOCONNECT_UNITTIME

    AUTOCONNECT_UNITTIME as macro defined in AutoConnectDefs.h file of library source code as the below: 

    // Number of seconds in uint time [s]\n#ifndef AUTOCONNECT_UNITTIME\n#define AUTOCONNECT_UNITTIME    30\n#endif\n

    "},{"location":"apiconfig.html#retainportal","title":"retainPortal","text":"

    Specify whether to continue the portal function even if the captive portal timed out. If the true, when a timeout occurs, the AutoConnect::begin function is exited with returns false, but the portal facility remains alive. So SoftAP remains alive and you can invoke AutoConnect while continuing sketch execution. The default is false. Type bool Value trueContinue the portal function even if the captive portal times out. The STA + SoftAP mode of the ESP module continues and accepts the connection request to the AP. falseWhen the captive portal times out, STA + SoftAP mode of the ESP module is stopped. This is default.

    Connection request after timed-out

    With the retainPortal, even if AutoConnect::begin in the setup() is timed out, you can execute the Sketch and the portal function as a WiFi connection attempt by calling AutoConnect::handleClient in the loop().

    All unresolved addresses redirects /_ac

    If you enable the retainPortal option, all unresolved URIs will be redirected to SoftAPIP/_ac. It happens frequently as client devices repeat captive portal probes in particular. To avoid this, you need to exit from the WiFi connection Apps on your device once.

    "},{"location":"apiconfig.html#staip","title":"staip","text":"

    Set a static IP address. The IP will behave with STA mode. Type IPAddress

    "},{"location":"apiconfig.html#stagateway","title":"staGateway","text":"

    Set the gateway address when using static IP address. Type IPAddress

    "},{"location":"apiconfig.html#stanetmask","title":"staNetmask","text":"

    Set the subnetmask when using static IP address. Type IPAddress

    "},{"location":"apiconfig.html#ticker","title":"ticker","text":"

    Set flicker signal output according to WiFi connection status during AutoConnect::begin behavior. Type bool Value trueOutput the flicker signal while AutoConnect::begin operation. The AUTOCONNECT_TICKER_PORT macro in the AutoConnectDefs.h header file assigns pins for signal output. The default pin is arduino valiant's LED_BUILTIN. For boards without the LED_BUILTIN pin, assume pin #2. falseNo flicker signal output.

    "},{"location":"apiconfig.html#tickerport","title":"tickerPort","text":"

    Specifies the GPIO port number to output the flicker signal of the ticker. The default assumes on the board dependent definition LED_BUILTIN macro redefined by AUTOCONNECT_TICKER_PORT in AutoConnectDefs.h. Type uint8_t

    "},{"location":"apiconfig.html#tickeron","title":"tickerOn","text":"

    Specifies the active logic level of the flicker signal. This value indicates the active signal level when driving the ticker. Type uint8_t Value LOWA flicker signal is an active-high. HIGHA flicker signal is an active-low.

    "},{"location":"apiconfig.html#title","title":"title","text":"

    Set the menu title. Type String

    "},{"location":"apiconfig.html#uptime","title":"uptime","text":"

    Specifies the waiting time for the module to reboot. Type intThe default value is AUTOCONNECT_TIMEOUT/1000.

    "},{"location":"apiconfig.html#username","title":"username","text":"

    Set the username for authentication. Type StringThe default value is same as apid.

    "},{"location":"apiconfig.html#autoconnectconfig-initial-values","title":"AutoConnectConfig Initial values","text":"Public member Data type Initial value definition Defined symbol 1 apid String esp8266apesp32ap AUTOCONNECT_APID apip IPAddress 172.217.28.1 AUTOCONNECT_AP_IP auth AC_AUTH_t AC_AUTH_NONE AC_AUTH_NONEAC_AUTH_DIGESTAC_AUTH_BASIC authScope AC_AUTHSCOPE_t AC_AUTHSCOPE_AUX AC_AUTHSCOPE_PARTIALAC_AUTHSCOPE_AUXAC_AUTHSCOPE_ACAC_AUTHSCOPE_PORTALAC_AUTHSCOPE_WITHCP autoReconnect bool false autoReset bool true autoRise bool true autoSave AC_SAVECREDENTIAL_t AC_SAVECREDENTIAL_AUTO AC_SAVECREDENTIAL_AUTOAC_SAVECREDENTIAL_ALWAYSAC_SAVECREDENTIAL_NEVER beginTimeout unsinged long 30000UL AUTOCONNECT_TIMEOUT bootUri AC_ONBOOTURI_t AC_ONBOOTURI_ROOT AC_ONBOOTURI_ROOTAC_ONBOOTURI_HOME boundaryOffset uint16_t 0 AC_IDENTIFIER_OFFSET channel uint8_t 1 AUTOCONNECT_AP_CH dns1 IPAddress 0UL dns2 IPAddress 0UL gateway IPAddress 172.217.28.1 AUTOCONNECT_AP_GW hidden uint8_t 0 homeUri String / AUTOCONNECT_HOMEURI hostName String NULL immediateStart bool false menuItems uint16_t AC_MENUITEM_CONFIGNEW+ AC_MENUITEM_OPENSSIDS+ AC_MENUITEM_DISCONNECT+ AC_MENUITEM_RESET+ AC_MENUITEM_UPDATE+ AC_MENUITEM_HOME AC_MENUITEM_CONFIGNEWAC_MENUITEM_OPENSSIDSAC_MENUITEM_DISCONNECTAC_MENUITEM_RESETAC_MENUITEM_UPDATEAC_MENUITEM_HOME minRSSI int16_t -120 AUTOCONNECT_MIN_RSSI netmask IPAddress 172.217.28.1 AUTOCONNECT_AP_NM ota AC_OTA_t AC_OTA_EXTRA AC_OTA_EXTRAAC_OTA_BUILTIN otaExtraCaption const char* nullptr password String Follow psk portalTimeout unsigned long 0UL AUTOCONNECT_CAPTIVEPORTAL_TIMEOUT preserveAPMode bool false principle AC_PRINCIPLE_t AC_PRINCIPLE_RECENT AC_PRINCIPLE_RECENTAC_PRINCIPLE_RSSI psk String 12345678 AUTOCONNECT_PSK reconnectInterval uint8_t 0 retainPortal bool false staGateway IPAddress 0UL staip IPAddress 0UL staNetmask IPAddress 0UL ticker bool false tickerOn uint8_t LOW AUTOCONNECT_UPDATE_LEDON tickerPort uint8_t LED_BUILTIN AUTOCONNECT_TICKER_PORT title String AutoConnect AUTOCONNECT_MENU_TITLE uptime int AUTOCONNECT_TIMEOUT/1000 AUTOCONNECT_STARTUPTIME username String Follow apid"},{"location":"apiconfig.html#autoconnectconfig-example","title":"AutoConnectConfig example","text":"
    AutoConnect        Portal;\nAutoConnectConfig  Config(\"\", \"passpass\");    // SoftAp name is determined at runtime\nConfig.apid = ESP.hostname();                 // Retrieve host name to SotAp identification\nConfig.apip = IPAddress(192,168,10,101);      // Sets SoftAP IP address\nConfig.gateway = IPAddress(192,168,10,1);     // Sets WLAN router IP address\nConfig.netmask = IPAddress(255,255,255,0);    // Sets WLAN scope\nConfig.autoReconnect = true;                  // Enable auto-reconnect\nConfig.autoSave = AC_SAVECREDENTIAL_NEVER;    // No save credential\nConfig.boundaryOffset = 64;                   // Reserve 64 bytes for the user data in EEPROM.\nConfig.portalTimeout = 60000;                 // Sets timeout value for the captive portal\nConfig.retainPortal = true;                   // Retains the portal function after timed-out\nConfig.homeUri = \"/index.html\";               // Sets home path of Sketch application\nConfig.title =\"My menu\";                      // Customize the menu title\nConfig.staip = IPAddress(192,168,10,10);      // Sets static IP\nConfig.staGateway = IPAddress(192,168,10,1);  // Sets WiFi router address\nConfig.staNetmask = IPAddress(255,255,255,0); // Sets WLAN scope\nConfig.dns1 = IPAddress(192,168,10,1);        // Sets primary DNS address\nPortal.config(Config);                        // Configure AutoConnect\nPortal.begin();                               // Starts and behaves captive portal\n

    1. Those symbols are defined in AutoConnectDefs.h.\u00a0\u21a9

    "},{"location":"apielements.html","title":"AutoConnectElements API","text":"

    Only for AutoConnect

    The following AutoConnectElements are valid only for AutoConnect; they are not available for AutoConnectCore.

    "},{"location":"apielements.html#autoconnectbutton","title":"AutoConnectButton","text":""},{"location":"apielements.html#constructor","title":"Constructor","text":"
    AutoConnectButton(const char* name = \"\", const char* value = \"\", const String& action = String(), const ACPosterior_t post = AC_Tag_None)\n
    Parameters nameThe element name. valueValue of the element. actionNative code of the action script executed when the button is clicked. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables","title":"Public member variables","text":""},{"location":"apielements.html#action","title":"action","text":"

    HTML native code of the action script to be executed when the button is clicked. It is mostly used with a JavaScript to activate a script.1 Type String

    "},{"location":"apielements.html#enable","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#name","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#value","title":"value","text":"

    Value of the element. Type String

    "},{"location":"apielements.html#public-member-functions","title":"Public member functions","text":""},{"location":"apielements.html#canhandle","title":"canHandle","text":"
    bool canHandle(void)\n

    Returns whether the AutoConnectButton element has a registered event handler and can respond to a click event. Return value trueAn event handler is registered. The element can correspond to a click event. falseAn event handler is not registered.

    "},{"location":"apielements.html#off","title":"off","text":"
    void off(void)\n

    Release a registered event handler so that the element does not react to events.

    "},{"location":"apielements.html#on","title":"on","text":"
    void on(std::function<void(AutoConnectButton&, AutoConnectAux&)> eventHandler)\n

    Register an event handler function so that the element can respond to a click event. Parameter eventHandlerA function instance corresponding to a click event on AutoConnectButton. It allows giving with lambda expressions.

    An eventHandler function will be called when a click event occurs with the AutoConnectButton. Its prototype declaration is follows:

    void eventHandler(AutoConnectButton& me, AutoConnectAux& aux)\n
    Parameter meA reference to the instance of the AutoConnectButton that fired the click event. auxReference to the AutoConnectAux instance to which the AutoConnectButton that generated the click event belongs."},{"location":"apielements.html#response","title":"response","text":"
    void response(const char* value)\n
    void response(const char* attribute, const char* value)\n

    Reply the value or attribute of an element to the client. The response is usually used for sending a reply to the client with the element's value or attribute that has been updated in an event handler function.

    The response function itself does not perform communication. It only temporarily accumulates updated values. The stored content constitutes the response data to the HTTP POST request sent from the client browser caused by the AutoConnectElements event.

    The response function has two overloads with different numbers of arguments. A response function suitable for just one argument will only update the value of the AutoConnectButton. It also stores the updated value of the button caption text (i.e., the innerHTML attribute dependent on the button type=\"button\" element) into the response data for real-time rendering in the browser upon response. Also, a response function suitable for two arguments allows updating all attributes of the HTML button type=\"button\" element derived from AutoConnectButton. Parameter valueSuitable for one argument format: A changing value of AutoConnectButton::value as response. It also will update the innerHTML attribute of the button type=\"button\" element derived from AutoConnectButton.Suitable for two argument format: Specifies a value of the HTML button type=\"button\" element to be modified as specified in the attribute argument. attributeAn attribute name of an HTML button type=\"button\" element to be changed.

    "},{"location":"apielements.html#typeof","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectButton. Return value AC_Button

    "},{"location":"apielements.html#autoconnectcheckbox","title":"AutoConnectCheckbox","text":""},{"location":"apielements.html#constructor_1","title":"Constructor","text":"
    AutoConnectCheckbox(const char* name = \"\", const char* value = \"\", const char* label = \"\", const bool checked = false, const ACPosition_t labelPosition = AC_Behind, const ACPosterior_t post = AC_Tag_BR)\n
    Parameters nameThe element name. valueValue of the element. labelA label string prefixed to the checkbox. checkChecked state of the checkbox. labelPositionSpecifies the position of the label to generate. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_1","title":"Public member variables","text":""},{"location":"apielements.html#checked","title":"checked","text":"

    It indicates the checked status of the checkbox. The value of the checked checkbox element is packed in the query string and sent by submit. Type bool"},{"location":"apielements.html#enable_1","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_1","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#label","title":"label","text":"

    A label is an optional string. A label is always arranged on the right side of the checkbox. Specification of a label will generate an HTML <label> tag with an id attribute. The checkbox and the label are connected by the id attribute. Type String

    "},{"location":"apielements.html#labelposition","title":"labelPosition","text":"

    Specifies the position of the label to generate with ACPostion_t enumeration value. Type ACPosition_t

    • AC_Infront : Place a label in front of the check box.
    • AC_Behind : Place a label behind the check box.
    "},{"location":"apielements.html#name_1","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_1","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#value_1","title":"value","text":"

    Value of the element. It becomes a value attribute of an HTML <input type=\"checkbox\"> tag. Type String

    "},{"location":"apielements.html#public-member-functions_1","title":"Public member functions","text":""},{"location":"apielements.html#canhandle_1","title":"canHandle","text":"
    bool canHandle(void)\n

    Returns whether the AutoConnectCheckbox element has a registered event handler and can respond to a change event. Return value trueAn event handler is registered. The element can correspond to a change event. falseAn event handler is not registered.

    "},{"location":"apielements.html#off_1","title":"off","text":"
    void off(void)\n

    Release a registered event handler so that the element does not react to events.

    "},{"location":"apielements.html#on_1","title":"on","text":"
    void on(std::function<void(AutoConnectCheckbox&, AutoConnectAux&)> eventHandler)\n

    Register an event handler function so that the element can respond to a change event. Parameter eventHandlerA function instance corresponding to a change event on AutoConnectCheckbox. It allows giving with lambda expressions.

    An eventHandler function will be called when a change event occurs with the AutoConnectCheckbox. Its prototype declaration is follows:

    void eventHandler(AutoConnectCheckbox& me, AutoConnectAux& aux)\n
    Parameter meA reference to the instance of the AutoConnectCheckbox that fired the change event. auxReference to the AutoConnectAux instance to which the AutoConnectCheckbox that generated the change event belongs."},{"location":"apielements.html#response_1","title":"response","text":"
    void response(const bool checked)\n
    void response(const char* attribute, const char* value)\n

    Reply the value or attribute of an element to the client. The response is usually used for sending a reply to the client with the element's value or attribute that has been updated in an event handler function.

    The response function itself does not perform communication. It only temporarily accumulates updated values. The stored content constitutes the response data to the HTTP POST request sent from the client browser caused by the AutoConnectElements event.

    The response function has two overloads with different numbers of arguments. A response function suitable for just one argument will only update the check status of the AutoConnectCheckbox. Also, a response function suitable for two arguments allows updating all attributes of the HTML input type=\"checkbox\" element derived from AutoConnectCheckbox. Parameter checkedA changing checked status of AutoConnectCheckbox::checked as response. valueSpecifies a value of the HTML input type=\"checkbox\" element to be modified as specified in the attribute argument. attributeAn attribute name of an HTML input type=\"checkbox\" element to be changed.

    "},{"location":"apielements.html#typeof_1","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectCheckbox. Return value AC_Checkbox

    "},{"location":"apielements.html#autoconnectelement","title":"AutoConnectElement","text":""},{"location":"apielements.html#constructor_2","title":"Constructor","text":"
    AutoConnectElement(const char* name = \"\", const char* value = \"\", const ACPosterior_t post = AC_Tag_None)\n
    Parameters nameThe element name. valueValue of the element. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_2","title":"Public member variables","text":""},{"location":"apielements.html#enable_2","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_2","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#name_2","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_2","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#value_2","title":"value","text":"

    Value of the element. It is output as HTML as it is as a source for generating HTML code. Type String

    "},{"location":"apielements.html#public-member-functions_2","title":"Public member functions","text":""},{"location":"apielements.html#typeof_2","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectElement. Return value AC_Element

    "},{"location":"apielements.html#ast","title":"as<T>","text":"
    AutoConnectElement& as<T>(void)\n

    Casts the reference to the AutoConnectElement the specified type. Parameter TThe element type. AutoConnectElements type such as AutoConnectButton, AutoConnectCheckbox, AutoConnectFile, AutoConnectInput, AutoConnectRadio, AutoConnectSelect, AutoConnectStyle, AutoConnectSubmit, AutoConnectText. Return value A reference to the AutoConnectElement with actual type.

    "},{"location":"apielements.html#autoconnectfile","title":"AutoConnectFile","text":""},{"location":"apielements.html#constructor_3","title":"Constructor","text":"
    AutoConnectFile(const char* name = \"\", const char* value = \"\", const char* label = \"\", const ACFile_t store = AC_File_FS, const ACPosterior_t post = AC_Tag_BR)\n
    Parameters nameThe element name. valueFile name to be upload. labelLabel string. storeThe ACFile_t enumerator that represents the media to save the uploaded file. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_3","title":"Public member variables","text":""},{"location":"apielements.html#enable_3","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_3","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#label_1","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the file input box. Specification of a label will generate an HTML <label> tag with an id attribute. The file input box and the label are connected by the id attribute. Type String

    "},{"location":"apielements.html#mimetype","title":"mimeType","text":"

    The mime type of the upload file which included as Media type in the http post request. Set by the client (usually the browser) that requested the upload. It is determined by the file type as application/octet-stream, text etc. which is described in IANA Media Type. Type String

    "},{"location":"apielements.html#name_3","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_3","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#size","title":"size","text":"

    Size of the uploading file. Type size_t

    "},{"location":"apielements.html#store","title":"store","text":"

    Specifies the save destination of the uploaded file. You can use the built-in uploader to save uploaded file to the flash of the ESP8266/ESP32 module or external SD media without writing a dedicated sketch code. It also supports saving to any destination using a custom uploader that inherits from the AutoConnectUploadHandler class. Type ACFile_t

    • AC_File_FS : Save the uploaded file to SPIFFS in the flash.
    • AC_File_SD : Save the uploaded file to SD.
    • AC_File_Extern : Save the file using your own upload handler.
    "},{"location":"apielements.html#value_3","title":"value","text":"

    File name to be upload. The value contains the value entered by the client browser to the <input type=\"file\"> tag and is read-only. Type String

    "},{"location":"apielements.html#public-member-functions_3","title":"Public member functions","text":""},{"location":"apielements.html#typeof_3","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectFile. Return value AC_File

    "},{"location":"apielements.html#autoconnectinput","title":"AutoConnectInput","text":""},{"location":"apielements.html#constructor_4","title":"Constructor","text":"
    AutoConnectInput(const char* name = \"\", const char* value = \"\", const char* label = \"\", const char* pattern = \"\", const char* placeholder = \"\", const ACPosterior_t post = AC_Tag_BR, const ACInput_t apply = AC_Input_Text)\n
    Parameters nameThe element name. valueValue of the element. labelLabel string. patternRegular expression string for checking data format. placeholderA placeholder string. postSpecifies the tag to be output afterward the element. applySpecifies the type of input that the text box accepts."},{"location":"apielements.html#public-member-variables_4","title":"Public member variables","text":""},{"location":"apielements.html#enable_4","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_4","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#label_2","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the input box. Specification of a label will generate an HTML <label> tag with an id attribute. The input box and the label are connected by the id attribute. Type String

    "},{"location":"apielements.html#name_4","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#pattern","title":"pattern","text":"

    A pattern specifies a regular expression that the input-box's value is checked against on form submission. Type String

    "},{"location":"apielements.html#placeholder","title":"placeholder","text":"

    A placeholder is an option string. Specification of a placeholder will generate a placeholder attribute for the input tag. Type String

    "},{"location":"apielements.html#post_4","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#value_4","title":"value","text":"

    Value of the element. It becomes a value attribute of an HTML <input type=\"text\"> tag. An entered text in the custom Web page will be sent with a query string of the form. The value set before accessing the page is displayed as the initial value. Type String

    "},{"location":"apielements.html#apply","title":"apply","text":"

    Specifies the type of input that the text box accepts. AutoConnectInput will generate either a <input type=\"text\">, <input type=\"password\">, or <input type=\"number\"> tag based on the apply specifying as input type. The input type can be specified the following values in the ACInput_t enumeration type. 1 Type ACInput_t

    • AC_Input_Text : input type=\"text\"
    • AC_Input_Password : input type=\"password\"
    • AC_Input_Number : input type=\"number\"
    "},{"location":"apielements.html#public-member-functions_4","title":"Public member functions","text":""},{"location":"apielements.html#canhandle_2","title":"canHandle","text":"
    bool canHandle(void)\n

    Returns whether the AutoConnectInput element has a registered event handler and can respond to a change event. Return value trueAn event handler is registered. The element can correspond to a change event. falseAn event handler is not registered.

    "},{"location":"apielements.html#isvalid","title":"isValid","text":"
    bool isValid(void)\n

    Evaluate the pattern as a regexp and return whether value matches. Always return true if the pattern is undefined. Return value trueThe value matches a pattern. falseThe value does not match a pattern.

    "},{"location":"apielements.html#off_2","title":"off","text":"
    void off(void)\n

    Release a registered event handler so that the element does not react to events.

    "},{"location":"apielements.html#on_2","title":"on","text":"
    void on(std::function<void(AutoConnectInput&, AutoConnectAux&)> eventHandler)\n

    Register an event handler function so that the element can respond to a change event. Parameter eventHandlerA function instance corresponding to a change event on AutoConnectInput. It allows giving with lambda expressions.

    An eventHandler function will be called when a change event occurs with the AutoConnectInput. Its prototype declaration is follows:

    void eventHandler(AutoConnectInput& me, AutoConnectAux& aux)\n
    Parameter meA reference to the instance of the AutoConnectInput that fired the change event. auxReference to the AutoConnectAux instance to which the AutoConnectInput that generated the change event belongs."},{"location":"apielements.html#response_2","title":"response","text":"
    void response(const char* value)\n
    void response(const char* attribute, const char* value)\n

    Reply the value or attribute of an element to the client. The response is usually used for sending a reply to the client with the element's value or attribute that has been updated in an event handler function.

    The response function itself does not perform communication. It only temporarily accumulates updated values. The stored content constitutes the response data to the HTTP POST request sent from the client browser caused by the AutoConnectElements event.

    The response function has two overloads with different numbers of arguments. A response function suitable for just one argument will only update the value of the AutoConnectInput. Also, a response function suitable for two arguments allows updating all attributes of the HTML input type=\"text\" element derived from AutoConnectInput. Parameter valueSuitable for one argument format: A changing value of AutoConnectInput::value as response.Suitable for two argument format: Specifies a value of the HTML input type=\"text\" element to be modified as specified in the attribute argument. attributeAn attribute name of an HTML input type=\"text\" element to be changed.

    "},{"location":"apielements.html#typeof_4","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectInput. Return value AC_Input

    "},{"location":"apielements.html#autoconnectradio","title":"AutoConnectRadio","text":""},{"location":"apielements.html#constructor_5","title":"Constructor","text":"
    AutoConnectRadio(const char* name = \"\", std::vector<String> const& values = {}, const char* label = \"\", const ACArrange_t order = AC_Vertical, const uint8_t checked = 0, const ACPosterior_t post = AC_Tag_BR)\n
    Parameters nameThe element name. valuesAn array of values of the radio buttons. Specifies a std::vector object. labelLabel string. orderThe direction to arrange the radio buttons. checkedAn index to be checked in the radio buttons. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_5","title":"Public member variables","text":""},{"location":"apielements.html#checked_1","title":"checked","text":"

    Specifies the index number (1-based) of the values to be checked. If this parameter is not specified neither item is checked. Type uint8_t

    "},{"location":"apielements.html#enable_5","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_5","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#label_3","title":"label","text":"

    A label is an optional string. A label will be arranged in the left or top of the radio buttons according to the order. Type String

    "},{"location":"apielements.html#name_5","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#order","title":"order","text":"

    Specifies the direction to arrange the radio buttons. A label will place in the left or the top according to the order. It is a value of ACArrange_t type and accepts one of the following: Type ACArrange_t

    • AC_Horizontal : Horizontal arrangement.
    • AC_Vertical : Vertical arrangement.
    "},{"location":"apielements.html#post_5","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#values","title":"values","text":"

    An array of String type for the radio button options. It is an initialization list can be used. The <input type=\"radio\"> tags will be generated from each entry in the values. Type std::vector<String>

    "},{"location":"apielements.html#public-member-functions_5","title":"Public member functions","text":""},{"location":"apielements.html#add","title":"add","text":"
    void add(const String& value)\n

    Adds an option for the radio button. Parameter valueAn option string to add to the radio button.

    "},{"location":"apielements.html#canhandle_3","title":"canHandle","text":"
    bool canHandle(void)\n

    Returns whether the AutoConnectRadio element has a registered event handler and can respond to a change event. Return value trueAn event handler is registered. The element can correspond to a change event. falseAn event handler is not registered.

    "},{"location":"apielements.html#check","title":"check","text":"
    void check(const String& value)\n

    Indicates the check of the specified option for the radio buttons. You can use the check function for checking dynamically with arbitrary of the radio button. Parameter valueAn option string to be checked.

    "},{"location":"apielements.html#empty","title":"empty","text":"
    void empty(const size_t reserve = 0)\n

    Clear the array of option strings that AutoConnectRadio has in the values. When the reserve parameter is specified, a vector container of that size is reserved.

    The empty function resets the checked value to zero. When the empty function is executed, any button will be turned off. Parameter reserveReserved size of a container for the radio button option strings.

    "},{"location":"apielements.html#off_3","title":"off","text":"
    void off(void)\n

    Release a registered event handler so that the element does not react to events.

    "},{"location":"apielements.html#on_3","title":"on","text":"
    void on(std::function<void(AutoConnectRadio&, AutoConnectAux&)> eventHandler)\n

    Register an event handler function so that the element can respond to a change event. Parameter eventHandlerA function instance corresponding to a change event on AutoConnectRadio. It allows giving with lambda expressions.

    An eventHandler function will be called when a change event occurs with the AutoConnectRadio. Its prototype declaration is follows:

    void eventHandler(AutoConnectRadio& me, AutoConnectAux& aux)\n
    Parameter meA reference to the instance of the AutoConnectRadio that fired the change event. auxReference to the AutoConnectAux instance to which the AutoConnectRadio that generated the change event belongs."},{"location":"apielements.html#operator","title":"operator [\u00a0]","text":"
    const String& operator[] (const std::size_t n)\n

    Returns a value string of the index specified by n. Parameter nIndex of values array to return. Its base number is 0. Return value A reference of a value string indexed by the specified the n.

    "},{"location":"apielements.html#size_1","title":"size","text":"
    size_t size(void)\n

    Returns number of options which contained. Return value Number of options which contained.

    "},{"location":"apielements.html#typeof_5","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectRadio. Return value AC_Radio

    "},{"location":"apielements.html#value_5","title":"value","text":"
      const String& value(void) const\n

    Returns current checked option of the radio buttons. Return value A String of an option current checked. If there is no checked option, a null string returned.

    "},{"location":"apielements.html#autoconnectrange","title":"AutoConnectRange","text":""},{"location":"apielements.html#constructor_6","title":"Constructor","text":"
    AutoConnectRange(const char* name = \"\", const int value = 0, const char* label = \"\", const int min = 0, const int max = 0, const int step = 1, const ACPosition_t magnify = AC_Void, const ACPosterior_t post = AC_Tag_BR, const char* style = \"\")\n
    Parameters nameThe element name. valueThe initial value in the range. labelLabel string. minThe most negative value within the range of allowed values. maxThe greatest value in the range of permitted values. stepThe granularity that the value must adhere to. magnifySpecifies the display position of the current value of the range. postSpecifies the tag to be output afterward the element. styleA style code with CSS format that qualifiers the range slider."},{"location":"apielements.html#public-member-variables_6","title":"Public member variables","text":""},{"location":"apielements.html#enable_6","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_6","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#label_4","title":"label","text":"

    A label is an optional string. A label is always arranged on the left side of the input box. Specification of a label will generate an HTML <label> tag with an id attribute. The range slider and the label are connected by the id attribute. Type String

    "},{"location":"apielements.html#magnify","title":"magnify","text":"Display position of the current value of the range. Type ACPosition_t
    • AC_Infront : Displays the current value on the left side.
    • AC_Behind : Displays the current value on the right side.
    • AC_Void : No display the current value. This is the default.
    "},{"location":"apielements.html#max","title":"max","text":"

    The greatest value in the range. Type int

    "},{"location":"apielements.html#min","title":"min","text":"

    The most negative value within the range. Type int

    "},{"location":"apielements.html#name_6","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_6","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#step","title":"step","text":"

    The granularity that the value must adhere to. Type int

    "},{"location":"apielements.html#style","title":"style","text":"

    A style code with CSS format that qualifiers the range slider. Type String

    "},{"location":"apielements.html#value_6","title":"value","text":"

    Value of the element. It becomes a value attribute of an HTML <input type=\"range\"> tag. A value of range in the custom Web page will be sent with a query string of the form. Type int

    "},{"location":"apielements.html#public-member-functions_6","title":"Public member functions","text":""},{"location":"apielements.html#typeof_6","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectRange. Return value AC_Range

    "},{"location":"apielements.html#autoconnectselect","title":"AutoConnectSelect","text":""},{"location":"apielements.html#constructor_7","title":"Constructor","text":"
    AutoConnectSelect(const char* name = \"\", std::vector<String> const& options = {}, const char* label = \"\", const uint8_t selected = 0, const ACPosterior_t post = AC_Tag_BR)\n
    Parameters nameThe element name. optionsAn array of options of the select element. Specifies a std::vector object. labelLabel string. selectedAn option should be pre-selected when the page loads. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_7","title":"Public member variables","text":""},{"location":"apielements.html#enable_7","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_7","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#name_7","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#label_5","title":"label","text":"

    A label is an optional string. A label will be arranged in the top of the selection list. Type String

    "},{"location":"apielements.html#options","title":"options","text":"

    An array of String type for the selection options. It is an initialization list can be used. The <option value> tags will be generated from each entry in the options. Type std::vector<String>

    "},{"location":"apielements.html#post_7","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#selected","title":"selected","text":"

    A selected is an optional value. Specifies 1-based index value of an options array that an option should be pre-selected when the page loads. Type uint8_t

    "},{"location":"apielements.html#public-member-functions_7","title":"Public member functions","text":""},{"location":"apielements.html#add_1","title":"add","text":"
    void add(const String& option)\n
    "},{"location":"apielements.html#canhandle_4","title":"canHandle","text":"
    bool canHandle(void)\n

    Returns whether the AutoConnectSelect element has a registered event handler and can respond to a change event. Return value trueAn event handler is registered. The element can correspond to a change event. falseAn event handler is not registered.

    Adds a selectable option string for the selection list. Parameter optionA string of selectable item to be contained in the select element.

    "},{"location":"apielements.html#empty_1","title":"empty","text":"
    void empty(const size_t reserve = 0)\n

    Clear the array of options list that AutoConnectSelect has in the options. When the reserve parameter is specified, a vector container of that size is reserved.

    The empty function resets the selected value to zero. When the empty function is executed, there are no selected options and the first item is placed at the beginning. Parameter reserveReserved size of a container for the options.

    "},{"location":"apielements.html#off_4","title":"off","text":"
    void off(void)\n

    Release a registered event handler so that the element does not react to events.

    "},{"location":"apielements.html#on_4","title":"on","text":"
    void on(std::function<void(AutoConnectSelect&, AutoConnectAux&)> eventHandler)\n

    Register an event handler function so that the element can respond to a change event. Parameter eventHandlerA function instance corresponding to a change event on AutoConnectSelect. It allows giving with lambda expressions.

    An eventHandler function will be called when a change event occurs with the AutoConnectSelect. Its prototype declaration is follows:

    void eventHandler(AutoConnectSelect& me, AutoConnectAux& aux)\n
    Parameter meA reference to the instance of the AutoConnectSelect that fired the change event. auxReference to the AutoConnectAux instance to which the AutoConnectSelect that generated the change event belongs."},{"location":"apielements.html#operator_1","title":"operator [\u00a0]","text":"
    const String& operator[] (const std::size_t n)\n

    Returns an option string of the index specified by n. Parameter nIndex of options array to return. Its base number is 0. Return value A reference of a option string indexed by the specified the n.

    "},{"location":"apielements.html#select","title":"select","text":"
    void  select(const String& value);\n

    Selects an option with the value. Parameter valueString value that option should be selected in an option array.

    "},{"location":"apielements.html#size_2","title":"size","text":"
    size_t size(void)\n

    Returns number of options which contained. Return value Number of options which contained.

    "},{"location":"apielements.html#typeof_7","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectSelect. Return value AC_Select

    "},{"location":"apielements.html#value_7","title":"value","text":"
    const String& value(void) const;\n

    Returns current selected option of the select list. Return value A String of an option current selected. If there is no select option, a null string returned.

    "},{"location":"apielements.html#autoconnectstyle","title":"AutoConnectStyle","text":""},{"location":"apielements.html#constructor_8","title":"Constructor","text":"
    AutoConnectStyle(const char* name = \"\", const char* value = \"\")\n
    Parameters nameThe element name. valueRaw CSS code to insert into a style block in a custom web page to generate."},{"location":"apielements.html#public-member-variables_8","title":"Public member variables","text":""},{"location":"apielements.html#enable_8","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#name_8","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#value_8","title":"value","text":"

    Raw CSS code to insert into a style block in a custom web page to generate. Type String

    "},{"location":"apielements.html#public-member-functions_8","title":"Public member functions","text":""},{"location":"apielements.html#typeof_8","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectStyle. Return value AC_Style

    "},{"location":"apielements.html#autoconnectsubmit","title":"AutoConnectSubmit","text":""},{"location":"apielements.html#constructor_9","title":"Constructor","text":"
    AutoConnectSubmit(const char* name = \"\", const char* value =\"\", char* uri = \"\", const ACPosterior_t post = AC_Tag_None)\n
    Parameters nameThe element name. valueThe name of the submit button as an HTML `#!html ` tag, it will also be the label of the button. uriDestination URI. postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_9","title":"Public member variables","text":""},{"location":"apielements.html#enable_9","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#global_8","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#name_9","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_8","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#uri","title":"uri","text":"

    Destination URI. Type String

    "},{"location":"apielements.html#value_9","title":"value","text":"

    The name of the submit button. It will also be the label of the button. Type String

    "},{"location":"apielements.html#public-member-functions_9","title":"Public member functions","text":""},{"location":"apielements.html#typeof_9","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectSubmit. Return value AC_Submit

    "},{"location":"apielements.html#autoconnecttext","title":"AutoConnectText","text":""},{"location":"apielements.html#constructor_10","title":"Constructor","text":"
    AutoConnectText(const char* name = \"\", const char* value = \"\", const char* style = \"\", const char* format = \"\", const ACPosterior_t post = AC_Tag_None)\n
    Parameters nameThe element name. valueString of content for the text element. styleA style code with CSS format that qualifiers the text. formatA pointer to a null-terminated multibyte string specifying how to interpret the value. It specifies the conversion format when outputting values. The format string conforms to C-style printf library functions postSpecifies the tag to be output afterward the element."},{"location":"apielements.html#public-member-variables_10","title":"Public member variables","text":""},{"location":"apielements.html#enable_10","title":"enable","text":"

    Enable HTML tag generation for the element. Type boolAutoConnect will generate the element into HTML only if the enable attribute is true.

    "},{"location":"apielements.html#format","title":"format","text":"

    The conversion format when outputting values. The format string conforms to C-style printf library functions. Type String

    "},{"location":"apielements.html#global_9","title":"global","text":"

    The global attribute copies input values between elements of the same name on different custom Web pages. Type boolAn entered value will be copied to elements of the same name in other AutoConnectAuxes during page transition.However, it will be copied only when the destination element has the true for a global attribute.

    "},{"location":"apielements.html#name_10","title":"name","text":"

    The element name. Type String

    "},{"location":"apielements.html#post_9","title":"post","text":"

    Specifies a tag to add behind the HTML code generated from the element. Type ACPosterior_t

    • AC_Tag_None : No generate additional tags.
    • AC_Tag_BR : Add a <br> tag to the end of the element.
    • AC_Tag_P : Include the element in the <p> ~ </p> tag.
    • AC_Tag_DIV : Include the element in the <div> ~ </div> tag.
    "},{"location":"apielements.html#style_1","title":"style","text":"

    A style code with CSS format that qualifiers the text. Type String

    "},{"location":"apielements.html#value_10","title":"value","text":"

    A content string of the text element. Type String

    "},{"location":"apielements.html#public-member-functions_10","title":"Public member functions","text":""},{"location":"apielements.html#response_3","title":"response","text":"
    void response(const char* value)\n
    void response(const char* attribute, const char* value)\n

    Reply the value or attribute of an element to the client. The response is usually used for sending a reply to the client with the element's value or attribute that has been updated in an event handler function.

    The response function itself does not perform communication. It only temporarily accumulates updated values. The stored content constitutes the response data to the HTTP POST request sent from the client browser caused by the AutoConnectElements event.

    The response function has two overloads with different numbers of arguments. A response function suitable for just one argument will only update the DOM text (i.e., the innerHTML attribute dependent on the div or span node) of the AutoConnectText. Also, a response function suitable for two arguments allows updating all attributes of the HTML div or span node derived from AutoConnectText. Parameter valueSuitable for one argument format: A changing value of AutoConnectText::value as response. It also will update the innerHTML attribute of the div or span node derived from AutoConnectText.Suitable for two argument format: Specifies a value of the HTML div or span node to be modified as specified in the attribute argument. attributeAn attribute name of an HTML div or span node to be changed.

    "},{"location":"apielements.html#typeof_10","title":"typeOf","text":"
    ACElement_t typeOf(void)\n

    Returns type of AutoConnectText. Return value AC_Text

    1. ACInput_t does not mind what kind of display effects on the browser. For example, input type=\"number\" has a spin button in Chrome, but has no display effects in iOS Safari. You will see the numeric keypad at inputting the number field with giving the pattern as \\d*.\u00a0\u21a9\u21a9

    "},{"location":"apiextra.html","title":"Something extra","text":""},{"location":"apiextra.html#icons","title":"Icons","text":"

    The library presents two PNG icons which can be used to embed a hyperlink to the AutoConnect menu.

    • Bar type
    • Cog type

    To reference the icon, use the AUTOCONNECT_LINK macro in the Sketch. It expands into the string literal as an HTML <a></a> tag with PNG embedded of the AutoConnect menu hyperlinks. Icon type is specified by the parameter of the macro.

    BAR_24Bars icon, 24x24. BAR_32Bars icon, 32x32. BAR_48Bars icon, 48x48. COG_16Cog icon, 16x16. COG_24Cog icon, 24x24. COG_32Cog icon, 32x32.

    Usage

    String html = \"<html>\";\nhtml += AUTOCONNECT_LINK(BAR_32);\nhtml += \"</html>\";\nserver.send(200, \"text/html\", html);\n
    "},{"location":"apiextra.html#captive-portal-availability-identification","title":"Captive Portal Availability Identification","text":"

    A check mark icon can be displayed adjacent to the AutoConnect menu title to indicate that a captive portal is available. This check mark indicates that the ESP module is not connected to any access point, SoftAP is enabled, and DNS lookup spoofing is working through the AutoConnect-initiated DNS server.

    This setting is enabled by turning on the AC_SHOW_PORTALIDENTIFIER macro defined in AutoConnectDefs.h header file.

    #define AC_SHOW_PORTALIDENTIFIER\n

    Using the PlatformIO as a build environment, you can enable it in the build_flags setting without modifying the library's AutoConnectDefs.h source file.

    platform = espressif32\nframework = arduino\nbuild_flags = -DAC_SHOW_PORTALIDENTIFIER\n
    "},{"location":"apiupdate.html","title":"AutoConnectUpdate API","text":"

    Only for AutoConnect

    The following AutoConnectUpdate API are valid only for AutoConnect; they are not available for AutoConnectCore.

    "},{"location":"apiupdate.html#constructor","title":"Constructor","text":""},{"location":"apiupdate.html#autoconnectupdate","title":"AutoConnectUpdate","text":"
    AutoConnectUpdate(const String& host, const uint16_t port, const String& uri, const int timeout, const uint8_t ledOn)\n
    Parameters hostUpdate server address. Specifies IP address or FQDN. portSpecifies HTTP port for the updating process. The default assumes AUTOCONNECT_UPDATE_PORT defined in the AutoConnectDefs.h header file. uriSpecifies a URI on the update server that has deployed available binary sketch files. timeoutSpecifies the maximum response time for the update server. The default assumes AUTOCONNECT_UPDATE_TIMEOUT in the AutoConnectDefs.h header file. ledOnActive signal to light the LED ticker during the update. Specifies HIGH or LOW

    The AutoConnectUpdate class inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    "},{"location":"apiupdate.html#public-member-functions","title":"Public member functions","text":""},{"location":"apiupdate.html#attach","title":"attach","text":"
    void AutoConnectUpdate::attach(AutoConnect& portal)\n

    Attaches the AutoConnectUpdate to the AutoConnect which constitutes the bedrock of the update process. This function creates a dialog page for the update operation as an instance of AutoConnectAux and participates in the AutoConnect menu. Parameter portalSpecifies a reference to the AutoConnect instance to attach.

    "},{"location":"apiupdate.html#disable","title":"disable","text":"
    void AutoConnectUpdate::disable(const bool activate)\n

    Disable the Update item in AutoConnect menu. The AutoConnect::disable function only hides the Update item from the menu, and the AutoConnectUpdate class is still active with the parameter condition. You can use the AutoConnectUpdate::enable function to appear it again in the menu. Parameter activateIf specified the true then the Update item will be displayed on the AutoConnect menu and OTA update will be available during the WiFi status is WL_CONNECTED. For the false, the OTA update feature is disabled.

    "},{"location":"apiupdate.html#enable","title":"enable","text":"
    void AutoConnectUpdate::enable(void)\n

    Makes AutoConnectUpdate class available by incorporating the OTA update function into the AutoConnect menu. In ordinarily, the AutoConnectUpdate class becomes available by just calling the AutoConnectUpdate::attach function.

    "},{"location":"apiupdate.html#handleupdate","title":"handleUpdate","text":"
    void AutoConnectUpdate::handleUpdate(void)\n

    Performs the update process. This function is called by AutoConnect::handleClient when AutoConnectUpdate is enabled. In many cases, sketches do not need to call this function on purpose.

    "},{"location":"apiupdate.html#isenabled","title":"isEnabled","text":"
    bool AutoConnectUpdate::isEnabled(void)\n

    Returns whether AutoConnectUpdate is enabled.

    "},{"location":"apiupdate.html#rebootonupdate","title":"rebootOnUpdate","text":"
    void AutoConnectUpdate::rebootOnUpdate(bool reboot)\n

    Specifies whether or not to automatically restart the module as a result of the successful completion of the update process. Parameter rebootIf specified the true then the ESP module will reboot after the updating successfully completed. For the false, The module does not reboot automatically. The uploaded new firmware remains in the updating stage of the flash on the ESP module. The boot process during the next start turn of the module by reset will copy the updated firmware to the actual program area and a new sketch program will start. The default value is true.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    "},{"location":"apiupdate.html#onend","title":"onEnd","text":"

    void AutoConnectUpdate::onEnd(HTTPUpdateEndCB fn)\n
    Register the on-end exit routine that is called only once when the update is finished. For the ESP32 platform, this function is only available in ESP32 Arduino core 2.0.0 or later. Parameter fnA function called when the update has been finished.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    An fn specifies the function called when the update has been finished. Its prototype declaration is defined as HTTPUpdateEndCB.

    using HTTPUpdateEndCB = std::function<void()>;\n
    "},{"location":"apiupdate.html#onerror","title":"onError","text":"
    void AutoConnectUpdate::onError(HTTPUpdateErrorCB fn)\n

    Register the exit routine that is called when some error occurred. For the ESP32 platform, this function is only available in ESP32 Arduino core 2.0.0 or later. Parameter fnA function called when some updating error occurs.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    An fn specifies the function called when the some error occurred. Its prototype declaration is defined as HTTPUpdateErrorCB.

    using HTTPUpdateErrorCB = std::function<void(int error)>;\n
    Parameter errorError code of the Update. It is defined in the ESP8266HTTPClient class, ESP8266HTTPUpdate class or the HTTPUpdate class of the Arduino core for each platform."},{"location":"apiupdate.html#onprogress","title":"onProgress","text":"
    void AutoConnectUpdate::onProgress(HTTPUpdateProgressCB fn)\n

    Register the exit routine that is called during the update progress. For the ESP32 platform, this function is only available in ESP32 Arduino core 2.0.0 or later. Parameter fnA function called during the updating progress.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    An fn specifies the function called during the updating progress. Its prototype declaration is defined as HTTPUpdateProgressCB.

    Updating Progress bar will not available

    AutoConnectUpdate uses the onProgress exit to update the progress bar on a web page during updating. If the user sketch registers its own exit routine with the onProgress function, AutoConnectUpdate's progress bar on the web page will not be updated.

    using HTTPUpdateProgressCB = std::function<void(int amount, int size)>;\n
    Parameters amountTotal amount of bytes received. sizeBlock size of current send."},{"location":"apiupdate.html#onstart","title":"onStart","text":"
    void AutoConnectUpdate::onStart(HTTPUpdateStartCB fn)\n

    Register the on-start exit routine that is called only once when the update has been started. For the ESP32 platform, this function is only available in ESP32 Arduino core 2.0.0 or later. Parameter fnA function called at the update start.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    An fn specifies the function called when the OTA starts. Its prototype declaration is defined as HTTPUpdateStartCB.

    using HTTPUpdateStartCB = std::function<void()>;\n
    "},{"location":"apiupdate.html#setledpin","title":"setLedPin","text":"
    void AutoConnectUpdate::setLedPin(int ledPin, uint8_t ledOn)\n

    Sets the port and the ON signal level of the externally connected LED that should act as a ticker during the update process. Parameter ledPinSpecifies the PIN connected external LED for the ticker. The default assumes AUTOCONNECT_TICKER_PORT defined in the AutoConnectDefs.h header file and it is derived from the board-specific LED_BUILTIN. By default, the AutoConnectUpdate class does not use the ticker for boards without the LED_BUILTIN definition. If you connect the ticker LED externally, you need to specify the PIN using the setLedPin function. ledOnSpecifies the the ON signal level of the LED PIN port. It is HIGH or LOW.

    This function inherits from the ESP8266HTTPUpdate (HTTPUpdate for ESP32) class.

    "},{"location":"apiupdate.html#status","title":"status","text":"
    AC_UPDATESTATUS_t AutoConnectUpdate::status(void)\n

    Returns the update process status transition indicator as an enumerated value of the AC_UPDATESTATUS_t type that indicates the process status of the AutoConnectUpdate class. Return value One of the enumerated values indicating the status of the Update class as follows:

    • UPDATE_RESET : Update process ended, need to reset.
    • UPDATE_IDLE : Update process has not started.
    • UPDATE_START : Update process has been started.
    • UPDATE_PROGRESS : Update process has been started.
    • UPDATE_SUCCESS : Update successfully completed.
    • UPDATE_NOAVAIL : No available update.
    • UPDATE_FAIL : Update failed.
    "},{"location":"apiupdate.html#public-member-variables","title":"Public member variables","text":""},{"location":"apiupdate.html#host","title":"host","text":"

    Update server address. Specifies IP address or FQDN. Type String

    "},{"location":"apiupdate.html#port","title":"port","text":"

    HTTP port for the updating process. Type StringThe default assumes AUTOCONNECT_UPDATE_PORT defined in the AutoConnectDefs.h header file.

    "},{"location":"apiupdate.html#uri","title":"uri","text":"

    URI on the update server that has deployed available binary sketch files. Type String

    "},{"location":"basicusage.html","title":"Basic usage","text":""},{"location":"basicusage.html#simple-usage","title":"Simple usage","text":""},{"location":"basicusage.html#embed-to-the-sketches","title":"Embed to the Sketches","text":"

    How embed the AutoConnect to the Sketches you have. Most simple approach to applying AutoConnect for the existing Sketches, follow the below steps. The below Sketch is for ESP8266. For ESP32, replace ESP8266WebServer with WebServer and ESP8266WiFi.h with WiFi.h respectively.

    Insert #include <AutoConnect.h> to behind of #include <ESP8266WebServer.h>.

    Insert AutoConnect PORTAL(WEBSERVER); to behind of ESP8266WebServer WEBSERVER; declaration.1

    Remove WiFi.begin(SSID,PSK) and the subsequent logic for the connection status check.

    Replace WEBSERVER.begin() to PORTAL.begin().2

    Replace WEBSERVER.handleClient() to PORTAL.handleClient().3

    If the connection checks logic is needed, you can check the return value according to PORTAL.begin() with true or false.

    "},{"location":"basicusage.html#basic-usage","title":"Basic usage","text":""},{"location":"basicusage.html#basic-logic-sequence-for-the-user-sketches","title":"Basic logic sequence for the user Sketches","text":""},{"location":"basicusage.html#1-a-typical-logic-sequence","title":"1. A typical logic sequence","text":"
    1. Include headers, ESP8266WebServer.h/WebServer.h and AutoConnect.h
    2. Declare an ESP8266WebServer variable for ESP8266 or a WebServer variable for ESP32.
    3. Declare an AutoConnect variable.
    4. Implement the URL handlers provided for the on method of ESP8266WebServer/WebServer with the function().
    5. setup() 5.1 Sets URL handler the function() to ESP8266WebServer/WebServer byESP8266WebServer::on/WebServer::on. 5.2 Starts AutoConnect::begin(). 5.3 Check WiFi connection status.
    6. loop() 6.1 Do the process for actual Sketch. 6.2 Invokes AutoConnect::handleClient(), or invokes ESP8266WebServer::handleClient()/WebServer::handleClient then AutoConnect::handleRequest().
    "},{"location":"basicusage.html#2-declare-autoconnect-object","title":"2. Declare AutoConnect object","text":"

    Two options are available for AutoConnect constructor.

    AutoConnect VARIABLE(&ESP8266WebServer);  // For ESP8266\nAutoConnect VARIABLE(&WebServer);         // For ESP32\n
    or

    AutoConnect VARIABLE;\n

    • The parameter with an ESP8266WebServer/WebServer variable: An ESP8266WebServer/WebServer object variable must be declared. AutoConnect uses its variable to handles the AutoConnect menu.

    • With no parameter: the Sketch does not declare ESP8266WebServer/WebServer object. In this case, AutoConnect allocates an instance of the ESP8266WebServer/WebServer internally. The logic sequence of the Sketch is somewhat different as the above. To register a URL handler function by ESP8266WebServer::on or WebServer::on should be performed after AutoConnect::begin.

    "},{"location":"basicusage.html#3-no-need-wifibegin","title":"3. No need WiFI.begin(...)","text":"

    AutoConnect internally performs WiFi.begin to establish a WiFi connection. There is no need for a general process to establish a connection using WiFi.begin with a Sketch code.

    "},{"location":"basicusage.html#4-alternate-esp8266webserverbegin-and-webserverbegin","title":"4. Alternate ESP8266WebServer::begin() and WebServer::begin()","text":"

    AutoConnect::begin executes ESP8266WebServer::begin/WebServer::begin internally too and it starts the DNS server to behave as a Captive portal. So it is not needed to call ESP8266WebServer::begin/WebServer::begin in the Sketch.

    Why DNS Server starts

    AutoConnect traps the detection of the captive portal and achieves a connection with the WLAN interactively by the AutoConnect menu. It responds SoftAP address to all DNS queries temporarily to trap. Once a WiFi connection establishes, the DNS server contributed by AutoConnect stops.

    "},{"location":"basicusage.html#5-autoconnectbegin-with-ssid-and-password","title":"5. AutoConnect::begin with SSID and Password","text":"

    SSID and Password can also specify by AutoConnect::begin. ESP8266/ESP32 uses provided SSID and Password explicitly. If the connection false with specified SSID with Password then a captive portal is activated. SSID and Password are not present, ESP8266 SDK will attempt to connect using the still effectual SSID and password. Usually, it succeeds.

    "},{"location":"basicusage.html#6-use-esp8266webserveron-and-webserveron-to-handle-url","title":"6. Use ESP8266WebServer::on and WebServer::on to handle URL","text":"

    AutoConnect is designed to coexist with the process for handling the web pages by user Sketches. The page processing function which will send an HTML to the client invoked by the \"on::ESP8266WebServer\" or the \"on::WebServer\" function is the same as when using ESP8266WebServer/WebServer natively.

    "},{"location":"basicusage.html#7-use-either-esp8266webserverhandleclientwebserverhandleclient-or-autoconnecthandleclient","title":"7. Use either ESP8266WebServer::handleClient()/WebServer::handleClient() or AutoConnect::handleClient()","text":"

    Both classes member function name is the same: handleClient, but the behavior is different. Using the AutoConnect embedded along with ESP8266WebServer::handleClient/WebServer::handleClient has limitations. Refer to the below section for details.

    "},{"location":"basicusage.html#esp8266webserverwebserver-hosted-or-parasitic","title":"ESP8266WebServer/WebServer hosted or parasitic","text":"

    The interoperable process with an ESP8266WebServer/WebServer depends on the parameters of the AutoConnect constructor.

    Declaration parameter for the constructor Use ESP8266WebServer::handleClient or WebServer::handleClient only Use AutoConnect::handleClient None AutoConnect menu not available.To use AutoConnect menu, need AutoConnect::handleRequest().also to use ESP8266WebServer/WebServer natively, need AutoConnect::host(). AutoConnect menu available.To use ESP8266WebServer/WebServer natively, need AutoConnect::host(). Reference to ESP8266WebServer/WebServer AutoConnect menu not available.To use AutoConnect menu, need AutoConnect::handleRequest(). AutoConnect menu available.

    • By declaration for the AutoConnect variable with no parameter: The ESP8266WebServer/WebServer instance is hosted by AutoConnect automatically then the Sketches use AutoConnect::host as API to get it after AutoConnect::begin performed.

    • By declaration for the AutoConnect variable with the reference of ESP8266WebServer/WebServer: AutoConnect will use it. the Sketch can use it is too.

    • In use ESP8266WebServer::handleClient()/WebServer::handleClient(): AutoConnect menu can be dispatched but not works normally. It is necessary to call AutoConnect::handleRequest after ESP8255WebServer::handleClient/WebServer::handleClient invoking.

    • In use AutoConnect::handleClient(): The handleClient() process and the AutoConnect menu is available without calling ESP8266WebServer::handleClient.

    Why AutoConnect::handleRequest is needed when using ESP8266WebServer::handleClient/WebServer::handleClient

    The AutoConnect menu function may affect WiFi connection state. It follows that the menu process must execute outside ESP8266WebServer::handleClient and WebServer::handleClient. AutoConnect::handleClient is equivalent ESP8266WebServer::handleClient and WEbServer::handleClient included AutoConnect::handleRequest.

    "},{"location":"basicusage.html#reducing-binary-size","title":"Reducing Binary Size","text":"

    Typically, AutoConnect components include AutoConnectAux for handling Custom Web pages; AutoConnectAux plays a central role in responding to requests for Custom Web pages. It also incorporates several AutoConnectElements used in the sketch, which may exceed 1 MB in binary size after the build. To reduce the binary size, you can deactivate the component to handle these custom web pages, depending on the use case. If your sketch does not use Custom web pages, allows you to exclude the AutoConnectAux component to reduce the built binary size.

    AutoConnect.h header file enables all AutoConnect components. In a normal sketch, including this header enables all AutoConnect functionality. On the other hand, for sketches that don't use custom web pages, you can apply the AutoConnectCore.h header file.

    AutoConnectCore.h provides an AutoConnect class that excludes AutoConnectAux and AutoConnectElements from AutoConnect. Therefore, it does not implement the APIs required for custom web page processing. Also, AutoConnectOTA and AutoConnectUpdate cannot be used. (i.e., to use AutoConnect's equipped OTA Update feature, you must include the full AutoConnect component in your sketch) Instead, the binary size of the AutoConnectCore component is reduced by about 170 KB (1.3 KB for RAM) compared to the ESP32 AutoConnect full component. (60KB for ESP8266)

    To switch between AutoConnect and AutoConnectCore, simply change the corresponding header file with #include header.

    "},{"location":"basicusage.html#using-autoconnect-full-component","title":"Using AutoConnect Full component","text":"
    #include <WiFi.h>\n#include <WebServer.h>\n#include <AutoConnect.h>\nstatic const char PAGE_HELLO[] = R\"(\n{\n  \"uri\": \"/\",\n  \"title\": \"Hello\",\n  \"menu\": false,\n  \"element\": [\n    {\n      \"name\": \"caption\",\n      \"type\": \"ACText\",\n      \"value\": \"Hello, World\"\n    },\n  ]\n}\n)\";\n\nWebServer Server;\nAutoConnect Portal(Server);\nAutoConnectConfig Config;\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  Config.ota = AC_OTA_BUILTIN;\n  Portal.config(Config);\n\n  portal.load(PAGE_HELLO);\n  Portal.begin();\n  Serial.println(\"Web Server started:\" + WiFi.localIP().toString());\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n
    "},{"location":"basicusage.html#using-autoconnectcore-without-custom-web-pages-and-ota-update-facilities","title":"Using AutoConnectCore without Custom Web pages and OTA Update facilities","text":"

    Even in the sketch with AutoConnectCore.h applied, the class name remains AutoConnect.

    #include <WiFi.h>\n#include <WebServer.h>\n#include <AutoConnectCore.h>\nWebServer Server;\nAutoConnect Portal(Server);\nvoid rootPage() {\nchar content[] = \"Hello, World\";\n  Server.send(200, \"text/plain\", content);\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  Server.on(\"/\", rootPage);\n  Portal.begin();\n  Serial.println(\"Web Server started:\" + WiFi.localIP().toString());\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    Either AutoConnect.h or AutoConnectCore.h

    A sketch can include either AutoConnect.h or AutoConnectCore.h. These two header files are mutually exclusive and cannot be included together at the same time. Also, If the sketch includes AutoConnectCore.h, some members involved in the custom web page facility are excluded from AutoConnectConfig class.

    1. Each VARIABLE conforms to the actual declaration in the Sketches.\u00a0\u21a9

    2. WiFi SSID and Password can be specified AutoConnect::begin() too.\u00a0\u21a9

    3. Replacement the handleClient method is not indispensable. AutoConnect can still connect with the captive portal as it is ESP8266WebServer::handleClient. But it can not valid AutoConnect menu.\u00a0\u21a9

    "},{"location":"changelabel.html","title":"Change label text","text":""},{"location":"changelabel.html#change-the-items-label-text","title":"Change the item's label text","text":"

    You can change the text of AutoConnect menu items. The easiest way is to rewrite the header file directly in the library that defines the menu label. Advanced Usage section describes the detailed how to change the label text directly.

    However, this way is less preferred as it modifies the library code and further affects the entire Arduino project you compile. So, here's how to change the label text for each Arduino project without directly modifying the library code. Using this method, you can also display the label text and fixed text on AutoConnect pages in your national language.

    (e.g. in Japanese)

    "},{"location":"changelabel.html#preparation","title":"Preparation","text":"

    AutoConnect needs a definition file as c++ header (.h) to change the label text. It is used when your Arduino project is compiled, and there is no additional memory consumption due to changing the label text. This header file describes each fixed text of AutoConnect with the #define preprocessor directive.

    The next thing you need is PlatformIO. PlatformIO is a very powerful environment for embedded development with multi-platform and multi-architecture build systems. And you can easily set up a PlatformIO for the Arduino development system as follows on your host machine.

    • Microsoft Visual Studio Code
    • PlatformIO IDE (included PlatformIO core)

    Install PlatformIO and VSCode

    Please refer to the official documentation for PlatformIO and VSCode installation.

    The rest of this section assumes that you have a PlatformIO environment with VSCode as the front end that has installed on your host machine.

    "},{"location":"changelabel.html#how-to-change-the-label-text","title":"How to change the label text","text":""},{"location":"changelabel.html#label-text-replacement-header-file","title":"Label text replacement header file","text":"

    AutoConnect label texts are pre-assigned with a fixed string so that it can be determined at compile time. Their default definitions are in the AutoConnectLabels.h file that has all the replaceable label text defined by the #define directive.

    Label placedPre-defined textID (#define macro) Menu itemConfigure new APAUTOCONNECT_MENULABEL_CONFIGNEW Open SSIDsAUTOCONNECT_MENULABEL_OPENSSIDS DisconnectAUTOCONNECT_MENULABEL_DISCONNECT Reset...AUTOCONNECT_MENULABEL_RESET HOMEAUTOCONNECT_MENULABEL_HOME UpdateAUTOCONNECT_MENULABEL_UPDATE Device infoAUTOCONNECT_MENULABEL_DEVINFO Button labelRESETAUTOCONNECT_BUTTONLABEL_RESET UPDATEAUTOCONNECT_BUTTONLABEL_UPDATE Page titlePage not foundAUTOCONNECT_PAGETITLE_NOTFOUND AutoConnect configAUTOCONNECT_PAGETITLE_CONFIG AutoConnect connectingAUTOCONNECT_PAGETITLE_CONNECTING AutoConnect connection failedAUTOCONNECT_PAGETITLE_CONNECTIONFAILED AutoConnect credentialsAUTOCONNECT_PAGETITLE_CREDENTIALS AutoConnect disconnectedAUTOCONNECT_PAGETITLE_DISCONNECTED AutoConnect resettingAUTOCONNECT_PAGETITLE_RESETTING AutoConnect statisticsAUTOCONNECT_PAGETITLE_STATISTICS Page:[statistics] rowEstablished connectionAUTOCONNECT_PAGESTATS_ESTABLISHEDCONNECTION ModeAUTOCONNECT_PAGESTATS_MODE IPAUTOCONNECT_PAGESTATS_IP GWAUTOCONNECT_PAGESTATS_GATEWAY Subnet maskAUTOCONNECT_PAGESTATS_SUBNETMASK SoftAP IPAUTOCONNECT_PAGESTATS_SOFTAPIP AP MACAUTOCONNECT_PAGESTATS_APMAC STA MACAUTOCONNECT_PAGESTATS_STAMAC ChannelAUTOCONNECT_PAGESTATS_CHANNEL dBmAUTOCONNECT_PAGESTATS_DBM Chip IDAUTOCONNECT_PAGESTATS_CHIPID CPU Freq.AUTOCONNECT_PAGESTATS_CPUFREQ Flash sizeAUTOCONNECT_PAGESTATS_FLASHSIZE Free memoryAUTOCONNECT_PAGESTATS_FREEMEM Page:[config] textTotal:AUTOCONNECT_PAGECONFIG_TOTAL Hidden:AUTOCONNECT_PAGECONFIG_HIDDEN SSIDAUTOCONNECT_PAGECONFIG_SSID PassphraseAUTOCONNECT_PAGECONFIG_PASSPHRASE Enable DHCPAUTOCONNECT_PAGECONFIG_ENABLEDHCP ApplyAUTOCONNECT_PAGECONFIG_APPLY Page:[open SSIDs] textDelete a credential?AUTOCONNECT_TEXT_DELETECREDENTIAL could not deletedAUTOCONNECT_TEXT_COULDNOTDELETED Page:[update] textUpdating firmwareAUTOCONNECT_TEXT_UPDATINGFIRMWARE Select firmware:AUTOCONNECT_TEXT_SELECTFIRMWARE Successfully updated, rebooting...AUTOCONNECT_TEXT_OTASUCCESS Failed to update:AUTOCONNECT_TEXT_OTAFAILURE Page:[connection failed]Connection FailedAUTOCONNECT_PAGECONNECTIONFAILED_CONNECTIONFAILED TextNo saved credentials.AUTOCONNECT_TEXT_NOSAVEDCREDENTIALS Menu TextConnectingAUTOCONNECT_MENUTEXT_CONNECTING DisconnectAUTOCONNECT_MENUTEXT_DISCONNECT FailedAUTOCONNECT_MENUTEXT_FAILED

    The definition of label text must conform to a certain coding pattern. Undefine with #undef the #define directive corresponding to the above IDs, and then redefine the ID with the replacement text. And surround it with #ifdef ~ #endif.

    #ifdef AUTOCONNECT_MENULABEL_CONFIGNEW\n#undef AUTOCONNECT_MENULABEL_CONFIGNEW\n#define AUTOCONNECT_MENULABEL_CONFIGNEW   \"NEW_STRING_YOU_WISH\"\n#endif\n

    You may not need to rewrite all definitions. It depends on your wishes and is sufficient that the above the include file contains only the labels you need.

    "},{"location":"changelabel.html#configuration-of-platformioini","title":"Configuration of platformio.ini","text":"

    You prepare its header file and place it in the src folder of the project folder. You can name the file whatever you like, but for the sake of explanation, let's say mylabels.h.

    When you store mylabels.h containing the new label text definition in the src folder, your Arduino project folder structure should look like this:

    <Project folder>\n|-- <pio>\n|-- <.vscode>\n|-- <include>\n|-- <lib>\n|-- <src>\n|   |-- main.cpp\n|   |-- mylabels.h  <-- Depends on the project\n|-- <test>\n|-- .gitignore\n|-- .travis.yml\n|-- platformio.ini\n

    Then, open platformio.ini file and add new build_flags for including mylabels.h to override the label text.

    build_flags = -DAC_LABELS='\"${PROJECT_SRC_DIR}/mylabels.h\"'\n

    Just change the mylabels.h

    Keep -DAC_LABELS='\"${PROJECT_SRC_DIR}/YOUR_FILE_NAME\"' when changing the above build_flags item to match your labels header file name.

    After placing the mylabels.h file and add the build_flags, build the project with the replaced label text. You will see the AutoConnect screen with the new text replaced by mylabels.h.

    Need clean-up before re-build with updated mylabels.h

    When you have updated mylabels.h, you need deleting compiled library object files before build. Use Clean of a PlatformIO task on VSCode status bar.

    "},{"location":"changelog.html","title":"Change log","text":""},{"location":"changelog.html#142-jan-31-2023","title":"[1.4.2] Jan. 31, 2023","text":""},{"location":"changelog.html#enhancements","title":"Enhancements","text":"
    • Supports whileConnecting exit called while waiting for WiFi connection.
    • Added AutoConnect::portalStatus function.
    "},{"location":"changelog.html#fix","title":"Fix","text":"
    • Fixed compilation error with ESP8266 Arduino Core 3.1.0 or later.
    "},{"location":"changelog.html#141-jan-5-2023","title":"[1.4.1] Jan. 5, 2023","text":""},{"location":"changelog.html#enhancements_1","title":"Enhancements","text":"
    • Supports asynchronous communication of custom web pages using the Fetch API. This allows interaction with the user without page transitions. See the chapter Interact between Sketch and AutoConnectElements for details.
    • Added the FetchLED example.
    • Added an AutoConnect::locate function.
    "},{"location":"changelog.html#fix_1","title":"Fix","text":"
    • Fixed AutoConnectConfigBase constructor missing to AutoConnectConfigExt.
    "},{"location":"changelog.html#140-nov-20-2022","title":"[1.4.0] Nov. 20, 2022","text":""},{"location":"changelog.html#enhancements_2","title":"Enhancements","text":"
    • Custom web page related features were decoupled to allow for two different configurations, AutoConnectCore and AutoConnect. AutoConnectCore reduces memory consumption by focusing only on WiFi connectivity utilities. See Reducing Binary Size chapter in the AutoConnect documentation for more information.
    • Supports credentials backup and restoration.
    • Added an AutoConnect::getCurrentCredential function.
    • Added an AutoConnectAux::referer function.
    • Added an AutoConnectConfig::preserveIP setting.
    • Added the WebSocketServer example.
    • Allow navigate to a custom URL once a WiFi connection is established.
    • Revised mqttRSSI examples program structure.
    "},{"location":"changelog.html#fix_2","title":"Fix","text":"
    • Fixed updateserver.py script security vulnerability.
    "},{"location":"changelog.html#137-aug-20-2022","title":"[1.3.7] Aug. 20, 2022","text":""},{"location":"changelog.html#fix_3","title":"Fix","text":"
    • Fixed an authentication failure in Captive Portal state.
    • Fixed loss of current SSID.
    "},{"location":"changelog.html#136-jul-26-2022","title":"[1.3.6] Jul. 26, 2022","text":""},{"location":"changelog.html#fix_4","title":"Fix","text":"
    • Fixed OTA being incomplete.
    "},{"location":"changelog.html#135-jun-03-2022","title":"[1.3.5] Jun. 03, 2022","text":""},{"location":"changelog.html#fix_5","title":"Fix","text":"
    • Fixed Fixed OTA exit not being called.
    • Fixed an ambiguous type call with IPAddress.
    • Fixed loss of response due to OTA session reset occurrence.
    • Made fit the mqttRSSI examples to ThingSpeak's updated channel authentication.

    For ESP-IDF 4.4 with Arduino ESP32 Core

    AutoConnect 1.3.5 is the version compatible with both ESP-IDF 4.4 and ESP-IDF 3.3. It is recommended to use Arduino esp32 core 1.0.6 for ESP-IDF 3.3 based and Arduino esp32 core 2.0.3 or later for ESP-IDF 4.4 based. If you are using PlatformIO as your development platform, you can select any of these two versions by specifying them in platformio.ini file.

    • For ESP-IDF 4.4 with Arduino ESP32 Core 2.0.3
    framework = arduino\nplatform = espressif32@4.4.0\n
    • For ESO-IDF 3.3 with Arduino ESP32 Core 1.0.6
    framework = arduino\nplatform = espressif32@3.5.0\n
    "},{"location":"changelog.html#134-mar-02-2022","title":"[1.3.4] Mar. 02, 2022","text":""},{"location":"changelog.html#enhancements_3","title":"Enhancements","text":"
    • Supports LittleFS_esp32 legacy library with ESP32 Arduino core 1.0.6 or less.
    • Added enablement of credentials removal function with Open SSIDs menu.
    • Migrate the CI platform to GitHub actions.
    "},{"location":"changelog.html#fix_6","title":"Fix","text":"
    • Fixed AutoConnectOTA crashing if there is no OTA partition.
    • Fixed AutoConnectUpdate crashing if there is no OTA partition.
    "},{"location":"changelog.html#133-jan-25-2022","title":"[1.3.3] Jan. 25, 2022","text":""},{"location":"changelog.html#fix_7","title":"Fix","text":"
    • Fixed the missing initialization of MQTT parameter settings of mqttRSSI.ino example sketch.
    • Reverted the MQTT API endpoint of Thingspeak.com in the mqttRSSI example sketches.
    • Changed ESP32Cam XCLK to be attenuated to avoid interference with WiFi signals.
    "},{"location":"changelog.html#132-jan-1-2022","title":"[1.3.2] Jan. 1, 2022","text":""},{"location":"changelog.html#enhancements_4","title":"Enhancements","text":"
    • Supports an AutoConnectRange as a new AutoConnectElement.
    • Adds the responsive parameter with AutoConnectAux.
    • Adds an AutoConnectAux::redirect function.
    • Adds an example for using AutoConnect with the ESP32 camera driver as WebCamServer.
    "},{"location":"changelog.html#fix_8","title":"Fix","text":"
    • Fixed an issue where a password is lost when SoftAP is stopped.
    "},{"location":"changelog.html#131-oct-09-2021","title":"[1.3.1] Oct. 09, 2021","text":""},{"location":"changelog.html#fixes","title":"Fixes","text":"
    • Fixed an issue that was incompatible with ArduinoJson version 5.
    • Fixed LittleFS mount check not working with ESP32.
    • Fixed autoReconnect not being able to restore a static IP setting.
    • Fixed that static IP settings were not cleared when loading credential.
    "},{"location":"changelog.html#130-sep-25-2021","title":"[1.3.0] Sep. 25, 2021","text":""},{"location":"changelog.html#enhancements_5","title":"Enhancements","text":"
    • Supports ESP8266 3.0.0 Arduino core.
    • Supports ESP32 Arduino core 2.0.0.
    • Supports LittleFS with ESP32.
    • Supports AutoConnectOTA status notifications.
    • Supports AutoConnectConfigAux. (Preview)
    • Supports to save credentials always.
    • Adds a style attribute with AutoConnectInput.
    • Adds the div tag generation with the AutoConnectElement.
    • Adds [] operator with const char for AutoConnectAux.
    • Adds [] operator with __FlashStringHelper for AutoConnectAux.
    • Adds AutoConnectAux::content function to get a number of AutoConnectElements.
    • Adds AutoConnect::getConfig function to get an actual instance of AutoConnectConfig.
    "},{"location":"changelog.html#fixes_1","title":"Fixes","text":"
    • Fixed CSS attribute missing of AutoConnectInput with the number type.
    • Fixed garbage being mixed in a loaded credential.
    • Fixed the output place of Posterior attribute for AutoConnectRadio.
    • Improved the the calculation for the size of ArduinoJson document.
    • Fixed Incomplete deletion with AutoConnectCredential.
    • Fixed credentials not erased correctly.
    • Fixed AutoConnectText posterior being unavailable.
    "},{"location":"changelog.html#123-jan-3-2021","title":"[1.2.3] Jan. 3, 2021","text":""},{"location":"changelog.html#enhancements_6","title":"Enhancements","text":"
    • Improved memory management.

    PageBuilder v1.5.0 is required

    Since AutoConnect v1.2.3, PageBuilder v1.5.0 or later is required. Please update PageBuilder to latest version.

    "},{"location":"changelog.html#122-dec-13-2020","title":"[1.2.2] Dec. 13, 2020","text":""},{"location":"changelog.html#fix_9","title":"Fix","text":"
    • Fixed an issue where OTA updates would crash on the ESP32 platform. (issue #284) With this fix, AUTOCONNECT_UPLOAD_ASFIRMWARE_USE_REGEXP must be enabled for regular expressions to be enabled in AUTOCONNECT_UPLOAD_ASFIRMWARE.
    "},{"location":"changelog.html#121-dec-5-2020","title":"[1.2.1] Dec. 5, 2020","text":""},{"location":"changelog.html#fix_10","title":"Fix","text":"
    • Fixed that not declared error with AUTOCONNECT_NOUSE_JSON. (issue #282)
    "},{"location":"changelog.html#120-dec-3-2020","title":"[1.2.0] Dec. 3, 2020","text":""},{"location":"changelog.html#new-features","title":"New features","text":"
    • Supports a whileCaptivePortal exit. (issue #149, issue #244)
    • Supports an onConnect exit.
    • Supports HTTP authentication. (issue #171)
    "},{"location":"changelog.html#enhancements_7","title":"Enhancements","text":"
    • Added AUTOCONNECT_APKEY_SSID definition to seek access points by SSID. (issue #251)
    • Added AutoConnect::append and AutoConnect::detach function that can be dynamically AutoConnectAux attaching and detaching. (issue #230)
    • Added AutoConnect::getEEPROMUsedSize that notifies the occupied size of the credential storage area. (issue #209)
    • Added AutoConnectConfig::beginTimeout setting. (issue #247)
    • Added AutoConnectConfig::preserveAPMode setting. (issue #210)
    • Enable support for the LittleFS as filesystem with ESP8266 platform.
    • Enhanced AutoConnectInput to allow accepts password and number type. (issue #237, issue #255)
    • Enhanced handleClient to dynamically launch the captive portal when losing WiFi connection.
    • Enhanced the ability to upload a regular file with AutoConnectOTA. (issue #236)
    • Enhanced ticker to work even in handleClient loop.
    • Improved autoReconnect to work even in handleClient loop. (issue #234, issue #251)
    "},{"location":"changelog.html#fixes_2","title":"Fixes","text":"
    • Avoids an empty-body warning when AC_DEBUG is disabled. (issue #218)
    • Fixed a core panic in the regex with ESP32.
    • Fixed an exception in the AutoConnect::end function.
    • Fixed an invalid SPIFFS compile error with ESP32.
    • Fixed deficiently forward references with HandleClient.ino example. (PR #275)
    • Fixed incorrect connection wait time. (issue #216)
    • Fixed not being able to specify channel ID with a mqttRSSI.ino example. (issue #262)
    • Fixed posterior being disabled in AutoConnectElement.
    "},{"location":"changelog.html#117-apr-19-2020","title":"[1.1.7] Apr. 19, 2020","text":""},{"location":"changelog.html#fixes_3","title":"Fixes","text":"
    • Fixed Apply button not work.
    "},{"location":"changelog.html#116-apr-17-2020","title":"[1.1.6] Apr. 17, 2020","text":""},{"location":"changelog.html#fixes_4","title":"Fixes","text":"
    • Fixed OTA page translation not work.
    "},{"location":"changelog.html#115-apr-15-2020","title":"[1.1.5] Apr. 15, 2020","text":""},{"location":"changelog.html#new-features_1","title":"New features","text":"
    • Supports AutoConnect menu configuration.
    • Supports the built-in OTA feature as AutoConnectOTA.
    "},{"location":"changelog.html#enhancements_8","title":"Enhancements","text":"
    • Enhanced allows the AutoConnect::begin to connect to the access point in order of signal strength. This option can specify the order of connection attempting according to the WiFi signal strength indicated with RSSI.
    • Changed the bootUri behavior to be an automatic pop-up at the captive portal.
    "},{"location":"changelog.html#114-feb-14-2020","title":"[1.1.4] Feb. 14, 2020","text":""},{"location":"changelog.html#new-features_2","title":"New features","text":"
    • Supports for overriding text of the menu items with user-defined labels.
    "},{"location":"changelog.html#fixes_5","title":"Fixes","text":"
    • Fixed the compiler warning with experimental WiFi mode of ESP8266.
    "},{"location":"changelog.html#113-jan-1-2020","title":"[1.1.3] Jan. 1, 2020","text":""},{"location":"changelog.html#enhancements_9","title":"Enhancements","text":"
    • Improved Config New button behavior.
    • Added AUTOCONNECT_NOUSE_JSON directive
    "},{"location":"changelog.html#fixes_6","title":"Fixes","text":"
    • Fixed relocate Config New menu URI inability.
    • Removed compiler warning of unused.
    "},{"location":"changelog.html#112-oct-22-2019","title":"[1.1.2] Oct. 22, 2019","text":""},{"location":"changelog.html#fixes_7","title":"Fixes","text":"
    • Fixed a crash when no SSID found.
    • Fixed memory leak on destruction.
    "},{"location":"changelog.html#111-oct-17-2019","title":"[1.1.1] Oct. 17, 2019","text":""},{"location":"changelog.html#fixes_8","title":"Fixes","text":"
    • Fixed crash with unique_ptr deleting reference content.
    • Fixed disconnection request initialization missing.
    "},{"location":"changelog.html#110-oct-15-2019","title":"[1.1.0] Oct. 15, 2019","text":""},{"location":"changelog.html#enhancements_10","title":"Enhancements","text":"
    • Enhanced to be able to specify static IP in the Configure new AP menu.
    "},{"location":"changelog.html#fixes_9","title":"Fixes","text":"
    • Fixed compilation error that no member named 'printTo' with ArduinoJson version 5.
    "},{"location":"changelog.html#103-sept-30-2019","title":"[1.0.3] Sept. 30, 2019","text":""},{"location":"changelog.html#fixes_10","title":"Fixes","text":"
    • Fixed a return of AutoConnectCredential::entries().
    "},{"location":"changelog.html#102-sept-19-2019","title":"[1.0.2] Sept. 19, 2019","text":""},{"location":"changelog.html#fixes_11","title":"Fixes","text":"
    • Fixed compilation error that no member named 'success' with ArduinoJson version 5.
    • Fixed SSID non termination.
    • Fixed compilation error that getBytesLength missing with ESP32.
    • Added #include directive restriction for EEPROM and ESP8266httpUpdate to FAQ.
    "},{"location":"changelog.html#101-sept-13-2019","title":"[1.0.1] Sept. 13, 2019","text":""},{"location":"changelog.html#enhancements_11","title":"Enhancements","text":"
    • Added an example sketch for ESP32 boards that migrates credentials stored in EEPROM partition to the Preferences.
    "},{"location":"changelog.html#100-sept-7-2019","title":"[1.0.0] Sept. 7, 2019","text":""},{"location":"changelog.html#new-features_3","title":"New features","text":"
    • Supports AutoConnectUpdate for the OTA update.
    "},{"location":"changelog.html#enhancements_12","title":"Enhancements","text":"
    • Supported Arduino core for ESP32 1.0.3.
    • Added AutoConnectAux::isValid function.
    • Added the global attribute with all AutoConnectElements.
    • Changed the credential storage area to Preferences with ESP32 core 1.0.3 and later. In ESP32, the credentials stored past in EEPROM will lose.
    "},{"location":"changelog.html#0912-aug-18-2019","title":"[0.9.12] Aug. 18, 2019","text":""},{"location":"changelog.html#fixes_12","title":"Fixes","text":"
    • 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.
    "},{"location":"changelog.html#0911-july-13-2019","title":"[0.9.11] July 13, 2019","text":""},{"location":"changelog.html#new-features_4","title":"New features","text":"
    • Supports new element as AutoConnectSytle that can insert the custom CSS into AutoConnectAux page.
    "},{"location":"changelog.html#enhancements_13","title":"Enhancements","text":"
    • Supports that <br> tags can now be added to each element.
    • Supports that able to place the checkbox label forward or backward.
    • Supports flicker signal output according to the status of WiFi_mode.
    • Supports AutoConnectAux::fetchElement function to retrieve inputted element values via a custom Web page.
    "},{"location":"changelog.html#fixes_13","title":"Fixes","text":"
    • Fixed bug in AutoConnectCredential when offset is >256.
    "},{"location":"changelog.html#0910-june-12-2019","title":"[0.9.10] June 12, 2019","text":""},{"location":"changelog.html#fixes_14","title":"Fixes","text":"
    • Fixed the unable to get AutoConnectElemets values in the sketch with ESP8266 arduino core 2.5.2.
    "},{"location":"changelog.html#099-may-25-2019","title":"[0.9.9] May 25, 2019","text":""},{"location":"changelog.html#enhancements_14","title":"Enhancements","text":"
    • Supports ESP8266 Arduino core 2.5.2.
    • Menu text/background color can be statically customized.
    • Added the enable attribute to the AutoConnectElements. This attribute gives dynamically change to the element activation during the sketch executing.
    • Added ID attribute to HTML tag generated from AutoConnectText.
    "},{"location":"changelog.html#fixes_15","title":"Fixes","text":"
    • Fixed the input box layout collapsed.
    • Fixed that the decoration of AutoConnectButton was disabled.
    • Fixed that the value remains even after clearing the option with AutoConnectSelect.
    • Fixed that an alignment violation exception occurred when loading AutoConnectAux described by JSON with PROGMEM attribute.
    "},{"location":"changelog.html#098-may-3-2019","title":"[0.9.8] May 3, 2019","text":""},{"location":"changelog.html#new-features_5","title":"New features","text":"
    • Supports new element type AutoConnectFile and built-in file uploader.
    "},{"location":"changelog.html#enhancements_15","title":"Enhancements","text":"
    • Enhanced to support ArduinoJson 6.9.1 or later.
    • Enhanced to use PSRAM on ESP32 module as the buffer allocation destination of JsonDocument with ArduinoJson 6.10.0 or later.
    • Added an operator[] as a shortcut for AutoConnectAux::getElement function.
    • Added an AutoConnectElement::as<T> function to easily coding for conversion from an AutoConnectElement to an actual type.
    • Added a format attribute with the AutoConnectText element.
    • Added a selected attribute with the AutoConnectSelect element.
    • Enhanced AutoConnectAux::loadElement with multiple elements loading.
    • Changed menu labels placement in source files structure.
    • Changed API interface of AutoConnect::where function.
    "},{"location":"changelog.html#fixes_16","title":"Fixes","text":"
    • Fixed blank page responds with Configure new.
    • Fixed loading elements value missing.
    • Fixed losing elements in saveElement with ArduinoJson version 6.
    • Fixed compile error with older than ESP8266 core 2.5.0.
    "},{"location":"changelog.html#097-jan-25-2019","title":"[0.9.7] Jan. 25, 2019","text":""},{"location":"changelog.html#new-features_6","title":"New features","text":"
    • Supports AutoConnect menu extension by user sketch with AutoConnectAux.
    • Supports loading and saving of user-defined parameters with JSON format.
    "},{"location":"changelog.html#enhancements_16","title":"Enhancements","text":"
    • Improved the WiFi connection sequence at the first WiFi.begin. Even if AutoConnectConfig::autoReconnect is disabled when SSID and PSK are not specified, it will use the information of the last established access point. The autoReconnect option will achieve trying the connect after a previous connection failed.
    • Added the AutoConnectConfig::immediateStart option and immediately starts the portal without first trying WiFi.begin. You can start the captive portal at any time in combination with the AutoConnectConfig::autoRise option.
    • Improved boot uri after reset. AutoConnectConfig::bootUri can be specified either /_ac or HOME path as the uri to be accessed after invoking Reset from AutoConnect menu.
    • Improved source code placement of predefined macros. Defined common macros have been moved to AutoConnectDefs.h.
    • Added AutoConnectConfig::hostName. It activates WiFi.hostname()/WiFi.setHostName().
    • Added the captive portal time-out. It can be controlled by AutoConnectConfig::portalTimeout and AutoConnectConfig::retainPortal.
    "},{"location":"changelog.html#fixes_17","title":"Fixes","text":"
    • Fixed crash in some environments. Thank you @ageurtse
    "},{"location":"changelog.html#096-sept27-2018","title":"[0.9.6] Sept.27, 2018.","text":""},{"location":"changelog.html#enhancements_17","title":"Enhancements","text":"
    • Improvement of RSSI detection for saved SSIDs.
    "},{"location":"changelog.html#fixes_18","title":"Fixes","text":"
    • Fixed disconnection SoftAP completely at the first connection phase of the AutoConnect::begin.
    "},{"location":"changelog.html#095-aug27-2018","title":"[0.9.5] Aug.27, 2018.","text":""},{"location":"changelog.html#enhancements_18","title":"Enhancements","text":"
    • Supports ESP32.
    "},{"location":"changelog.html#fixes_19","title":"Fixes","text":"
    • Fixed that crash may occur if the number of stored credentials in the EEPROM is smaller than the number of found WiFi networks.
    "},{"location":"changelog.html#094-may-5-2018","title":"[0.9.4] May 5, 2018.","text":""},{"location":"changelog.html#new-features_7","title":"New features","text":"
    • Supports AutoConnectConfig::autoReconnect option, it will scan the WLAN when it can not connect to the default SSID, apply the applicable credentials if it is saved, and try reconnecting.
    "},{"location":"changelog.html#enhancements_19","title":"Enhancements","text":"
    • Automatically focus Passphrase after selecting SSID with Configure New AP.
    "},{"location":"changelog.html#093-march-23-2018","title":"[0.9.3] March 23, 2018.","text":""},{"location":"changelog.html#enhancements_20","title":"Enhancements","text":"
    • Supports a static IP address assignment.
    "},{"location":"changelog.html#092-march-19-2018","title":"[0.9.2] March 19, 2018.","text":""},{"location":"changelog.html#enhancements_21","title":"Enhancements","text":"
    • Improvement of string literal declaration with the examples, no library change.
    "},{"location":"changelog.html#091-march-13-2018","title":"[0.9.1] March 13, 2018.","text":"
    • A release of the stable.
    "},{"location":"colorized.html","title":"Custom colorized","text":""},{"location":"colorized.html#autoconnect-menu-colorizing","title":"AutoConnect menu colorizing","text":"

    You can easily change the color of the AutoConnect menu. Menu colors can be changed statically by the AutoConnect menu color definition determined at compile time. You cannot change the color while the Sketch is running.

    The menu color scheme has been separated to AutoConnectLabels.h placed the AutoConnect library folder.1 You can change the color scheme of the menu with the following three color codes. The color code also accepts CSS standard color names.2

    In AutoConnectLabels.h you can find three definition macros for menu colors:

    • #define AUTOCONNECT_MENUCOLOR_TEXT Defines the menu text color.

    • #define AUTOCONNECT_MENUCOLOR_BACKGROUND Defines the menu background color.

    • #define AUTOCONNECT_MENUCOLOR_ACTIVE Defines the active menu item background color.

    "},{"location":"colorized.html#typical-color-schemes","title":"Typical color schemes","text":"

    Here are some color schemes picked up.

    "},{"location":"colorized.html#indigo","title":"Indigo","text":"
    #define AUTOCONNECT_MENUCOLOR_TEXT        \"#ffa500\"\n#define AUTOCONNECT_MENUCOLOR_BACKGROUND  \"#1a237e\"\n#define AUTOCONNECT_MENUCOLOR_ACTIVE      \"#283593\"\n
    "},{"location":"colorized.html#dim-gray","title":"Dim-gray","text":"
    #define AUTOCONNECT_MENUCOLOR_TEXT        \"#fffacd\"\n#define AUTOCONNECT_MENUCOLOR_BACKGROUND  \"#696969\"\n#define AUTOCONNECT_MENUCOLOR_ACTIVE      \"#808080\"\n
    "},{"location":"colorized.html#brown","title":"Brown","text":"
    #define AUTOCONNECT_MENUCOLOR_TEXT        \"#e6e6fa\"\n#define AUTOCONNECT_MENUCOLOR_BACKGROUND  \"#3e2723\"\n#define AUTOCONNECT_MENUCOLOR_ACTIVE      \"#4e342e\"\n

    1. Usually, it will locate to the Arduino/libraries/AutoConnect/src folder of user documents.\u00a0\u21a9

    2. The W3C HTML and CSS standards have listed only 16 valid color names: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, and yellow. Major browsers can accept more color names, but they are not web safe in typically.\u00a0\u21a9

    "},{"location":"credit.html","title":"Saved credentials access","text":""},{"location":"credit.html#saved-credentials-in-the-flash","title":"Saved credentials in the flash","text":"

    AutoConnect stores the credentials of 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 the AutoConnectCredential, which provides the way of access to the credentials stored in flash.1

    "},{"location":"credit.html#credentials-storage-location","title":"Credentials storage location","text":"

    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 nvs2) are used depending on the library versions.

    AutoConnect Arduino corefor ESP8266 Arduino core for ESP32 1.0.2 earlier 1.0.3 later v0.9.12 earlier EEPROM EEPROM (partition) Not supported v1.0.0 later Preferences (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 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_PREFERENCES3 macro definition in AutoConnectCredentials.h file. AutoConnect behaves assuming that credentials are stored in EEPROM if AUTOCONNECT_USE_PREFERENCES is not defined.

    "},{"location":"credit.html#autoconnectcredential","title":"AutoConnectCredential","text":""},{"location":"credit.html#include-header","title":"Include header","text":"
    #include <AutoConnectCredential.h>\n
    "},{"location":"credit.html#constructors","title":"Constructors","text":"
    AutoConnectCredential();\n

    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.

    AutoConnectCredential(uint16_t offset);\n
    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. This parameter is ignored for AutoConnect v1.0.0 or later with arduino-esp32 core 1.0.3 or later."},{"location":"credit.html#public-member-functions","title":"Public member functions","text":""},{"location":"credit.html#backup","title":"backup","text":"
    bool backup(Stream& out)\n

    Outputs all credentials currently stored by AutoConnect to the stream. Parameter outOutput destination stream. Return value trueAll credentials were successfully output. falseFailed to output.

    "},{"location":"credit.html#del","title":"del","text":"
    bool del(const char* ssid)\n

    Delete a credential the specified SSID. Parameter ssidSSID to be deleted. Return value trueSuccessfully deleted. falseFailed to delete.

    Clear saved credentials

    There is no particular API for batch clearing of all credential data stored by AutoConnect. It is necessary to prepare a sketch function that combines several AutoConnectCredential APIs to erase all saved credentials. The following function is an implementation example, and you can use it to achieve batch clearing.

    void deleteAllCredentials(void) {\n  AutoConnectCredential credential;\n  station_config_t config;\nuint8_t ent = credential.entries();\n\nwhile (ent--) {\n    credential.load(0, &config);\n    credential.del((const char*)&config.ssid[0]);\n  }\n}\n
    "},{"location":"credit.html#entries","title":"entries","text":"
    uint8_t entries(void)\n

    Returns number of entries as contained credentials. Return value Number of entries as contained credentials.

    "},{"location":"credit.html#load","title":"load","text":"
    int8_t load(const char* ssid, station_config_t* config)\n

    Load a credential entry and store to config. Parameters ssidSSID to be loaded. configstation_config_t Return value Save the specified SSID's credential entry to station_config_t pointed to by the parameter as config. -1 is returned if the SSID is not saved.

    "},{"location":"credit.html#load_1","title":"load","text":"
    bool load(int8_t entry, station_config_t* config)\n

    Load a credential entry and store to config. Parameters entrySpecifies the index number based 0 to be loaded. configstation_config_t Return value Save the specified credential entry to station_config_t pointed to by the parameter as config. -1 is returned if specified number is not saved.

    "},{"location":"credit.html#restore","title":"restore","text":"
    bool restore(Stream& in)\n

    The credentials data saved by the backup function is input from Storm and saved as AutoConnect credentials. Parameter inAn input stream of a file containing credential data saved with the backup function. Return value trueCredentials successfully restored. falseFailed to restore.

    "},{"location":"credit.html#save","title":"save","text":"
    bool save(const station_config_t* config)\n

    Save a credential entry. Parameter configstation_config_t to be saved. Return value trueSuccessfully saved. falseFailed to save.

    "},{"location":"credit.html#the-data-structures","title":"The data structures","text":""},{"location":"credit.html#station_config_t","title":"station_config_t","text":"

    The saved credential structure is defined as station_config_t in the AcutoConnectCredential header file.

    typedef struct {\nuint8_t ssid[32];\nuint8_t password[64];\nuint8_t bssid[6];\nuint8_t dhcp;   /**< 0:DHCP, 1:Static IP */\nunion _config {\nuint32_t  addr[5];\nstruct _sta {\nuint32_t ip;\nuint32_t gateway;\nuint32_t netmask;\nuint32_t dns1;\nuint32_t dns2;\n    } sta;\n  } config;\n} station_config_t;\n

    The byte size of station_config_t in program memory and stored credentials is different

    There is a gap byte for boundary alignment between the dhcp member and the static IP members of the above station_config_t. Its gap byte will be removed with saved credentials on the flash.

    "},{"location":"credit.html#the-credential-entry","title":"The credential entry","text":"

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

    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 1 Flag for DHCP or Static IP (0:DHCP, 1:Static IP) The following IP address entries are stored only for static IPs. variable(1) 4 Station IP address (uint32_t) variable(5) 4 Gateway address (uint32_t) variable(9) 4 Netmask (uint32_t) variable(13) 4 Primary DNS address (uint32_t) variable(17) 4 Secondary DNS address (uint32_t) variable variable Contained the next entries. (Continuation SSID+Password+BSSID+DHCP flag+Static IPs(if exists)) variable 1 0x00. End of container.

    AutoConnectCredential has changed

    It was lost AutoConnectCredential backward compatibility. Credentials saved by AutoConnect v1.0.3 (or earlier) will not work properly with AutoConnect v1.1.0. You need to erase the flash of the ESP module using the esptool before the sketch uploading. 

    esptool -c esp8266 (or esp32) -p [COM_PORT] erase_flash\n

    1. An example using AutoConnectCredential is provided as an example of a library sketch to delete saved credentials.\u00a0\u21a9

    2. The namespace for Preferences used by AutoConnect is AC_CREDT.\u00a0\u21a9

    3. Available only for AutoConnect v1.0.0 and later.\u00a0\u21a9

    4. There may be 0xff as an invalid data in the credential saving area. The 0xff area would be reused.\u00a0\u21a9

    "},{"location":"datatips.html","title":"Tips for data conversion","text":""},{"location":"datatips.html#convert-autoconnectelements-value-to-actual-data-type","title":"Convert AutoConnectElements value to actual data type","text":"

    The values in the AutoConnectElements field of the custom Web page are all typed as String. A sketch needs to be converted to an actual data type if the data type required for sketch processing is not a String type.

    The AutoConnect library does not provide the data conversion utility, and its function depends on Arduino language functions or functions of the type class. However, commonly used data conversion methods are generally similar.

    Here, represent examples the typical method for the data type conversion for the AutoConnectElements value of custom Web pages.

    "},{"location":"datatips.html#integer","title":"Integer","text":"

    Use int() or toInt() of String.

    AutoConnectInput& input = aux.getElement<AutoConnectInput>(\"INPUT\");\nint value = input.value.toInt();\n
    You can shorten it and write as like: 
    int value = aux[\"INPUT\"].value.toInt();\n

    "},{"location":"datatips.html#float","title":"Float","text":"

    Use float() or toFloat() of String.

    AutoConnectInput& input = aux.getElement<AutoConnectInput>(\"INPUT\");\nfloat value = input.value.toFloat();\n
    You can shorten it and write as like: 
    float value = aux[\"INPUT\"].value.toFloat();\n

    "},{"location":"datatips.html#date-time","title":"Date & Time","text":"

    The easiest way is to use the Arduino Time Library. Sketches must accommodate differences in date and time formats depending on the time zone. You can absorb the difference in DateTime format by using sscanf function.1

    #include <TimeLib.h>\n\ntime_t tm;\nint Year, Month, Day, Hour, Minute, Second;\n\nAutoConnectInput& input = aux.[\"INPUT\"].as<AutoConnectInput>();\nsscanf(input.value.c_str(), \"%d-%d-%d %d:%d:%d\", &Year, &Month, &Day, &Hour, &Minute, &Second);\ntm.Year = CalendarYrToTm(Year);\ntm.Month = Month;\ntm.Day = Day;\ntm.Hour = Hour;\ntm.Minute = Minute;\ntm.Second = Second;\n
    "},{"location":"datatips.html#ip-address","title":"IP address","text":"

    To convert a String to an IP address, use IPAddress::fromString. To stringize an instance of an IP address, use IPAddress::toString.

    IPAddress ip;\nAutoConnectInput& input aux[\"INPUT\"].as<AutoConnectInput>();\nip.fromString(input.value);\ninput.value = ip.toString();\n
    "},{"location":"datatips.html#validation-for-the-value","title":"Validation for the value","text":"

    To convert input data correctly from the string, it must match its format. The validation implementation with sketches depends on various perspectives. Usually, the tiny devices have no enough power for the lexical analysis completely. But you can reduce the burden for data verification using the pattern of AutoConnectInput.

    By giving a pattern to AutoConnectInput, you can find errors in data format while typing in custom Web pages. Specifying the input data rule as a regular expression will validate the type match during input. If there is an error in the format during input, the background color of the field will change to pink. Refer to section Handling the custom Web pages.

    However, input data will be transmitted even if the value does not match the pattern. Sketches require the validation of the received data. You can use the AutoConnectInput::isValid function to validate it. The isValid function validates whether the value member variable matches a pattern and returns true or false.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nstatic const char input_page[] PROGMEM = R\"raw(\n[\n  {\n    \"title\": \"IP Address\",\n    \"uri\": \"/\",\n    \"menu\": true,\n    \"element\": [\n      {\n        \"name\": \"ipaddress\",\n        \"type\": \"ACInput\",\n        \"label\": \"IP Address\",\n        \"pattern\": \"^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$\"\n      },\n      {\n        \"name\": \"send\",\n        \"type\": \"ACSubmit\",\n        \"value\": \"SEND\",\n        \"uri\": \"/check\"\n      }\n    ]\n  },\n  {\n    \"title\": \"IP Address\",\n    \"uri\": \"/check\",\n    \"menu\": false,\n    \"element\": [\n      {\n        \"name\": \"result\",\n        \"type\": \"ACText\"\n      }\n    ]\n  }\n]\n)raw\";\n\nAutoConnect portal;\n\nString checkIPAddress(AutoConnectAux& aux, PageArgument& args) {\n  AutoConnectAux&   input_page = *portal.aux(\"/\");\n  AutoConnectInput& ipaddress = input_page[\"ipaddress\"].as<AutoConnectInput>();\n  AutoConnectText&  result = aux[\"result\"].as<AutoConnectText>();\n\nif (ipaddress.isValid()) {\n    result.value = \"IP Address \" + ipaddress.value + \" is OK.\";\n    result.style = \"\";\n  }\nelse {\n    result.value = \"IP Address \" + ipaddress.value + \" error.\";\n    result.style = \"color:red;\";\n  }\nreturn String(\"\");\n}\n\nvoid setup() {\n  portal.load(input_page);\n  portal.on(\"/check\", checkIPAddress);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    Regular Expressions for JavaScript

    Regular expressions specified in the AutoConnectInput pattern conforms to the JavaScript specification.

    Here, represent examples the typical regular expression for the input validation.

    "},{"location":"datatips.html#url","title":"URL","text":"
    ^\\w+([-+.]\\w+)*@\\w+([-.]\\w+)*\\.\\w+([-.]\\w+)*$\n
    "},{"location":"datatips.html#dns-hostname","title":"DNS hostname","text":"
    ^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\-]*[A-Za-z0-9])$\n
    "},{"location":"datatips.html#email-address-2","title":"email address 2","text":"
    ^[a-zA-Z0-9.!#$%&'*+\\/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*$\n
    "},{"location":"datatips.html#ip-address_1","title":"IP Address","text":"
    ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$\n
    "},{"location":"datatips.html#date-as-mmddyyyy-3","title":"Date as MM/DD/YYYY 3","text":"
    ^(0[1-9]|1[012])[- \\/.](0[1-9]|[12][0-9]|3[01])[- \\/.](19|20)\\d\\d$\n

    Contain with backquote

    If that regular expression contains a backquote it must be escaped by backquote duplication.

    1. The ssanf library function cannot be used with the old Arduino core.\u00a0\u21a9

    2. This regular expression does not fully support the format of the e-mail address requested in RFC5322.\u00a0\u21a9

    3. This regular expression does not consider semantic constraints. It is not possible to detect errors that do not exist as actual dates.\u00a0\u21a9

    "},{"location":"esp32cam.html","title":"Works with ESP32-CAM","text":""},{"location":"esp32cam.html#what-this-example-presents","title":"What this example presents","text":"

    ESP-IDF is offering ESP32 Camera Driver as an interface to small image sensors that can work with ESP32. This driver supports a variety of popular image sensors, such as the OV2640, which has low power consumption and mega-pixel sensing capability. By reading through this chapter you will know how to make the sketch featuring a UI that looks like the followings. Of course, it has the convenience of AutoConnect as well. This example shows how to sketch the Web Camera Application that involves using AutoConnect together with the ESP32 Camera Driver.

    "},{"location":"esp32cam.html#why-we-can-not-use-app_httpdcpp-together-with-autoconnect","title":"Why we can not use app_httpd.cpp together with AutoConnect","text":"

    The ESP32 library of the ESP32 Arduino core features a CameraWebServer.ino that includes an interface to drive the Camera Driver. The core process of the server-side of that sketch application is app_httpd.cpp, which consists of initializing and configuring the image sensor, configuring and capturing image frames, and sending the image frames through an internally started HTTP server.

    While Web UI provided by CameraWebServer.ino is sophisticated, the role of app_httpd.cpp is focused on responding to the Fetch required by the Web UI (which is actually an HTML page specific to each sensor model that is extracted from the gzipped camera_index.h). It is a set of primitive functions that are integrated with the Web UI. Also, app_httpd.cpp has hardcoded the TCP port of the internally invoking HTTP server as fixed at 80, which conflicts with the HTTP port used by a typical captive portal. Therefore, It is impossible to apply app_httpd.cpp which has fixed 80 TCP port depending on the WebUI of CameraWebServer.ino to sketches using AutoConnect as it is.

    CameraWebServer.ino extended version available on GitHub

    An extended version of app_httpd.cpp is available on the GitHub repository to make it a bit more flexible for different usage scenarios. It also can handling the captive portal itself.

    "},{"location":"esp32cam.html#strategy","title":"Strategy","text":"

    As mentioned earlier, app_httpd.cpp is integrated with CameraWebServer.ino's Web UI. However, its functionality can be separated into two parts: an interface for driving the image sensor correctly and sending the captured images on the HTTP stream as requested by the client. It also has the ability to configure the sensor settings over the network remotely, but this can be omitted at the expense of interactivity. (We can implement that feature after the initial purpose is achieved)

    So, I have prepared two separate classes with these functions. ESP32WebCam and ESP32Cam are independent classes inspired by app-httpd.cpp, and they can interface with the ESP32 Camera Driver individually, or send out motion JPEGs via an HTTP server task running inside the class.

    These two classes are completely independent of the AutoConnect library and can be incorporated into your various other sketches on their own. the source code for the ESP32WebCam and ESP32Cam classes can be found in the AutoConnect library examples and are distributed together. The API specifications for these two classes are described later in this chapter.

    "},{"location":"esp32cam.html#implementing-a-streaming-server-with-esp32-cam-using-autoconnect","title":"Implementing a Streaming Server with ESP32-CAM using AutoConnect","text":"

    A minimal sketch that involves the ESP32WebCam and ESP32Cam classes and incorporates them together with AutoConnect is shown below. This sketch will work with Ai-Thinker ESP32-CAM, which is one of the most popular ESP32 modules with OmniVision OV2640 image sensor.

    In order to experience this sketch, copy the five files ESP32WebCam.h, ESP32WebCam.cpp, ESP32Cam.h, ESP32Cam.cpp, and ESP32Cam_pins.h from the WebCamServer folder located AutoConnect library examples to the same folder as the sketchbook folder where you placed this sketch. Connect the ESP32-CAM module to your PC and launch the Arduino IDE. Then select the correct board you using from the Tool menu of Arduino IDE and compile it. (Don't forget to open the serial monitor)

    #include <Arduino.h>\n#include <WiFi.h>\n#include <WebServer.h>\n#include <AutoConnect.h>\n#include \"ESP32WebCam.h\"\n\nconst char  CAMERA_VIEWER[] = R\"*(\n{\n  \"title\": \"Camera\",\n  \"uri\": \"/\",\n  \"menu\": false,\n  \"element\": [\n    {\n      \"name\": \"viewport\",\n      \"type\": \"ACText\",\n      \"format\": \"<img src='http://%s'>\",\n      \"posterior\": \"none\"\n    },\n    {\n      \"name\": \"discon\",\n      \"type\": \"ACElement\",\n      \"value\": \"<script>window.addEventListener('pagehide',function(){window.stop();});</script>\"\n    }\n  ]\n}\n)*\";\n\n// Declare ESP32-CAM handling interface. It contains ESP-IDF Web Server.\nESP32WebCam webcam(ESP32Cam::CAMERA_MODEL_AI_THINKER);\n\n// AutoConnect portal. It contains the WebServer from ESP32 Arduino Core.\nAutoConnect portal;\nAutoConnectConfig config;\n\n// AutoConnectAux page handler, it starts streaming by adding the ESP32WebCam\n// streaming endpoint to the src attribute of the img tag on the AutoConnectAux page.\nString viewer(AutoConnectAux& aux, PageArgument &args) {\n  AutoConnectAux& viewer = *portal.aux(\"/\");\n// Set the Streaming server host, port, and endpoint\n  viewer[\"viewport\"].value = WiFi.localIP().toString() + \":\" + String(webcam.getServerPort())\n+ String(webcam.getStreamPath());\nreturn String();\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n// Start Image sensor\nif (webcam.sensorInit() != ESP_OK) {\n    Serial.println(\"Camera initialize failed\");\n  }\n\n// Allow automatic re-connection as long as the WiFi connection is established.\n  config.autoReconnect = true;\n  config.reconnectInterval = 1;\n  portal.config(config);\n\n// Start the portal, it will launch the WebServer for the portal from inside of AutoConnect.\nif (portal.begin()) {\n    portal.load(CAMERA_VIEWER);\n    portal.on(\"/\", viewer);\n// Start ESP32 Camera Web Server\nif (webcam.startCameraServer() == ESP_OK) {\n      Serial.printf(\"ESP32WebCam server %s port %u ready\\n\", WiFi.localIP().toString().c_str(),\n        webcam.getServerPort());\n    }\nelse {\n      Serial.println(\"ESP32WebCam server start failed\");\n    }\n  }\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    If your ESP32-CAM module still has no connection with any access point, a captive portal will open. Use your cellphone to connect the ESP32-CAM to the access point. When ESP32-CAM successfully connects to the access point, you will see the IP address on the serial monitor. You visit the IP address from your browser, you can see the image captured by the ESP32-CAM.

    Streaming stops caused by ERR_CONNECTION_RESET

    Sometimes the browser will throw the above error and the streaming will stop. In the simple sketch above, which does not include the transmission error recovery process, the TCP packet transmission is incomplete due to a weak WiFi signal or other reasons, and the browser will stop loading the image. Send errors can be recovered by incorporating an event handler into the img tag, and an example of its implementation is shown later in this chapter.

    "},{"location":"esp32cam.html#program-structure","title":"Program structure","text":"

    The sketch of AutoConnect using ESP32WebCam and ESP32Cam classes is divided into several components, which will take a similar form in any sketch application. Their logical components are as follows:

    1. Include ESP32WebCam.h header file. 

      #include \"ESP32WebCam.h\"\n

    2. AutoConnectAux defines a custom web page in JSON description. It includes an img tag that displays the captured image. The src attribute of the img tag is not hard-coded and can be dynamically set in a custom web page handler to make the sketch more applicable to various situations. 

      {\n\"name\": \"viewport\",\n\"type\": \"ACText\",\n\"format\": \"<img src='http://%s'>\",\n\"posterior\": \"none\"\n}\n

    3. Insert AutoConnectElement in the JSON description of your custom web page with JavaScript enclosed in <script>~</script> in HTML to stop streaming on page transition. 

      window.addEventListener('pagehide', function () {\n  window.stop();\n});\n

      Why window.stop() is needed

      That's because image streaming is achieved by continuous loading of Motion JPEG using HTTP multipart/x-mixed-replace keep-alive stream. With this type of MIME content, the server will continue to push the content unless the client explicitly notifies the server of the end of the session. The method of notifying the end of the session varies depending on the client browser, and by issuing window.stop(), the difference in the behavior of each browser is absorbed.

    4. Declare ESP32WebCam instance. It accompanies the parameters with the appropriate model specifiers. 

      ESP32WebCam webcam(ESP32Cam::CAMERA_MODEL_AI_THINKER);\n
      For details on identifiers that can be specified as image sensor models, please refer to the APIs described below.

    5. Declare AutoConnect instance. If your sketch requires a native web page that is not an AutoConnectAux, you can declare a WebServer instance at the same place to make it easier to call from functions in your sketch. 

      AutoConnect portal;\n

    6. Declare AutoConnectConfig to control WiFi connection behavior if necessary. 

      AutoConnectConfig config;\n

    7. Prepare an AutoConnectAux custom page handler for the declared above AutoConnectAux JSON. Typically, this handler is responsible for handling the ESP32Cam class via the endpoint interface provided by the ESP32Cam class. In the above sketch, we have only given the endpoint (i.e. http://{WiFi.localIP}:3000/_stream) for streaming by the ESP32WebCam class as the src attribute of the img tag identified id=viewport, since we are focusing on the minimum necessary processing. ESP32WebCam class will deliver the captured image with just this operation. 

      AutoConnectAux& viewer = *portal.aux(\"/\");\nviewer[\"viewport\"].value = WiFi.localIP().toString() + \":\" + String(webcam.getServerPort())\n+ String(webcam.getStreamPath());\n
      For more information about ESP32Cam capability and ESP32WebCam endpoints, please refer to the Endpoint interfaces described below.

      Using AutoConnectText with format string

      In the sketch above, the format attribute of AutoConnectText is used to set the src attribute of the img tag. The AutoConnectText format attribute produces the same output as a C-style printf(format, value), depending on the string that can be derived from the value. 

      printf(\"<img src='http://%s'>\", \"localhost:3000/_stream\");\n

    8. Start the sketch and initialize the camera using ESP32WebCam::sensorInit. ESP_OK will returned on success to initialize the image sensor. 

      ESP32WebCam webcam(ESP32Cam::CAMERA_MODEL_AI_THINKER);\n\nif (webcam.sensorInit() != ESP_OK) {\n  Serial.println(\"Camera initialize failed\");\n}\n

    9. Configure WiFi state control to maintain connection. Usually, AutoConnectConfig::autoReconnect will keep WiFi connection stateful. 

      config.autoReconnect = true;\nconfig.reconnectInterval = 1;\nportal.config(config);\n

    10. Start the portal, and load the view page. 

      portal.begin();\nportal.load(CAMERA_VIEWER);\n

    11. Register the view page handler and start the streaming server using ESP32WebCam::startCameraServer. ESP_OK will returned on start the streaming server successfully. 

      portal.on(\"/\", viewer);\nif (webcam.startCameraServer() == ESP_OK) {\n  Serial.printf(\"ESP32WebCam server ready: %s\\n\", WiFi.localIP().toString().c_str());\n}\nelse {\n  Serial.println(\"ESP32WebCam server start failed\");\n}\n

    12. Loop for portal.handleClient().

    The app_httpd.cpp, which is the core of CameraWebServer.ino's functionality, has a mixture of an interface with the ESP32 Camera Driver and remote control over the network via an HTTP server. While it is highly functional, but it will cause a decline in versatility. ESP32WebCam and ESP32Cam separate the mixed functionality of app_httpd.cpp into two classes, each with a single role. This makes them versatile and simple to use. And they can coexist with AutoConnect.

    If you only need to stream from the image sensor, you can simplify the sketch structure as in the example above. The simplicity of the sketch is mainly due to the usefulness of the ESP32WebCam and ESP32Cam classes. In driving the ESP32 Camera Driver on the ESP32-CAM module, the sketch interfaces with the ESP32WebCam class and processes the ESP32Cam class through the ESP32WebCam endpoint interface.

    "},{"location":"esp32cam.html#esp32webcam-class-and-esp32cam-class","title":"ESP32WebCam Class and ESP32Cam Class","text":"

    The ESP32WebCam class has an endpoint interface to allow the sketch to manipulate the image sensor over the network. The sketch can use HTTP GET method to capture images, stream the captured images, and save them to SD card. It also starts its own HTTP server task internally, and this HTTP server runs as a separate task from the WebServer hosted by AutoConnect.

    The ESP32Cam class is a wrapper that governs the native interface with the ESP32 Camera Driver which is a component of ESP-IDF. It can initialize the sensor, set the sensor characteristics, save and load the settings, and save the captured images to the SD card.

    In the case of accessing image sensors located across a network, the sketch will usually have a UI to remotely control the ESP32-CAM. If the UI is intended to be a web interface, the sketch will use a request handler that is compatible with the ESP32 WebServer hosted by AutoConnect to serve the manipulation web page. That page can be an AutoConnectAux-based custom web page, or it can be the RequestHanlder callback that can respond to the ESP32 WebServer class. In any case, those UI pages can remotely access the image sensor of the ESP32-CAM module through the HTTP endpoint interface deployed at a specific URL of the HTTP server launched by the ESP32WebCam class, and do the required processing.

    "},{"location":"esp32cam.html#esp32webcam-features","title":"ESP32WebCam features:","text":"
    • Run the HTTP server as a background task.
    • Stream Motion JPEG via HTTP multipart/x-mixed-replace MIME.
    • Serves a captured image via HTTP.
    • Instruct the ESP32Cam to save the captured image to the SD card via HTTP.

    Of these processing requests, the ESP32Cam class is responsible for the ones that actually need to interface with the camera driver. (However, reading from the frame buffer is excluded. ESP32WebCam reads image data directly from the frame buffer of the image sensor without ESP32Cam.) The ESP32Cam class manipulates sensor characteristics, including setting image frame properties, image format settings, and exposure, gain, white balance, and band filter settings. It also saves the captured image to an SD card wired to the ESP32-CAM.

    "},{"location":"esp32cam.html#esp32cam-features","title":"ESP32Cam features:","text":"
    • Directs and acquires sensor settings.
    • Save and load the sensor settings to the flash memory on the ESP32 module.
    • Save the captured image to the SD card which is wired to ESP32 module.
    • Save captured images to SD card periodically using an ESP32 built-in hardware timer.
    "},{"location":"esp32cam.html#esp32webcam-class-apis","title":"ESP32WebCam Class APIs","text":""},{"location":"esp32cam.html#constructor","title":"Constructor","text":"
    ESP32WebCam(const uint16_t port = ESP32CAM_DEFAULT_HTTPPORT)\n
    ESP32WebCam(const ESP32Cam::CameraId model, const uint16_t port = ESP32CAM_DEFAULT_HTTPPORT)\n

    Instantiate ESP32WebCam. The constructor also instantiates ESP32Cam, so there is no need to explicitly declare the ESP32Cam class in the sketch. At the time of declaring the constructor, the camera is not initialized and the HTTP server is not started. Each of them requires a separate dedicated function to be called. Parameters portPort number of the HTTP server that ESP32WebCam starts. Default port number defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h modelSpecifies the model of the onboard image sensor. The image sensor models that can be specified are as follows:

    • ESP32Cam::CAMERA_MODEL_WROVER_KIT
    • ESP32Cam::CAMERA_MODEL_ESP_EYE
    • ESP32Cam::CAMERA_MODEL_M5STACK_NO_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_V2_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_WIDE
    • ESP32Cam::CAMERA_MODEL_M5STACK_ESP32CAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_UNITCAM
    • ESP32Cam::CAMERA_MODEL_AI_THINKER
    • ESP32Cam::CAMERA_MODEL_TTGO_T_JOURNAL
    "},{"location":"esp32cam.html#getcapturepath","title":"getCapturePath","text":"
    const char* getCapturePath(void)\n

    Get a path containing the first '/' of the currently valid endpoint URL to capture. Return valueA path of capturing URL. Default path defined by ESP32CAM_DEFAULT_PATH_CAPTURE macro directive in ESP32WebCam.h.

    "},{"location":"esp32cam.html#getpromptpath","title":"getPromptPath","text":"
    const char* getPromptPath(void)\n

    Get a path containing the first '/' of the currently valid endpoint URL to prompt. Return valueA path of prompting URL. Default path defined by ESP32CAM_DEFAULT_PATH_PROMPT macro directive in ESP32WebCam.h.

    "},{"location":"esp32cam.html#getserverhandle","title":"getServerHandle","text":"
    httpd_handle_t getServerHandle(void)\n

    Returns the handle of the HTTP server started by ESP32WebCam. Return valueReturns the httpd_handle_t value of an HTTP server started by ESP32WebCam. If the HTTP server task is not running, nullptr is returned.

    "},{"location":"esp32cam.html#getserverport","title":"getServerPort","text":"
    uint16_t getServerPort(void)\n

    Returns the port number that the HTTP server on listens to. Return valueReturns a port number of an HTTP server started by ESP32WebCam. Default port number defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h

    "},{"location":"esp32cam.html#getstreampath","title":"getStreamPath","text":"
    const char* getStreamPath(void)\n

    Get a path containing the first '/' of the currently valid endpoint URL to streaming. Return valueA path of streaming URL. Default path defined by ESP32CAM_DEFAULT_PATH_STREAM macro directive in ESP32WebCam.h.

    "},{"location":"esp32cam.html#isserverstarted","title":"isServerStarted","text":"
    bool isServerStarted(void)\n

    Returns a boolean value indicating whether the HTTP server task is running or not. Return value trueThe HTTP Server tasks is running. falseThe HTTP server task has not been started.

    "},{"location":"esp32cam.html#sensor","title":"sensor","text":"
    ESP32Cam& sensor(void)\n

    Returns a reference to ESP32Cam, which is instantiated internally by ESP32WebCam constructor. Return valueA reference to ESP32Cam instance. The image sensor is not initialized just by calling the ESP32WebCam constructor. To initialize the sensor, you need to call the sensorInit() function.

    ESP32WebCam webcam();\nwebcam.sensorInit();\n

    "},{"location":"esp32cam.html#sensorinit","title":"sensorInit","text":"
    esp_err_t sensorInit(void)\n
    esp_err_t sensorInit(const ESP32Cam::CameraId model)\n

    Initialize the image sensor via the ESP32Cam class. The sketch needs to initialize the sensor with the sensorInit function prior to all processing of the image sensor. Parameters modelSpecifies the model of the onboard image sensor. The image sensor models that can be specified are same as the constructor parameter. Return value ESP_OKAn image sensor successfully initialized. ESP_ERR_CAMERA_NOT_SUPPORTEDSpecified model is not supported. ESP_ERR_CAMERA_NOT_DETECTEDAn image sensor not detected. ESP_ERR_CAMERA_FAILED_TO_SET_FRAME_SIZEFrame identifier is invalid. ESP_ERR_CAMERA_FAILED_TO_SET_OUT_FORMATOutput image format is invalid. ESP_FAILOther error occurred.

    "},{"location":"esp32cam.html#setcapturepath","title":"setCapturePath","text":"
    void setCapturePath(const char* path)\n

    Reconfigure the already defined path of the endpoint for capture. Parameters pathSpecifies the path of the capture endpoint to be set newly, as a string starting with '/'. If this path is not specified, the default path defined by ESP32CAM_DEFAULT_PATH_CAPTURE macro directive will be assumed.

    "},{"location":"esp32cam.html#setpromptpath","title":"setPromptPath","text":"
    void setPromptPath(const char* path)\n

    Reconfigure the already defined path of the endpoint for prompt. Parameters pathSpecifies the path of the prompt endpoint to be set newly, as a string starting with '/'. If this path is not specified, the default path defined by ESP32CAM_DEFAULT_PATH_PROMPT macro directive will be assumed.

    "},{"location":"esp32cam.html#setserverport","title":"setServerPort","text":"
    void setServerPort(const uint16_t port)\n

    Reconfigure the already defined port number of an HTTP server. Parameters portSpecifies port number of an HTTP Server. Default port number defined by ESP32CAM_DEFAULT_HTTPPORT macro directive will be assumed.

    "},{"location":"esp32cam.html#setstreampath","title":"setStreamPath","text":"
    void setStreamPath(const char* path)\n

    Reconfigure the already defined path of the endpoint for stream. Parameters pathSpecifies the path of the stream endpoint to be set newly, as a string starting with '/'. If this path is not specified, the default path defined by ESP32CAM_DEFAULT_PATH_STREAM macro directive will be assumed.

    "},{"location":"esp32cam.html#startcameraserver","title":"startCameraServer","text":"
    esp_err_t startCameraServer(const char* streamPath)\n
    esp_err_t startCameraServer(const char* streamPath, const char* capturePath, const char* promptPath)\n
    esp_err_t startCameraServer(const char* streamPath, const char* capturePath, const char* promptPath, const uint16_t port)\n
    esp_err_t startCameraServer(const char* streamPath, const uint16_t port)\n
    esp_err_t startCameraServer(const uint16_t port)\n
    esp_err_t startCameraServer(void)\n

    Begins the HTTP server task, and start the endpoint service. By starting the HTTP server task, the endpoint interface provided by ESP32WebCam will be available. Parameters streamPathSpecifies the path of the stream endpoint. Default stream path is defined by ESP32CAM_DEFAULT_PATH_STREAM macro directive in ESP32WebCam.h header file. capturePathSpecifies the path of the capture endpoint. Default capture path is defined by ESP32CAM_DEFAULT_PATH_CAPTURE macro directive in ESP32WebCam.h header file. promptPathSpecifies the path of the prompt endpoint. Default prompt path is defined by ESP32CAM_DEFAULT_PATH_PROMPT macro directive in ESP32WebCam.h header file. portSpecifies port number on which the HTTP server listens. Default port number is 3000 which defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h header file. Return value ESP_OKAn HTTP server task successfully started. ESP_ERR_HTTPD_HANDLERS_FULLAll slots for registering URI handlers have been consumed. ESP_ERR_HTTPD_ALLOC_MEMFailed to dynamically allocate memory for resource. ESP_ERR_HTTPD_TASKFailed to launch server task/thread. ESP_FAILOther error occurred.

    HTTP server task stack size

    ESP32WebCam allocates 8KB of stack when it starts the HTTP server task. This stack size is larger than the size allocated by the default HTTPD_DEFAULT_CONFIG in ESP-IDF. This is to include the stack consumed by the file system of the SD card triggered by the timer shot. This stack size can be changed as needed, and the default value is defined in the ESP32Cam.h header file as ESP32CAM_TIMERTASK_STACKSIZE.

    "},{"location":"esp32cam.html#stopcameraserver","title":"stopCameraServer","text":"
    void stopCameraServer(void)\n

    Stop an HTTP server task and free resources.

    "},{"location":"esp32cam.html#esp32webcam-endpoint-interfaces","title":"ESP32WebCam Endpoint Interfaces","text":"

    ESP32WebCam has endpoint interfaces for simple manipulation of image sensors over the network via an internally launched HTTP server, which follows the traditional HTTP request and response, not WebAPI or REST. It supports the HTTP GET1 method and will be available after the HTTP server is started by the ESP32WebCam::startCameraServer function.

    If you are using Visual Studio Code as your build system for Arduino sketch, you can easily experiment with the ESP32WebCam endpoint interface using the VSCode extension. REST Client is an excellent VSCode extension that allows you to send HTTP requests directly from within the editor. The following screenshot shows the result of sending an HTTP request directly to the capture endpoint of ESP32WebCam using the REST Client on a VSCode with the PlatformIO build system.

    The top left editor pane is the sketch code described above, and the bottom pane is the serial monitor output of the sketch. The pane between the top and bottom panes is the REST Client. Run the sketch, and when the serial monitor shows a message that ESP32Cam has started the HTTP server, use the REST client to send an HTTP GET request as GET http://{HOST}:{PORT}/_capture (In the screenshot above, the request is sent to http://192.168.1.19:3000/_capture) to the capture endpoint.2 You will see the response of the image captured by ESP32-CAM in the right pane.

    "},{"location":"esp32cam.html#the-default-settings-for-the-endpoint-interface-provided-by-esp32webcam-are-as-follows","title":"The default settings for the endpoint interface provided by ESP32WebCam are as follows:","text":"Endpoint Default path Function Default value defined in ESP32WebCam.h Capture /_capture Responds as a captured image ESP32CAM_DEFAULT_PATH_CAPTURE Prompt /_prompt Save and load the captured image, Save the sensor settings ESP32CAM_DEFAULT_PATH_PROMPT Stream /_stream Stream image ESP32CAM_DEFAULT_PATH_STREAM"},{"location":"esp32cam.html#capture","title":"Capture","text":"
    GET http://{HOST}:{PORT}{PATH}\n

    The capture endpoint responds captured image with the image/jpeg mime format. Parameters HOSTHost address of ESP32-CAM. PORTPort number of HTTP server listening on. Default port number is 3000 which defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h header file. PATHA path for the capture endpoint. Response code 200Content body contains captured image data.

    "},{"location":"esp32cam.html#prompt","title":"Prompt","text":"
    GET http://{HOST}:{PORT}{PATH}?{QUERY}\n

    You can use the prompt endpoint to save the captured image to the SD card at that moment or in a timer cycle, save the sensor settings, and load them into the flash memory built into the ESP32 module. The instructions for the prompt action performed by ESP32WebCam are specified as the query string with \"key=value\" form for the parameters of the GET request.Parameters HOSTHost address of ESP32-CAM. PORTPort number of HTTP server listening on. Default port number is 3000 which defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h header file. PATHA path for the capture endpoint. QUERYThe QUERY that Prompt can accept are different for each feature. The query formats that can be specified and the corresponding functions are shown below. Response code 202Request accepted. 400Query string has syntax error, or Fatal error occurred. Content body has detailed error code.

    "},{"location":"esp32cam.html#the-following-features-are-currently-supported-by-the-prompt-endpoint","title":"The following features are currently supported by the prompt endpoint:","text":"Specifying by query string Function Behavior mf=oneshot[&fs={sd|mmc}][&filename=<FILENAME>] One-shot Take a one-shot image and save it to the SD card. mf=timershot[&fs={sd|mmc}][&filename=<FILENAME>][&period=<INTERVAL>] Timer-shot Repeatedly takes a one-shot image at specified an INTERVAL of seconds and saves it to the SD card. mf=distimer Disable timer Suspend timer for Timer-shot mf=entimer Enable timer Resume timer for Timer-shot mf=load Load settings Load the image sensor settings from the NVS mf=save Save settings Save the image sensor settings to the NVS

    The query formats that can be specified and their corresponding functions are described below.Functions: Specifies with the mf= query. oneshotCapture an image at the requested timing and save them to the SD card. Species either sd or mmc for the fs argument. If the fs argument does not exist, mmc is assumed.Saves the captured image with the file name specified by the filename argument; if the filename argument does not exist, it assumes a file name consisting of a prefix and a timestamp. In that case, the fixed string defined by the ESP32CAM_GLOBAL_IDENTIFIER macro directive in ESP32Cam.h is used as the prefix. timershotRepeatedly takes a one-shot image at specified an INTERVAL of seconds with period argument and saves it to the SD card. Species either sd or mmc for the fs argument. If the fs argument does not exist, mmc is assumed.Saves the captured image to a file whose name consists of the prefix and timestamp suffix specified by the filename argument. If the filename argument does not exist, the prefix will be assumed a fixed string defined by the ESP32CAM_GLOBAL_IDENTIFIER macro directive in ESP32Cam.h header file. distimerTemporarily stops the timer for the timershot. This can be resumed with entimer. entimerResumes a timer-shot that was temporarily stopped by distimer. loadLoad the image sensor settings from NVS. saveSave the image sensor settings to NVS.

    Whether it is SD or MMC depends on the hardware

    The ESP32 Arduino SD library supports two types of SD cards with different interfaces. Which type of SD card is used depends on the ESP32 module and needs to be chosen appropriately. In the case of the Ai-Thinker ESP32-CAM 3, the ESP32 is wired to the SD slot with each HS2 signal. Hence, We can see from the schematic that it is using MMC.

    "},{"location":"esp32cam.html#stream","title":"Stream","text":"
    GET http://{HOST}:{PORT}{PATH}\n

    The stream endpoint responds captured image with the image/jpeg mime format with multipart/x-mixed-replace HTTP header. Parameters HOSTHost address of ESP32-CAM. PORTPort number of HTTP server listening on. Default port number is 3000 which defined by ESP32CAM_DEFAULT_HTTPPORT macro directive in ESP32WebCam.h header file. PATHA path for the stream endpoint. Response code 200Content body contains captured image data with multipart boundary.

    "},{"location":"esp32cam.html#esp32cam-class-apis","title":"ESP32Cam Class APIs","text":""},{"location":"esp32cam.html#constructor_1","title":"Constructor","text":"
    ESP32Cam()\n
    ESP32Cam(const CameraId model)\n

    Instantiate ESP32Cam. The image sensor is not initialized just by calling the constructor. To initialize the sensor, you need to call the init function. Parameters modelSpecifies the model of the onboard image sensor. The image sensor models that can be specified are as follows:

    • ESP32Cam::CAMERA_MODEL_WROVER_KIT
    • ESP32Cam::CAMERA_MODEL_ESP_EYE
    • ESP32Cam::CAMERA_MODEL_M5STACK_NO_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_V2_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_WIDE
    • ESP32Cam::CAMERA_MODEL_M5STACK_ESP32CAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_UNITCAM
    • ESP32Cam::CAMERA_MODEL_AI_THINKER
    • ESP32Cam::CAMERA_MODEL_TTGO_T_JOURNAL
    "},{"location":"esp32cam.html#getstatus","title":"getStatus","text":"
    esp_err_t getStatus(camera_status_t* status)\n

    Get the camera_status_t data structure from the image sensor. Parameters statusPointer to the buffer to store the acquired camera_status_t structure. Return value ESP_OKcamera_status_t is read successfully. ESP_FAILImage sensor is not initialized.

    "},{"location":"esp32cam.html#getframesize","title":"getFramesize","text":"
    framesize_t getFramesize(void)\n

    Get the current configuration of the image sensor frame size. Return value framesize_tThe framesize_t enumeration value.

    "},{"location":"esp32cam.html#getframeheight","title":"getFrameHeight","text":"
    uint16_t  getFrameHeight(void)\n

    Returns the height of the current image frame in pixels. Return value uint16_tHeight of the image frame.

    "},{"location":"esp32cam.html#getframewidth","title":"getFrameWidth","text":"
    uint16_t  getFrameWidth(void)\n

    Returns the width of the current image frame in pixels. Return value uint16_tWidth of the image frame.

    "},{"location":"esp32cam.html#init","title":"init","text":"
    esp_err_t init(void)\n
    esp_err_t init(const CameraId model)\n

    Initialize the image sensor. Parameters modelSpecifies the model of the onboard image sensor. The image sensor models that can be specified are as follows:

    • ESP32Cam::CAMERA_MODEL_WROVER_KIT
    • ESP32Cam::CAMERA_MODEL_ESP_EYE
    • ESP32Cam::CAMERA_MODEL_M5STACK_NO_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_V2_PSRAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_WIDE
    • ESP32Cam::CAMERA_MODEL_M5STACK_ESP32CAM
    • ESP32Cam::CAMERA_MODEL_M5STACK_UNITCAM
    • ESP32Cam::CAMERA_MODEL_AI_THINKER
    • ESP32Cam::CAMERA_MODEL_TTGO_T_JOURNAL
    "},{"location":"esp32cam.html#loadsettings","title":"loadSettings","text":"
    esp_err_t loadSettings(const char* key = nullptr)\n

    Load the image sensor settings from NVS in the ESP32 flash. Parameters keySpecifies NVS key name. If key is nullptr or not specified, default key which defined by ESP32CAM_NVS_KEYNAME macro directive in ESP32Cam.h header file will be assumed. Return value ESP_OKThe image sensor settings has been successfully loaded.

    "},{"location":"esp32cam.html#savesettings","title":"saveSettings","text":"
    esp_err_t saveSettings(const char* key = nullptr)\n

    Save the current image sensor settings to NVS in the ESP32 flash. Parameters keySpecifies NVS key name. If key is nullptr or not specified, default key which defined by ESP32CAM_NVS_KEYNAME macro directive in ESP32Cam.h header file will be assumed. Return value ESP_OKThe image sensor settings has been successfully saved.

    "},{"location":"esp32cam.html#setstatus","title":"setStatus","text":"
    esp_err_t setStatus(const camera_status_t& status)\n

    Set the content of camera_status_t structure to the image sensor. Parameters statusReference of the camera_status_t structure. Return value ESP_OKcamera_status_t has been set successfully. ESP_FAILImage sensor is not initialized.

    "},{"location":"esp32cam.html#setframesize","title":"setFramesize","text":"
    esp_err_t setFramesize(const framesize_t framesize)\n

    Set the image sensor frame size. Parameters framesizeThe framesize_t enumeration value to be set. Return value ESP_OKFramesize has been set. ESP_ERR_CAMERA_FAILED_TO_SET_FRAME_SIZEImage sensor is not initialized, the framesize is invalid, or the pixel format is not JPEG.

    "},{"location":"esp32cam.html#setimageformat","title":"setImageFormat","text":"
    esp_err_t setImageFormat(const pixformat_t format)\n

    Set the image format. Parameters formatThe pixformat_t enumeration value to be set. Return value ESP_OKFormat has been set. ESP_ERR_CAMERA_FAILED_TO_SET_OUT_FORMATSpecified format is invalid. ESP_FAILImage sensor is not initialized.

    "},{"location":"esp32cam.html#oneshot","title":"oneShot","text":"
    esp_err_t oneShot(fs::SDFS& sd, const char* filename = nullptr)\n
    esp_err_t oneShot(fs::SDMMCFS& mmc, const char* filename = nullptr)\n

    Take a one-shot image and save it to the SD card or MMC. This function writes to a file compliant with the ESP32 Arduino SD library. Either fs::SDFS or fs::SDMMCFS can be specified for the file system that represents sd or mmc. Parameters sdSpecifies the SD file system when the SD card is wired with SPI interface. In usually, you can use a SD variable that is instantiated and exported globally by the ESP32 Arduino core. mmcSpecifies the SD_MMC file system when the SD card is wired with HS2 interface. In usually, you can use a SD_MMC variable that is instantiated and exported globally by the ESP32 Arduino core. filenameSpecifies the file name when saving the captured image to the SD card. if the filename does not exist, it assumes a file name consisting of a prefix and a timestamp. In that case, the fixed string defined by the ESP32CAM_GLOBAL_IDENTIFIER macro directive in ESP32Cam.h is used as the prefix. Return value ESP_OKFormat has been set. ESP_ERR_NOT_FOUNDSD card is not mounted. ESP_FAILOther error occurred.

    "},{"location":"esp32cam.html#timershot","title":"timerShot","text":"
    esp_err_t timerShot(const unsigned long period, fs::SDFS& sd, const char* filePrefix = nullptr)\n
    esp_err_t timerShot(const unsigned long period, fs::SDMMCFS& mmc, const char* filePrefix = nullptr)\n

    Repeatedly takes a one-shot image at specified an interval of seconds with period parameter and saves it to the SD card or MMC. This function writes to a file compliant with the ESP32 Arduino SD library. Either fs::SDFS or fs::SDMMCFS can be specified for the file system that represents sd or mmc. Parameters periodSpecifies the shooting interval time in second unit. sdSpecifies the SD file system when the SD card is wired with SPI interface. In usually, you can use a SD variable that is instantiated and exported globally by the ESP32 Arduino core. mmcSpecifies the SD_MMC file system when the SD card is wired with HS2 interface. In usually, you can use a SD_MMC variable that is instantiated and exported globally by the ESP32 Arduino core. filePrefixSpecifies the prefix of file name when saving the captured image to the SD card. This function saves files each time whose name consists of the prefix and timestamp suffix specified by the filePrefix parameter. If the filePrefix does not exist, it assumes a fixed string defined by the ESP32CAM_GLOBAL_IDENTIFIER macro directive in ESP32Cam.h for the prefix. Return value ESP_OKFormat has been set. ESP_ERR_NOT_FOUNDSD card is not mounted. ESP_FAILOther error occurred.

    "},{"location":"esp32cam.html#disabletimershot","title":"disableTimerShot","text":"
    void disableTimerShot(void)\n

    Temporarily stops the timerShot. To restart it, call enableTimerShot.

    "},{"location":"esp32cam.html#enabletimershot","title":"enableTimerShot","text":"
    void enableTimerShot(void)\n

    Restarts the timerShot that was temporarily stopped by disableTimerShot.

    "},{"location":"esp32cam.html#deq","title":"deq","text":"
    void deq(void)\n

    Release a semaphore.

    "},{"location":"esp32cam.html#enq","title":"enq","text":"
    portBASE_TYPE enq(TickType_t ms)\n

    Take a semaphore to prevent resource collisions with the image sensor. ESP32Cam uses a semaphore for each of oneShot and timerShot to prevent image sensor resources from colliding while performing each other's tasks. The enq function reserves a semaphore to wait for a subsequent oneShot or timerShot task. Parameters msSpecifies the maximum waiting time in milliseconds for a semaphore to be released. If portMAX_DELAY is specified, it will wait indefinitely for the semaphore to be released. Return value pdTRUESemaphore was reserved. !pdTRUESemaphore was not released within the specified ms time.

    "},{"location":"esp32cam.html#webcamserver-like-as-camerawebserver","title":"WebCamServer like as CameraWebServer","text":"

    The WebCamServer.ino sketch combines AutoConnectAux's custom web pages with native HTML pages. The image viewer is placed on the native HTML page using the img tag, and the slide-in navigation panel is incorporated using CSS. AutoConnect is only directly involved in the image sensor setup page, which is JSON defined in CAMERA_SETUP_PAGE. The setSensor function in the sketch is a handler for a custom web page for CAMERA_SETUP_PAGE, and its role is to communicate the sensor settings to the ESP32 camera driver via ESP32Cam.

    In the WebCamServer.ino sketch, most of the front-end is taken care of by the UI, which is a web page written in HTML. The slide-in menu allows navigation to stream images, capture still images, save a one-shot image to the SD card, and the timer-shot. Image streaming and capture are achieved by giving the URLs of the Stream endpoint and Capture endpoint in the src attribute of the img tag in the HTML using JavaScript DOM interface.

    <body>\n  <li id=\"onair\" onclick=\"stream(!isStreaming())\">Start Streaming</li>\n  <img id=\"img-frame\" />\n</body>\n
    const onAir = document.getElementById('onair');\nconst imgFrame = document.getElementById('img-frame');\n\nfunction isStreaming() {\nstatus.innerText = null;\nreturn onAir.innerText.startsWith(\"Stop\");\n}\n\nfunction stream(onOff) {\nif (onOff && !isStreaming()) {\n    window.stop();\nimgFrame.src = streamUrl;\nonAir.innerText = onAir.innerText.replace(\"Start\", \"Stop\");\ncontent.focus();\n  }\nelse if (!onOff && isStreaming()) {\n    window.stop();\nimgFrame.src = noa;\nonAir.innerText = onAir.innerText.replace(\"Stop\", \"Start\");\n  }\n}\n

    Also, One-shot and timer-shot also use JavaScript Fetch API to send a query string compliant with each function to the Prompt endpoint.

    <li id=\"oneshot\" onclick=\"oneshot()\">One-Shot</li>\n<li><label for=\"period\">Period [s]</label><input type=\"number\" name=\"peirod\" id=\"period\" min=\"1\" value=\"1\" pattern=\"\\d*\"/></li>\n<li><input type=\"button\" value=\"ARM\" onclick=\"arm()\"/></li>\n
    var promptUrl = endpoint(host, promptPath, port);\n\nfunction endpoint(host, path, port) {\nvar url = new URL(path, \"http://\" + host);\nurl.port = port;\nreturn url;\n}\n\nfunction prompt(url) {\nvar res;\nstream(false);\nfetch(url)\n    .then(response => {\nres = \"status:\" + response.status + \" \";\nif (!response.ok) {\nreturn response.text().then(text => {\nthrow new Error(text);\n        });\n      }\nelse {\nstatus.style.color = '#297acc';\nstatus.innerText = res + response.statusText;\n      }\n    })\n    .catch(err => {\nvar desc = err.message;\nif (err.message.indexOf(\"0x0103\", 1) > 0) {\ndesc = \"SD not mounted\";\n      }\nif (err.message.indexOf(\"0x0105\", 1) > 0) {\ndesc = \"SD open failed\";\n      }\nstatus.style.color = '#cc2929';\nstatus.innerText = res + desc;\n    });\n}\n\nfunction oneshot() {\npromptUrl.search = \"?mf=oneshot&fs=mmc\";\nprompt(promptUrl);\n}\n\nfunction arm() {\npromptUrl.search = \"?mf=timershot&fs=mmc&period=\" + document.getElementById('period').value;\nprompt(promptUrl);\n}\n

    The following diagram shows the program structure of the WebCamServer.ino sketch. Its structure is somewhat more complex than the simple sketch presented at the beginning of this chapter because of the native HTML intervening.

    1. ESP32WebCam endpoint interface supports only HTTP GET method, it cannot respond to other HTTP methods such as POST.\u00a0\u21a9

    2. Do not use the REST Client to send requests to the stream endpoints, the REST Client does not fully support multipart/x-mixed-replace mime.\u00a0\u21a9

    3. When using MMC on AI-Thinker ES32-CAM, the LED flash on the module blinks every time the SD is accessed, because the HS2 DATA1 signal is wired to the driver transistor of the LED FLASH. I can't envision why HS2 DATA1 signal was chosen to drive the LED.\u00a0\u21a9

    "},{"location":"faq.html","title":"FAQ","text":""},{"location":"faq.html#after-connected-autoconnect-menu-performs-but-no-happens","title":"After connected, AutoConnect menu performs but no happens.","text":"

    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().

    See also the explanation here.

    "},{"location":"faq.html#after-updating-to-autoconnect-v100-established-aps-disappear-from-open-ssids-with-esp32","title":"After updating to AutoConnect v1.0.0, established APs disappear from Open SSIDs with ESP32.","text":"

    Since AutoConnect v1.0.0 for ESP32, the storage location in the flash of established credentials has moved from EEPROM to Preferences. After You update AutoConnect to v1.0.0, past credentials saved by v0.9.12 earlier will not be accessible from the AutoConnect menu - Open SSIDs. You need to transfer once the stored credentials from the EEPROM area to the Preferences area.

    You can migrate the past saved credentials using CreditMigrate.ino which the examples folder contains.

    Needs to Arduino core for ESP32 1.0.2 or earlier

    EEPROM area with arduino-esp32 core 1.0.3 has moved from partition to the nvs. CreditMigrate.ino requires arduino-esp32 core 1.0.2 or earlier to migrate saved credentials.

    "},{"location":"faq.html#an-esp8266ap-as-softap-was-connected-but-captive-portal-does-not-start","title":"An esp8266ap as SoftAP was connected but Captive portal does not start.","text":"

    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.

    "},{"location":"faq.html#autoconnect-web-pages-are-broken","title":"AutoConnect Web Pages are broken.","text":"

    When the captive portal opens, AutoConnect's embedded web page may be broken or display an incomplete menu like the one below. This is due to AutoConnect temporarily abandoning HTML generation because the ESP module's heap memory was exhausted. This phenomenon may frequently occur, especially with ESP8266 Arduino core 3.1.0 or later.

    ESP8266 Arduino core 3.1.0 or later has increased heap consumption due to the application of Non-OS SDK 3.0.x. This makes the ESP8266 more prone to running out of memory than previous core versions.

    To reduce RAM consumption, apply workarounds such as reducing the number of AutoConnectElements placed on the custom web pages, or enabling AutoConnectOTA only when a WiFi connection is established to an access point. For example, the code snippet for enabling OTA when a WiFi connection is established is as follows:

    AutoConnect portal;\nAutoConnectConfig config;\n\nvoid wifiConnect(IPAddress& ip) {\n  Serial.println(\"WiFi connected:\" + WiFi.SSID());\n  Serial.println(\"IP:\" + WiFi.localIP().toString());\n  config.ota = AC_OTA_BUILTIN;\n  portal.config(config);\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  portal.onConnect(wifiConnect);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"faq.html#cannot-automatically-reconnect-to-a-wifi-hotspot","title":"Cannot automatically reconnect to a WiFi Hotspot","text":"

    WiFi Hotspot ability using a cell phone has no official designation name, but it is commonly referred to as a mobile hotspot or a Personal Hotspot. Generally, this feature using data communication with your cellular to ensure the connection to the Internet. AutoConnect allows you to connect to a WiFi hotspot that has been temporarily launched as an access point and then stores a credential for establishing a connection in the same way as a regular fixed access point.

    However, there's a case where it may not be able to reconnect automatically to a known WiFi hotspot. For security reasons, some device operating systems randomly change the MAC address of the WiFi hotspot at each boot for a hotspot. (Especially iOS14) AutoConnect uses the BSSID to find the known SSID from among WiFi signals being broadcast. (it's the MAC address) This method works if the BSSID that the hotspot originates is fixed, but AutoConnect will not be able to find known SSIDs when it changes. Consider activating the AUTOCONNECT_APKEY_SSID definition if you want to reconnect automatically to a known WiFi hotspot.

    Cannot immobilize the MAC address of Personal Hotspot

    We may not be able to immobilize the MAC address of Personal Hotspot on iOS14. This specification change seems to be related to the private network connection enhancement of iOS14 devices. I found this change during the testing phase, but it is not the confirmed information. (iOS14 offers an option to immobilize the MAC address as a client device, but there is still no option to immobilize it where the device became a hotspot)

    "},{"location":"faq.html#captive-portal-does-not-pop-up","title":"Captive portal does not pop up.","text":"

    If the ESP module is already transparent to the Internet, the device's captive portal screen does not pop up even if AutoConnectConfig::retainPortal is enabled. The captive portal popup may also be misinterpreted as automatically activated when AutoConnect is disconnected from the Internet.

    When your device connects to an access point, it determines if it is also transparent to the Internet according to the HTTP response from a specific URL. AutoConnect traps the HTTP request issued by the device and responds with a portal screen for AutoConnect. Then the device automatically pops up the HTML in response. It means the auto-popup when opening a captive portal is a feature your device OS has. In this mechanism, AutoConnect impersonates an internally launched DNS server response to trap HTTP requests for Internet transparency determination.

    However, its DNS response disguise is very rough, redirecting all FQDNs that do not end in .local to the SoftAP IP address of the ESP module. The redirect location is /_ac, and the responder for /_ac is AutoConnect. This kind of hack is also available as an example in the Arduino ESP8266/ESP32 DNS server library.

    The reason AutoConnect shuts down the DNS server after establishing a connection with a WiFi access point and stops hacking HTTP requests for Internet transparency detection is because AutoConnect can only trap a broad range of DNS requests. After the ESP module connects to the access point, the sketch can access the Internet using the FQDN. To prevent it from interfering with that access, AutoConnect will stop the internally launched DNS. In other words, the only scene that allows automatic pop-ups to lead to the captive portal is when the ESP module is not transparent to the Internet.

    Instead, AutoConnect has options to restart the internal DNS server when the ESP module loses WiFi connectivity, allowing the device to auto-pop up a captive portal screen. If the sketch enables AutoConnectConfig::retainPotral and AutoConnectConfig::autoRise, then when the WiFi connection is lost (i.e. WiFi.status() != WL_CONNECTED), AutoConnect will initiate a trap by starting the SoftAP and the internal DNS server. At this time, the ESP module will transition to WIFI_AP_STA mode. The AutoConnect::handleClient function performs this restart sequence each time it is called, so the sketch can resume the captive portal automatic pop-up while the loop function is running.

    "},{"location":"faq.html#compile-error-due-to-file-system-header-file-not-found","title":"Compile error due to File system header file not found","text":"

    In PlatformIO, it may occur compilation error such as the bellows:

    In file included from C:\\Users\\<user>\\Documents\\Arduino\\libraries\\AutoConnect\\src\\AutoConnect.h:30:0,\nfrom src/main.cpp:28:\nC:\\Users\\<user>\\Documents\\Arduino\\libraries\\PageBuilder\\src\\PageBuilder.h:88:27:\nfatal error: SPIFFS.h: No such file or directory\n
    In file included from C:\\Users\\<user>\\Documents\\Arduino\\libraries\\AutoConnect\\src\\AutoConnect.h:30,\nfrom src\\main.cpp:28:\nC:\\Users\\<user>\\Documents\\Arduino\\libraries\\PageBuilder\\src\\PageBuilder.h:93:17:\nfatal error: LittleFS.h: No such file or directory\n

    This compilation error is due to PlatformIO's Library Dependency Finder not being able to detect #include with default mode chain. Chain mode does not recursively evaluate .cpp files. However, AutoConnect determines the default file system at compile time, depending on the platform. In order for LDF to detect it correctly, it is necessary to recursively scan #include of the header file, which depends on the file system used.

    To avoid compilation errors in PlatformIO, specify lib_ldf_mode in platformio.ini as follows:

    [env]\nlib_ldf_mode = deep+\n

    You should specify deep+ with lib_ldf_mode.

    Another option is to explicitly specify the file system to be applied to AutoConnect at build time. The compiler determines the file system to be applied to AutoConnect by preprocessor macro definitions defined in AutoConnectDefs.h. The directives defined as AC_USE_SPIFFS and AC_USE_LITTLEFS specify that the respective file systems apply. The chapter Using Filesystem details how to explicitly specify a file system for AutoConnect in PlatformIO.

    "},{"location":"faq.html#compile-error-occurs-due-to-the-text-section-exceeds","title":"Compile error occurs due to the text section exceeds","text":"

    When building the sketch, you may receive a compilation error message similar that the text section exceeds the available space on the board. This error occurs with ESP32 arduino core 2.0.0 or later. Since ESP32 arduino core 2.0.0, the object size of the library tends to be oversized, and the AutoConnect object size is also bloated. And also for some example sketches such as mqttRSSI, the BIN size after linkage does not fit in the default partition scheme.

    I'm aware of this issue1 and trying to reduce the size of the AutoConnect object, but for now, changing the partition table at build is the most effective workaround. See How much memory does AutoConnect consume? for information on how to change the partition table.

    "},{"location":"faq.html#compile-error-that-eeprom-was-not-declared-in-this-scope","title":"Compile error that 'EEPROM' was not declared in this scope","text":"

    If the user sketch includes the header file as EEPROM.h, this compilation error may occur depending on the order of the #include directives. AutoConnectCredentials.h including in succession linked from AutoConnect.h defines NO_GLOBAL_EEPROM internally, so if your sketch includes EEPROM.h after AutoConnect.h, the EEPROM global variable will be lost.

    If you use EEPROM with your sketch, declare #include <EEPROM.h> in front of #include <AutoConnect.h>.

    "},{"location":"faq.html#compile-error-that-esphttpupdate-was-not-declared-in-this-scope","title":"Compile error that 'ESPhttpUpdate' was not declared in this scope","text":"

    If the user sketch includes the header file as ESP8266httpUpdate.h, this compilation error may occur depending on the order of the #include directives. AutoConnectUpdate.h including in succession linked from AutoConnect.h defines NO_GLOBAL_HTTPUPDATE internally, so if your sketch includes ESP8266httpUpdate.h after AutoConnect.h, the ESPhttpUpdate global variable will be lost.

    You can avoid a compile error in one of two ways:

    1. Disable an AutoConnectUpdate feature if you don't need.

      You can disable the AutoConnectUpdate feature by commenting out the AUTOCONNECT_USE_UPDATE macro in the AutoConnectDefs.h header file. 

      #define AUTOCONNECT_USE_UPDATE\n

    2. Change the order of #include directives.

      With the Sketch, #include <ESP8266httpUpdate.h> before #include <AutoConnect.h>.

    "},{"location":"faq.html#connection-lost-immediately-after-establishment-with-ap","title":"Connection lost immediately after establishment with AP","text":"

    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.

    "},{"location":"faq.html#data-saved-to-eeprom-is-different-from-my-sketch-wrote","title":"Data saved to EEPROM is different from my sketch wrote.","text":"

    By default, AutoConnect saves the credentials of the established connection into EEPROM. The credential area of EEPROM used by AutoConnect will conflict with data owned by the user sketch if without measures taken. It will destroy the user sketch data and the data stored in EEPROM by AutoConnect with each other. You have the following two options to avoid this conflict:

    • Move the credential saving area of EEPROM. You can protect your data from corruption by notifying AutoConnect where to save credentials. Notification of the save location for the credentials uses AutoConnectConfig::boundaryOffset option. Refer to the chapter on Move the saving area of EEPROM for the credentials for details.

    • Suppresses the automatic save operation of credentials by AutoConnect. You can completely stop saving the credentials by AutoConnect. However, if you select this option, you lose the past credentials which were able to connect to the AP. Therefore, the effect of the automatic reconnection feature will be lost. If you want to stop the automatic saving of the credentials, uses AutoConnectConfig::autoSave option specifying AC_SAVECREDENTIAL_NEVER. Refer to the chapter on Advanced usage for details.

    "},{"location":"faq.html#does-not-appear-esp8266ap-in-smartphone","title":"Does not appear esp8266ap in smartphone.","text":"

    Maybe it is successfully connected at the 1st-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>\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  WiFi.mode(WIFI_STA);\n  delay(100);\n  WiFi.begin();\nif (WiFi.waitForConnectResult() == WL_CONNECTED) {\n    WiFi.disconnect();\nwhile (WiFi.status() == WL_CONNECTED)\n      delay(100);\n  }\n  Serial.println(\"WiFi disconnected.\");\n}\n\nvoid loop() {\n  delay(1000);\n}\n
    You can interactively check the WiFi state of ESP8266.

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

    "},{"location":"faq.html#does-not-response-from-_ac","title":"Does not response from /_ac.","text":"

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

    "},{"location":"faq.html#hang-up-after-reset","title":"Hang up after Reset?","text":"

    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 2

    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)\nets Jan  8 2013,rst cause:4, boot mode:(1,6) or (1,7)\nwdt reset\n

    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 on2: external reset4: 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)."},{"location":"faq.html#how-can-i-detect-the-captive-portal-starting","title":"How can I detect the captive portal starting?","text":"

    You can use the AutoConnect::onDetect exit routine. For more details and an implementation example of the onDetect exit routine, refer to the chapter Captive portal start detection.

    "},{"location":"faq.html#how-change-http-port","title":"How change HTTP port?","text":"

    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\n
    "},{"location":"faq.html#how-change-ssid-or-password-in-captive-portal","title":"How change SSID or Password in Captive portal?","text":"

    You can change both by using AutoConnectConfig::apid and AutoConnectConfig::psk. Refer to section Change SSID and Password for SoftAP in Settings and controls for network and WiFi.

    "},{"location":"faq.html#how-do-i-detach-the-ardunojson","title":"How do I detach the ArdunoJson?","text":"

    If you don't use ArduinoJson at all, you can detach it from the library. By detaching ArduinoJson, the binary size after compilation can be reduced. You can implement custom Web pages with your sketches without using ArduinoJson. Its method is described in Custom Web pages w/o JSON. To completely remove ArduinoJson at compile-time from the binary, you need to define a special #define directive for it. And if you define the directive, you will not be able to use the OTA update with the update server feature as well as AutoConnectAux described by JSON.

    To exclude ArduinoJson at compile-time, give the following #define directive as a compiler option such as the arduino-cli or PlatformIO.

    #define AUTOCONNECT_NOUSE_JSON\n

    For example, add the following description to the [env] section of the platformio.ini file with the build-flags.

    build-flags = -DAUTOCONNECT_NOUSE_JSON\n
    "},{"location":"faq.html#how-erase-the-credentials-saved-in-eeprom","title":"How erase the credentials saved in EEPROM?","text":"

    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. Refer to Saved credential access for details.

    Hint

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

    "},{"location":"faq.html#how-locate-the-link-button-to-the-autoconnect-menu","title":"How locate the link button to the AutoConnect menu?","text":"

    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>\n
    "},{"location":"faq.html#how-much-memory-does-autoconnect-consume","title":"How much memory does AutoConnect consume?","text":""},{"location":"faq.html#sketch-size","title":"Sketch size","text":"

    1. For ESP8266 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)

    2. For ESP32 The BIN size of the sketch grows to over 1M bytes. In the case of a sketch with many custom Web pages, when applying the partition table for the default scheme, the remaining flash size that can be utilized by the user application may be less than 200K bytes. Therefore, it is advisable to resize the partition to make more available space for the application. The ESP32 arduino core has various partition schemes, and you can choose it according to your Sketch feature. You can change the partition scheme from the Tools > Partition Scheme menu of Arduino IDE.

    Change the partition scheme with PlatformIO

    Use board_build.partitions directive with platformio.ini. 

    [env:esp32dev]\nboard_build.partitions = min_spiffs.csv\n
    Details for the PlatformIO documentation.

    "},{"location":"faq.html#heap-size","title":"Heap size","text":"

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

    Reducing Binary Size

    For sketches that do not require OTA feature or Custom Web pages, the build size can be reduced. See Reducing Binary Size in Basic Usage for details.

    "},{"location":"faq.html#how-placing-a-style-qualified-autoconnecttext-horizontally","title":"How placing a style-qualified AutoConnectText horizontally?","text":"

    When the style parameter is specified for AutoConnectText, it is always enclosed by the <div> tag, so the element placement direction is vertical and subsequent elements cannot be horizontal. If you want to place an element after AutoConnectText with the style, you can place the AutoConnectText horizontally by specifying the display CSS property with inline or inline-block in the style value. 

    {\n\"name\": \"text1\",\n\"type\": \"ACText\",\n\"value\": \"Hello,\",\n\"style\": \"display:inline;color:#f5ad42;font-weight:bold;margin-right:3px\"\n},\n{\n\"name\": \"text2\",\n\"type\": \"ACText\",\n\"value\": \"world\",\n\"posterior\": \"br\"\n}\n

    See also AutoConnectText chapter, CSS Flow Layout by MDN.

    "},{"location":"faq.html#how-placing-html-elements-undefined-in-autoconnectelements","title":"How placing HTML elements undefined in AutoConnectElements?","text":"

    AutoConnectElement can be applied in many cases when trying to place HTML elements that are undefined in AutoConnectElemets on custom Web pages. See Handling the custom Web Pages section.

    "},{"location":"faq.html#i-cannot-complete-to-wifi-login-from-smartphone","title":"I cannot complete to WiFi login from smartphone.","text":"

    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.

    "},{"location":"faq.html#i-cannot-see-the-custom-web-page","title":"I cannot see the custom Web page.","text":"

    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.

    "},{"location":"faq.html#nvs_open-failed-not_found-occurs","title":"nvs_open failed: NOT_FOUND occurs.","text":"

    In ESP32, NVS open failure may occur during execution of AutoConnect::begin with the following message on the Serial monitor.

    [E][Preferences.cpp:38] begin(): nvs_open failed: NOT_FOUND\n

    This is not a malfunction and expected behavior. AutoConnect will continue to execute normally.

    AutoConnect saves the credentials of the access point to which it was able to connect to the NVS of the ESP32 module as Preferences instances. The above error occurs when the area keyed for AutoConnect credentials does not exist in NVS. Usually, this error occurs immediately after erasing the ESP32 module flash or when running the AutoConnect sketch for the first time. If the AutoConnect credentials area does not exist in NVS, AutoConnect will automatically allocate it. Therefore, this error can be ignored and will not affect the execution of the sketch.

    "},{"location":"faq.html#request-handler-not-found-in-webserver","title":"Request handler not found in WebServer.","text":"

    It forms the following message as the most common form.

    request handler not found\n

    In ESP32, the above message has a detailed issuer.

    [WebServer.cpp:649] _handleRequest(): request handler not found\n

    If this message appears just by opening your custom web page or AutoConnect built-in page from a browser, it is probably the browser requesting a favicon for that html page. Please instead of prematurely assuming that the detection of this message indicates an implementation flaw, identify the URL from which the request originated. You can find it in the AutoConnect trace that outputs to the serial monitor by enabling AC_DEBUG macro.

    You can probably find the above message in the AC_DEBUG trace log. And if you can find the following trace just before that message, your sketch is working fine.

    [AC] Host:192.168.1.17,/favicon.ico,ignored\n

    It's just the browser asking for a favicon. Of course, your sketch doesn't have a favicon. That's what the \"request handler not found\" message means.

    The AC_DEBUG trace will record URL requests for which no request handler exists. If you find a [AC] Host: IP_ADDRESS, URL, ignored style message in the AC_DEBUG log, the request handler for that URL has not been registered with the WebServer. Even if your sketch has a custom web page with the said URL, it is probably causing a JSON syntax error and failing to deserialize. In such cases, the ArduinoJson Assistant can be helpful. It will find syntax errors in the JSON description for your custom web page.

    "},{"location":"faq.html#saved-credentials-are-wrong-or-lost","title":"Saved credentials are wrong or lost.","text":"

    A structure of AutoConnect saved credentials has changed two times throughout enhancement with v1.0.3 and v1.1.0. In particular, due to enhancements in v1.1.0, AutoConnectCredential data structure has lost the backward compatibility with previous versions. You must erase the flash of the ESP module using the esptool completely to save the credentials correctly with v1.1.0. 

    esptool -c esp8266 (or esp32) -p [COM_PORT] erase_flash\n

    "},{"location":"faq.html#some-autoconnect-page-is-cut-off","title":"Some AutoConnect page is cut off.","text":"

    It may be two possibilities as follows:

    1. Packet loss during transmission due to a too weak WiFi signal.
    2. Heap is insufficient memory. AutoConnect entrusts HTML generation to PageBuilder that makes heavy use the String::concatenate function and causes memory fragmentation. This is a structural problem with PageBuilder, but it is difficult to solve immediately.

    If this issue produces with your sketch, Reloading the page may recover. Also, you can check the memory running out status by rebuilding the Sketch with PageBuilder's debug log option turned on.

    If the heap memory is insufficient, the following message is displayed on the serial console.

    [PB] Failed building, free heap:<Size of free heap>\n
    "},{"location":"faq.html#submit-element-in-a-custom-web-page-does-not-react","title":"Submit element in a custom Web page does not react.","text":"

    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.

    "},{"location":"faq.html#unable-to-change-any-macro-definitions-by-the-sketch","title":"Unable to change any macro definitions by the Sketch.","text":"

    The various macro definitions that determine the configuration of AutoConnect cannot be redefined by hard-coding with Sketch. The compilation unit has a different AutoConnect library itself than the Sketch, and the configuration definitions in AutoConnectDefs.h are quoted in the compilation for AutoConnect only. For example, the following Sketch does not enable AC_DEBUG and does not change HTTP port also the menu background color:

    #define AC_DEBUG                                    // No effect\n#define AUTOCONNECT_HTTPPORT    8080                // No effect\n#define AUTOCONNECT_MENUCOLOR_BACKGROUND  \"#696969\" // No effect\n#include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect Portal;\n\nvoid setup() {\n  Portal.begin();\n}\n\nvoid loop() {\n  Portal.handleClient();\n}\n

    To enable them, edit AutoConnectDefs.h as the library source code directly, or supply them as the external parameters using a build system like PlatformIO with platformio.ini:

    platform = espressif8266\nboard = nodemcuv2\nboard_build.f_cpu = 160000000L\nboard_build.f_flash = 80000000L\nboard_build.flash_mode = dio\nboard_build.filesystem = littlefs\nbuild_flags =\n-DAC_DEBUG\n-DAUTOCONNECT_HTTPPORT=8080\n-DAUTOCONNECT_MENUCOLOR_BACKGROUND='\"#696969\"'\n
    "},{"location":"faq.html#unauthorize-error-without-prompting-the-login-dialog","title":"Unauthorize error without prompting the login dialog.","text":"

    The custom web pages that require authentication will occur unauthorized error always without prompting the login dialog under the captive portal state on some OS. This is a captive portal restriction and expected behavior. The captive portal web browser is almost a complete web browser, but while the captive portal session restricts the response to WWW-authenticate requests. (In intrinsically, the captive portal is a mechanism for authentication in itself)

    Once you exit from the captive portal session and connect SoftAP IP directly afresh, you can access custom web pages along with prompting a login dialog.

    "},{"location":"faq.html#uploaded-bin-via-ota-but-the-sketch-stopped-after-reboot","title":"Uploaded BIN via OTA, but the sketch stopped after reboot.","text":"

    Perhaps the current sketch as the uploader does not match the partition size of the BIN file to be uploaded. For example, if the current sketch (i.e. it performs OTA) is built with a partition table of Default.csv and the new BIN file to be updated is min_spiffs.csv.

    Also, the file system of the uploader sketch and the uploaded sketch must be the same. If the file system of the uploader sketch is SPIFFS while the uploaded BIN file is LITTLEFS, file system initialization will fail.

    "},{"location":"faq.html#still-not-stable-with-my-sketch","title":"Still, not stable with my sketch.","text":"

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

    "},{"location":"faq.html#1-change-wifi-channel","title":"1. Change WiFi channel","text":"

    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;\nAutoConnectConfig config;\n\nconfig.channel = 3;     // Specifies a channel number that matches the AP\nportal.config(config);  // Apply channel configuration\nportal.begin();         // Start the portal\n

    Channel selection guide

    Espressif Systems has released a channel selection guide.

    "},{"location":"faq.html#2-change-the-arduino-core-version","title":"2. Change the arduino core version","text":"

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

    "},{"location":"faq.html#with-esp8266-arduino-core","title":"with ESP8266 arduino core","text":"

    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.

    "},{"location":"faq.html#with-esp32-arduino-core","title":"with ESP32 arduino core","text":"

    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.

    "},{"location":"faq.html#3-turn-on-the-debug-log-options","title":"3. Turn on the debug log options","text":"

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

    AutoConnectDefs.h

    #define AC_DEBUG\n

    PageBuilder.h 3

    #define PB_DEBUG\n

    How to enable the AC_DEBUG, PB_DEBUG

    See Debug Print section, and one similarly too.

    "},{"location":"faq.html#4-reports-the-issue-to-autoconnect-github-repository","title":"4. Reports the issue to AutoConnect Github repository","text":"

    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:4

    • Hardware module
    • Arduino core version Including the upstream commit ID if necessary
    • Operating System which you use
    • Your smartphone OS and version (Especially for Android)
    • Your AP information (IP, channel) if related
    • lwIP variant
    • Problem description
    • If you have a STACK DUMP decoded result with formatted by the code block tag
    • the Sketch code with formatted by the code block tag (Reduce to the reproducible minimum code for the problem)
    • Debug messages output (Including arduino core)

    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.

    1. In this case, the underlying factor is mainly the bloat of ESP-IDF. This issue is also being discussed by many contributors of the Arduino core development community and efforts are underway to make a solution. Refs: espressif/arduino-esp32/issue#5630 \u21a9

    2. This issue has been resolved in ESP8266 core 2.5.0 and later.\u00a0\u21a9

    3. PageBuilder.h exists in the libraries/PageBuilder/src directory under your sketch folder.\u00a0\u21a9

    4. Without this information, the reproducibility of the problem is reduced, making diagnosis and analysis difficult.\u00a0\u21a9

    "},{"location":"filesystem.html","title":"Using Filesystem","text":""},{"location":"filesystem.html#selecting-appropriate-filesystem","title":"Selecting appropriate Filesystem","text":"

    There are two file systems for utilizing the onboard flash on the ESP8266 or the ESP32, SPIFFS and LittleFS. The file system to be applied is determined at the time of the sketch built. AutoConnect will determine as a file system to apply either SPIFFS or LittleFS according to the macro definition in AutoConnectDefs.h and has the following two definitions to include the file system.

    #define AC_USE_SPIFFS\n#define AC_USE_LITTLEFS\n

    The AC_USE_SPIFFS and AC_USE_LITTLEFS macros declare which file system to apply. Their definitions are contradictory to each other and you cannot activate both at the same time.

    Each platform supported by AutoConnect has a default file system, which is LittleFS for ESP8266 and SPIFFS for ESP32. Neither AC_USE_SPIFFS nor AC_USE_LITTLE_FS needs to be explicitly defined as long as you use the default file system. The default file system for each platform is assumed.

    SPIFFS has deprecated for ESP8266

    SPIFFS has deprecated on EP8266 core. AC_USE_SPIFFS flag indicates that the migration to LittleFS has not completed for the Sketch with ESP8266. You will get a warning message when you compile a sketch using SPIFFS. Also, LittleFS support on the ESP32 is expected to be in the future beyond Arduino ESP32 core v2. If you want to use the LittleFS library on your ESP32, you must use a third-party source provided externally.

    The file system intended by the sketch must match the file system applied to AutoConnect. (i.e. it is provided by the definitions of AC_USE_SPIFFS and AC_USE_LITTLEFS) For example, if the sketch includes LittleFS.h, but AC_USE_SPIFFS is defined, the sketch will not be able to sucessfully acces the built file system.

    "},{"location":"filesystem.html#filesystem-applied-to-pagebuilder-must-match-to-autoconnect","title":"Filesystem applied to PageBuilder must match to AutoConnect","text":"

    Also, PageBuilder has a definition of file system choices to use, similar to AutoConnect. It is the definition of PB_USE_SPIFFS and PB_USE_LITTLEFS in PageBuilder.h of PageBuilder library source, and its role is the same as these of AutoConnect. 

    #define PB_USE_SPIFFS\n#define PB_USE_LITTLEFS\n

    Note the version of each library

    Support for AC_USE_SPIFFS / AC_USE_LITTLEFS and PB_USE_SPIFFS / PB_USE_LITLTEFS is from AutoConnect 1.3.0 and PageBuilder 1.5.0 and later.

    "},{"location":"filesystem.html#to-determine-the-file-system-to-be-used","title":"To determine the file system to be used","text":"

    The most direct way is to edit the library source AutoConnectDefs.h directly and uncomment the definition of #define AC_USE_SPIFFS or #define AC_USE_LITTLES. In addition to that editing work, the definitions of PB_USE_SPIFFS and PB_USE_LITTLEFS in PageBuilder.h also need to be changed. Their definitions must match the AC_USE_SPIFFS and AC_USE_LITTLEFS definitions in AutoConnectDefs.h. PB_USE_SPIFFS enabled and AC_USE_LITTLEFS enabled state is not allowed, and vice-versa.

    However, this way makes the AutoConnect library inconsistent and may include your unintended file system on a project-by-project basis. By using PlatformIO, you can efficiently select a file system. That way, you can choose any file system for each project without polluting the library source.

    To apply a different file system for each project without modifying the library source code, add the following build_flags directive to platformio.ini as a project configuration file of each project.

    [env:esp_wroom_02]\nplatform = espressif8266\nboard = esp_wroom_02\nframework = arduino\nlib_extra_dirs = ~/Documents/Arduino/libraries\nlib_ldf_mode = deep+\nbuild_flags =\n-DAC_USE_SPIFFS\n-DPB_USE_SPIFFS\nupload_speed = 921600\nmonitor_speed = 115200\n

    The build_flags as build options allows PlatformIO can provide preprocessor macro definitions. -D name for build_flags, which specifies a predefined content, is treated as 1 equal to the #define directive.

    Library dependency search with PlatformIO

    If #include <LITTLEFS.h> becomes Not Found with PlatformIO built, try specifying lib_ldf_mode=deep+ with platformio.ini. Due to the deep nesting by preprocessor instructions, the include file cannot be detected by the chain mode (nested include search) of PlatformIO's Library Dependency Finder. See also FAQ.

    LittleFS for ESP8266 with PlatformIO

    The SPIFFS file system is used by default in order to keep legacy projects compatible. To choose LittleFS as the file system with ESP8266 platform, it should be explicitly specified using board_build.filesystem option in platformio.ini as follows: 

    [env:esp_wroom_02]\nplatform = espressif8266\nframework = arduino\nboard = esp_wroom_02\nboard_build.filesystem = littlefs\n...\n

    "},{"location":"filesystem.html#practical-situations-where-autoconnect-uses-a-file-system","title":"Practical situations where AutoConnect uses a file system","text":"

    AutoConnect has the ability to use the file system that is:

    • Place the custom web page defined in the JSON document in an external file and separate it from the sketch source code. This approach allows you to change the layout design of your custom web page by simply modifying the external file without recompiling the sketch.

    • Use the AutoConnectFile element to upload some parameters that control sketch execution to the file system on the ESP module. You can upload from the browser on the client PC via OTA.

    The following is an example of a scenario that embodies the combination of these facilities. The sketch below controls LED that blinks like heartbeat by PWM (Pulse-Width Modulation) from ESP8266. Custom web page contains an AutoConnectFile element that allows you to upload a parameter file to the ESP module from the browser on the client PC. And place the custom web page as a JSON document on the LittleFS of the ESP module.

    "},{"location":"filesystem.html#screenshot","title":"Screenshot","text":"

    The sketch UI of this scenario provides as shown by the screenshot below:

    It arranges in a very simple style to focus on how the sketch incorporating AutoConnect will handle the file system. This custom web page is loaded from LittleFS at the beginning of the sketch processing and has already been uploaded to LittleFS on the ESP8266.

    "},{"location":"filesystem.html#custom-web-page-json-definition","title":"Custom Web page JSON definition","text":"

    It has a file name as \"custom_pages.json\" and has two pages whose URI are \"/\" and \"/set\". An AutoConnectFile element named \"param\" is placed to upload a file from a client browser that contains the parameters to determine the behavior of this sketch. (ie. LED blinking cycle of the heartbeat)

    After selecting the parameter file to upload, click the AutoConnectSubmit element named \"set\". This will upload the selected file to LittleF on the ESP8266 module and start processing the sketch-coded \"/set\" page handler.

    [\n  {\n\"title\": \"Heartbeat\",\n\"uri\": \"/\",\n\"menu\": true,\n\"element\": [\n      {\n\"name\": \"param\",\n\"type\": \"ACFile\",\n\"label\": \"Parameter file:\",\n\"store\": \"fs\"\n      },\n      {\n\"name\": \"set\",\n\"type\": \"ACSubmit\",\n\"value\": \"SET\",\n\"uri\": \"/set\"\n      }\n    ]\n  },\n  {\n\"title\": \"Heartbeat\",\n\"uri\": \"/set\",\n\"menu\": false,\n\"element\": [\n      {\n\"name\": \"param\",\n\"type\": \"ACText\"\n      }\n    ]\n  }\n]\n
    "},{"location":"filesystem.html#parameter-file","title":"Parameter file","text":"

    You can make the parameters that determine the heartbeat cycle with the JSON definition using your favorite text editor as follows:

    {\n\"led\": 16,\n\"freq\": 1000,\n\"range\": 511,\n\"cycle\": 2\n}\n

    We use PWM to make the LED blinking gently repeat like a heartbeat. In addition, we also need the interval time to blink. We will put these values in the parameter file.

    • led : Blinking LED assignment pin (Depending on your ESP8266 module)
    • freq : PWM frequency [ms] (milliseconds unit)
    • range : PWM range (511 ~ 1023, 511 ~ 767 is recommended for smooth blinking)
    • cycle : Heartbeat cycle [s] (seconds unit. 4 seconds or less recommended)

    Save the text file with these settings as param.json on your PC. You can upload this file to the ESP8266 module using the AutoConnectFile element named param above. When executing a sketch, the settings described in this file will be read by the /set custom web page handler to control the analog output of the ESP8266 module.

    "},{"location":"filesystem.html#the-sketch","title":"The sketch","text":"

    Below is the final sketch that allows the LED to blink like a heartbeat according to the settings contained in the two external files custome_pages.json and param.json mentioned above.

    #include <Arduino.h>\n#include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <LittleFS.h>\n#include <AutoConnect.h>\n#include <ArduinoJson.h>\nAutoConnect portal;\nAutoConnectConfig config;\n\n// File names\nconst char* paramFile = \"param.json\";\nconst char* auxFile = \"custom_pages.json\";\n\n// Parameters for LED PWM control\nunsigned int  led = 0;\nunsigned long freq;\nunsigned long range;\nunsigned int  cycle;\nconst unsigned long reso = 10;\nint duty;\nint increase;\nunsigned long tmCycle;\nunsigned long tmStep;\n\nString onSet(AutoConnectAux& aux, PageArgument& args) {\n  StaticJsonDocument<128> doc;\n\n// Open uploaded parameter and parse parameters with JSON\n  File param = LittleFS.open(paramFile, \"r\");\nif (param) {\n    DeserializationError error = deserializeJson(doc, param);\nif (error) {\n      aux[\"param\"].value = \"JSON de-serialization failed: \" + String(error.c_str());\n    }\nelse {\n// Parsing the parameter JSON was successful.\n// Read the parameters as JSON document from the uploaded parameter file.\n      led = doc[\"led\"];\n      freq = doc[\"freq\"];\n      range = doc[\"range\"];\n      cycle = doc[\"cycle\"];\n\n// Set PWM conditions\n      analogWriteFreq(freq);\n      analogWriteRange(range);\n      increase = ((range / cycle) / reso) / 2;\n      duty = 0;\n      tmCycle = millis();\n      tmStep = tmCycle;\n\n// Echo back uploaded parameters to Custom web page\n      String  result;\n      serializeJson(doc, result);\n      aux[\"param\"].value = result;\n    }\n    param.close();\n  }\nelse\n    aux[\"param\"].value = String(paramFile) + String(\" open error\");\n\nreturn String();\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  LittleFS.begin();\n// Load Custom web pages from LittleFS\n  File aux = LittleFS.open(auxFile, \"r\");\nif (aux) {\n// Attach Custom web page and handler\n    portal.load(aux);\n    portal.on(\"/set\", onSet);\n\n// Exclude the HOME item from the menu as the custom web page will\n// be placed in the root path.\n    config.menuItems = 0x00ff & ~(AC_MENUITEM_HOME | AC_MENUITEM_DEVINFO);\n    config.ota = AC_OTA_BUILTIN;  // You can even update this sketch remotely\n    portal.config(config);\n\n// You can close the file once the custom web page has finished loading.\n    aux.close();\n  }\nelse {\n    Serial.print(auxFile);\n    Serial.println(\" open error\");\n  }\n\n  portal.begin();\n}\n\nvoid loop() {\nif (led) {  // The heartbeat begins after the led parameter will set.\nif (millis() - tmStep > abs(increase)) {\n      duty += increase;\nif (duty < 0)\n        duty = 0;\n      analogWrite(led, duty);\n      tmStep = millis();\n    }\nif (millis() - tmCycle > (cycle * 1000) / 2) {\n      increase *= -1;\n      tmCycle = millis();\n    }\n  }\n  portal.handleClient();\n}\n

    This final sketch consists of four components:

    • Include appropriate header files: Include the appropriate file system header files to operate the external files of the ESP8266 module by the sketch. For LitteleFS, it is #include <LittleFS.h>. Also, since we wrote the parameter setting file in JSON, we will deserialize it using ArduinoJson. The header required for the deserialization process is #include <ArduinoJson.h>.

    • setup: In the sketch setup phase, the procedure is similar to other sketches when using AutoConnect. In this case, the following steps are appended to apply the file system.

      • Start the file system as LittleFS. Then open the custom web page definition file. Upload this file as a LittleFS file on the ESP8266 module in advance.
      • Arduino can handle the opened file as a stream, so register the file stream with AutoConnect using the AutoConnect::load function. This procedure is also detailed in the documentation Loading & saving AutoConnectElements with JSON.

    • loop: In the loop, the duty is calculated and analog output is performed to the LED pin. Duty is a value for PWM. PWM is a modulation method that can adjust strength of electric power by turning the pulse train on and off at regular intervals and change the on-time width. In this sketch, the LED on-time is dynamically changed and supplied as the PWM duty to achieve the slow blinking like the heartbeat. The loop calculates this dynamic on-time change from the heartbeat cycle time (cycle setting of param.json) and executes analogWrite at the appropriate timing. The freq value in the parameter settings indicates the regular interval of the PWM.

      Do not use delay in a loop to create time variation for PWM

      It is a fault often found in careless sketches. An HTTP request is sent to the ESP8266 module each time you interact with the AutoConnect menu from the client browser. The request is properly answered by the AutoConnect::handleClient function. The delay function in the loop obstructs the flow of its processing. Remember that the sketching process will be suspended for the time period you specify by the delay.

    • /set custom web page handler: It is named onSet function in above sketch. The onSet handler retrieves PWM settings using ArduinoJson deserialization from the uploaded param.json file. Each fetched setting value is stored in each global variable. The loop function refers to that value to achieve PWM pulse control.

    "},{"location":"filesystem.html#adapts-the-sketch-to-the-selected-file-system-in-autoconnect","title":"Adapts the sketch to the selected file system in AutoConnect","text":"

    AutoConnect determines the appropriate file system instance according to the AC_USE_SPIFFS or AC_USE_LITTLEFS macro definition. This determination is made by the c++ preprocessor when the sketch is built. It then exports a macro definition that identifies the determined file system. Its macro definition allows the sketch to reference a valid file system after including the AutoConnect.h header file.

    The following two macro definitions, which can be referenced after including the AutoConnect.h header file, help the sketch choose the appropriate file system.

    • AUTOCONNECT_USE_SPIFFS: AutoConnect uses SPIFFS. The sketch should include SPIFFS.h. Also, the file system instance is SPIFFS.
    • AUTOCONNECT_USE_LITTLEFS: AutoConnect uses LITTLEFS. The sketch should include LittleFS.h. Also, the file system instance is LittleFS.

    Combining the c++ preprocessor directives with the two macro definitions above, you can write a common sketch code for both SPIFFS and LittleFS, as shown in the code as follows:

    #include <AutoConnect.h>\n\n#ifdef AUTOCONNECT_USE_LITTLEFS\n#include <LittleFS.h>\n#if defined(ARDUINO_ARCH_ESP8266)\nFS& FlashFS = LittleFS;\n#elif defined(ARDUINO_ARCH_ESP32)\nfs::LittleFSFS& FlashFS = LittleFS;\n#endif\n#else\n#include <FS.h>\n#include <SPIFFS.h>\nfs::SPIFFSFS& FlashFS = SPIFFS;\n#endif\n\nvoid setup() {\n  ...\n  FlashFS.begin();\n  ...\n}\n
    "},{"location":"gettingstarted.html","title":"Getting started","text":""},{"location":"gettingstarted.html#lets-do-the-most-simple-sketch","title":"Let's do the most simple sketch","text":"

    Open the Arduino IDE, write the following sketch and upload it. The feature of this sketch is that the SSID and Password are not coded.

    #include <ESP8266WiFi.h>          // Replace with WiFi.h for ESP32\n#include <ESP8266WebServer.h>     // Replace with WebServer.h for ESP32\n#include <AutoConnect.h>\n\nESP8266WebServer Server;          // Replace with WebServer for ESP32\nAutoConnect      Portal(Server);\n\nvoid rootPage() {\nchar content[] = \"Hello, world\";\n  Server.send(200, \"text/plain\", content);\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  Server.on(\"/\", rootPage);\nif (Portal.begin()) {\n    Serial.println(\"WiFi connected: \" + WiFi.localIP().toString());\n  }\n}\n\nvoid loop() {\n    Portal.handleClient();\n}\n

    The above code can be applied to ESP8266. To apply to ESP32, replace ESP8266WebServer class with WebServer and include WiFi.h and WebServer.h of arduino-esp32 appropriately.

    "},{"location":"gettingstarted.html#run-at-first","title":"Run at first","text":"

    After about 30 seconds, if the ESP8266 cannot connect to nearby Wi-Fi spot, you pull out your smartphone and open Wi-Fi settings from the Settings Apps. You can see the esp8266ap 1 in the list of \"CHOOSE A NETWORK...\". Then tap the esp8266ap and enter password 12345678, a something screen pops up automatically as shown below.

    This is the AutoConnect statistics screen. This screen displays the current status of the established connection, WiFi mode, IP address, free memory size, and etc. Also, the hamburger icon is the control menu of AutoConnect seems at the upper right. By tap the hamburger icon, the control menu appears as the below.

    "},{"location":"gettingstarted.html#join-to-the-new-access-point","title":"Join to the new access point","text":"

    Here, tap \"Configure new AP\" to connect the new access point then the SSID configuration screen would be shown. Enter the SSID and Passphrase and tap apply to start connecting the access point.

    Can be configured with static IP

    Since v1.1.0, Configure new AP menu can configure for WIFI_STA with static IP.

    "},{"location":"gettingstarted.html#connection-establishment","title":"Connection establishment","text":"

    After connection established, the current status screen will appear. It is already connected to WLAN with WiFi mode as WIFI_AP_STA and the IP connection status is displayed there including the SSID. Then at this screen, you have two options for the next step.

    For one, continues execution of the Sketch while keeping this connection. You can access ESP8266 via browser through the established IP address after cancel to \"Log in\" by upper right on the screen. Or, \"RESET\" can be selected. The ESP8266 resets and reboots. After that, immediately before the connection will be restored automatically with WIFI_STA mode.

    "},{"location":"gettingstarted.html#run-for-usually","title":"Run for usually","text":"

    The IP address of ESP8266 would be displayed on the serial monitor after connection restored. Please access its address from the browser. The \"Hello, world\" page will respond. It's the page that was handled by in the Sketch with \"on\" function of ESP8266WebServer.

    1. When applied to ESP32, SSID will appear as esp32ap.\u00a0\u21a9

    "},{"location":"howtoembed.html","title":"How to embed","text":""},{"location":"howtoembed.html#embed-the-autoconnect-to-the-sketch","title":"Embed the AutoConnect to the Sketch","text":"

    Here hold two case examples. Both examples perform the same function. Only how to incorporate the AutoConnect into the Sketch differs. Also included in the sample folder, HandlePortal.ino also shows how to use the PageBuilder library for HTML assemblies.

    "},{"location":"howtoembed.html#what-does-this-example-do","title":"What does this example do?","text":"

    Uses the web interface to light the LED connected to the D0 (sometimes called BUILTIN_LED) port of the NodeMCU module like the following animation.

    Access to the ESP8266 module connected WiFi from the browser then the page contains the current value of the D0 port would be displayed. The page has the buttons to switch the port value. The LED will blink according to the value with clicked by the button. This example is a typical sketch of manipulating ESP8266's GPIO via WLAN.

    Embed AutoConnect library into this sketch. There are few places to be changed. And you can use AutoConnect's captive portal function to establish a connection freely to other WiFi spots.

    "},{"location":"howtoembed.html#embed-autoconnect","title":"Embed AutoConnect","text":""},{"location":"howtoembed.html#pattern-a","title":"Pattern A.","text":"

    Bind to ESP8266WebServer, performs handleClient with handleRequest.

    In what situations should the handleRequest be used.

    It is something needs to be done immediately after the handle client. It is better to call only AutoConnect::handleClient whenever possible.

    "},{"location":"howtoembed.html#pattern-b","title":"Pattern B.","text":"

    Declare only AutoConnect, performs handleClient.

    "},{"location":"howtoembed.html#used-with-mqtt-as-a-client-application","title":"Used with MQTT as a client application","text":"

    The effect of AutoConnect is not only for ESP8266/ESP32 as the web server. It has advantages for something WiFi client as well. For example, AutoConnect is also convenient for publishing MQTT messages from various measurement points. Even if the SSID is different for each measurement point, it is not necessary to modify the Sketch.

    In this example, it is trying to publish a WiFi signal strength being received ESP8266 through the services on the cloud that can visualize the live data streams for IoT. Using the IoT platform provided by ThingSpeak\u2122, the ESP8266 publishes RSSI values to ThingSpeak MQTT broker channel via the MQTT client library.

    This example is a good indication of the usefulness of AutoConnect, as RSSI values can typically measure different intensities for each access point. By simply adding a few lines to the Sketch, you do not have to rewrite and upload the Sketch for each access point.

    "},{"location":"howtoembed.html#advance-procedures","title":"Advance procedures","text":"
    • Arduino Client for MQTT - It's the PubSubClient, install it to Arduino IDE. If you have the latest version already, this step does not need.
    • Create a channel on ThingSpeak.
    • Register the ESP module as an MQTT device to a ThingSpeak channel, allowing it to be published and subscribed to on that channel.
    • Get the Channel API Keys and MQTT device credentials from ThingSpeak, and put its keys to the Sketch.

    The ThingSpeak is the open IoT platform. It is capable of sending data privately to the cloud and analyzing, visualizing its data. If you do not have an account of ThingSpeak, you need that account to proceed further. ThingSpeak has the free plan for the account which uses within the scope of this example.1 You can sign up with the ThingSpeak sign-up page.

    Whether you should do sign-up or not.

    You are entrusted with the final judgment of account creation for ThingSpeak. Create an account at your own risk.

    "},{"location":"howtoembed.html#create-a-channel-on-thingspeak","title":"Create a channel on ThingSpeak","text":"

    Sign in ThingSpeak. Select Channels to show the My Channels, then click New Channel.

    At the New Channel screen, enter each field as a below. And click Save Channel at the bottom of the screen to save.

    • Name: ESP8266 Signal Strength
    • Description: ESP8266 RSSI publish
    • Field1: RSSI

    "},{"location":"howtoembed.html#get-channel-id-and-api-keys","title":"Get Channel ID and API Keys","text":"

    The channel successfully created, you can see the channel status screen as a below. Channel ID is displayed there.2

    Here, switch the channel status tab to API Keys. The API key required to publish the message is the Write API Key.

    The last key you need is the User API Key and can be confirmed it in the user profile. Pull down Account from the top menu, select My profile. Then you can see the ThingSpeak settings and the User API Key is displayed middle of this screen.

    "},{"location":"howtoembed.html#add-a-new-mqtt-device","title":"Add a new MQTT Device","text":"

    Since January 2022, the ThingSpeak channel authentication scheme has changed, and the following procedures are for the new authentication. You will need to obtain the credentials of the MQTT device by registering it with the channel you created in the previous step.

    Once you have defined your ThingSpeak channel, you can define devices: select MQTT from the Devices menu that appears in ThingSpeak's channel information to begin registering devices.

    Give the device a name on the next page that appears after you select the MQTT device. In this example, its device should be the ESP module that the ThingSpeak MQTT channel would identify. You then specify the channel and message type you want to allow for the device. (i.e., the ESP module)

    Upon successful registration of the MQTT device, Client ID, Username, and Password are issued as credentials for the device. You can retrieve the credentials and save them as JSON. After downloading the credential file, open it with a text editor and check the contents.

    "},{"location":"howtoembed.html#sketch-publishes-messages","title":"Sketch publishes messages","text":"

    The mqttRSSI.ino sketch in the AutoConnect repository is the complete code for publishing RSSI to the ThingSpeak channel. The sketch comes with an AutoConnectAux custom Web page to flexibly configure channel information created as a ThingSpeak channel.

    Parameters for the ThingSpeak MQTT channels

    Various settings of the MQTT Setting for the ThingSpeak channels via the above AutoConnectAux are following:

    • Server: mqtt3.thingspeak.com
    • User API Key: Specify the User API Key that can be confirmed with ThingSpeak My Profile page.
    • Channel ID: Specify the channel ID that can be confirmed with ThingSpeak My Channels page.
    • Write API Key: Specify the Write API Key that can be confirmed by following navigate to \"ThingSpeak My Channels > Your Channel Name > API Keys Tab > Write API Key\".
    • Client ID: Specify the client ID from the MQTT Devices page according to the previous step.
    • Username: Specify the user name from the MQTT Devices page according to the previous step.
    • Password: Specify the password from the MQTT Devices page according to the previous step.
    "},{"location":"howtoembed.html#publish-messages","title":"Publish messages","text":"

    After uploading the mqttRSSI.ino and restarting the ESP module, Messages will begin to be issued via the connected WiFi access point. The message will carry the RSSI value of the current WiFi signal strength; changes in signal strength due to RSSI will be displayed on the ThingSpeak Channel Stats page.

    "},{"location":"howtoembed.html#how-embed-to-your-sketches","title":"How embed to your sketches","text":"

    For the client sketches, the code required to connect to WiFi is the following four parts only.

    1. #include directive3

      Include AutoConnect.h header file behind the include of ESP8266WiFi.h.

    2. Declare AutoConnect

      The declaration of the AutoConnect variable is not accompanied by ESP8266WebServer.

    3. Invokes \"begin()\"

      Call AutoConnect::begin. If you need to assign a static IP address, executes AutoConnectConfig before that.

    4. Performs \"handleClent()\" in \"loop()\"

      Invokes AutoConnect::handleClient() at inside loop() to enable the AutoConnect menu.

    1. As of March 21, 2018.\u00a0\u21a9

    2. '454951' in the example above, but your channel ID should be different.\u00a0\u21a9

    3. #include <ESP8266WebServer.h> does not necessary for uses only client.\u00a0\u21a9

    "},{"location":"license.html","title":"License","text":"

    MIT License

    Copyright \u00a9 2018-2023 Hieromon Ikasamo

    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Acknowledgments

    Each of the following libraries used by AutoConnect is under its license:

    • The Luxbar is licensed under the MIT License. https://github.com/balzss/luxbar
    • ArduinoJson is licensed under the MIT License. https://arduinojson.org/
    "},{"location":"lsbegin.html","title":"Inside AutoConnect::begin","text":""},{"location":"lsbegin.html#autoconnectbegin-logic-sequence","title":"AutoConnect::begin logic sequence","text":"

    The following parameters of AutoConnectConfig affect the behavior and control a logic sequence of AutoConnect::begin function. These parameters are evaluated on a case-by-case basis and may not be valid in all situations. The Sketch must consider the role of these parameters and the conditions under which they will work as intended. You need to understand what happens when using these parameters in combination.

    • autoReconnect : Attempts re-connect with past SSID by saved credential.
    • autoRise : Controls starting the captive portal.
    • immediateStart : Starts the captive portal immediately, without the 1st-WiFi.begin.
    • portalTimeout : Time out limit for the portal.
    • retainPortal : Keep DNS server functioning for the captive portal.

    The following chart shows the AutoConnect::begin logic sequence that contains the control flow with each parameter takes effect.

    For example, AutoConnect::begin will not end without the portalTimeout while the connection not establishes, but WebServer will start to work. Also, the DNS server will start to make a series of the captive portal operation on the client device. The custom web pages now respond correctly by the two internally launched servers, and the Sketch looks like working. But AutoConnect::begin does not end yet. Especially when invoking AutoConnect::begin in the setup(), control flow does not pass to the loop().

    However, portalTimeout can be used effectively in various scenes in combination with immediateStart. Its combination is useful for implementing Sketches that can work in situations where WiFi is not always available. Namely, Sketch will support a running mode with both offline and online. If AutoConnect staying in the captive portal exceeds the time limit, Sketch can switch a process-mode to offline according to WiFi signal detection. Conversely, it can start a captive portal immediately with intentional control to shift the process-mode to online from offline. Especially, You can activate the process-mode shift manually by trigger via external switches.

    The retainPortal option allows continuing the captive portal operation even after exiting from AutoConnect::begin. This option allows the use of the automatic portal pop-ups on the smartphone devices etc. even after the ESP module has established a connection with some access point in STA mode. (Excepts blocking a series of portal processes via intentionally accessing a URL outside the scope of /_ac. eg., if you try to communicate with the mqtt server without connecting to the access point, its access will be redirected to /_ac caused by the trap of the captive portal detection)

    The AutoConnect::begin 3rd parameter

    Another parameter as the 3rd parameter of AutoConnect::begin related to timeout constrains the connection wait time after WiFi.begin. It is the CONNECTED judgment of the above chart that it has an effect.

    "},{"location":"menu.html","title":"AutoConnect menu","text":"

    Luxbar

    The AutoConnect menu is developed using the LuxBar which is licensed under the MIT License. See the License.

    "},{"location":"menu.html#where-the-from","title":"Where the from","text":"

    The following screen will appear as the AutoConnect menu when you access to AutoConnect root URL via http://{localIP}/_ac. (eg. http://172.217.28.1/_ac) It is a top page of AutoConnect which shows the current WiFi connection statistics. To invoke the AutoConnect menu, you can tap at right on top.

    AutoConnect root URL

    It is assigned \"/_ac\" located on the local IP address of ESP8266/ESP32 module by default and can be changed with the Sketch. A local IP means Local IP at connection established or SoftAP's IP.

    "},{"location":"menu.html#right-on-top","title":"Right on top","text":"

    Currently, AutoConnect supports six 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 the flash.
    • Disconnect: Disconnects current connection.
    • Reset...: Rest the ESP8266/ESP32 module.
    • Update: OTA updates. (Optional)
    • HOME: Return to user home page.

    "},{"location":"menu.html#configure-new-ap","title":"Configure new AP","text":"

    It scans all available access points in the vicinity and display it further the WiFi signal strength and security indicator as of the detected AP. Below that, the number of discovered hidden APs will be displayed. Enter SSID and Passphrase and tap \"Apply\" to start a WiFi connection.

    If you want to configure with static IP, uncheck \"Enable DHCP\". Once the WiFi connection is established, the entered static IP1 configuration will be stored to the credentials in the flash and restored to the station configuration via the Open SSIDs menu.

    "},{"location":"menu.html#open-ssids","title":"Open SSIDs","text":"

    After WiFi connected, AutoConnect will automatically save the established SSID and password to the flash on the ESP module. Open SSIDs menu reads the saved SSID credentials and lists them as below. Listed items are clickable buttons and can initiate a connection to its access point.

    Also, this menu allows you to interactively delete the stored credentials. icon will appear next to each SSID in the Open SSIDs menu when the credential removal feature is enabled with AutoConnectConfig::menuItems. Clicking the on this screen will delete the SSID. This feature is disabled by default.

    Saved credentials data structure has changed

    A structure of AutoConnect saved credentials has changed in v1.1.0 and was lost backward compatibility. Credentials saved by AutoConnect v1.0.3 (or earlier) will not display properly with AutoConnect v1.1.0. You need to erase the flash of the ESP module using the esptool before the Sketch uploading. 

    esptool -c esp8266 (or esp32) -p [COM_PORT] erase_flash\n

    "},{"location":"menu.html#disconnect","title":"Disconnect","text":"

    It disconnects ESP8266/ESP32 from the current connection. Also, ESP8266/ESP32 can be automatically reset after WiFi cutting by instructing with the Sketch using the AutoConnect API.

    After tapping the Disconnect, you will not be able to reach the AutoConnect menu. Once disconnected, you will need to set the SSID again for connecting to the WLAN.

    "},{"location":"menu.html#reset","title":"Reset...","text":"

    Resetting the ESP8266/ESP32 module will initiate a reboot. When the module restarting, the esp8266ap or esp32ap access point will disappear from the WLAN and the ESP8266/ESP32 module will begin to reconnect a previous access point with WIFI_STA mode.

    Not every ESP8266 module will be rebooted normally

    The Reset menu is using the ESP.reset() function for ESP8266. This is an almost hardware reset. In order to resume the Sketch normally, the state of GPIO0 is important. Since this depends on the circuit implementation for each module, not every module will be rebooted normally. See also FAQ.

    "},{"location":"menu.html#custom-menu-items","title":"Custom menu items","text":"

    If the Sketch has custom Web pages, the AutoConnect menu lines them up with the AutoConnect's items. Details for Custom Web pages in AutoConnect menu.

    "},{"location":"menu.html#update","title":"Update","text":"

    If you specify AutoConnectConfig::ota to import the OTA update feature into Sketch, an item will appear in the menu list as Update.

    The Update menu item will appear only AutoConnectOTA enabled

    The Update item is displayed automatically in the menu only when AutoConnectConfig::ota is specified with AC_OTA_BUILTIN or AutoConnectUpdate is attached.

    "},{"location":"menu.html#home","title":"HOME","text":"

    A HOME item at the bottom of the menu list is a link to the home path, and the default URI is / which is defined by AUTOCONNECT_HOMEURI in AutoConnectDefs.h header file.

    #define AUTOCONNECT_HOMEURI     \"/\"\n

    Also, you can change the HOME path using the AutoConnect API. The AutoConnect::home function sets the URI as a link of the HOME item in the AutoConnect menu.

    "},{"location":"menu.html#applying-the-active-menu-items","title":"Applying the active menu items","text":"

    Each of the above menu items can be configured with a Sketch. AutoConnectConfig::menuItems specifies the menu items that will be enabled at runtime. You can also adjust available menu items using AutoConnect::enableMenu and AutoConnect::disableMenu function. It is an alternative to AutoConnectConfig::menuItems and provides a shortcut to avoid using AutoConnectConfig. For example, by disabling the Configure new AP and Disconnect item, you can prevent the configuration for unknown access points.

    AutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  config.menuItems = AC_MENUITEM_OPENSSIDS | AC_MENUITEM_RESET | AC_MENUITEM_HOME;\n  portal.config(config);\n}\n

    Following code snippet is another way to achieve the same effect.

    AutoConnect portal;\n\nvoid setup() {\n  portal.disableMenu(AC_MENUITEM_CONFIGNEW | AC_MENUITEM_DISCONNECT);\n  portal.config(config);\n}\n

    Here is the result of running the above sketch:

    AutoConnectConfig::menuItems section has more details.

    AutoConnect shows and hides menu items when AutoConnect::begin is executed and when AutoConnect::handleClient is executed in a loop function. You can dynamically change the available menu items during the loop() by setting the show/hide items before executing those functions with AutoConnect::enableMenu and AutoConnect::disableMenu.

    The current menu item settings held by AutoConnectConfig can be retrieved with the AutoConnect::getConfig function, and the code snippet to reconfigure menu items based on the getConfig return value is as follows:

    "},{"location":"menu.html#enable-ota-menu-on-demand-using-an-external-switch-connected-to-a-gpio","title":"Enable OTA menu on demand using an external switch connected to a GPIO.","text":"
    const int externalSwitch = 5;  // Assign the OTA activation switch to D1 (GPIO5).\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n// The logic level of the external switch assumes active LOW.\n// Note: A said switch is an alternate and must retain its state.\n  pinMode(externalSwitch, INPUT_PULLUP);\n\n// Set up OTA, but hide the Update item from the menu list until an external\n// switch is pressed.\n  config.ota = AC_OTA_BUILTIN;\n  portal.config(config);\n  portal.disableMenu(AC_MENUITEM_UPDATE);\n  portal.begin(); \n}\n\nvoid loop() {\n// Use AutoConnect::getConfig to obtain the current AutoConnectConfig values\n// and indicate the display state of an Update item.\nbool  menuUpdate = portal.getConfig().menuItems & AC_MENUITEM_UPDATE;\n\n// Hides the Update item from the menu list depending on the state of the switch.\nif (digitalRead(externalSwitch) == LOW && !(menuUpdate)) {\n    portal.enableMenu(AC_MENUITEM_UPDATE);\n  }\nelse {\n    portal.disableMenu(AC_MENUITEM_UPDATE);\n  }\n\n  portal.handleClient();\n}\n

    enableMenu/disableMenu has no effect for custom web page items

    AutoConnect::enableMenu and disableMenu functions are not enabled to show/hide menu items for custom web pages. They only work on AutoConnect's built-in pages2. Use the AutoConnectAux::menu and AutoConnectAux::isMenu functions to show/hide menu items for custom web pages. For more information, see Custom Web pages in AutoConnect menu section.

    "},{"location":"menu.html#attaching-to-autoconnect-menu","title":"Attaching to AutoConnect menu","text":"

    The AutoConnect menu can contain your sketch's web pages as extra items as a custom. It works for HTML pages implemented by the ESP8266WebServer::on handler or the WebServer::on handler for ESP32. That is, you can make them invoke the legacy web pages from the AutoConnect menu. The below screen-shot is the result of adding an example sketch for the ESP8266WebServer library known as FSBrowser to the AutoConnect menu item. It can add Edit and List items with little modification to the legacy sketch code.

    AutoConnect allows capturing the extra pages handled with ESP8266WebServer or WebServer's legacy into the AutoConnect menu. See Section Advanced Usage for detailed instructions on how to add the extra pages into its menu.

    1. AutoConnect does not check the syntax and validity of the entered IP address. If the entered static IPs are incorrect, it cannot connect to the access point.\u00a0\u21a9

    2. AutoConnect built-in pages are predefined by the AC_MENUITEM_t enum value.\u00a0\u21a9

    "},{"location":"menuize.html","title":"Attach the menus","text":""},{"location":"menuize.html#the-feature-of-menu-attaching-using-autoconnect","title":"The feature of menu attaching using AutoConnect","text":"

    In this section, it presents numerous ways to customize the AutoConnect menu with your Sketch. AutoConnect dynamically materializes menu items at the Sketch run time with joined AutoConnectAux as a sourced configuration. Typically, it has AutoConnectElements for page rendering in its composition but can configure a Web page as a menu item without having AutoConnectElements. In other words, the AutoConnect Menu component allows you to easily embed a navigation menu with WiFi connection expansion in your Sketch, which has legacy pages for ESP8266WebServer or WebServer of ESP32.

    "},{"location":"menuize.html#the-basic-mechanism-for-menu-generation","title":"The basic mechanism for menu generation","text":"

    Sketch can equip the AutoConnect menu by using three patterns according to the appropriate usage of the AutoConnect API.

    Basic menu It is the most basic menu for a WiFi connection only. Sketch can automatically display it using the typical calling sequence of the AutoConnect API with AutoConnect::begin and AutoConnect::handleClient. Extra menu with custom Web pages which is consisted by AutoConnectElements It is an extended menu that appears when the Sketch consists of the custom Web pages with AutoConnectAux and AutoConnectElements. Refer to section Custom Web pages section. Extra menu which contains legacy pages It provides an item for including a legacy page in the AutoConnect menu that natively uses the page request handler attached by the ESP8266WebServer::on function. (Similarly, WebServer::on for ESP32)

    The mechanism by which AutoConnect dynamically generates the menu is simple. The member variables title and uri of AutoConnectAux will be transferred into <li> HTML tag as they are. Then all <li> elements are included in the form that makes up the menu. Therefore, the Sketch can register the legacy web pages to the menu by simply declaring the title and URI with AutoConnectAux and binding it to AutoConnect.

    "},{"location":"menuize.html#place-the-item-for-the-legacy-sketches-on-the-menu","title":"Place the item for the legacy sketches on the menu","text":"

    To implement this with your sketch, use only the AutoConnectAux constructed with the title and URI of that page. AutoConnectElements is not required.

    The AutoConnect library package contains an example sketch for ESP8266WebServer known as FSBrowser. Its example is a sample implementation that supports AutoConnect without changing the structure of the original FSBrowser and has the menu item for Edit and List.

    "},{"location":"menuize.html#slightly-changes-to-adapt-fsbrowser-to-autoconnect-menu","title":"Slightly changes to adapt FSBrowser to AutoConnect menu","text":"

    The changes I made to adapt the FSBrowser to the AutoConnect menu are slight as follows:

    1. Add AutoConnect declaration.
    2. Add AutoConnectConfig declaration to replace the menu title to FSBRowser.
    3. Set the menu title using AutoConnectConfig::title.
    4. Replace the destination of the not found handler (404 handler) from ESP8266WebServer to AutoConnect. 1IMPORTANT
    5. Add AutoConnectAux using AutoConnect::append and combine an item for Edit.
    6. Add AutoConnectAux using AutoConnect::append and combine an item for List.
    7. Establish a WiFi connection using AutoConnect::begin and execute AutoConnect::handleClient in the loop, as in the case of handling the basic menu.
    "},{"location":"menuize.html#fsbrowser-with-embedded-autoconnect","title":"FSBrowser with embedded AutoConnect","text":"

    Modification for FSBrowser as follows: (Excerpt of the sketch code)

    ... and embeds a hyperlink with an icon in the bottom of the body section of index.htm contained in the data folder to jump to the AutoConnect menu.

    <p style=\"padding-top:15px;text-align:center\">\n  <a href=\"/_ac\"><img src=\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAC2klEQVRIS61VvWsUQRSfmU2pon9BUIkQUaKFaCBKgooSb2d3NSSFKbQR/KrEIiIKBiGF2CgRxEpjQNHs7mwOUcghwUQ7g58IsbGxEBWsb2f8zR177s3t3S2cA8ftzPu993vzvoaSnMu2vRKlaqgKp74Q/tE8qjQPyHGcrUrRjwlWShmDbFMURd/a6TcQwNiYUmpFCPElUebcuQ2vz6aNATMVReHEPwzfSSntDcNwNo2rI+DcvQzhpAbA40VKyV0p1Q9snzBG1qYVcYufXV1sREraDcxpyHdXgkfpRBj6Uwm2RsC5dxxmZ9pdOY9cKTISRcHTCmGiUCh4fYyplTwG2mAUbtMTBMHXOgK9QfyXEZr+TkgQ1oUwDA40hEgfIAfj+HuQRaBzAs9eKyUZ5Htx+T3ZODKG8DzOJMANhmGomJVMXPll+hx9UUAlzZrJJ4QNCDG3VEfguu7mcpmcB/gkBOtShhQhchAlu5jlLUgc9ENgyP5gf9+y6LTv+58p5zySkgwzLNOIGc8sEoT1Lc53NMlbCQQuvMxeCME1NNPVVkmH/i3IzzXDtCSA0qQQwZWOCJDY50jsQRjJmkslEOxvTcDRO6zPxOh5xZglKkYLhWM9jMVnkIsTyMT6NBj7IbOCEjm6HxNVVTo2WXqEWJZ1T8rytB6GxizyDkPhWVpBqfiXUtbo/HywYJSpA9kMamNNPZ71R9Hcm+TMHHZNGw3EuraXEUldbfvw25UdOjqOt+JhMwJd7+jSTpZaEiIcaCDwPK83jtWnTkwnunFMtxeL/ge9r4XItt1RNNaj/0GAcV2bR3U5sG3nEh6M61US+Qrfd9Bs31GGulI2GOS/8dgcQZV1w+ApjIxB7TDwF9GcNzJzoA+rD0/8HvPnXQJCt2qFCwbBTfRI7UyXumWVt+HJ9NO4XI++bdsb0YyrqXmlh+AWOLHaLqS5CLQR5EggR3YlcVS9gKeH2hnX8r8Kmi1CAsl36QAAAABJRU5ErkJggg==\" border=\"0\" title=\"AutoConnect menu\" alt=\"AutoConnect menu\"/></a>\n</p>\n

    1. Missing this step, AutoConnect cannot handle the menu. Refs: 404 handler \u21a9

    "},{"location":"otabrowser.html","title":"OTA via Web Browser","text":""},{"location":"otabrowser.html#updates-with-the-web-browserupdated-wv115","title":"Updates with the Web Browser\u00a0UPDATED w/v1.1.5","text":"

    AutoConnect features a built-in OTA function to update ESP module firmware. You can easily make the Sketch that equips OTA and able to operate with the AutoConnect menu. As the AutoConnectOTA class, which is compliant with OTA updates using a web browser as described in the ESP8266 Arduino Core documentation.

    You will be able to import the AutoConnectOTA class into your sketch just by specifying AutoConnectConfig::ota. By incorporating the AutoConnectOTA class into your Sketch, you can have an OTA updating feature which able to updating binary sketch from the AutoConnect menu.

    The AutoConnectOTA feature is implemented based on the Updater class of the ESP8266 arduino core library. Its Updater class is also supported by the ESP32 Arduino core, so you can commonly import AutoConnectOTA into the Sketch without being aware of the differences between ESP8266 and ESP32 modules.

    Limitation of AutoConnectOTA with authentication

    AutoConnectOTA does not support authentication in v1.1.5 yet. It is planned for inclusion in AutoConnect v1.2.0, which will support HTTP authentication.

    "},{"location":"otabrowser.html#how-to-embed-autoconnectota-in-your-sketch","title":"How to embed AutoConnectOTA in your sketch","text":"

    To embed the AutoConnectOTA class into your sketch, basically follow these steps:

    1. Include ESP8266WiFi.h, ESP8266WebServer.h and AutoConnect.h as usual.1
    2. Declare an ESP8266WebServer object. It's optional. (as WebServer for ESP32)
    3. Declare an AutoConnect object, with an argument as ESP8266WebServer if separate the declarations.
    4. Declare an AutoConnectConfig object.
    5. Declare an AutoConnectAux object for your sketch own if needed.
    6. Perform the following procedure steps in the setup() function:
      1. Set AutoConnectConfig::ota to AC_OTA_BUILTIN and configure AutoConnect.
      2. Load the AutoConnectAux pages declared in step #4 for your application.
      3. Join these pages to AutoConnect.
      4. Invokes AutoConnect::begin function.
    7. Invokes AutoConnect::handleClient function in the loop().
    #include <ESP8266WiFi.h>            // Step #1\n#include <ESP8266WebServer.h>       // Step #1\n#include <AutoConnect.h>            // Step #1\n\nESP8266WebServer  server;           // Step #2\nAutoConnect       portal(server);   // Step #3\nAutoConnectConfig config;           // Step #4\nAutoConnectAux    hello;            // Step #5\n\nstatic const char HELLO_PAGE[] PROGMEM = R\"(\n{ \"title\": \"Hello world\", \"uri\": \"/\", \"menu\": true, \"element\": [\n    { \"name\": \"caption\", \"type\": \"ACText\", \"value\": \"<h2>Hello, world</h2>\",  \"style\": \"text-align:center;color:#2f4f4f;padding:10px;\" },\n    { \"name\": \"content\", \"type\": \"ACText\", \"value\": \"In this page, place the custom web page handled by the Sketch application.\" } ]\n}\n)\";                                 // Step #5\n\nvoid setup() {\n  config.ota = AC_OTA_BUILTIN;      // Step #6.a\n  portal.config(config);            // Step #6.a\n  hello.load(HELLO_PAGE);           // Step #6.b\n  portal.join({ hello });           // Step #6.c\n  portal.begin();                   // Step #6.d\n}\n\nvoid loop() {\n  portal.handleClient();            // Step #7\n}\n

    How LED ticking during updates

    AutoConnectOTA applies LED ticking during updates automatically. The destination LED port and ticker drive depends on AutoConnectConfig::tickerPort and AutoConnectConfig::tickerOn specifying.

    IMPORTANT The AutoConnectOTA activates the ticker constantly regardless of the AutoConnectConfig::ticker value. If you want to stop the ticker output to GPIO during updates, give 0xff to AutoConnectConfig::tickerPort.

    "},{"location":"otabrowser.html#autoconnectota-allocation-uri","title":"AutoConnectOTA allocation URI","text":"

    AutoConnectOTA has implemented using AutoConnectAUX. So it occupies two URIs by default. An update operation page is assigned to AUTOCONNECT_URI_UPDATE and the binary file uploader for the update is assigned to AUTOCONNECT_URI_UPDATE_ACT. These symbols are defined in the AutoConnectDefs.h header file as follows:

    #define AUTOCONNECT_URI             \"/_ac\"\n#define AUTOCONNECT_URI_UPDATE      AUTOCONNECT_URI \"/update\"\n#define AUTOCONNECT_URI_UPDATE_ACT  AUTOCONNECT_URI \"/update_act\"\n

    Therefore, the normal Sketch that imports AutoConnectOTA while keeping the default, you cannot use the two URIs /_ac/update and /_ac/update_act for your specific. If you want to use the URIs for any purpose other than AutoConnectOTA, you need to override the AutoConnectDefs.h definition at compile time. It can be overwritten by giving the build flags for platformio.ini as follows with the PlatformIO environment for example.

    build_flags = -DAUTOCONNECT_URI_UPDATE='\"/YOURURI\"'\n-DAUTOCONNECT_URI_UPDATE_ACT='\"/YOURURIACT\"'\n
    "},{"location":"otabrowser.html#timing-of-autoconnectota-instantiation","title":"Timing of AutoConnectOTA instantiation","text":"

    It will be born during AutoConnect::handleClient process. AutoConnect will evaluate the enabled state of AutoConnectConfig::ota each time the handleClient is executed, and if OTA is enabled then it creates an AutoConnectAux internally and assigns it to the update page. At this time, AutoConnectOTA is also instantiated together. The generated AUX page containing AutoConnectOTA is bound to AutoConnect inside the AutoConnect::handleClient process.

    If you want to attach AutoConnectOTA dynamically with an external trigger, you can sketch like this: This sketch imports the OTA update feature with an external switch assigned to the GPIO pin. While the trigger not occurs, AutoConnectOTA will not be imported into Sketch and will not appear on the menu list.

    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\n#define TRIGGER 4   // pin assigned to external trigger switch\n\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  pinMode(TRIGGER, INPUT);\n  portal.begin();\n}\n\nvoid loop() {\nif (digitalRead(TRIGGER) == HIGH) {\n    config.ota = AC_OTA_BUILTIN;\n    portal.config(config);\n  }\n  portal.handleClient();\n}\n

    AutoConnectOTA cannot detach dynamically

    Once imported, AutoConnectOTA cannot be removed from the Sketch. It can be only excluded from the menu by overriding AutoConnectConfig::menuItems. In this case, the AutoConnectOTA instance remains as a residue.

    "},{"location":"otabrowser.html#authentication-with-autoconnectota","title":"Authentication with AutoConnectOTA","text":"

    HTTP authentication of AutoConnect is also effective for OTA. Since the implementation of AutoConnectOTA is based on AutoConnectAux, the AutoConnectConfig::auth setting is valid for AutoConnectOTA as well. Also, it allows you to make authentication only on the OTA page while various custom Web pages coexist.

    The AC_AUTH_BASIC or AC_AUTH_DIGEST setting to the AutoConnectConfig::auth enables HTTP authentication. If it is in combination with AC_AUTHSCOPE_PARTIAL specified AutoConnectConfig::authScope setting, only an OTA page will be authenticated, excluding other custom Web pages that co-exist.

    AutoConnect portal;\nAutoConnectConfig config;\nAutoConnectAux aux(\"/aux\", \"AUX\");\n\nvoid setup() {\n// Join some custom web page\n  portal.join(aux);\n\n// Add OTA into the Sketch\n  config.ota = AC_OTA_BUILTIN;\n// Enable authentication on OTA page only\n  config.auth = AC_AUTH_DIGEST;\n  config.authScope = AC_AUTHSCOPE_PARTIAL;\n// Configure other settings\n  ...\n\n// Apply configuration settings\n  portal.config(config);\n  portal.begin();\n}\n
    "},{"location":"otabrowser.html#how-to-make-the-binary-sketch","title":"How to make the binary sketch","text":"

    Binary sketch files for updating can be retrieved using the Arduino IDE. Open the Sketch menu and select the Export compiled Binary, then starts compilation.

    When the compilation is complete, a binary sketch will save with the extension .bin in the same folder as the Sketch.

    "},{"location":"otabrowser.html#select-a-partition-scheme-to-enable-ota-wesp32","title":"Select a partition scheme to enable OTA w/ESP32","text":"

    To enable OTA on the ESP32, you need to build a sketch with a partition scheme that has reserved a binary sketch space for OTA. The ESP32 Arduino core comes with a variety of pre-configured partition schemes that can be selected from the Tools menu in the Arduino IDE.

    In most cases, this is simply a matter of selecting a built-in partition scheme with a reserved OTA area from the Tools menu in the Arduino IDE. However, Of the various ESP32-based modules, only a few have many partition schemes pre-configured. If you cannot find a partition scheme with reserved OTA space for your ESP32 module, you will need to modify boards.txt as the board configuration file included in the ESP32Arduino core distribution. The WebCamServer.ino example in the AutoConnect library shows the changes to boards.txt for esp32cam. But this modification is not recommended as it can inadvertently destroy the board configuration and will be overwritten and restored by the Arduino core version upstreams.

    Another way to choose a partition scheme is to use PlatformIO for your build system. You can easily select the reserved partition scheme for the OTA area using PlatformIO. When using PlatformIO, you can select a partition scheme with OTA reserved space by simply writing the following line in the platformio.ini file.

    board_build.partitions = min_spiffs.csv\n
    "},{"location":"otabrowser.html#ota-updates-wbrowser-without-using-autoconnectota","title":"OTA updates w/browser without using AutoConnectOTA","text":"

    The legacy OTA method based on ESP8266HTTPUpdateServer without AutoConnectOTA is still valid. To embed the ESP8266HTTPUpdateServer class with AutoConnect into your sketch, basically follow these steps:

    1. Include ESP8266HTTPUpdateServer.h, also WiFiClient.h, in addition to the usual directives as ESP8266WebServer.h and AutoConnect.h.2
    2. Declare an ESP8266WebServer object. (In ESP32, as WebServer)
    3. Declare an ESP8266HTTPUpdateServer object.
    4. Declare an AutoConnect object with an ESP8266WebServer object as an argument.
    5. Declare an AutoConnectAux object for the update operation page.
    6. Assign /update to the URI of the update dialog page.
    7. Assign any title as the AutoConnect menu for the update dialog page.
    8. Declare additional AutoConnectAux pages for your application intention if needed.
    9. Perform the following procedure steps in the setup() function:
      1. Invokes ESP8288HTTPUpdateServer::setup function, specifies the USERNAME and the PASSWORD as needed.
      2. Load the AutoConnectAux pages declared in step #8 for your application. (Except the update dialog page)
      3. Join these pages to AutoConnect along with the update dialog page declared in step #5.
      4. Invokes AutoConnect::begin function.
    10. Invokes AutoConnect::handleClient function in the loop(). 
    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <ESP8266HTTPUpdateServer.h>    // Step #1\n#include <WiFiClient.h>                 // Step #1\n#include <AutoConnect.h>\n\nstatic const char HELLO_PAGE[] PROGMEM = R\"(\n{ \"title\": \"Hello world\", \"uri\": \"/\", \"menu\": true, \"element\": [\n    { \"name\": \"caption\", \"type\": \"ACText\", \"value\": \"<h2>Hello, world</h2>\",  \"style\": \"text-align:center;color:#2f4f4f;padding:10px;\" },\n    { \"name\": \"content\", \"type\": \"ACText\", \"value\": \"In this page, place the custom web page handled by the Sketch application.\" } ]\n}\n)\";\n\nESP8266WebServer httpServer;                // Step #2\nESP8266HTTPUpdateServer httpUpdate;         // Step #3\nAutoConnect portal(httpServer);             // Step #4\nAutoConnectAux update(\"/update\", \"UPDATE\"); // Step #5, #6, #7\nAutoConnectAux hello;                       // Step #8\n\nvoid setup() {\n  httpUpdate.setup(&httpServer, \"USERNAME\", \"PASSWORD\"); // Step #9.a\n  hello.load(HELLO_PAGE);                   // Step #9.b\n  portal.join({ hello, update });           // Step #9.c\n  portal.begin();                           // Step #9.d\n}\n\nvoid loop() {\n  portal.handleClient();                    // Step #10\n}\n
    "},{"location":"otabrowser.html#regular-file-uploading-using-autoconnectotaenhanced-wv120","title":"Regular file uploading using AutoConnectOTA\u00a0ENHANCED w/v1.2.0","text":"

    The built-in OTA update feature can update the firmware as well as upload regular files placed in the file system on the ESP module. It allows a regular file is uploaded via OTA using the Update of AutoConnect menu without adding a particular custom Web page that contains AutoConnectFile. This utilization is useful for the operation of transferring the JSON document of the custom web page definition, the external parameter file of your sketch, and so on into the target ESP module via OTA.

    The built-in OTA update feature determines where to save the uploaded file according to the filename pattern. By default, a filename with ends a .bin extension is subject to firmware updates. A file that has another extensions will be saved as a regular to LittleFS (or SPIFFS) in the flash.

    The filename extension that should be treated as the firmware is defined as the AUTOCONNECT_UPLOAD_ASFIRMWARE macro in AutoConnectDefs.h header file of the library source code. When dealing with another extensions for the updating file as firmware change this macro definition.

    #define AUTOCONNECT_UPLOAD_ASFIRMWARE \".bin\"\n

    Specify with the PlatformIO

    AUTOCONNECT_UPLOAD_ASFIRMWARE pattern will be embedded into the binary sketch is determined at compile time. The PlatformIO build system allows you to change the pattern of the file extension for each project without modifying the library source code.

    build_flags=-DAUTOCONNECT_UPLOAD_ASFIRMWARE='\".bin\"'\n

    Use a regular expression to specify the file extension

    By default, you can specify only one file extension to be treated as firmware in OTA updates. However, you can specify the file extension as a regular expression, but it consumes a lot of memory.

    If the file extension pattern contains a regular expression, you need to enable the flag of AUTOCONNECT_UPLOAD_ASFIRMWARE_USE_REGEXP in AutoConnectDefs.h. Also, the AUTOCONNECT_UPLOAD_ASFIRMWARE definition as a regular expression is treated as a replacement string for the #define directive for C++ preprocessor, so the backslash must be escaped.

    "},{"location":"otabrowser.html#display-an-extra-string-on-the-update-screenenhanced-wv130","title":"Display an extra string on the update screen\u00a0ENHANCED w/v1.3.0","text":"

    You can add an extra string to the OTA update screen by the sketch. If an extra string is specified, it will be displayed on the right side of \"Updating firmware\" caption.

    The screenshot above shows an example of adding the current version of the sketch to the OTA caption.

    To display in the add an extra caption to the OTA update screen, sets the AutoConnectConfig::otaExtraCaption by your sketch. A type of the extra caption type to set in AutoConnectConfig::otaExtraCaption is the const char pointer. So, its string must remain in the memory area for the duration of OTA. (This string is not copied to the AutoConnectOTA class and expiration must be guaranteed by your sketch)

    #define FIRMWARE_VERSION  \"1.1.12-dev\"\n...\n#include <AutoConnect.h>\n...\nconst char* fw_ver = FIRMWARE_VERSION;\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid setup() {\n  config.ota = AC_OTA_BUILTIN;\n  config.otaExtraCaption = fw_ver;\n  portal.config(config);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    Common mistakes about variable expiration

    Local variables are valid only within the function. The following code seems to work at first glance. But practically, *fw_ver is released at the end of the function. AutoConnectConfig::otaExtraCaption holds only a pointer to the extra caption string.

    #define FIRMWARE_VERSION  \"1.1.12-dev\"\n...\n#include <AutoConnect.h>\n...\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid setupConfig() {\nconst char* fw_ver = FIRMWARE_VERSION;\n  config.ota = AC_OTA_BUILTIN;\n  config.otaExtraCaption = fw_ver;  // This code doesn't work as intended.\n  portal.config(config);\n}\n\nvoid setup() {\n  setupConfig();\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n
    "},{"location":"otabrowser.html#receive-the-autoconnectota-status-changeenhanced-wv130","title":"Receive the AutoConnectOTA status change\u00a0ENHANCED w/v1.3.0","text":"

    You can capture the change in the state of the OTA by registering the exit routine to AutoConnect. The exit routine for notifying the state change of AutoConnectOTA can execute the user's sketch function during specific stages of OTA or on an error. Also, these exit routines have the same interface as the similar exit functions included in the Arduino core.

    The following functions register the function in your sketch with AutoConnect to notify OTA state changes.

    • AutoConnect::onOTAStart : Register the on-start exit routine that is called only once when the OTA has been started.
    • AutoConnect::onOTAProgress : Register the exit routine that is called during the OTA progress.
    • AutoConnect::onOTAEnd : Register the on-end exit routine that is called only once when the OTA is finished.
    • AutoConnect::onOTAError : Register the exit routine that is called when some error occurred.
    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nAutoConnect portal;\nAutoConnectConfig config;\n\nvoid OTAStart() {\n  Serial.println(\"Start OTA updating\");\n}\n\nvoid OTAEnd() {\n  Serial.println(\"\\nEnd\");\n}\nvoid OTAProgress(unsigned int amount, unsigned int size) {\n  Serial.printf(\"Progress: %u(%u)\\r\", amount, size);\n}\n\nvoid OTAError(uint8_t error) {\n  Serial.printf(\"Error[%u]: \", error);\n}\n\nvoid setup() {\n  delay(1000);\n  Serial.begin(115200);\n  Serial.println();\n\n  config.ota = AC_OTA_BUILTIN;\n  portal.config(config);\n  portal.onOTAStart(OTAStart);\n  portal.onOTAEnd(OTAEnd);\n  portal.onOTAProgress(OTAProgress);\n  portal.onOTAError(OTAError);\n  portal.begin();\n}\n\nvoid loop() {\n  portal.handleClient();\n}\n

    1. For ESP32, change the following items:

      • Change the include directives appropriately for the ESP32 environment.
      • Change ESP8266WebServer to WebServer.

      \u21a9

    2. The AutoConnect library provides an implementation of the HTTPUpdateServer class that ported from ESP8266HTTPUpdateServer class for ESP32 intention. It is contained the WebUpdate under the examples folder.\u00a0\u21a9

    "},{"location":"otaserver.html","title":"OTA using Update Server","text":""},{"location":"otaserver.html#updates-with-the-update-server","title":"Updates with the update server","text":"

    Since the v1.0.0 release, AutoConnect provides new feature for updating sketch firmware of ESP8266 or ESP32 modules via OTA using the AutoConnectUpdate class that is an implementation of the Sketch binary update by the HTTP server mentioned in the OTA update of the ESP8266 Arduino Core documentation, which inherits from the ESP8266HTTPUpdate class (as HTTPUpdate class in the case of ESP32). It acts as a client agent for a series of update operations.

    This method allows you to remotely update the ESP module's firmware beyond the network segments from the update server, as long as you can ensure proper routing and forwarding.

    If you choose this update method, you need to prepare the server process as a variant of the HTTP server that supplies the binary sketch files to the updating client agent. Its server requires to be able to handle the HTTP headers extended by ESP8266HTTPUpdate class as described in the ESP8266 Arduino Core documentation. There are various implementations of the update server that provide binary sketch files. For example, the ESP8266 Arduino Core documentation suggests an advanced updater php script that can be fully communicated with the client agent using the ESP8266HTTPUpdate class. That is, the update server for AutoConnect must work with the client agent, and its implementation should make the handshake well with the AutoConnectUpdate class which wraps an ESP8266HTTPUpdate class. The AutoConnect library provides an update server script implemented in Python that can combine with the AutoConnectUpdate class.

    "},{"location":"otaserver.html#how-to-embed-autoconnectupdate-to-your-sketch","title":"How to embed AutoConnectUpdate to your sketch","text":"

    To embed the AutoConnectUpdate class into your sketch, basically follow these steps:

    1. Declare an ESP8266WebServer object. (In ESP32, as WebServer)
    2. Declare an AutoConnect object with an ESP8266WebServer object.
    3. Declare an AutoConnectUpdate object with the update server address and the HTTP port as parameters.
    4. Invokes AutoConnect::begin function.
    5. Attach the AutoConnectUpdate object to AutoConnect using AutoConnectUpdate::attach function.
    6. Invokes AutoConnect::handleClient function in the loop().
    #include <ESP8266WiFi.h>\n#include <ESP8266WebServer.h>\n#include <AutoConnect.h>\n\nESP8266WebServer server;                          // Step #1\nAutoConnect portal;                               // Step #2\nAutoConnectUpdate update(\"192.168.0.100\", 8000);  // Step #3\n\nvoid setup() {\nif (portal.begin()) {     // Step #4\n    update.attach(portal);  // Step #5\n  }\n}\n\nvoid loop() {\n  portal.handleClient();    // Step #6\n}\n

    "},{"location":"otaserver.html#behavior-of-the-autoconnectupdate-class","title":"Behavior of the AutoConnectUpdate class","text":"

    A sketch incorporating the AutoConnectUpdate class has an extended menu item as UPDATE in the AutoConnect menu. UPDATE as menu item will be attached by the AutoConnectUpdate automatically.

    When an UPDATE item started, its first action is requesting a catalog list of updatable binary sketch files to the update server. Then the update server sends back the catalog list of stored binary sketch files to a client which is the ESP module. The AutoConnectUpdate class will display responded list to a custom Web page1 on the browser.

    The substance of Available firmware list is a custom Web page by AutoConnectAux, and you can select the target binary sketch file with the radio button (AutoConnectRadio). A progress bar will appear to notify the updating status once the update has begun. When the update finished, the ESP module will reset automatically to launch a new firmware.

    The AutoConnectUpdate class performs the above series of operations in conjunction with the update server. All you need to do is attach the AutoConnectUpdate class to AutoConnect and execute the AutoConnect::handleClient function in the loop().

    "},{"location":"otaserver.html#update-server-for-the-autoconnectupdate-class","title":"Update server for the AutoConnectUpdate class","text":"

    The above series of operations using AutoConnectUpdate class requires an update server that can work with it. AutoConnect provides an update server script implemented in Python. This server script conforms to a sketch that uses the AutoConnectUpdate class as an update client agent.2

    In the OTA platform, you can place the update server operated by the script in a location that is reachable from the ESP module on the network.

    updateserver.py [-h] [--port PORT] [--bind IP_ADDRESS] [--catalog CATALOG] [--log LOG_LEVEL]\n
    --help | -hShow help message and exit. --port | -pSpecifies PORT number (Default: 8000) --bind | -bSpecifies the IP address to which the update server binds. Usually, it is the host address of the update server. When multiple NICs configured, specify one of the IP addresses. (Default: HOST IP or 127.0.0.0) --catalog | -dSpecifies the directory path on the update server that contains the binary sketch files. (Default: The current directory) --log | -lSpecifies the level of logging output. It accepts the Logging Levels specified in the Python logging module.

    updateserver.py usage

    1. Python First, prepare a Python environment. It is also possible with a tiny single-board computer like the raspberry pi. Popular distributions such as Ubuntu for Linux include Python. You can easily set up a Python 2 or 3 environment. If you are using a Mac, you already have the Python 2 environment. macOS is equipped with Python 2.7 by default. In the case of Windows OS, it is necessary to install the Python environment intentionally. Please refer to the Python official page to install Python in your environment.

    2. Deploy the binary sketch files Use the Arduino IDE to output a binary file of sketches and deploy it3 under the update server. The path which specifies for the --catalog option of updateServer.py is the path of the binary sketch files you deployed.

    3. Start updateserver.py For example, to start the update server on the host with IP address 172.16.1.10 using 8080 port4, execute the following command: 

      python updateserver.py --port 8080 --bind 172.16.1.10 --catalog bin --log debug\n
      In this example assumes that the binary sketch files are deployed under the path bin from the current directory.

    Limitations of the updateserver.py

    The updateserver.py script equips only the minimum facility because it assumes a private small OTA platform without identifying individual modules and version restrictions etc. To operate a larger OTA platform, it is necessary to identify the individual ESP module and to consider version control and security.

    "},{"location":"otaserver.html#http-contents-and-the-sequence-for-the-autoconnectupdate-class","title":"HTTP contents and the sequence for the AutoConnectUpdate class","text":"

    You can also equip an update server that works with the AutoConnectUpdate class. It can be improved more widely applicable by adding extensions such as version control and authentication to the updateserver.py script. It is necessary to understand the specifications related to HTTP data streams and sequences to enhance the update server that the AutoConnectUpdate class assumes.

    This section describes the contents of the HTTP data stream required by the communication with AutoConnectUpdate class. To work correctly with the AutoConnectUpdate class, the update server must meet two requirements:

    • The update server notifies the catalog list of updatable binary files which stored in the update server to the client agent. 5
    • Send an updating binary file and MD5 hash to a client in response to URI request (HTTP GET). 6

    Above requirements will be implemented on along the HTTP protocol. The AutoConnectUpdate class requests an update server to notify the client for a catalog list of binary sketch files using an HTTP URL query string. The specifications of the HTTP query and the contents of the catalog list to be returned are as follows:

    "},{"location":"otaserver.html#1-http-url-query-for-the-catalog-list-of-the-updatable","title":"1. HTTP URL query for the catalog list of the updatable","text":"
    [address]/_catalog?op=list&path=[path]\n
    addressURL of the update server /_catalogRequest path, it is fixed. opOperation command for the update server. Currently, only 'list' occurs. pathPath containing the updatable binary files on the update server."},{"location":"otaserver.html#2-the-catalog-list-content","title":"2. The catalog list content","text":"

    The response (that is, the catalog list) to the above query from the server is the following specification in JSON format.

    {\n\"name\" : FILE_NAME,\n\"type\" : FILE_TYPE,\n\"date\" : FILE_TIMESTAMP_DATED,\n\"time\" : FILE_TIMESTAMP_TIMED,\n\"size\" : FILE_SIZE\n}\n
    nameBinary sketch file name for update (String) typeOne of 'bin', 'directory' or 'file'. AutoConnect Update recognizes only file types of 'bin' as update targets. (String) dateFile update date. AutoConnect v1.0.0 treats the file update date as an annotation and is not equip the version control feature yet. (String) timeFile update time. AutoConnect v1.0.0 treats the file update date as an annotation and is not equip the version control feature yet. (String) sizeFile byte count (Numeric)

    The above JSON object is one entry. The actual catalog list is an array of this entry since it assumes that an update server will provide multiple update binary files in production. The update server should respond with the MIME type specified as application/json for the catalog list.7

    "},{"location":"otaserver.html#3-the-binary-sketch-file-used-for-updating","title":"3. The binary sketch file used for updating","text":"

    The AutoConnectUpdate class issues a HTTP GET request with the specified host address and URI. The update server responds by sending back a binary sketch file with the following header:

    Content-Type: application/octet-stream\nContent-Disposition: attachment; filename=\"BINARY_SKETCH_FILE_NAME\"\nContent-Length: LENGTH_OF_CONTENT\nx-MD5: HEXDIGEST\n

    The header x-MD5 is a 128-bit hash value (digest in hexadecimal) that represents the checksum of the binary sketch file for updates required for the ESP8266HTTPUpdate class.

    1. You can scroll horizontally on the browser to see the timestamp and file size that the catalog list contains.\u00a0\u21a9

    2. The folders containing the script: For Python2: AUTOCONNECT_LIBRARY_PATH/src/updateserver/python2 For Python3: AUTOCONNECT_LIBRARY_PATH/src/updateserver/python3\u00a0\u21a9

    3. Deploying the binary sketch file output by Arduino IDE is usually just copying to the folder for deployment. However, its folder must be accessible from the updateserver.py script.\u00a0\u21a9

    4. The port of the update server and the port used by the AutoConnectUpdate class must be the same.\u00a0\u21a9

    5. The client agent is an instance of the AutoConnectUpdate class.\u00a0\u21a9

    6. The client agent will send its URI request to the update server.\u00a0\u21a9

    7. It should be represented as Content-Type: application/json in the HTTP response header.\u00a0\u21a9

    "},{"location":"otaupdate.html","title":"OTA Updates","text":"

    Only for AutoConnect

    AutoConnect OTA features are valid only for AutoConnect; they are not available for AutoConnectCore.

    "},{"location":"otaupdate.html#ota-updates-with-autoconnect","title":"OTA Updates with AutoConnect","text":"

    AutoConnect provides two type platforms for updating the binary sketch in the ESP8266 or ESP32 module via OTA. They correspond to the Web Browser Update and HTTP Server Update whiches mentioned in the ESP8266 Arduino Core documentation.

    The update behavior using a web browser as the client that supplies the binary sketch file for update follows the scenario assumed by the ESP8266 Arduino core. Therefore, the user sketch must meet the requirements described in the ESP8266 Arduino Core documentation, but you can easily embed the OTA update feature that able to operate via the web browser by AutoConnect menu. All you need to do is that specify AutoConnectConfig.

    It is for the only the same network

    This method can apply only if the client browser and the ESP module belong to the same network segment. It cannot work correctly across networks.

    Another update method using an update server can be applied more broadly than using a web browser. This method can also update the ESP module over the Internet if you can secure the correct route and transparency between the ESP module and the update server. To configure this platform, you need to have an update server along with using the AutoConnectUpdate class in your sketch.

    Security Disclaimer

    The security level of the OTA update platform provided by AutoConnect is very weak. No guarantees as to the level of security for your application by the AutoConnect OTA Update is implied.

    "},{"location":"wojson.html","title":"Custom Web pages w/o JSON","text":""},{"location":"wojson.html#suppress-increase-in-memory-consumption","title":"Suppress increase in memory consumption","text":"

    Custom Web page processing consumes a lot of memory. AutoConnect will take a whole string of the JSON document for the custom Web pages into memory. The required buffer size for the JSON document of example sketch mqttRSSI reaches approximately 3000 bytes. And actually, it needs twice the heap area. Especially this constraint will be a problem with the ESP8266 which has a heap size poor.

    AutoConnect can handle custom Web pages without using JSON. In that case, since the ArduinoJson library will not be bound, the Sketch size will also be reduced.

    "},{"location":"wojson.html#writing-the-custom-web-pages-without-json","title":"Writing the custom Web pages without JSON","text":"

    To handle the custom Web pages without using JSON, follow the steps below.

    1. Create or define AutoConnectAux for each page.
    2. Create or define AutoConnectElement(s).
    3. Add AutoConnectElement(s) to AutoConnectAux.
    4. Create more AutoConnectAux containing AutoConnectElement(s), if necessary.
    5. Register the request handlers for the custom Web pages.
    6. Join prepared AutoConnectAux(s) to AutoConnect.
    7. Invoke AutoConnect::begin().

    In addition to the above procedure, to completely cut off for binding with the ArduinoJson library, turn off the ArduinoJson use indicator which is declared by the AutoConnect definitions. Its declaration is in AutoConnectDefs.h file.1

    // Comment out the AUTOCONNECT_USE_JSON macro to detach the ArduinoJson.\n#define AUTOCONNECT_USE_JSON\n

    JSON processing will be disabled

    Commenting out the AUTOCONNECT_USE_JSON macro invalidates all functions related to JSON processing. If the Sketch is using the JSON function, it will result in a compile error.

    Exclude the ArduinoJson by each compile-time

    If you want to exclude ArduinoJson without changing the library code, specify the AUTOCONNECT_NOUSE_JSON directive as a compiler option according to the method described in the FAQ.

    "},{"location":"wojson.html#implementation-example-without-arduinojson","title":"Implementation example without ArduinoJson","text":"

    The code excluding JSON processing from the mqttRSSI sketch attached to the library is as follows. (It is a part of code. Refer to mqttRSSI_NA.ino for the whole sketch.)

    The JSON document for mqttRSSI

    [\n  {\n\"title\": \"MQTT Setting\",\n\"uri\": \"/mqtt_setting\",\n\"menu\": true,\n\"element\": [\n      {\n\"name\": \"header\",\n\"type\": \"ACText\",\n\"value\": \"<h2>MQTT broker settings</h2>\",\n\"style\": \"text-align:center;color:#2f4f4f;padding:10px;\"\n      },\n      {\n\"name\": \"caption\",\n\"type\": \"ACText\",\n\"value\": \"Publishing the WiFi signal strength to MQTT channel. RSSI value of ESP8266 to the channel created on ThingSpeak\",\n\"style\": \"font-family:serif;color:#4682b4;\"\n      },\n      {\n\"name\": \"mqttserver\",\n\"type\": \"ACInput\",\n\"value\": \"\",\n\"label\": \"Server\",\n\"pattern\": \"^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\\\-]*[a-zA-Z0-9])\\\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\\\-]*[A-Za-z0-9])$\",\n\"placeholder\": \"MQTT broker server\"\n      },\n      {\n\"name\": \"channelid\",\n\"type\": \"ACInput\",\n\"label\": \"Channel ID\",\n\"pattern\": \"^[0-9]{6}$\"\n      },\n      {\n\"name\": \"userkey\",\n\"type\": \"ACInput\",\n\"label\": \"User Key\"\n      },\n      {\n\"name\": \"apikey\",\n\"type\": \"ACInput\",\n\"label\": \"API Key\"\n      },\n      {\n\"name\": \"newline\",\n\"type\": \"ACElement\",\n\"value\": \"<hr>\"\n      },\n      {\n\"name\": \"uniqueid\",\n\"type\": \"ACCheckbox\",\n\"value\": \"unique\",\n\"label\": \"Use APID unique\",\n\"checked\": false\n      },\n      {\n\"name\": \"period\",\n\"type\": \"ACRadio\",\n\"value\": [\n\"30 sec.\",\n\"60 sec.\",\n\"180 sec.\"\n        ],\n\"label\": \"Update period\",\n\"arrange\": \"vertical\",\n\"checked\": 1\n      },\n      {\n\"name\": \"newline\",\n\"type\": \"ACElement\",\n\"value\": \"<hr>\"\n      },\n      {\n\"name\": \"hostname\",\n\"type\": \"ACInput\",\n\"value\": \"\",\n\"label\": \"ESP host name\",\n\"pattern\": \"^([a-zA-Z0-9]([a-zA-Z0-9-])*[a-zA-Z0-9]){1,32}$\"\n      },\n      {\n\"name\": \"save\",\n\"type\": \"ACSubmit\",\n\"value\": \"Save&amp;Start\",\n\"uri\": \"/mqtt_save\"\n      },\n      {\n\"name\": \"discard\",\n\"type\": \"ACSubmit\",\n\"value\": \"Discard\",\n\"uri\": \"/\"\n      }\n    ]\n  },\n  {\n\"title\": \"MQTT Setting\",\n\"uri\": \"/mqtt_save\",\n\"menu\": false,\n\"element\": [\n      {\n\"name\": \"caption\",\n\"type\": \"ACText\",\n\"value\": \"<h4>Parameters saved as:</h4>\",\n\"style\": \"text-align:center;color:#2f4f4f;padding:10px;\"\n      },\n      {\n\"name\": \"parameters\",\n\"type\": \"ACText\"\n      },\n      {\n\"name\": \"clear\",\n\"type\": \"ACSubmit\",\n\"value\": \"Clear channel\",\n\"uri\": \"/mqtt_clear\"\n      }\n    ]\n  }\n]\n
    Exclude the JSON and replace to the AutoConnectElements natively

    // In the declaration,\n// Declare AutoConnectElements for the page asf /mqtt_setting\nACText(header, \"<h2>MQTT broker settings</h2>\", \"text-align:center;color:#2f4f4f;padding:10px;\");\nACText(caption, \"Publishing the WiFi signal strength to MQTT channel. RSSI value of ESP8266 to the channel created on ThingSpeak\", \"font-family:serif;color:#4682b4;\");\nACInput(mqttserver, \"\", \"Server\", \"^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\\\-]*[a-zA-Z0-9])\\\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\\\-]*[A-Za-z0-9])$\", \"MQTT broker server\");\nACInput(channelid, \"\", \"Channel ID\", \"^[0-9]{6}$\");\nACInput(userkey, \"\", \"User Key\");\nACInput(apikey, \"\", \"API Key\");\nACElement(newline, \"<hr>\");\nACCheckbox(uniqueid, \"unique\", \"Use APID unique\");\nACRadio(period, { \"30 sec.\", \"60 sec.\", \"180 sec.\" }, \"Update period\", AC_Vertical, 1);\nACSubmit(save, \"Start\", \"mqtt_save\");\nACSubmit(discard, \"Discard\", \"/\");\n\n// Declare the custom Web page as /mqtt_setting and contains the AutoConnectElements\nAutoConnectAux mqtt_setting(\"/mqtt_setting\", \"MQTT Setting\", true, {\n  header,\n  caption,\n  mqttserver,\n  channelid,\n  userkey,\n  apikey,\n  newline,\n  uniqueid,\n  period,\n  newline,\n  save,\n  discard\n});\n\n// Declare AutoConnectElements for the page as /mqtt_save\nACText(caption2, \"<h4>Parameters available as:</h4>\", \"text-align:center;color:#2f4f4f;padding:10px;\");\nACText(parameters);\nACSubmit(clear, \"Clear channel\", \"/mqtt_clear\");\n\n// Declare the custom Web page as /mqtt_save and contains the AutoConnectElements\nAutoConnectAux mqtt_save(\"/mqtt_save\", \"MQTT Setting\", false, {\n  caption2,\n  parameters,\n  clear\n});\n\n// In the setup(),\n// Join the custom Web pages and performs begin\n  portal.join({ mqtt_setting, mqtt_save });\n  portal.begin();\n

    1. Detaching the ArduinoJson library reduces the Sketch size by approximately 10K bytes.\u00a0\u21a9

    "}]} \ No newline at end of file diff --git a/docs/sitemap.xml b/docs/sitemap.xml index ef973779..101a040b 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -2,202 +2,202 @@ https://Hieromon.github.io/AutoConnect/index.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/acelements.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/achandling.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/acinteract.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/acintro.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/acjson.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/acupload.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/adauthentication.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/adconnection.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/adcpcontrol.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/adcredential.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/adexterior.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/adnetwork.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/adothers.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/advancedusage.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/api.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/apiaux.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/apiconfig.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/apielements.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/apiextra.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/apiupdate.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/basicusage.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/changelabel.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/changelog.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/colorized.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/credit.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/datatips.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/esp32cam.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/faq.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/filesystem.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/gettingstarted.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/howtoembed.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/license.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/lsbegin.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/menu.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/menuize.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/otabrowser.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/otaserver.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/otaupdate.html - 2023-02-18 + 2023-02-22 daily https://Hieromon.github.io/AutoConnect/wojson.html - 2023-02-18 + 2023-02-22 daily \ No newline at end of file diff --git a/docs/sitemap.xml.gz b/docs/sitemap.xml.gz index 21e748f6cd03ad7963a42e941ca627d68ea73dad..8be36f697211af1354651f31d9f44eec968dcaf2 100644 GIT binary patch delta 465 zcmV;?0WSXJ1LFe+ABzYGIOg?{2OfWxT-u5ysw!1|fc60fdln`&9^x4m(x;9L@V6~P;JJ{?%NDJ8GlqZtsQ@cr+)DBiXCvH%x^n(yM9U>2vXLP}xI*$67J&h6 zh-b3mgk`frEpdCH!HU+_sJwVL&0qz)%mLI!7W5$G?L^nDYJ?u6B`@2^1<#Q){YD!z ziG9RKHYUC$4$5R_wvo0d^JC*-GJ(Coiw!45lvh!-aajjcr8I~_RwF@iF!HL5Q*VSD z$zu{5U)?A@4rJrcM;X;FW}xL;Yr@J3edbj#Tj3V!)sEKCgkk0X_h0;NC8*sW7i!BY HlN$g4{N>(1 delta 466 zcmV;@0WJRH1LOk-ABzYG3)b+F2OfWBb4e?fsEQQz0on%`>{*!9c!+0MNT0qY8&!L+ zRB5;X#*BXAaKK7a;gT^ z>8o?gveZI~BTQ0r?w$Cd?1=kpbcgy&)!yyOvK6>)eJo96-)>c;l=)7WdE|do_oTzz z)x_@Gto+O=p;t#K;93tl#>Q=@-Btn7kwbet93S?FE;JWJ)SeZwE-x; zH}0n8%5#5x{~!gA5l2iaM!2PHh~-Wj;Zjn};MEQ{vk~j7l!G>?^As6^4Qzl}hY|?n zLCMM$4*t4j2s{;XdD)^BZ^nPHJr!UDjB80=;%tPQP#4a>jA*$;L^d*H2p32m!z|FF z4e>-)oG`Ces3mUC)LYTo8kHCCsu`?c=P7{N$bt@pyq)N}R*leMwB%(Qx!^f+rr&5| zCb5ke$;QOD#6g+tOg7RMWqLSz7)@Z$@MgnF5#?PJZCutKRVnqNkkvv+91OfD