<p>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 <ahref="#autoconnectstyle">AutoConnectStyle</a> will insert the raw CSS code into the style block in HTML of the custom Web page.</p>
<h2id="form-and-autoconnectelements">Form and AutoConnectElements<aclass="headerlink"href="#form-and-autoconnectelements"title="Permanent link">¶</a></h2>
<p>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 <ahref="#autoconnectsubmit">AutoConnectSubmit</a> using the <strong>POST</strong> method with HTTP. The post method sends the actual form data which is a query string whose contents are the <strong>name</strong> and <strong>value</strong> of AutoConnectElements. You can retrieve the value for the parameter with the sketch from the query string with <ahref="https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#getting-information-about-request-arguments">ESP8266WebServer::arg</a> function or <ahref="https://github.com/Hieromon/PageBuilder#arguments-of-invoked-user-function">PageArgument</a> class of the <ahref="api.html#on">AutoConnect::on</a> handler when the form is submitted.</p>
<p>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 <ahref="#autoconnectsubmit">AutoConnectSubmit</a> using the <strong>POST</strong> method with HTTP. The post method sends the actual form data which is a query string whose contents are the <strong>name</strong> and <strong>value</strong> of AutoConnectElements. You can retrieve the value for the parameter with the Sketch from the query string with <ahref="https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer#getting-information-about-request-arguments">ESP8266WebServer::arg</a> function or <ahref="https://github.com/Hieromon/PageBuilder#arguments-of-invoked-user-function">PageArgument</a> class of the <ahref="api.html#on">AutoConnect::on</a> handler when the form is submitted.</p>
<h2id="autoconnectelement-a-basic-class-of-elements">AutoConnectElement - <small>A basic class of elements</small><aclass="headerlink"href="#autoconnectelement-a-basic-class-of-elements"title="Permanent link">¶</a></h2>
<p>AutoConnectElement is a base class for other element classes and has common attributes for all elements. It can also be used as a <ahref="#variant-for-autoconnectelements">variant</a> of each element. The following items are attributes that AutoConnectElement has and are common to other elements.</p>
<p>The <strong>type</strong> indicates the type of the element and represented as the <em>ACElement_t</em> 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 <ahref="apielements.html#typeof"><strong>typeOf()</strong></a> function. The following example changes the font color of all <ahref="#autoconnecttext">AutoConnectText</a> elements of a custom Web page to gray.</p>
<p>The <strong>type</strong> indicates the type of the element and represented as the <em>ACElement_t</em> 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 <ahref="apielements.html#typeof"><strong>typeOf()</strong></a> function. The following example changes the font color of all <ahref="#autoconnecttext">AutoConnectText</a> elements of a custom Web page to gray.</p>
<p>Furthermore, to convert an entity that is not an AutoConnectElement to its native type, you must <ahref="https://en.cppreference.com/w/cpp/language/reinterpret_cast">re-interpret</a> that type with c++. Or, you can be coding the sketch more easily with using the <ahref="apielements.html#ast62"><strong>as<T></strong></a> function.</p>
<p>Furthermore, to convert an entity that is not an AutoConnectElement to its native type, you must <ahref="https://en.cppreference.com/w/cpp/language/reinterpret_cast">re-interpret</a> that type with c++. Or, you can be coding the Sketch more easily with using the <ahref="apielements.html#ast62"><strong>as<T></strong></a> function.</p>
@ -2173,7 +2173,7 @@ Only <i class="far fa-square"></i> will be displayed if a label is not specified
<ul>
<li><strong><code>AC_File_FS</code></strong> : Save as the SPIFFS file in flash of ESP8266/ESP32 module.</li>
<li><strong><code>AC_File_SD</code></strong> : Save to an external SD device connected to ESP8266/ESP32 module.</li>
<li><strong><code>AC_File_Extern</code></strong> : Pass the content of the uploaded file to the uploader which is declared by the sketch individually. Its uploader must inherit <ahref="acupload.html#to-upload-to-a-device-other-than-flash-or-sd"><strong>AutoConnectUploadHandler</strong></a> class and implements <em>_open</em>, <em>_write</em> and <em>_close</em> function.</li>
<li><strong><code>AC_File_Extern</code></strong> : Pass the content of the uploaded file to the uploader which is declared by the Sketch individually. Its uploader must inherit <ahref="acupload.html#to-upload-to-a-device-other-than-flash-or-sd"><strong>AutoConnectUploadHandler</strong></a> class and implements <em>_open</em>, <em>_write</em> and <em>_close</em> function.</li>
</ul>
<divclass="admonition note">
<pclass="admonition-title">Built-in uploader is ready.</p>
@ -2182,7 +2182,7 @@ Only <i class="far fa-square"></i> will be displayed if a label is not specified
<p>AutoConnectInput generates an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">input</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"text"</span><spanstyle="color: #f8f8f2">></span></code> tag and a <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">label</span><spanstyle="color: #f8f8f2">></span></code> 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.</p>
<p>AutoConnectInput generates an HTML <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">input</span><spanstyle="color: #a6e22e">type</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"text"</span><spanstyle="color: #f8f8f2">></span></code> tag and a <codeclass="codehilite"><spanstyle="color: #f8f8f2"><</span><spanstyle="color: #f92672">label</span><spanstyle="color: #f8f8f2">></span></code> 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.</p>
<p>It is the <code>name</code> of the AutoConnectStyle element and is useful only to access this element from the sketch. It does not affect the generated HTML code.</p>
<p>It is the <code>name</code> of the AutoConnectStyle element and is useful only to access this element from the Sketch. It does not affect the generated HTML code.</p>
<p>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.</p>
<p>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.</p>
<h2id="handing-autoconnectelements-with-the-sketches">Handing AutoConnectElements with the sketches<aclass="headerlink"href="#handing-autoconnectelements-with-the-sketches"title="Permanent link">¶</a></h2>
<h2id="handing-autoconnectelements-with-the-sketches">Handing AutoConnectElements with the Sketches<aclass="headerlink"href="#handing-autoconnectelements-with-the-sketches"title="Permanent link">¶</a></h2>
<p>The AutoConnectAux class has several functions to manipulate AutoConnectElements. The functions can add, delete, retrieve elements, and get and set values.</p>
<h3id="add-autoconnectelements-to-the-autoconnectaux-object"><iclass="fa fa-edit"></i> Add AutoConnectElements to the AutoConnectAux object<aclass="headerlink"href="#add-autoconnectelements-to-the-autoconnectaux-object"title="Permanent link">¶</a></h3>
<p>To add AutoConnectElment(s) to an AutoConnectAux object, use the add function.</p>
<p>The add function adds the specified AutoConnectElement to AutoConnectAux. The AutoConnectElementVT type is the <ahref="https://en.cppreference.com/w/cpp/container/vector"><em>std::vector</em></a> of the <ahref="https://en.cppreference.com/w/cpp/utility/functional/reference_wrapper"><em>reference wrapper</em></a> to AutoConnectElements, and you can add these elements in bulk by using the <ahref="https://en.cppreference.com/w/cpp/language/list_initialization"><em>list initialization</em></a> with the sketch.</p>
<p>The add function adds the specified AutoConnectElement to AutoConnectAux. The AutoConnectElementVT type is the <ahref="https://en.cppreference.com/w/cpp/container/vector"><em>std::vector</em></a> of the <ahref="https://en.cppreference.com/w/cpp/utility/functional/reference_wrapper"><em>reference wrapper</em></a> to AutoConnectElements, and you can add these elements in bulk by using the <ahref="https://en.cppreference.com/w/cpp/language/list_initialization"><em>list initialization</em></a> with the Sketch.</p>
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.<supid="fnref:1"><aclass="footnote-ref"href="#fn:1">1</a></sup> In the following example, AutoConnectButton <code>button</code> addition will invalid because <code>hello</code> with the same name already exists as AutoConnectText.</p>
@ -1202,7 +1202,7 @@ AutoConnectElements contained in AutoConnectAux object are uniquely identified b
<p>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.</p>
</div>
<h3id="get-autoconnectelement-from-the-autoconnectaux"><iclass="fa fa-edit"></i> Get AutoConnectElement from the AutoConnectAux<aclass="headerlink"href="#get-autoconnectelement-from-the-autoconnectaux"title="Permanent link">¶</a></h3>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>You can also use the <ahref="apiaux.html#operator">operator <strong><code>[]</code></strong> of AutoConnectAux</a> as another way to get the desired element. An operator <strong><code>[]</code></strong> is a shortcut for <ahref="apiaux.html#getelement">getElement</a> 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 <ahref="apielements.html#ast62"><strong>AutoConnectElement::as<T></strong></a> function with the operator <code>[]</code>, 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 <code>caption</code>.</p>
<p>You can also use the <ahref="apiaux.html#operator">operator <strong><code>[]</code></strong> of AutoConnectAux</a> as another way to get the desired element. An operator <strong><code>[]</code></strong> is a shortcut for <ahref="apiaux.html#getelement">getElement</a> 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 <ahref="apielements.html#ast62"><strong>AutoConnectElement::as<T></strong></a> function with the operator <code>[]</code>, 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 <code>caption</code>.</p>
<h3id="enable-autoconnectelements-during-the-sketch-execution"><iclass="fa fa-edit"></i> Enable AutoConnectElements during the sketch execution<aclass="headerlink"href="#enable-autoconnectelements-during-the-sketch-execution"title="Permanent link">¶</a></h3>
<h3id="enable-autoconnectelements-during-the-sketch-execution"><iclass="fa fa-edit"></i> Enable AutoConnectElements during the Sketch execution<aclass="headerlink"href="#enable-autoconnectelements-during-the-sketch-execution"title="Permanent link">¶</a></h3>
<p>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.</p>
<p>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:</p>
@ -1323,7 +1323,7 @@ AutoConnectElements contained in AutoConnectAux object are uniquely identified b
<divclass="admonition hint">
<pclass="admonition-title">Desirable to set or reset the enable attribute in the page handler</p>
<p>The enable attribute can be set at any time during the sketch execution. The page handler with the <ahref="apiaux.html#on">AC_EXIT_AHEAD</a> option is sure to handle it.</p>
<p>The enable attribute can be set at any time during the Sketch execution. The page handler with the <ahref="apiaux.html#on">AC_EXIT_AHEAD</a> option is sure to handle it.</p>
</div>
<h2id="loading-saving-autoconnectelements-with-json">Loading & saving AutoConnectElements with JSON<aclass="headerlink"href="#loading-saving-autoconnectelements-with-json"title="Permanent link">¶</a></h2>
<p>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 <ahref="acjson.html">JSON document for AutoConnect</a>. However, it can not save all AutoConnectElements contained in the page as a custom Web page. (ie. AutoConnectAux)</p>
@ -1751,7 +1751,7 @@ ESP8266WebServer class will parse the query string and rebuilds its arguments wh
</div>
<h3id="retrieve-the-values-with-webserveron-handler"><iclass="fa fa-wrench"></i> Retrieve the values with WebServer::on handler<aclass="headerlink"href="#retrieve-the-values-with-webserveron-handler"title="Permanent link">¶</a></h3>
<p>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.</p>
<p>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 <ahref="acelements.html#uri">uri</a> attribute of <ahref="acelements.html#autoconnectsubmit">AutoConnectSubmit</a>) 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 <ahref="apiaux.html#fetchelement">AutoConnectAux::fetchElement</a> function for value processing with the on-page handler.</p>
<p>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 <ahref="acelements.html#uri">uri</a> attribute of <ahref="acelements.html#autoconnectsubmit">AutoConnectSubmit</a>) 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 <ahref="apiaux.html#fetchelement">AutoConnectAux::fetchElement</a> function for value processing with the on-page handler.</p>
<p>The following sketch is an example of extracting values inputted on a custom web page with an on-page handler and then processing it.</p>
@ -1802,7 +1802,7 @@ ESP8266WebServer class will parse the query string and rebuilds its arguments wh
<h3id="overwrite-the-autoconnectelements"><iclass="fa fa-wpforms"></i> Overwrite the AutoConnectElements<aclass="headerlink"href="#overwrite-the-autoconnectelements"title="Permanent link">¶</a></h3>
<p>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 <ahref="apiaux.html#loadelement">AutoConnectAux::loadElement</a>. </p>
<p>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 <ahref="api.html#load">AutoConnect::load</a> function.</p>
<p>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.</p>
<p>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.</p>
<p><iclass="fab fa-js-square"></i> External JSON document for the below sketch to modify the text style.
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.</p>
<p><imgsrc="images/ac_declaration.svg"></p>
<p>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 <em>header</em> and <em>caption</em>, adds them to the AutoConnectAux object as <em>aux</em>, binds to an AutoConnect object named <em>portal</em>. This sequence is the basic procedure for creating custom Web pages with the sketch. The further explanation is available in section <ahref="acelements.html">AutoConnectElements</a> also.</p>
<p>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 <em>header</em> and <em>caption</em>, adds them to the AutoConnectAux object as <em>aux</em>, binds to an AutoConnect object named <em>portal</em>. This sequence is the basic procedure for creating custom Web pages with the Sketch. The further explanation is available in section <ahref="acelements.html">AutoConnectElements</a> also.</p>
<h2id="custom-web-pages-in-autoconnect-menu">Custom Web pages in AutoConnect menu<aclass="headerlink"href="#custom-web-pages-in-autoconnect-menu"title="Permanent link">¶</a></h2>
<ulclass="horizontal-list">
<li><imgstyle="margin:0 20px 0 -20px;float:left;width:300px;"src="images/ac_auxmenu.png">
@ -918,7 +918,7 @@ AutoConnectAux is a container for AutoConnectElements. To make a custom Web page
<p>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.</p>
<li><pstyle="margin:0 20px 0 -20px"><spanstyle="margin-left:20px;float:right;width:280px;height:497px;border:1px solid lightgrey;"><imgdata-gifffer="images/aux_menu.gif"data-gifffer-width="278"data-gifffer-height="495"/></span>In the above code, the third parameter of <i>aux2</i> is <b>false</b>. 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 <i>aux2</i> by the utility of the <ahref="acelements.html#autoconnectsubmit"><b>AutoConnectSubmit</b></a> element owned by <i>aux1</i>.<supid="fnref:2"><aclass="footnote-ref"href="#fn:2"rel="footnote">2</a></sup><br>The <i>aux2</i> page transitions only from the <i>aux1</i> 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.</p></li>
<li><pstyle="margin:0 20px 0 -20px"><spanstyle="margin-left:20px;float:right;width:280px;height:497px;border:1px solid lightgrey;"><imgdata-gifffer="images/aux_menu.gif"data-gifffer-width="278"data-gifffer-height="495"/></span>In the above code, the third parameter of <i>aux2</i> is <b>false</b>. 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 <i>aux2</i> by the utility of the <ahref="acelements.html#autoconnectsubmit"><b>AutoConnectSubmit</b></a> element owned by <i>aux1</i>.<supid="fnref:2"><aclass="footnote-ref"href="#fn:2"rel="footnote">2</a></sup><br>The <i>aux2</i> page transitions only from the <i>aux1</i> 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.</p></li>
</ul>
<h2id="basic-steps-to-use-custom-web-pages">Basic steps to use custom Web pages<aclass="headerlink"href="#basic-steps-to-use-custom-web-pages"title="Permanent link">¶</a></h2>
@ -935,7 +935,7 @@ AutoConnectAux is a container for AutoConnectElements. To make a custom Web page
</ol>
<h2id="write-the-custom-web-page-with-json">Write the custom Web page with JSON<aclass="headerlink"href="#write-the-custom-web-page-with-json"title="Permanent link">¶</a></h2>
<p>You can write the custom Web page in JSON without using sketch codes.<supid="fnref:3"><aclass="footnote-ref"href="#fn:3">3</a></sup> 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 <ahref="api.html#load"><strong>load</strong></a> 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 footnote<supid="fnref:2"><aclass="footnote-ref"href="#fn:2">2</a></sup> is equivalent.</p>
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 footnote<supid="fnref:2"><aclass="footnote-ref"href="#fn:2">2</a></sup> is equivalent.</p>
<p>You can embed custom Web pages written in <ahref="https://www.json.org/index.html"><strong>JSON</strong></a> 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.<supid="fnref:1"><aclass="footnote-ref"href="#fn:1">1</a></sup></p>
<p>You can embed custom Web pages written in <ahref="https://www.json.org/index.html"><strong>JSON</strong></a> 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.<supid="fnref:1"><aclass="footnote-ref"href="#fn:1">1</a></sup></p>
<p>By providing the following JSON document to AutoConnect, you can include the custom Web page like the below:</p>
<p>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.</p>
<p>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.</p>
<divclass="admonition caution">
<pclass="admonition-title">Adopt ArduinoJson v5 or v6</p>
<p>To handle AutoConnectAux and AutoConnectElements written in JSON, you need to install the ArduinoJson library. You can adopt either <ahref="https://arduinojson.org/v5/doc/installation/">version 5</a> or <ahref="https://arduinojson.org/v6/doc/installation/">version 6</a> for the ArduinoJson. AutoConnect supports both versions.</p>
@ -1485,7 +1485,7 @@
<li><strong>store</strong> : Specifies the destination to save the uploaded file. Its value accepts one of the following:<p>
<b>fs</b> : Save as the SPIFFS file in flash of ESP8266/ESP32 module.<br>
<b>sd</b> : Save to an external SD device connected to ESP8266/ESP32 module.<br>
<b>extern</b> : Pass the content of the uploaded file to the uploader which is declared by the sketch individually. Its uploader must inherit <ahref="acupload.html#to-upload-to-a-device-other-than-flash-or-sd"><strong>AutoConnectUploadHandler</strong></a> class and implements <em>_open</em>, <em>_write</em> and <em>_close</em> function.</p></li>
<b>extern</b> : Pass the content of the uploaded file to the uploader which is declared by the Sketch individually. Its uploader must inherit <ahref="acupload.html#to-upload-to-a-device-other-than-flash-or-sd"><strong>AutoConnectUploadHandler</strong></a> class and implements <em>_open</em>, <em>_write</em> and <em>_close</em> function.</p></li>
</ul>
</dd>
</dl>
@ -1595,7 +1595,7 @@
<li>
<p>Load directly into AutoConnect</p>
<p>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.</p>
<p>Using the <ahref="api.html#load">AutoCoonnect::load</a> 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 <ahref="api.html#aux">AutoConnect::aux</a> function. You can reach the AutoConnectElements you desired using the <ahref="apiaux.html#getelement">AutoConnectAux::getElement</a> function of its AutoConnectAux.</p>
<p>Using the <ahref="api.html#load">AutoCoonnect::load</a> 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 <ahref="api.html#aux">AutoConnect::aux</a> function. You can reach the AutoConnectElements you desired using the <ahref="apiaux.html#getelement">AutoConnectAux::getElement</a> function of its AutoConnectAux.</p>
<p>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.</p>
<p>Load to AutoConnectAux and join to AutoConnect</p>
<p>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.</p>
<p>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.</p>
<p>After loading a JSON document using the <ahref="apiaux.html#load">AutoConnectAux::load</a> function by each, integrate those into AutoConnect using the <ahref="api.html#join">AutoConnect::join</a> function.</p>
<p>In the following example, you can see the difference between two sketches in a sketch modified using the AutoConnectAux::load.</p>
<p>For ESP32 module equips with PSRAM, you can allocate the JSON document buffer to PSRAM. Buffer allocation to PSRAM will enable when <strong>PSRAM:Enabled</strong> option selected in the Arduino IDE's Board Manager menu. It is available since ArduinoJson 6.10.0.</p>
<p>The sketch can persist AutoConnectElements as a JSON document and also uses <ahref="achandling.html#saving-autoconnectelements-with-json">this function</a> 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 <ahref="achandling.html#loading-autoconnectaux-autoconnectelements-with-json">load function</a>. </p>
<p>the Sketch can persist AutoConnectElements as a JSON document and also uses <ahref="achandling.html#saving-autoconnectelements-with-json">this function</a> 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 <ahref="achandling.html#loading-autoconnectaux-autoconnectelements-with-json">load function</a>. </p>
<h2id="uploading-file-from-web-browser">Uploading file from Web Browser<aclass="headerlink"href="#uploading-file-from-web-browser"title="Permanent link">¶</a></h2>
<p>If you have to write some data individually to the ESP8266/ESP32 module for the sketch behavior, the <ahref="acelements.html#autoconnectfile">AutoConnectFile</a> element will assist with your wants implementation. The AutoConnectFile element produces an HTML <code><input type="file"></code> 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.
<p>If you have to write some data individually to the ESP8266/ESP32 module for the Sketch behavior, the <ahref="acelements.html#autoconnectfile">AutoConnectFile</a> element will assist with your wants implementation. The AutoConnectFile element produces an HTML <code><input type="file"></code> 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.
<h2id="basic-steps-of-the-file-upload-sketch">Basic steps of the file upload sketch<aclass="headerlink"href="#basic-steps-of-the-file-upload-sketch"title="Permanent link">¶</a></h2>
<p>Here is the basic procedure of the sketch which can upload files from the client browser using AutoConnectFile:<supid="fnref:1"><aclass="footnote-ref"href="#fn:1">1</a></sup></p>
<p>Here is the basic procedure of the Sketch which can upload files from the client browser using AutoConnectFile:<supid="fnref:1"><aclass="footnote-ref"href="#fn:1">1</a></sup></p>
<ol>
<li>Place AutoConnectFile on a custom Web page by writing JSON or constructor code directly with the sketch.</li>
<li>Place AutoConnectFile on a custom Web page by writing JSON or constructor code directly with the Sketch.</li>
<li>Place other AutoConnectElements as needed.</li>
<li>Place AutoConnectSubmit on the same custom Web page.</li>
<li>Perform the following process in the on-handler of submitting destination:<ul>
@ -1099,7 +1099,7 @@
<p><code>AUTOCONNECT_SD_SPEED</code> defines SPI clock speed depending on the connected device.</p>
<divclass="admonition info">
<pclass="admonition-title">Involves both the begin() and the end()</p>
<p>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 <strong>restart it with the begin</strong> function.</p>
<p>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 <strong>restart it with the begin</strong> function.</p>
</div>
<h2id="when-it-will-be-uploaded">When it will be uploaded<aclass="headerlink"href="#when-it-will-be-uploaded"title="Permanent link">¶</a></h2>
<p>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.</p>
@ -1112,7 +1112,7 @@
<p>You can output the file to any device using a custom uploader by specifying <ahref="acjson.html#acfile"><strong>extern</strong></a> with the <ahref="acjson.html#acfile"><strong>store</strong></a> attribute of <ahref="acjson.html#acfile">AutoConnectFile</a> (or specifying <ahref="acelements.html#store"><strong>AC_File_Extern</strong></a> for the <ahref="apielements.html#store"><strong>store</strong></a> 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 <ahref="#upload-handler-base-class"><strong>AutoConnectUploadHandler</strong></a> class which is the base class of the upload handler.</p>
<divclass="admonition note">
<pclass="admonition-title">It's not so difficult</p>
<p>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.</p>
<p>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.</p>
</div>
<h3id="upload-handler-base-class"><iclass="fa fa-code"></i> Upload handler base class<aclass="headerlink"href="#upload-handler-base-class"title="Permanent link">¶</a></h3>
<p>AutoConnectUploadHandler is a base class of upload handler and It has one public member function and three protected functions. </p>
@ -1218,7 +1218,7 @@
<dd><spanclass="apidef">T</span><spanclass="apidesc">Specifies a class name of the custom uploader. This class name is a class that you implemented by inheriting AutoConnectUploadHandler for custom upload.</span></dd>
<dd><spanclass="apidef">uploadClass</span><spanclass="apidesc">Specifies the custom upload class instance.</span></dd>
</dl></p>
<p>The rough structure of the sketches that completed these implementations will be as follows:</p>
<p>The rough structure of the Sketches that completed these implementations will be as follows:</p>
<p>Registering the "not found" handler is a different way than ESP8266WebServer (WebServer as ESP32). The <em>onNotFound</em> of ESP8266WebServer/WebServer does not work with AutoConnect. AutoConnect overrides <em>ESP8266WebServer::onNotFound</em>/<em>WebServer::onNotFound</em> to handle a captive portal. To register "not found" handler, use <ahref="api.html#onnotfound"><em>AutoConnect::onNotFound</em></a>.</p>
<h3id="access-to-saved-credentials"><iclass="fa fa-caret-right"></i> Access to saved credentials<aclass="headerlink"href="#access-to-saved-credentials"title="Permanent link">¶</a></h3>
<p>AutoConnect stores the established WiFi connection in the flash of the ESP8266/ESP32 module and equips the class to access it from the sketch. You can read, write or erase the credentials using this class individually. It's <ahref="credit.html#autoconnectcredential">AutoConnectCredential</a> class which provides the access method to the saved credentials in the flash. Refer to section <ahref="credit.html">Saved credentials access</a> for details.</p>
<p>AutoConnect stores the established WiFi connection in the flash of the ESP8266/ESP32 module and equips the class to access it from the Sketch. You can read, write or erase the credentials using this class individually. It's <ahref="credit.html#autoconnectcredential">AutoConnectCredential</a> class which provides the access method to the saved credentials in the flash. Refer to section <ahref="credit.html">Saved credentials access</a> for details.</p>
<divclass="admonition note">
<pclass="admonition-title">Where to store credentials in ESP32 with AutoConnect v1.0.0 or later</p>
<p>Since v1.0.0, credentials are stored in nvs of ESP32. AutoConnect v1.0.0 or later accesses the credentials area using the <strong>Preferences</strong> class with the arduino esp-32 core. So in ESP32, the credentials are not in the EEPROM, it is in the namespace <strong>AC_CREDT</strong> of the nvs. See <ahref="credit.html">Saved credentials access</a> for details.<br/>
@ -1304,7 +1318,7 @@ See the <a href="credit.html">Saved credentials access</a> chapter for details o
<p>The captive portal will only be activated if the first <em>WiFi::begin</em> fails. Sketch can detect with the <ahref="api.html#ondetect"><em>AutoConnect::onDetect</em></a> 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.</p>
<p>The captive portal will only be activated if 1<sup>st</sup>-WiFi::begin fails. Sketch can detect with the <ahref="api.html#ondetect"><em>AutoConnect::onDetect</em></a> 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.</p>
<p>Basically, the captive portal launch is subject to 1<sup>st</sup>-WiFi.begin result, but Sketch can control it. The Sketch can direct the following four actions by configuring AutoConnect with two parameters, <ahref="apiconfig.html#immediatestart"><em>AutoConnectConfig::immediateStart</em></a> and <ahref="apiconfig.html#autorise"><em>AutoConnectConfig::autoRise</em></a>.</p>
<td>Skip 1st-WiFi.begin<br>ESP module becomes SoftAP and the captive portal starts immediately.<br></td>
<td>Not attempt WiFi connection.<br>Only WebServer will start in STA mode.</td>
</tr>
<tr>
<td>false</td>
<td>Attempts WiFi connection in STA mode.<br>In some cases, the autoReconnect may restore the connection even if 1st-WiFiBeing fails.<br>If the connection is completely lost, the captive portal will be launched.<br><b>This is the default.</b></td>
<td>Attempts WiFi connection in STA mode.<br>In some cases, the autoReconnect may restore the connection even if 1st-WiFiBeing fails.<br>ESP module stays in STA mode and WebServer will start.</td>
<p>AutoConnect has two parameters for timeout control. One is a timeout value used when trying to connect to the specified AP. It behaves the same as general timeout control in connection attempt by WiFi.begin. This control is specified by the third parameter of <ahref="api.html#begin"><em>AutoConnect::begin</em></a>. The default value is macro defined by <ahref="api.html#defined-macros"><strong>AUTOCONNECT_TIMEOUT</strong></a> in the <strong>AutoConnectDefs.h</strong> file.</p>
<p>Once AutoConnect has entered the captive portal state due to the above conditions, it will not exit until a WiFi connection can be established. (But that is the default behavior)</p>
<p>The Sketch can abort the <ahref="api.html#begin"><em>AutoConnect::begin</em></a> by setting the captive portal timeout and returns control to Sketch. AutoConnect has two parameters for timeout control. One is a timeout value used when trying to connect to the specified AP. It behaves the same as general timeout control in connection attempt by WiFi.begin. This control is specified by the third parameter of <ahref="api.html#begin"><em>AutoConnect::begin</em></a>. The default value is macro defined by <ahref="api.html#defined-macros"><strong>AUTOCONNECT_TIMEOUT</strong></a> in the <strong>AutoConnectDefs.h</strong> file.</p>
<p>The other timeout control is for the captive portal itself. It is useful when you want to continue sketch execution with offline even if the WiFi connection is not possible. You can also combine it with the <ahref="#on-demand-start-the-captive-portal"><strong>immediateStart</strong></a> option to create sketches with high mobility.</p>
<p>The timeout of the captive portal is specified together with <ahref="apiconfig.html#portaltimeout"><em>AutoConnectConfig::portalTimeout</em></a> as follows.</p>
@ -1380,7 +1418,7 @@ Also, if you want to stop AutoConnect completely when the captive portal is time
<spanstyle="color: #f8f8f2">}</span>
</code></pre></div>
<p>There is another option related to timeout in AutoConnectConfig. It can make use of the captive portal function even after a timeout. The <ahref="apiconfig.html#retainportal"><em>AutoConnectConfig::retainPortal</em></a> option will not stop the SoftAP when the captive portal is timed out. If you enable the ratainPortal option, you can try to connect to the AP at any time while continuing to sketch execution with offline even after the captive portal timed-out. Compared to the above code specified no option with the following example code, the captive portal will remain available even after a timeout without changing the logic of the sketch.</p>
<p>There is another option related to timeout in AutoConnectConfig. It can make use of the captive portal function even after a timeout. The <ahref="apiconfig.html#retainportal"><em>AutoConnectConfig::retainPortal</em></a> option will not stop the SoftAP when the captive portal is timed out. If you enable the ratainPortal option, you can try to connect to the AP at any time while continuing to sketch execution with offline even after the captive portal timed-out. Compared to the above code specified no option with the following example code, the captive portal will remain available even after a timeout without changing the logic of the Sketch.</p>
@ -1464,7 +1502,7 @@ Also, if you want to stop AutoConnect completely when the captive portal is time
<ol>
<li>
<p>Overwrite the label literal of library source code directly.</p>
<p>You can change the label of the AutoConnect menu item by rewriting the default label literal in <ahref="https://github.com/Hieromon/AutoConnect/blob/master/src/AutoConnectLabels.h">AutoConnectLabels.h</a> macros. However, changing menu items literal influences all the sketch's build scenes.</p>
<p>You can change the label of the AutoConnect menu item by rewriting the default label literal in <ahref="https://github.com/Hieromon/AutoConnect/blob/master/src/AutoConnectLabels.h">AutoConnectLabels.h</a> macros. However, changing menu items literal influences all the Sketch's build scenes.</p>
<divclass="codehilite"style="background: #272822"><prestyle="line-height: 125%"><span></span><code><spanstyle="color: #7a7a7a">#define AUTOCONNECT_MENULABEL_CONFIGNEW "Configure new AP"</span>
@ -1489,7 +1527,7 @@ And PlatformIO is a build system. Library sources will not be compiled unless Au
</li>
</ol>
<h3id="combination-with-mdns"><iclass="fa fa-caret-right"></i> Combination with mDNS<aclass="headerlink"href="#combination-with-mdns"title="Permanent link">¶</a></h3>
<p>With <ahref="https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266mDNS">mDNS library</a>, you can access to ESP8266 by name instead of IP address after connection. The sketch can start the MDNS responder after <ahref="api.html#begin"><em>AutoConnect::begin</em></a>.</p>
<p>With <ahref="https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266mDNS">mDNS library</a>, you can access to ESP8266 by name instead of IP address after connection. The Sketch can start the MDNS responder after <ahref="api.html#begin"><em>AutoConnect::begin</em></a>.</p>
@ -1536,7 +1574,7 @@ Combining these two parameters allows you to filter the destination AP when mult
<td>Restoring static IPs suitable for the SSID from saved credentials</td>
</tr>
<tr>
<td>Specified with the sketch</td>
<td>Specified with the Sketch</td>
<td>Not efective</td>
<td>By AutoConnect::begin parameters</td>
<td>Use the specified value of AutoConnectConfig</td>
@ -1560,7 +1598,7 @@ Combining these two parameters allows you to filter the destination AP when mult
</code></pre></div>
<h3id="disable-the-captive-portal"><iclass="fa fa-caret-right"></i> Disable the captive portal<aclass="headerlink"href="#disable-the-captive-portal"title="Permanent link">¶</a></h3>
<p>It can also prevent the captive portal from starting even if the connection at the first <em>WiFi.begin</em> fails. In this case, <ahref="api.html#begin"><em>AutoConnect::begin</em></a> behaves same as <em>WiFi.begin</em>.</p>
<p>It can also prevent the captive portal from starting even if the connection at the 1<sup>st</sup>-WiFi.begin fails. In this case, <ahref="api.html#begin"><em>AutoConnect::begin</em></a> behaves same as <em>WiFi.begin</em>.</p>
<p>For disabling the captive portal, <ahref="apiconfig.html#autorise"><strong>autoRise</strong></a> sets to false with <ahref="apiconfig.html">AutoConnectConfig</a>.</p>
@ -1704,7 +1742,7 @@ Known access point credentials are saved by AutoConnect, to the ESP module can u
<p>The host() can be referred at after <em>AutoConnect::begin</em>.</p>
</div>
<h3id="usage-for-automatically-instantiated-esp8266webserverwebserver"><iclass="fa fa-caret-right"></i> Usage for automatically instantiated ESP8266WebServer/WebServer<aclass="headerlink"href="#usage-for-automatically-instantiated-esp8266webserverwebserver"title="Permanent link">¶</a></h3>
<p>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 <ahref="api.html#host"><em>AutoConnect::host</em></a> function. The sketch can use the '<strong>on</strong>' function, '<strong>send</strong>' function, '<strong>client</strong>' function and others by ESP8266WebServer/WebServer reference of its return value.</p>
<p>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 <ahref="api.html#host"><em>AutoConnect::host</em></a> function. The Sketch can use the '<strong>on</strong>' function, '<strong>send</strong>' function, '<strong>client</strong>' function and others by ESP8266WebServer/WebServer reference of its return value.</p>
@ -1741,7 +1779,7 @@ Known access point credentials are saved by AutoConnect, to the ESP module can u
<divclass="admonition note">
<pclass="admonition-title">ESP8266WebServer/WebServer function should be called after AutoConnect::begin</p>
<p>The sketch cannot refer to an instance of ESP8266WebServer/WebServer until AutoConnect::begin completes successfully.</p>
<p>The Sketch cannot refer to an instance of ESP8266WebServer/WebServer until AutoConnect::begin completes successfully.</p>
</div>
<divclass="admonition warning">
<pclass="admonition-title">Do not use with ESP8266WebServer::begin or WebServer::begin</p>
@ -1774,7 +1812,7 @@ Known access point credentials are saved by AutoConnect, to the ESP module can u
<h3id="assign-user-sketchs-home-path"><iclass="fa fa-caret-right"></i> Assign user sketch's home path<aclass="headerlink"href="#assign-user-sketchs-home-path"title="Permanent link">¶</a></h3>
<p><strong>HOME</strong> for returning to the user's sketch homepage will display at the bottom of the AutoConnect menu. It could be set using the <ahref="api.html#home"><em>AutoConnect::home</em></a> function.</p>
<p><imgsrc="images/menu_home.png"/></p>
<p>The sketch HOME path is closely related to the <ahref="apiconfig.html#booturi">bootUri</a> that specifies the access path on module restart. AutoConnect has the following three parameters concerning control the URIs:</p>
<p>The Sketch HOME path is closely related to the <ahref="apiconfig.html#booturi">bootUri</a> that specifies the access path on module restart. AutoConnect has the following three parameters concerning control the URIs:</p>
<ul>
<li><strong>AUTOCONNECT_URI</strong><br/>
The <strong>ROOT</strong> of AutoConnect. It is defined in <code>AutoConnectDefs.h</code> and is assigned an <ahref="menu.html#where-the-from">AutoConnect statistics screen</a> by default.</li>
@ -1872,7 +1910,7 @@ See the <a href="otabrowser.html">Updates with the Web Browser</a> chapter for d
<p>You can also assign no password to SoftAP launched as a captive portal. Assigning a null string as <code>String("")</code> to <ahref="apiconfig.html#psk"><em>AutoConnectConfig::psk</em></a> does not require a password when connecting to SoftAP.<br/>
But this method is not recommended. The broadcast radio of SSID emitted from SoftAP will leak and reach several tens of meters.</p>
<h3id="configuration-for-soft-ap-and-captive-portal"><iclass="fa fa-caret-right"></i> Configuration for Soft AP and captive portal<aclass="headerlink"href="#configuration-for-soft-ap-and-captive-portal"title="Permanent link">¶</a></h3>
<p>AutoConnect will activate SoftAP at failed the first <em>WiFi.begin</em>. It SoftAP settings are stored in <ahref="apiconfig.html#autoconnectconfig"><strong>AutoConnectConfig</strong></a> as the following parameters. The sketch could be configured SoftAP using these parameters, refer the <ahref="apiconfig.html#public-member-variables">AutoConnectConfig API</a> for details.</p>
<p>AutoConnect will activate SoftAP at failed the 1<sup>st</sup>-WiFi.begin. It SoftAP settings are stored in <ahref="apiconfig.html#autoconnectconfig"><strong>AutoConnectConfig</strong></a> as the following parameters. The Sketch could be configured SoftAP using these parameters, refer the <ahref="apiconfig.html#public-member-variables">AutoConnectConfig API</a> for details.</p>
<p>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.</p>
<p>The default channel when a captive portal starts and AutoConnect itself becomes an access point is the <ahref="apiconfig.html#channel"><em>AutoConnectConfig::channel</em></a> 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.</p>
<p>Run the AutoConnect site using the externally ensured ESP8266WebServer for ESP8266 or WebServer for ESP32.</p>
<p>The <ahref="api.html#handleclient"><strong>handleClient</strong></a> function of AutoConnect can include the response of the URI handler added by the user using the "<em>on</em>" function of ESP8266WebServer/WebServer. If ESP8266WebServer/WebServer is assigned internally by AutoConnect, the sketch can obtain that reference with the <ahref="api.html#host"><strong>host</strong></a> function.
<p>The <ahref="api.html#handleclient"><strong>handleClient</strong></a> function of AutoConnect can include the response of the URI handler added by the user using the "<em>on</em>" function of ESP8266WebServer/WebServer. If ESP8266WebServer/WebServer is assigned internally by AutoConnect, the Sketch can obtain that reference with the <ahref="api.html#host"><strong>host</strong></a> function.
<dlclass="apidl">
<dt><strong>Parameter</strong></dt>
<dd><spanclass="apidef">webServer</span><spanclass="apidesc">A reference of ESP8266WebServer or WebServer instance.</span></dd>
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 <ahref="apiaux.html#add">add</a> function or the <ahref="apiaux.html#loadelement">loadElement</a> function, the sketch can change the style of the custom Web page according to its behavior.
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 <ahref="apiaux.html#add">add</a> function or the <ahref="apiaux.html#loadelement">loadElement</a> function, the Sketch can change the style of the custom Web page according to its behavior.
<dlclass="apidl">
<dt><strong>Parameter</strong></dt>
<dd><spanclass="apidef">name</span><spanclass="apidesc">Specifies the name of AutoConnectElements to be released.</span></dd>
@ -1359,7 +1359,7 @@ Sets the value of the specified AutoConnectElement. If values is specified
</dl></p>
<divclass="admonition hint">
<pclass="admonition-title">You can directly access the value member variable.</p>
<p>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.
<p>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.
<p>Captive portal activation switch. False for disabling the captive portal. It prevents starting the captive portal even if the connection at the first <em>WiFi.begin</em> fails.
<p>Captive portal activation switch. False for disabling the captive portal. It prevents starting the captive portal even if the connection at the 1<sup>st</sup>-WiFi.begin fails.
<dlclass="apidl">
<dt><strong>Type</strong></dt>
<dd>bool</dd>
@ -1404,7 +1404,7 @@ This option is valid only for ESP8266 or ESP32 arduino core 1.0.2 earlier.
</dl></p>
<divclass="admonition warning">
<pclass="admonition-title">It will conflict with user data.</p>
<p>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.</p>
<p>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.</p>
<p>Disable the first WiFi.begin() and start the captive portal. If this option is enabled, the module will be in AP_STA mode and the captive portal will be activated regardless of<ahref="apiconfig.html#autorise"><strong>AutoConnectConfig::autoRise</strong></a> specification.
<p>Disable the 1<sup>st</sup>-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<ahref="apiconfig.html#autorise"><strong>AutoConnectConfig::autoRise</strong></a>. Even if immediateStart is true, the captive portal will not launch if autoRise is false.
<dlclass="apidl">
<dt><strong>Type</strong></dt>
<dd>bool</dd>
<dt><strong>Value</strong></dt>
<dd><spanclass="apidef">true</span><spanclass="apidesc">Start the captive portal with <ahref="api.html#begin"><strong>AutoConnect::begin</strong></a>.</span></dd>
<dd><spanclass="apidef">false</span><spanclass="apidesc">Enable the first WiFi.begin() and it will start captive portal when connection failed. This is default.</span></dd>
<dd><spanclass="apidef">false</span><spanclass="apidesc">Enable the 1<sup>st</sup>-WiFi.begin and it will start captive portal when connection failed. This is default.</span></dd>
<p>Configure applying items of the <ahref="menu.html">AutoConnect menu</a>. You can arbitrarily combine valid menus by coordinating the menuItems value.
@ -1502,7 +1502,7 @@ However, even if you specify like the above, the AutoConnectAux page items still
<dd><spanclass="apidef">IPAddress</span><spanclass="apidesc">The default value is <strong>255.255.255.0</strong></span></dd>
<p>Specifies to import the built-in OTA update class into the sketch. When this option is enabled, an <strong>Update</strong> item will appear in the AutoConnect menu, and the OTA update via Web browser will be automatically embedded to the Sketch.
<p>Specifies to import the built-in OTA update class into the Sketch. When this option is enabled, an <strong>Update</strong> item will appear in the AutoConnect menu, and the OTA update via Web browser will be automatically embedded to the Sketch.
<dlclass="apidl">
<dt><strong>Type</strong></dt>
<dd>AC_OTA_t</dd>
@ -1542,7 +1542,7 @@ However, even if you specify like the above, the AutoConnectAux page items still
</dl></p>
<divclass="admonition hint">
<pclass="admonition-title">Connection request after timed-out</p>
<p>With the <strong>retainPortal</strong>, 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().</p>
<p>With the <strong>retainPortal</strong>, 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().</p>
</div>
<divclass="admonition info">
<pclass="admonition-title">All unresolved addresses redirects to /_ac</p>
@ -1608,7 +1608,7 @@ However, even if you specify like the above, the AutoConnectAux page items still
<spanstyle="color: #f8f8f2">Config.boundaryOffset</span><spanstyle="color: #f92672">=</span><spanstyle="color: #ae81ff">64</span><spanstyle="color: #f8f8f2">;</span><spanstyle="color: #7a7a7a">// Reserve 64 bytes for the user data in EEPROM.</span>
<spanstyle="color: #f8f8f2">Config.portalTimeout</span><spanstyle="color: #f92672">=</span><spanstyle="color: #ae81ff">60000</span><spanstyle="color: #f8f8f2">;</span><spanstyle="color: #7a7a7a">// Sets timeout value for the captive portal</span>
<spanstyle="color: #f8f8f2">Config.retainPortal</span><spanstyle="color: #f92672">=</span><spanstyle="color: #f8f8f2">true;</span><spanstyle="color: #7a7a7a">// Retains the portal function after timed-out</span>
<spanstyle="color: #f8f8f2">Config.homeUri</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"/index.html"</span><spanstyle="color: #f8f8f2">;</span><spanstyle="color: #7a7a7a">// Sets home path of the sketch application</span>
<spanstyle="color: #f8f8f2">Config.homeUri</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"/index.html"</span><spanstyle="color: #f8f8f2">;</span><spanstyle="color: #7a7a7a">// Sets home path of Sketch application</span>
<spanstyle="color: #f8f8f2">Config.title</span><spanstyle="color: #f92672">=</span><spanstyle="color: #e6db74">"My menu"</span><spanstyle="color: #f8f8f2">;</span><spanstyle="color: #7a7a7a">// Customize the menu title</span>
<li>Bar type <imgsrc="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAApklEQVRYR2NkGGDAOMD2M4w6YDQEkEMgEJggZwCxGI0T5mug+alAvBFkD7IDXtLBcpjfXgEZ4ugOeAETpHEIgIwHeVYC3QH+0CgAS9AQgCwHRcFmdAfQ0E7cRo9mw0EVAqPlAKhwEKVTVsBZDsyiQ2k4Wg6gxPKgyoZ0Sn+o1iCHQBBQaiYQi9DYJTjbAyAJWluOtz0wWg7QOOqxGz+aDUdDYMBDAACA0x4hs/MPrwAAAABJRU5ErkJggg=="title="AutoConnect menu"alt="AutoConnect menu"/></li>
<li>Cog type <imgsrc="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=="title="AutoConnect menu"alt="AutoConnect menu"/></li>
</ul>
<p>To reference the icon, use the <strong>AUTOCONNECT_LINK</strong> macro in the sketch. It expands into the string literal as an HTML <code><a></a></code> tag with PNG embedded of the AutoConnect menu hyperlinks. Icon type is specified by the parameter of the macro.</p>
<p>To reference the icon, use the <strong>AUTOCONNECT_LINK</strong> macro in the Sketch. It expands into the string literal as an HTML <code><a></a></code> tag with PNG embedded of the AutoConnect menu hyperlinks. Icon type is specified by the parameter of the macro.</p>
<h3id="embed-to-the-sketches"><iclass="fa fa-edit"></i> Embed to the sketches<aclass="headerlink"href="#embed-to-the-sketches"title="Permanent link">¶</a></h3>
<p>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 <code>ESP8266WebServer</code> with <code>WebServer</code> and <code>ESP8266WiFi.h</code> with <code>WiFi.h</code> respectively.</p>
<h3id="embed-to-the-sketches"><iclass="fa fa-edit"></i> Embed to the Sketches<aclass="headerlink"href="#embed-to-the-sketches"title="Permanent link">¶</a></h3>
<p>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 <code>ESP8266WebServer</code> with <code>WebServer</code> and <code>ESP8266WiFi.h</code> with <code>WiFi.h</code> respectively.</p>
<p><imgsrc="images/BeforeAfter.svg"/></p>
<ulclass="ulsty-edit"style="list-style:none;">
<li>Insert <codeclass="codehilite"><spanclass="cp">#include</span><spanclass="cpf"><AutoConnect.h></span></code> to behind of <codeclass="codehilite"><spanclass="cp">#include</span><spanclass="cpf"><ESP8266WebServer.h></span></code>.</li>
<h3id="basic-logic-sequence-for-the-user-sketches"><iclass="fa fa-caret-right"></i> Basic logic sequence for the user sketches<aclass="headerlink"href="#basic-logic-sequence-for-the-user-sketches"title="Permanent link">¶</a></h3>
<h3id="basic-logic-sequence-for-the-user-sketches"><iclass="fa fa-caret-right"></i> Basic logic sequence for the user Sketches<aclass="headerlink"href="#basic-logic-sequence-for-the-user-sketches"title="Permanent link">¶</a></h3>
<h4id="1-a-typical-logic-sequence">1. A typical logic sequence<aclass="headerlink"href="#1-a-typical-logic-sequence"title="Permanent link">¶</a></h4>
6.1 <strong>Do the process for actual sketch.</strong><br/>
6.1 <strong>Do the process for actual Sketch.</strong><br/>
6.2 <strong>Invokes </strong><code>AutoConnect::handleClient()</code><strong>, or invokes </strong><code>ESP8266WebServer::handleClient()</code><strong>/</strong><code>WebServer::handleClient</code><strong> then </strong><code>AutoConnect::handleRequest()</code><strong>.</strong></li>
</ol>
</div>
@ -1046,13 +1046,13 @@ or</p>
<p><strong>The parameter with an ESP8266WebServer/WebServer variable:</strong> An ESP8266WebServer/WebServer object variable must be declared. AutoConnect uses its variable to handles the <ahref="menu.html">AutoConnect menu</a>.</p>
</li>
<li>
<p><strong>With no parameter:</strong>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 <em>ESP8266WebServer::on</em> or <em>WebServer::on</em> should be performed after <ahref="api.html#begin"><em>AutoConnect::begin</em></a>.</p>
<p><strong>With no parameter:</strong>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 <em>ESP8266WebServer::on</em> or <em>WebServer::on</em> should be performed after <ahref="api.html#begin"><em>AutoConnect::begin</em></a>.</p>
</li>
</ul>
<h4id="3-no-need-wifibegin">3. No need WiFI.begin(...)<aclass="headerlink"href="#3-no-need-wifibegin"title="Permanent link">¶</a></h4>
<p>AutoConnect internally performs <em>WiFi.begin</em> to establish a WiFi connection. There is no need for a general process to establish a connection using <em>WiFi.begin</em> with a sketch code.</p>
<p>AutoConnect internally performs <em>WiFi.begin</em> to establish a WiFi connection. There is no need for a general process to establish a connection using <em>WiFi.begin</em> with a Sketch code.</p>
<h4id="4-alternate-esp8266webserverbegin-and-webserverbegin">4. Alternate ESP8266WebServer::begin() and WebServer::begin()<aclass="headerlink"href="#4-alternate-esp8266webserverbegin-and-webserverbegin"title="Permanent link">¶</a></h4>
<p><ahref="api.html#begin"><em>AutoConnect::begin</em></a> executes <em>ESP8266WebServer::begin</em>/<em>WebServer::begin</em> internally too and it starts the DNS server to behave as a Captive portal. So it is not needed to call <em>ESP8266WebServer::begin</em>/<em>WebServer::begin</em> in the sketch.</p>
<p><ahref="api.html#begin"><em>AutoConnect::begin</em></a> executes <em>ESP8266WebServer::begin</em>/<em>WebServer::begin</em> internally too and it starts the DNS server to behave as a Captive portal. So it is not needed to call <em>ESP8266WebServer::begin</em>/<em>WebServer::begin</em> in the Sketch.</p>
<divclass="admonition info">
<pclass="admonition-title">Why DNS Server starts</p>
<p>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.</p>
@ -1060,7 +1060,7 @@ or</p>
<h4id="5-autoconnectbegin-with-ssid-and-password">5. AutoConnect::begin with SSID and Password<aclass="headerlink"href="#5-autoconnectbegin-with-ssid-and-password"title="Permanent link">¶</a></h4>
<p>SSID and Password can also specify by <ahref="api.html#begin"><em>AutoConnect::begin</em></a>. 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.</p>
<h4id="6-use-esp8266webserveron-and-webserveron-to-handle-url">6. Use ESP8266WebServer::on and WebServer::on to handle URL<aclass="headerlink"href="#6-use-esp8266webserveron-and-webserveron-to-handle-url"title="Permanent link">¶</a></h4>
<p>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 "<em>on::ESP8266WebServer</em>" or the "<em>on::WebServer</em>" function is the same as when using ESP8266WebServer/WebServer natively.</p>
<p>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 "<em>on::ESP8266WebServer</em>" or the "<em>on::WebServer</em>" function is the same as when using ESP8266WebServer/WebServer natively.</p>
<h4id="7-use-either-esp8266webserverhandleclientwebserverhandleclient-or-autoconnecthandleclient">7. Use either ESP8266WebServer::handleClient()/WebServer::handleClient() or AutoConnect::handleClient()<aclass="headerlink"href="#7-use-either-esp8266webserverhandleclientwebserverhandleclient-or-autoconnecthandleclient"title="Permanent link">¶</a></h4>
<p>Both classes member function name is the same: <em>handleClient</em>, but the behavior is different. Using the AutoConnect embedded along with ESP8266WebServer::handleClient/WebServer::handleClient has limitations. Refer to the below section for details. </p>
<h3id="esp8266webserverwebserver-hosted-or-parasitic"><iclass="fa fa-caret-right"></i> ESP8266WebServer/WebServer hosted or parasitic<aclass="headerlink"href="#esp8266webserverwebserver-hosted-or-parasitic"title="Permanent link">¶</a></h3>
@ -1088,10 +1088,10 @@ or</p>
</table>
<ul>
<li>
<p><strong>By declaration for the AutoConnect variable with no parameter</strong>: The ESP8266WebServer/WebServer instance is hosted by AutoConnect automatically then the sketches use <ahref="api.html#host"><em>AutoConnect::host</em></a> as API to get it after <ahref="api.html#begin"><em>AutoConnect::begin</em></a> performed.</p>
<p><strong>By declaration for the AutoConnect variable with no parameter</strong>: The ESP8266WebServer/WebServer instance is hosted by AutoConnect automatically then the Sketches use <ahref="api.html#host"><em>AutoConnect::host</em></a> as API to get it after <ahref="api.html#begin"><em>AutoConnect::begin</em></a> performed.</p>
</li>
<li>
<p><strong>By declaration for the AutoConnect variable with the reference of ESP8266WebServer/WebServer</strong>: AutoConnect will use it. The sketch can use it is too.</p>
<p><strong>By declaration for the AutoConnect variable with the reference of ESP8266WebServer/WebServer</strong>: AutoConnect will use it. the Sketch can use it is too.</p>
</li>
<li>
<p><strong>In use ESP8266WebServer::handleClient()/WebServer::handleClient()</strong>: AutoConnect menu can be dispatched but not works normally. It is necessary to call <ahref="api.html#void-handlerequest"><em>AutoConnect::handleRequest</em></a> after <em>ESP8255WebServer::handleClient</em>/<em>WebServer::handleClient</em> invoking.</p>
@ -1109,7 +1109,7 @@ or</p>
<hr/>
<ol>
<liid="fn:1">
<p>Each <em>VARIABLE</em> conforms to the actual declaration in the sketches. <aclass="footnote-backref"href="#fnref:1"title="Jump back to footnote 1 in the text">↩</a></p>
<p>Each <em>VARIABLE</em> conforms to the actual declaration in the Sketches. <aclass="footnote-backref"href="#fnref:1"title="Jump back to footnote 1 in the text">↩</a></p>
</li>
<liid="fn:2">
<p>WiFi SSID and Password can be specified AutoConnect::begin() too. <aclass="footnote-backref"href="#fnref:2"title="Jump back to footnote 2 in the text">↩</a></p>
<h2id="autoconnect-menu-colorizing">AutoConnect menu colorizing<aclass="headerlink"href="#autoconnect-menu-colorizing"title="Permanent link">¶</a></h2>
<p>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.</p>
<p>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.</p>
<p>The menu color scheme has been separated to <code>AutoConnectLabels.h</code> placed the AutoConnect library folder.<supid="fnref:1"><aclass="footnote-ref"href="#fn:1">1</a></sup> You can change the color scheme of the menu with the following three color codes. The color code also accepts CSS standard color names.<supid="fnref:2"><aclass="footnote-ref"href="#fn:2">2</a></sup></p>
<p>In <code>AutoConnectLabels.h</code> you can find three definition macros for menu colors:</p>
<h2id="after-connected-autoconnect-menu-performs-but-no-happens"><iclass="fa fa-question-circle"></i> After connected, AutoConnect menu performs but no happens.<aclass="headerlink"href="#after-connected-autoconnect-menu-performs-but-no-happens"title="Permanent link">¶</a></h2>
<p>If you can access the <strong>AutoConnect root path</strong> as <ahref="http://ESP8266IPADDRESS/_ac">http://ESP8266IPADDRESS/_ac</a> from browser, probably the sketch uses <em>ESP8266WebServer::handleClient()</em> without <ahref="api.html#handlerequest"><em>AutoConnect::handleRequest()</em></a>.<br/>
<p>If you can access the <strong>AutoConnect root path</strong> as <ahref="http://ESP8266IPADDRESS/_ac">http://ESP8266IPADDRESS/_ac</a> from browser, probably the Sketch uses <em>ESP8266WebServer::handleClient()</em> without <ahref="api.html#handlerequest"><em>AutoConnect::handleRequest()</em></a>.<br/>
For AutoConnect menus to work properly, call <ahref="api.html#handlerequest"><em>AutoConnect::handleRequest()</em></a> after <em>ESP8266WebServer::handleClient()</em> invoked, or use <ahref="api.html#handleclient"><em>AutoConnect::handleClient()</em></a>. <ahref="api.html#handleclient"><em>AutoConnect::handleClient()</em></a> is equivalent <em>ESP8266WebServer::handleClient</em> combined <ahref="api.html#handlerequest"><em>AutoConnect::handleRequest()</em></a>.</p>
<p>See also the explanation <ahref="basicusage.html#esp8266webserver-hosted-or-parasitic">here</a>.</p>
<h2id="after-updating-to-autoconnect-v100-established-aps-disappear-from-open-ssids-with-esp32"><iclass="fa fa-question-circle"></i> After updating to AutoConnect v1.0.0, established APs disappear from Open SSIDs with ESP32.<aclass="headerlink"href="#after-updating-to-autoconnect-v100-established-aps-disappear-from-open-ssids-with-esp32"title="Permanent link">¶</a></h2>
@ -1295,7 +1295,7 @@ For AutoConnect menus to work properly, call <a href="api.html#handlerequest"><e
</li>
<li>
<p>Change the order of <code>#include</code> directives.</p>
<p>With the sketch, <code>#include <ESP8266httpUpdate.h></code> before <code>#include <AutoConnect.h></code>.</p>
<p>With the Sketch, <code>#include <ESP8266httpUpdate.h></code> before <code>#include <AutoConnect.h></code>.</p>
</li>
</ol>
<h2id="connection-lost-immediately-after-establishment-with-ap"><iclass="fa fa-question-circle"></i> Connection lost immediately after establishment with AP<aclass="headerlink"href="#connection-lost-immediately-after-establishment-with-ap"title="Permanent link">¶</a></h2>
@ -1356,14 +1356,14 @@ You have the following two options to avoid this conflict:</p>
<h2id="does-not-response-from-_ac"><iclass="fa fa-question-circle"></i> Does not response from /_ac.<aclass="headerlink"href="#does-not-response-from-_ac"title="Permanent link">¶</a></h2>
<p>Probably <strong>WiFi.begin</strong> failed with the specified SSID. Activating the <ahref="advancedusage.html#debug-print">debug printing</a> will help you to track down the cause.</p>
<h2id="hang-up-after-reset"><iclass="fa fa-question-circle"></i> Hang up after Reset?<aclass="headerlink"href="#hang-up-after-reset"title="Permanent link">¶</a></h2>
<p>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: <ahref="https://github.com/esp8266/Arduino/issues/1017">https://github.com/esp8266/Arduino/issues/1017</a><supid="fnref:1"><aclass="footnote-ref"href="#fn:1">1</a></sup></p>
<p>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: <ahref="https://github.com/esp8266/Arduino/issues/1017">https://github.com/esp8266/Arduino/issues/1017</a><supid="fnref:1"><aclass="footnote-ref"href="#fn:1">1</a></sup></p>
<p>If you received the following message, the boot mode is still sketch uploaded. It needs to the manual reset once.</p>
<p>It is described by <ahref="https://www.espressif.com/en/products/hardware/esp8266ex/resources">ESP8266 Non-OS SDK API Reference</a>, section A.5.</p>
@ -1407,7 +1407,7 @@ To completely remove ArduinoJson at compile-time from the binary, you need to de
</code></pre></div>
<h2id="how-erase-the-credentials-saved-in-eeprom"><iclass="fa fa-question-circle"></i> How erase the credentials saved in EEPROM?<aclass="headerlink"href="#how-erase-the-credentials-saved-in-eeprom"title="Permanent link">¶</a></h2>
<p>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 <em>AutoConnectCredential</em>. The <em>AutoConnectCrendential</em> class provides the access method to the saved credential in EEPROM and library source file is including it. Refer to '<ahref="credit.html#saved-credential-in-eeprom">Saved credential access</a>' on section <ahref="credit.html">Appendix</a> for details.</p>
<p>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 <em>AutoConnectCredential</em>. The <em>AutoConnectCrendential</em> class provides the access method to the saved credential in EEPROM and library source file is including it. Refer to '<ahref="credit.html#saved-credential-in-eeprom">Saved credential access</a>' on section <ahref="credit.html">Appendix</a> for details.</p>
<divclass="admonition hint">
<pclass="admonition-title">Hint</p>
<p>With the <ahref="https://github.com/Hieromon/ESPShaker"><strong>ESPShaker</strong></a>, you can access EEPROM interactively from the serial monitor, and of course you can erase saved credentials.</p>
@ -1425,7 +1425,7 @@ To completely remove ArduinoJson at compile-time from the binary, you need to de
<h2id="i-cannot-complete-to-wi-fi-login-from-smartphone"><iclass="fa fa-question-circle"></i> I cannot complete to Wi-Fi login from smartphone.<aclass="headerlink"href="#i-cannot-complete-to-wi-fi-login-from-smartphone"title="Permanent link">¶</a></h2>
<p>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.</p>
<h2id="i-cannot-see-the-custom-web-page"><iclass="fa fa-question-circle"></i> I cannot see the custom Web page.<aclass="headerlink"href="#i-cannot-see-the-custom-web-page"title="Permanent link">¶</a></h2>
<p>If the sketch is correct, a JSON syntax error may have occurred. In this case, activate the <ahref="faq.html#3-turn-on-the-debug-log-options">AC_DEBUG</a> and rerun. If you take the message of JSON syntax error, the <ahref="https://arduinojson.org/v5/assistant/">Json Assistant</a> helps syntax checking. This online tool is provided by the author of ArduinoJson and is most consistent for the AutoConnect. </p>
<p>If the Sketch is correct, a JSON syntax error may have occurred. In this case, activate the <ahref="faq.html#3-turn-on-the-debug-log-options">AC_DEBUG</a> and rerun. If you take the message of JSON syntax error, the <ahref="https://arduinojson.org/v5/assistant/">Json Assistant</a> helps syntax checking. This online tool is provided by the author of ArduinoJson and is most consistent for the AutoConnect. </p>
<h2id="saved-credentials-are-wrong-or-lost"><iclass="fa fa-question-circle"></i> Saved credentials are wrong or lost.<aclass="headerlink"href="#saved-credentials-are-wrong-or-lost"title="Permanent link">¶</a></h2>
<p>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.
@ -1437,7 +1437,7 @@ To completely remove ArduinoJson at compile-time from the binary, you need to de
<li>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.</li>
</ol>
<p>If this issue produces with your sketch, Reloading the page may recover.<br/>
Also, you can check the memory running out status by rebuilding the sketch with <ahref="faq.html#fn:2">PageBuilder's debug log option</a> turned on.</p>
Also, you can check the memory running out status by rebuilding the Sketch with <ahref="faq.html#fn:2">PageBuilder's debug log option</a> turned on.</p>
<p>If the heap memory is insufficient, the following message is displayed on the serial console.</p>
<liclass="task-list-item"><inputtype="checkbox"disabled/> Problem description</li>
<liclass="task-list-item"><inputtype="checkbox"disabled/> If you have a STACK DUMP decoded result with formatted by the code block tag</li>
<liclass="task-list-item"><inputtype="checkbox"disabled/>The sketch code with formatted by the code block tag (Reduce to the reproducible minimum code for the problem)</li>
<liclass="task-list-item"><inputtype="checkbox"disabled/>the Sketch code with formatted by the code block tag (Reduce to the reproducible minimum code for the problem)</li>
<p>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.</p>
<p>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 "<strong>Log in</strong>" by upper right on the screen.<br/>
<p>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 "<strong>Log in</strong>" by upper right on the screen.<br/>
Or, "<strong>RESET</strong>" can be selected. The ESP8266 resets and reboots. After that, immediately before the connection will be restored automatically with WIFI_STA mode.</p>
<h3id="run-for-usually"><iclass="fa fa-play-circle"></i> Run for usually<aclass="headerlink"href="#run-for-usually"title="Permanent link">¶</a></h3>
<p>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 "<strong>on</strong>" function of <em>ESP8266WebServer</em>.</p>
<p>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 "<strong>on</strong>" function of <em>ESP8266WebServer</em>.</p>
<h2id="embed-the-autoconnect-to-the-sketch">Embed the AutoConnect to the sketch<aclass="headerlink"href="#embed-the-autoconnect-to-the-sketch"title="Permanent link">¶</a></h2>
<p>Here hold two case examples. Both examples perform the same function. Only how to incorporate the <strong>AutoConnect</strong> into the sketch differs. Also included in the sample folder, HandlePortal.ino also shows how to use the <ahref="https://github.com/Hieromon/PageBuilder">PageBuilder</a> library for HTML assemblies.</p>
<h2id="embed-the-autoconnect-to-the-sketch">Embed the AutoConnect to the Sketch<aclass="headerlink"href="#embed-the-autoconnect-to-the-sketch"title="Permanent link">¶</a></h2>
<p>Here hold two case examples. Both examples perform the same function. Only how to incorporate the <strong>AutoConnect</strong> into the Sketch differs. Also included in the sample folder, HandlePortal.ino also shows how to use the <ahref="https://github.com/Hieromon/PageBuilder">PageBuilder</a> library for HTML assemblies.</p>
<h2id="what-does-this-example-do">What does this example do?<aclass="headerlink"href="#what-does-this-example-do"title="Permanent link">¶</a></h2>
<p>Uses the web interface to light the LED connected to the D0 (sometimes called <em>BUILTIN_LED</em>) port of the <strong><ahref="https://github.com/nodemcu/nodemcu-devkit-v1.0">NodeMCU</a></strong> module like the following animation.</p>
<p>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.</p>
@ -1022,14 +1022,14 @@
<p>Declare only AutoConnect, performs handleClient.</p>
<p><imgsrc="images/handlePortal.svg"/></p>
<h2id="used-with-mqtt-as-a-client-application">Used with MQTT as a client application<aclass="headerlink"href="#used-with-mqtt-as-a-client-application"title="Permanent link">¶</a></h2>
<p>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.</p>
<p>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.</p>
<p>This example tries to publish the WiFi signal strength of ESP8266 with MQTT. It uses the <ahref="https://thingspeak.com/">ThingSpeak</a> for MQTT broker. ESP8266 publishes the RSSI value to the channel created on ThingSpeak as <ahref="https://github.com/knolleary/pubsubclient">MQTT client</a>. This example is well suited to demonstrate the usefulness of AutoConnect, as RSSI values are measured at each access point usually. Just adding a few lines of code makes it unnecessary to upload sketches with the different SSIDs rewrite for each access point.</p>
<li>Arduino Client for MQTT - It's the <ahref="https://github.com/knolleary/pubsubclient">PubSubClient</a>, install it to Arduino IDE. If you have the latest version already, this step does not need.</li>
<li>Create a channel on ThingSpeak.</li>
<li>Get the Channel API Keys from ThingSpeak, put its keys to the sketch.</li>
<li>Get the Channel API Keys from ThingSpeak, put its keys to the Sketch.</li>
</ul>
<p>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.<supid="fnref:1"><aclass="footnote-ref"href="#fn:1">1</a></sup> You can sign up with the <ahref="https://thingspeak.com/users/sign_up">ThingSpeak sign-up page</a>.</p>
<divclass="admonition warning">
@ -1052,8 +1052,8 @@
<p><imgsrc="images/APIKeys.png"width="70%"/></p>
<p>The last key you need is the <strong>User API Key</strong> and can be confirmed it in the user profile. Pull down <strong>Account</strong> from the top menu, select <strong>My profile</strong>. Then you can see the ThingSpeak settings and the <strong>User API Key</strong> is displayed middle of this screen.</p>
<p>The complete code of the sketch is <ahref="https://github.com/Hieromon/AutoConnect/blob/master/examples/mqttRSSI/mqttRSSI.ino">mqttRSSI.ino</a> in the <ahref="https://github.com/Hieromon/AutoConnect">AutoConnect repository</a>. Replace the following #define in a sketch with <strong>User API Key</strong>, <strong>Write API Key</strong> and <strong>Channel ID</strong>. After Keys updated, compile the sketch and upload it.</p>
<p>The complete code of the Sketch is <ahref="https://github.com/Hieromon/AutoConnect/blob/master/examples/mqttRSSI/mqttRSSI.ino">mqttRSSI.ino</a> in the <ahref="https://github.com/Hieromon/AutoConnect">AutoConnect repository</a>. Replace the following #define in a sketch with <strong>User API Key</strong>, <strong>Write API Key</strong> and <strong>Channel ID</strong>. After Keys updated, compile the Sketch and upload it.</p>
<divclass="codehilite"style="background: #272822"><prestyle="line-height: 125%"><span></span><code><spanstyle="color: #7a7a7a">#define MQTT_USER_KEY "****************" // Replace to User API Key.</span>
<spanstyle="color: #7a7a7a">#define CHANNEL_ID "******" // Replace to Channel ID.</span>
<spanstyle="color: #7a7a7a">#define CHANNEL_API_KEY_WR "****************" // Replace to the write API Key.</span>
<p>To the dynamic configuration for joining to WLAN with SSID and PSK accordingly. It an Arduino library united with <em>ESP8266WebServer</em> class for ESP8266 or <em>WebServer</em> 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.</p>
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.</p>
<h3id="no-need-pre-coded-ssid-password"><iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> No need pre-coded SSID & password<aclass="headerlink"href="#no-need-pre-coded-ssid-password"title="Permanent link">¶</a></h3>
<p><spanclass="lead">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.</span></p>
<p><spanclass="lead">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.</span></p>
<p><spanclass="lead">AutoConnect control screen will be displayed automatically for establishing new connections. It aids by the <ahref="https://en.wikipedia.org/wiki/Captive_portal">captive portal</a> when vested the connection cannot be detected.<br>By using the <ahref="menu.html">AutoConnect menu</a>, to manage the connections convenient.</span></p>
<h3id="store-the-established-connection"><iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Store the established connection<aclass="headerlink"href="#store-the-established-connection"title="Permanent link">¶</a></h3>
<p><spanclass="lead">The connection authentication data as credentials are saved automatically in the flash of ESP8266/ESP32 and You can select the past SSID from the <ahref="menu.html">AutoConnect menu</a>.</span></p>
<h3id="easy-to-embed-in"><iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Easy to embed in<aclass="headerlink"href="#easy-to-embed-in"title="Permanent link">¶</a></h3>
<p><spanclass="lead">AutoConnect can be placed easily in your sketch. It's "<strong>begin</strong>" and "<strong>handleClient</strong>" only.</span></p>
<h3id="lives-with-your-sketches"><iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Lives with your sketches<aclass="headerlink"href="#lives-with-your-sketches"title="Permanent link">¶</a></h3>
<p><spanclass="lead">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.</span></p>
<p><spanclass="lead">AutoConnect can be placed easily in your Sketch. It's "<strong>begin</strong>" and "<strong>handleClient</strong>" only.</span></p>
<h3id="lives-with-your-sketches"><iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Lives with your Sketches<aclass="headerlink"href="#lives-with-your-sketches"title="Permanent link">¶</a></h3>
<p><spanclass="lead">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.</span></p>
<h3id="easy-to-add-the-custom-web-pages-enhanced-wv097"><iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Easy to add the <ahref="acintro.html">custom Web pages</a><sup><sub>ENHANCED w/v0.9.7</sub></sup><aclass="headerlink"href="#easy-to-add-the-custom-web-pages-enhanced-wv097"title="Permanent link">¶</a></h3>
<p><spanclass="lead">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.</span></p>
<divstyle="display:block;height:425px;">
@ -1044,7 +1044,7 @@ Easy implementing the Web interface constituting the WLAN for ESP8266/ESP32 WiFi
</div>
<h3id="quick-and-easy-to-equip-the-ota-update-feature-updated-wv115"><iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Quick and easy to equip the <ahref="otaupdate.html">OTA update feature</a><sup><sub>UPDATED w/v1.1.5</sub></sup><aclass="headerlink"href="#quick-and-easy-to-equip-the-ota-update-feature-updated-wv115"title="Permanent link">¶</a></h3>
<p><spanclass="lead">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.</span></p>
<p><spanclass="lead">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.</span></p>
@ -1068,14 +1068,14 @@ Easy implementing the Web interface constituting the WLAN for ESP8266/ESP32 WiFi
</ul>
<divclass="admonition info">
<pclass="admonition-title">About flash size on the module</p>
<p>The AutoConnect sketch size is relatively large. Large flash capacity is necessary. 512Kbyte (4Mbits) flash inclusion module such as ESP-01 is not recommended.</p>
<p>The AutoConnect Sketch size is relatively large. Large flash capacity is necessary. 512Kbyte (4Mbits) flash inclusion module such as ESP-01 is not recommended.</p>
<p>The current upstream at the 1.8 level or later is needed. Please install from the <ahref="https://www.arduino.cc/en/Main/Software">official Arduino IDE download page</a>. This step is not required if you already have a modern version.</p>
<p>AutoConnect targets sketches made on the assumption of <ahref="https://github.com/esp8266/Arduino">ESP8266 Community's Arduino core</a>. Stable 2.4.0 or higher required and the <ahref="https://github.com/esp8266/Arduino/releases/latest">latest release</a> is recommended.<br/>
<p>AutoConnect targets Sketches made on the assumption of <ahref="https://github.com/esp8266/Arduino">ESP8266 Community's Arduino core</a>. Stable 2.4.0 or higher required and the <ahref="https://github.com/esp8266/Arduino/releases/latest">latest release</a> is recommended.<br/>
Install third-party platform using the <em>Boards Manager</em> of Arduino IDE. Package URL is <ahref="http://arduino.esp8266.com/stable/package_esp8266com_index.json">http://arduino.esp8266.com/stable/package_esp8266com_index.json</a></p>
<p>Also, to apply AutoConnect to ESP32, the <ahref="https://github.com/espressif/arduino-esp32">arduino-esp32 core</a> provided by Espressif is needed. Stable 1.0.1 or required and the <ahref="https://github.com/espressif/arduino-esp32/releases/latest">latest release</a> is recommended.<br/>
@ -1089,7 +1089,7 @@ Install third-party platform using the <em>Boards Manager</em> of Arduino IDE. Y
To install the PageBuilder library into your Arduino IDE, you can use the <em>Library Manager</em>. Select the board of ESP8266 series in the Arduino IDE, open the library manager and search keyword '<strong>PageBuilder</strong>' with the topic '<strong>Communication</strong>', then you can see the <em>PageBuilder</em>. The latest version is required <strong>1.3.6</strong><strong>later</strong>.<supid="fnref:1"><aclass="footnote-ref"href="#fn:1">1</a></sup></p>
<p>By adding the <ahref="https://github.com/bblanchon/ArduinoJson">ArduinoJson</a> library, AutoConnect will be able to handle the <ahref="acintro.html"><strong>custom Web pages</strong></a> 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. <ahref="https://arduinojson.org/">ArduinoJson</a> is required to use this feature.<supid="fnref:2"><aclass="footnote-ref"href="#fn:2">2</a></sup> AutoConnect can work with ArduinoJson both <ahref="https://arduinojson.org/v5/doc/">version 5</a> and <ahref="https://arduinojson.org/v6/doc/">version 6</a>.</p>
<p>By adding the <ahref="https://github.com/bblanchon/ArduinoJson">ArduinoJson</a> library, AutoConnect will be able to handle the <ahref="acintro.html"><strong>custom Web pages</strong></a> 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. <ahref="https://arduinojson.org/">ArduinoJson</a> is required to use this feature.<supid="fnref:2"><aclass="footnote-ref"href="#fn:2">2</a></sup> AutoConnect can work with ArduinoJson both <ahref="https://arduinojson.org/v5/doc/">version 5</a> and <ahref="https://arduinojson.org/v6/doc/">version 6</a>.</p>
<h3id="install-the-autoconnect">Install the AutoConnect<aclass="headerlink"href="#install-the-autoconnect"title="Permanent link">¶</a></h3>
<p>Clone or download from the <ahref="https://github.com/Hieromon/AutoConnect">AutoConnect GitHub repository</a>.</p>
<p><imgsrc="images/gitrepo.png"width="640"/></p>
@ -1112,7 +1112,7 @@ To install the PageBuilder library into your Arduino IDE, you can use the <em>Li
<p>Since AutoConnect v1.1.3, PageBuilder v1.3.6 later is required. <aclass="footnote-backref"href="#fnref:1"title="Jump back to footnote 1 in the text">↩</a></p>
</li>
<liid="fn:2">
<p>Using the AutoConnect API natively allows you to sketch custom Web pages without JSON. <aclass="footnote-backref"href="#fnref:2"title="Jump back to footnote 2 in the text">↩</a></p>
<p>Using the AutoConnect API natively allows you to Sketch custom Web pages without JSON. <aclass="footnote-backref"href="#fnref:2"title="Jump back to footnote 2 in the text">↩</a></p>
<p>The following parameters of <ahref="apiconfig.html">AutoConnectConfig</a> affect the behavior and control a logic sequence of <ahref="api.html#begin">AutoConnect::begin</a> 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.</p>
<ul>
<li><ahref="apiconfig.html#immediatestart">immediateStart</a> : The captive portal start immediately, without the 1<sup>st</sup>-WiFi.begin.</li>
<li><ahref="apiconfig.html#autoreconnect">autoReconenct</a> : Attempt re-connect with past SSID by saved credential.</li>
<li><ahref="apiconfig.html#autoreconnect">autoReconnect</a> : Attempts re-connect with past SSID by saved credential.</li>
<li><ahref="apiconfig.html#autorise">autoRise</a> : Controls starting the captive portal.</li>
<li><ahref="apiconfig.html#immediatestart">immediateStart</a> : Starts the captive portal immediately, without the 1<sup>st</sup>-WiFi.begin.</li>
<li><ahref="apiconfig.html#portaltimeout">portalTimeout</a> : Time out limit for the portal.</li>
<li><ahref="apiconfig.html#retainportal">retainPortal</a> : Keep DNS server functioning for the captive portal.</li>
<p>It is assigned "<strong>/_ac</strong>" located on the <em>local IP address</em> 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.</p>
<p>It is assigned "<strong>/_ac</strong>" located on the <em>local IP address</em> 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.</p>
</div>
<h2id="right-on-top"><iclass="fa fa-bars"></i> Right on top<aclass="headerlink"href="#right-on-top"title="Permanent link">¶</a></h2>
<p>Currently, AutoConnect supports six menus. Undermost menu as "HOME" returns to the home path of its sketch.</p>
@ -984,22 +984,22 @@ Enter SSID and Passphrase and tap "<strong>Apply</strong>" to start a WiFi conne
<pclass="admonition-title">Saved credentials data structure has changed</p>
<p>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.
<p>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.
<p>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 <ahref="api.html#autoreset">AutoConnect API</a>.</p>
<p>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 <ahref="api.html#autoreset">AutoConnect API</a>.</p>
<p>After tapping the <strong>Disconnect</strong>, 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. </p>
<p>Resetting the ESP8266/ESP32 module will initiate a reboot. When the module restarting, the <em>esp8266ap</em> or <em>esp32ap</em> access point will disappear from the WLAN and the ESP8266/ESP32 module will begin to reconnect a previous access point with WIFI_STA mode.</p>
<pclass="admonition-title">Not every ESP8266 module will be rebooted normally</p>
<p>The Reset menu is using the <strong>ESP.reset()</strong> function for ESP8266. This is an almost hardware reset. In order to resume the sketch normally, the <ahref="https://github.com/esp8266/esp8266-wiki/wiki/Boot-Process#esp-boot-modes">state of GPIO0</a> is important. Since this depends on the circuit implementation for each module, not every module will be rebooted normally. See also <ahref="faq.html#hang-up-after-reset">FAQ</a>.</p>
<p>The Reset menu is using the <strong>ESP.reset()</strong> function for ESP8266. This is an almost hardware reset. In order to resume the Sketch normally, the <ahref="https://github.com/esp8266/esp8266-wiki/wiki/Boot-Process#esp-boot-modes">state of GPIO0</a> is important. Since this depends on the circuit implementation for each module, not every module will be rebooted normally. See also <ahref="faq.html#hang-up-after-reset">FAQ</a>.</p>
</div>
<h2id="custom-menu-items"><iclass="fa fa-bars"></i> Custom menu items<aclass="headerlink"href="#custom-menu-items"title="Permanent link">¶</a></h2>
<p>If the sketch has custom Web pages, the AutoConnect menu lines them up with the AutoConnect's items. Details for <ahref="acintro.html#custom-web-pages-in-autoconnectmenu">Custom Web pages in AutoConnect menu</a>.</p>
<p>If the Sketch has custom Web pages, the AutoConnect menu lines them up with the AutoConnect's items. Details for <ahref="acintro.html#custom-web-pages-in-autoconnectmenu">Custom Web pages in AutoConnect menu</a>.</p>
<p>If you specify <ahref="apiconfig.html#ota">AutoConnectConfig::ota</a> to import the OTA update feature into Sketch, an item will appear in the menu list as <strong>Update</strong>.</p>
<h2id="what-menus-can-be-made-using-autoconnect">What menus can be made using AutoConnect<aclass="headerlink"href="#what-menus-can-be-made-using-autoconnect"title="Permanent link">¶</a></h2>
<p>AutoConnect generates a menu dynamically depending on the instantiated <ahref="acintro.html#how-it-works">AutoConnectAux</a> at the sketch executing time. Usually, it is a collection of <ahref="acelements.html">AutoConnectElement</a>. In addition to this, you can generate a menu from only AutoConnectAux, without AutoConnectElements.<br>In other words, you can easily create a built-in menu featuring the WiFi connection facility embedding the legacy web pages.</p>
<p>AutoConnect generates a menu dynamically depending on the instantiated <ahref="acintro.html#how-it-works">AutoConnectAux</a> at the Sketch executing time. Usually, it is a collection of <ahref="acelements.html">AutoConnectElement</a>. In addition to this, you can generate a menu from only AutoConnectAux, without AutoConnectElements.<br>In other words, you can easily create a built-in menu featuring the WiFi connection facility embedding the legacy web pages.</p>
<h2id="basic-mechanism-of-menu-generation">Basic mechanism of menu generation<aclass="headerlink"href="#basic-mechanism-of-menu-generation"title="Permanent link">¶</a></h2>
<p>The sketch can display the <ahref="menu.html">AutoConnect menu</a> by following three patterns depending on AutoConnect-API usage.</p>
<p>the Sketch can display the <ahref="menu.html">AutoConnect menu</a> by following three patterns depending on AutoConnect-API usage.</p>
<dd>It is the most basic menu for only connecting WiFi. Sketch can automatically display this menu with the basic call sequence of the AutoConnect API which invokes <ahref="api.html#begin">AutoConnect::begin</a> and <ahref="api.html#handleclient">AutoConnect::handleClient</a>.</dd>
<dt><iclass="fa fa-desktop"></i> <strong>Extra menu with custom Web pages which is consisted by <ahref="acelements.html">AutoConnectElements</a></strong></dt>
<dd>It is an extended menu that appears when the sketch consists of the custom Web pages with <ahref="acintro.html#how-it-works">AutoConnectAux</a> and AutoConnectElements. Refer to section <ahref="acintro.html#custom-web-pages-in-autoconnect-menu"><em>Custom Web pages section</em></a>.</dd>
<dd>It is an extended menu that appears when the Sketch consists of the custom Web pages with <ahref="acintro.html#how-it-works">AutoConnectAux</a> and AutoConnectElements. Refer to section <ahref="acintro.html#custom-web-pages-in-autoconnect-menu"><em>Custom Web pages section</em></a>.</dd>
<dt><iclass="fa fa-desktop"></i> <strong>Extra menu which contains legacy pages</strong></dt>
<dd>It is for the legacy sketches using the <strong>on</strong> handler of ESP8266WebServer/WebServer(for ESP32) class natively and looks the same as the extra menu as above.</dd>
<spanstyle="color: #e6db74"> { "name": "content", "type": "ACText", "value": "In this page, place the custom web page handled by the sketch application." } ]</span>
<spanstyle="color: #e6db74"> { "name": "content", "type": "ACText", "value": "In this page, place the custom web page handled by the Sketch application." } ]</span>
@ -1004,7 +1004,7 @@ The AutoConnectOTA activates the ticker constantly regardless of the <a href="ap
<h3id="how-to-make-the-binary-sketch"><iclass="fa fa-wrench"></i> How to make the binary sketch<aclass="headerlink"href="#how-to-make-the-binary-sketch"title="Permanent link">¶</a></h3>
<p>Binary sketch files for updating can be retrieved using the Arduino IDE. Open the <strong>Sketch</strong> menu and select the <strong>Export compiled Binary</strong>, then starts compilation.</p>
<p>When the compilation is complete, a binary sketch will save with the extension <code>.bin</code> in the same folder as the sketch.</p>
<p>When the compilation is complete, a binary sketch will save with the extension <code>.bin</code> in the same folder as the Sketch.</p>
<h3id="ota-updates-wbrowser-without-using-autoconnectota"><iclass="fa fa-edit"></i> OTA updates w/browser without using AutoConnectOTA<aclass="headerlink"href="#ota-updates-wbrowser-without-using-autoconnectota"title="Permanent link">¶</a></h3>
<p>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:</p>
@ -1035,7 +1035,7 @@ To embed the ESP8266HTTPUpdateServer class with AutoConnect into your sketch, ba
<spanstyle="color: #e6db74"> { "name": "content", "type": "ACText", "value": "In this page, place the custom web page handled by the sketch application." } ]</span>
<spanstyle="color: #e6db74"> { "name": "content", "type": "ACText", "value": "In this page, place the custom web page handled by the Sketch application." } ]</span>
<h2id="updates-with-the-update-server">Updates with the update server<aclass="headerlink"href="#updates-with-the-update-server"title="Permanent link">¶</a></h2>
<p>Since the v1.0.0 release, AutoConnect provides new feature for updating sketch firmware of ESP8266 or ESP32 modules via OTA using the <ahref="apiupdate.html#autoconnectupdate">AutoConnectUpdate</a> class that is an implementation of the sketch binary update by the HTTP server mentioned in the <ahref="https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#http-server">OTA update</a> 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.</p>
<p>Since the v1.0.0 release, AutoConnect provides new feature for updating sketch firmware of ESP8266 or ESP32 modules via OTA using the <ahref="apiupdate.html#autoconnectupdate">AutoConnectUpdate</a> class that is an implementation of the Sketch binary update by the HTTP server mentioned in the <ahref="https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#http-server">OTA update</a> 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.</p>
<p>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.</p>
<p>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 <ahref="https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#server-request-handling">ESP8266 Arduino Core documentation</a>. There are various implementations of the update server that provide binary sketch files. For example, the ESP8266 Arduino Core documentation suggests an <ahref="https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#id5">advanced updater</a> 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.<br/>
<h2id="suppress-increase-in-memory-consumption">Suppress increase in memory consumption<aclass="headerlink"href="#suppress-increase-in-memory-consumption"title="Permanent link">¶</a></h2>
<p>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 <em>mqttRSSI</em> 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.</p>
<p>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.</p>
<p>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.</p>
<h2id="writing-the-custom-web-pages-without-json">Writing the custom Web pages without JSON<aclass="headerlink"href="#writing-the-custom-web-pages-without-json"title="Permanent link">¶</a></h2>
<p>To handle the custom Web pages without using JSON, follow the steps below.</p>
<ol>
@ -862,7 +862,7 @@
<divclass="admonition caution">
<pclass="admonition-title">JSON processing will be disabled</p>
<p>Commenting out the <strong>AUTOCONNECT_USE_JSON</strong> macro invalidates all functions related to JSON processing. If the sketch is using the JSON function, it will result in a compile error.</p>
<p>Commenting out the <strong>AUTOCONNECT_USE_JSON</strong> macro invalidates all functions related to JSON processing. If the Sketch is using the JSON function, it will result in a compile error.</p>
</div>
<divclass="admonition hint">
<pclass="admonition-title">Exclude the ArduinoJson by each compile-time</p>
@ -1041,7 +1041,7 @@
<hr/>
<ol>
<liid="fn:1">
<p>Detaching the ArduinoJson library reduces the sketch size by approximately 10K bytes. <aclass="footnote-backref"href="#fnref:1"title="Jump back to footnote 1 in the text">↩</a></p>
<p>Detaching the ArduinoJson library reduces the Sketch size by approximately 10K bytes. <aclass="footnote-backref"href="#fnref:1"title="Jump back to footnote 1 in the text">↩</a></p>
Hieromon Ikasamo
5 years ago
