An Arduino library for ESP8266 WLAN configuration at run time with web interface. [](https://travis-ci.org/Hieromon/AutoConnect)
An Arduino library for ESP8266/ESP32 WLAN configuration at run time with web interface. [](https://travis-ci.org/Hieromon/AutoConnect)
## Overview
To the dynamic configuration for joining to WLAN with SSID and PSK accordingly. It an Arduino library united with *ESP8266WebServer* class.
Easily implementing the Web interface constituting the WLAN for ESP8266 WiFi connection. With this library to make a sketch easily which connects from ESP8266 to the access point at runtime by the web interface without hard-coded SSID and password.
To the dynamic configuration for joining to WLAN with SSID and PSK accordingly. It an Arduino library united with *ESP8266WebServer* class of ESP8266 or *WebServer* class of ESP32.
Easily 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.
It is no needed hard-coding in advance the SSID and Password into the sketch to connect between ESP8266 and WLAN. You can input SSID & Password from a smartphone via the web interface at runtime.
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.
### Simple usage
@ -19,7 +19,7 @@ AutoConnect control screen will be displayed automatically for establishing new
### Store the established connection
The connection authentication data as credentials are saved automatically in EEPROM of ESP8266 and You can select the past SSID from the [AutoConnect menu](https://hieromon.github.io/AutoConnect/menu/index.html).
The connection authentication data as credentials are saved automatically in EEPROM of ESP8266/ESP32 and You can select the past SSID from the [AutoConnect menu](https://hieromon.github.io/AutoConnect/menu/index.html).
### Easy to embed in
@ -27,7 +27,7 @@ AutoConnect can be embedded easily into your sketch, just "**begin**" and "**han
### Lives with the your sketches
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.
The sketches which provide the web page using ESP8266WebServer/WebServer there is, AutoConnect will not disturb it. AutoConnect can use an already instantiated ESP8266WebServer object(ESP8266) or WebServer object(ESP32), or itself can assign it.
## Supported hardware
@ -42,6 +42,16 @@ Apply the [Arduino core](https://github.com/esp8266/Arduino) of the ESP8266 Comm
- SparkFun Thing
- SweetPea ESP-210
Alter the platform applying the [arduino-esp32](https://github.com/espressif/arduino-esp32) for the ESP32 modules.
- ESP32Dev Board
- SparkFun ESP32 Thing
- WEMOS LOLIN D32
- Ai-Thinker NodeMCU-32S
- Heltec WiFi Kit 32
- M5Stack
- And other ESP32 modules supported by the Additional Board Manager URLs of the Arduino-IDE.
## Simple usage
### The AutoConnect menu
@ -68,6 +78,10 @@ Full documentation is available on https://Hieromon.github.io/AutoConnect, some
## Change log
### [0.9.5] Aug. 27, 2018
- Supports the espressif arduino-esp32 core.
- Fixed that crash may occur if the number of stored credentials in the EEPROM is smaller than the number of found WiFi networks.
### [0.9.4] May 5, 2018.
- Automatically focus passphrase after selecting SSID with Configure New AP.
- Supports AutoConnectConfig::autoReconnect option, it will scan the WLAN when it can not connect to the default SSID, apply the applicable credentials if it is saved, and try reconnecting.
<p>Registering the "not found" handler is a different way than ESP8266WebServer. The <em>onNotFound</em> of ESP8266WebServer does not work with AutoConnect. AutoConnect overrides <em>ESP8266WebServer::onNotFound</em> to handle a captive portal. To register "not found" handler, use <ahref="../api/index.html#onnotfound"><em>AutoConnect::onNotFound</em></a>.</p>
<p>Registering the "not found" handler is a different way than ESP8266WebServer/WebServer. 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/index.html#onnotfound"><em>AutoConnect::onNotFound</em></a>.</p>
<p>When the captive portal is started, SoftAP starts and the STA is disconnected. The current SSID setting memorized in ESP8266 will be lost.<br/>
<p>When the captive portal is started, SoftAP starts and the STA is disconnected. The current SSID setting memorized in ESP8266 will be lost but then the reconnect behavior of ESP32 is somewhat different from this.<br/>
The <ahref="https://github.com/espressif/arduino-esp32/blob/a0f0bd930cfd2d607bf3d3288f46e2d265dd2e11/libraries/WiFi/src/WiFiSTA.h#L46">WiFiSTAClass::disconnect</a> function implemented in the arduino-esp32 has extended parameters than the ESP8266's arduino-core. The second parameter of WiFi.disconnect on the arduino-esp32 core that does not exist in the <ahref="https://github.com/esp8266/Arduino/blob/7e1bdb225da8ab337373517e6a86a99432921a86/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.cpp#L296">ESP8266WiFiSTAClass</a> has the effect of deleting the currently connected WiFi configuration and its default value is "false". On the ESP32 platform, even if WiFi.disconnect is executed, WiFi.begin() without the parameters in the next turn will try to connect to that AP. That is, automatic reconnection is implemented in arduino-esp32 already. Although this behavior appears seemingly competent, it is rather a disadvantage in scenes where you want to change the access point each time. When explicitly disconnecting WiFi from the Disconnect menu, AutoConnect will erase the AP connection settings saved by arduino-esp32 core. AutoConnect's automatic reconnection is a mechanism independent from the automatic reconnection of the arduino-esp32 core.<br/>
If the <ahref="../api/index.html#autoreconnect"><strong>autoReconnect</strong></a> option of the <ahref="../api/index.html#autoconnectconfig-api"><strong>AutoConnectConfig</strong></a> class is enabled, it automatically attempts to reconnect to the disconnected past access point. When the autoReconnect option is specified, AutoConnect will not start SoftAP immediately if the first WiFi.begin fails. It will scan WiFi signal and the same connection information as the detected BSSID is stored in EEPROM as AutoConnect's credentials, explicitly apply it with WiFi.begin and rerun.</p>
<pclass="admonition-title">In ESP32, the credentials for AutoConnect are not in NVS</p>
<p>The credentials used by AutoConnect are not saved in NVS on ESP32 module. ESP-IDF saves the WiFi connection configuration to NVS, but AutoConnect stores it on the eeprom partition. You can find the partition table for default as <ahref="https://github.com/espressif/arduino-esp32/blob/master/tools/partitions/default.csv">default.csv</a></p>
<p>The captive portal will only be activated if the first <em>WiFi::begin</em> fails. Sketch can detect with the <ahref="../api/index.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>
@ -823,10 +828,10 @@ If the <a href="../api/index.html#autoreconnect"><strong>autoReconnect</strong><
<blockquote>
<p>EEPROM library uses one sector of flash located <ahref="http://arduino-esp8266.readthedocs.io/en/latest/libraries.html?highlight=SPIFFS#eeprom">just after the SPIFFS</a>.</p>
</blockquote>
<p>So in the default state, the credential storage area used by AutoConnect conflicts with data owned by the user sketch. It will be destroyed together saved data in EEPROM by user sketch and AutoConnect each other. But you can move the storage area to avoid this.</p>
<p>Also, the placement of the EEPROM area of ESP32 is described in the <ahref="https://github.com/espressif/arduino-esp32/blob/master/tools/partitions/default.csv">partition table</a>. So in the default state, the credential storage area used by AutoConnect conflicts with data owned by the user sketch. It will be destroyed together saved data in EEPROM by user sketch and AutoConnect each other. But you can move the storage area to avoid this.</p>
<p>The <ahref="../api/index.html#boundaryoffset"><strong>boundaryOffset</strong></a> in <ahref="../api/index.html#autoconnectconfig-api"><strong>AutoConnectConfig</strong></a> specifies the start offset of the credentials storage area. The default value is 0.</p>
<h3id="refers-the-hosted-esp8266webserver"><iclass="fa fa-caret-right"></i> Refers the hosted ESP8266WebServer<aclass="headerlink"href="#refers-the-hosted-esp8266webserver"title="Permanent link">¶</a></h3>
<p>Constructing an AutoConnect object variable without parameters then creates and starts an ESP8266WebServer inside the AutoConnect. This object variable could be referred by <ahref="../api/index.html#host"><em>AutoConnect::host()</em></a> function to access ESP8266WebServer instance as like below.</p>
<h3id="refers-the-hosted-esp8266webserverwebserver"><iclass="fa fa-caret-right"></i> Refers the hosted ESP8266WebServer/WebServer<aclass="headerlink"href="#refers-the-hosted-esp8266webserverwebserver"title="Permanent link">¶</a></h3>
<p>Constructing an AutoConnect object variable without parameters then creates and starts an ESP8266WebServer/WebServer inside the AutoConnect. This object variable could be referred by <ahref="../api/index.html#host"><em>AutoConnect::host()</em></a> function to access ESP8266WebServer/WebServer instance as like below.</p>
@ -838,8 +843,8 @@ If the <a href="../api/index.html#autoreconnect"><strong>autoReconnect</strong><
<pclass="admonition-title">When host() is valid</p>
<p>The host() can be referred at after <em>AutoConnect::begin</em>.</p>
</div>
<h3id="usage-for-automatically-instantiated-esp8266webserver"><iclass="fa fa-caret-right"></i> Usage for automatically instantiated ESP8266WebServer<aclass="headerlink"href="#usage-for-automatically-instantiated-esp8266webserver"title="Permanent link">¶</a></h3>
<p>The sketch can handle URL requests using ESP8266WebServer that AutoConnect started internally. ESP8266WebServer instantiated dynamically by AutoConnect can be referred to by <ahref="../api/index.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 reference of its return value.</p>
<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/index.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>
@ -875,12 +880,12 @@ If the <a href="../api/index.html#autoreconnect"><strong>autoReconnect</strong><
</pre></div>
<divclass="admonition note">
<pclass="admonition-title">ESP8266WebServer function should be called after AutoConnect::begin</p>
<p>The sketch cannot refer to an instance of ESP8266WebServer until AutoConnect::begin completes successfully.</p>
<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>
</div>
<divclass="admonition warning">
<pclass="admonition-title">Do not use with ESP8266WebServer::begin</p>
<p>ESP8266WebServer is already running inside the AutoConnect.</p>
<pclass="admonition-title">Do not use with ESP8266WebServer::begin or WebServer::begin</p>
<p>ESP8266WebServer/WebServer is already running inside the AutoConnect.</p>
</div>
<h3id="use-with-the-pagebuilder-library"><iclass="fa fa-caret-right"></i> Use with the <ahref="https://github.com/Hieromon/PageBuilder">PageBuilder</a> library<aclass="headerlink"href="#use-with-the-pagebuilder-library"title="Permanent link">¶</a></h3>
<p>In ordinary, the URL handler will respond the request by sending some HTML. <ahref="https://github.com/Hieromon/PageBuilder">PageBuilder</a> library is HTML assembly aid. it can handle predefined HTML as like a template and simplify an HTML string assemble logic, and also the generated HTML send automatically.</p>
@ -917,8 +922,8 @@ If the <a href="../api/index.html#autoreconnect"><strong>autoReconnect</strong><
</pre></div>
<h3id="static-ip-assignment-1"><iclass="fa fa-caret-right"></i> Static IP assignment <supid="fnref:1"><aclass="footnote-ref"href="#fn:1"rel="footnote">1</a></sup><aclass="headerlink"href="#static-ip-assignment-1"title="Permanent link">¶</a></h3>
<p>It is also possible to assign static IP Address to ESP8266 in STA mode. By default DHCP is enabled and it becomes the IP address assigned by the DHCP server with <em>WiFi.begin</em>.</p>
<p>To assign a static IP to ESP8266 with WIFI_MODE_STA, the following parameters are required:</p>
<p>It is also possible to assign static IP Address to ESP8266/ESP32 in STA mode. By default DHCP is enabled and it becomes the IP address assigned by the DHCP server with <em>WiFi.begin</em>.</p>
<p>To assign a static IP to ESP8266/ESP32 with WIFI_MODE_STA, the following parameters are required:</p>
<p>AutoConnect default constructor. This entry internally allocates the ESP8266WebServer and is activated internally.</p>
<p>AutoConnect default constructor. This entry internally allocates the ESP8266WebServer for ESP8266 or WebServer for ESP32 and is activated internally.</p>
<p>Run the AutoConnect site using the externally ensured ESP8266WebServer.</p>
<p>The <ahref="index.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. If ESP8266WebServer is assigned internally by AutoConnect, the sketch can obtain that reference with the <ahref="../api.me#host"><strong>host</strong></a> function.
<p>Run the AutoConnect site using the externally ensured ESP8266WebServer for ESP8266 or WebServer for ESP32.</p>
<p>The <ahref="index.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.me#host"><strong>host</strong></a> function.
<dlclass="apidl">
<dt><strong>Parameters</strong></dt>
<dd><spanclass="apidef">webServer</span>A reference of ESP8266WebServer instance.</dd>
<dd><spanclass="apidef">webServer</span>A reference of ESP8266WebServer or WebServer instance.</dd>
</dl></p>
<h3id="public-member-functions"><iclass="fa fa-code"></i> Public member functions<aclass="headerlink"href="#public-member-functions"title="Permanent link">¶</a></h3>
AutoConnect first invokes <em>WiFi.begin</em>. If the case of SSID and Password missing, its <em>WiFi.begin</em> has no SSID and Password. The WiFi mode at this time is WIFI_STA. Then ESP8266WebServer will be started immediately after the first <em>WiFi.beign</em> regardless of the result.</p>
<p>The captive portal will not be started if the connection has been established with first <em>WiFi.begin</em>. If the connection cannot establish, switch to WIFI_AP_STA mode and activate SoftAP. Then DNS server starts.
<p>Starts establishing the WiFi connection. The WiFi mode at this time is WIFI_STA.<br/>
AutoConnect first invokes <em>WiFi.begin</em>. If the <em>ssid</em> and the <em>passphrase</em> are missing, its <em>WiFi.begin</em> has no SSID and Password. Regardless of the result, ESP8266WebServer/WebServer will start immediately after the first <em>WiFi.begin</em>.<br/>
The captive portal will not be started if the connection has been established with first <em>WiFi.begin</em>. If the connection cannot establish, switch to WIFI_AP_STA mode and activate SoftAP. Then DNS server starts.
<dlclass="apidl">
<dt><strong>Parameters</strong></dt>
<dd><spanclass="apidef">ssid</span>SSID to be connected.</dd>
@ -1181,7 +1190,7 @@ AutoConnect first invokes <em>WiFi.begin</em>. If the case of SSID and Password
<dlclass="apidl">
<dt><strong>Parameters</strong></dt>
<dd><spanclass="apidef">config</span>Reference to <ahref="index.html#autoconnectconfig"><strong>AutoConnectConfig</strong></a> containing SoftAP's parameters and static IP parameters.</dd>
<dd><spanclass="apidef">ap</span>SSID for SoftAP. The default value is <strong>esp8266ap</strong>.</dd>
<dd><spanclass="apidef">ap</span>SSID for SoftAP. The default value is <strong>esp8266ap</strong> for ESP8266, <strong>esp32ap</strong> for ESP32.</dd>
<dd><spanclass="apidef">password</span>Password for SodtAP. The default value is <strong>12345678</strong>.</dd>
<p>Process the AutoConnect menu interface. It will be processed the client request too contained in the user sketch handler by calling from inside of AutoConnect to the hosted <em>ESP8266WebServer::handleClient</em>.</p>
<p>Process the AutoConnect menu interface. The handleClient() function of the ESP8266WebServer/WebServer hosted by AutoConnect is also called from within AutoConnect, and the client request handlers contained in the user sketch are also handled.</p>
@ -1208,7 +1217,7 @@ AutoConnect first invokes <em>WiFi.begin</em>. If the case of SSID and Password
<p>Handling for the AutoConnect menu request.</p>
<divclass="admonition warning">
<pclass="admonition-title">About used in combination with handleClient</p>
<p>The handleRequest function is not supposed to use with AutoConnect::handleClient. It should be used with ESP8266::handleClient.</p>
<p>The handleRequest function is not supposed to use with AutoConnect::handleClient. It should be used with ESP8266WebServer::handleClient or WebServer::handleClient.</p>
Register the handler function for undefined URL request detected.
<dlclass="apidl">
@ -1273,7 +1300,7 @@ Register the handler function for undefined URL request detected.
</pre></div>
<dlclass="apidl">
<dt><strong>Parameters</strong></dt>
<dd><spanclass="apidef">ap</span>SSID for SoftAP. The length should be up to 31. The default value is <strong>esp8266ap</strong>.</dd>
<dd><spanclass="apidef">ap</span>SSID for SoftAP. The length should be up to 31. The default value is <strong>esp8266ap</strong> for ESP8266, <strong>esp32ap</strong> for ESP32.</dd>
<dd><spanclass="apidef">password</span>Password for SodtAP. The length should be from 8 to up to 63. The default value is <strong>12345678</strong>.</dd>
</dl></p>
<h3id="public-member-variables"><iclass="fa fa-code"></i> Public member variables<aclass="headerlink"href="#public-member-variables"title="Permanent link">¶</a></h3>
@ -1290,7 +1317,7 @@ Register the handler function for undefined URL request detected.
<dd><spanclass="apidef"style="width:230px;">IPAddress</span>The default value is <strong>192.168.244.1</strong></dd>
<p>Automatically reconnect to past established access point (BSSID) when the current configured SSID in ESP8266 could not be connected. By enabling this option, <em>AutoConnect::begin()</em> function will attempt to reconnect to a known access point using credentials stored in the EEPROM, even if the connection failed by current SSID.<br/>
<p>Automatically will try to reconnect with the past established access point (BSSID) when the current configured SSID in ESP8266/ESP32 could not be connected. By enabling this option, <em>AutoConnect::begin()</em> function will attempt to reconnect to a known access point using credentials stored in the EEPROM, even if the connection failed by current SSID.<br/>
If the connection fails, starts the captive portal in SoftAP + STA mode.<br/>
<ahref="#4-alternate-esp8266webserverbegin-and-webserverbegin"title="4. Alternate ESP8266WebServer::begin() and WebServer::begin()"class="md-nav__link">
4. Alternate ESP8266WebServer::begin() and WebServer::begin()
</a>
</li>
@ -412,15 +412,15 @@
</li>
<liclass="md-nav__item">
<ahref="#6-use-esp8266webserveron-to-handle-url"title="6. Use ESP8266WebServer::on to handle URL"class="md-nav__link">
6. Use ESP8266WebServer::on to handle URL
<ahref="#6-use-esp8266webserveron-and-webserveron-to-handle-url"title="6. Use ESP8266WebServer::on and WebServer::on to handle URL"class="md-nav__link">
6. Use ESP8266WebServer::on and WebServer::on to handle URL
</a>
</li>
<liclass="md-nav__item">
<ahref="#7-use-either-esp8266webserverhandleclient-or-autoconnecthandleclient"title="7. Use either ESP8266WebServer::handleClient() or AutoConnect::handleClient()"class="md-nav__link">
7. Use either ESP8266WebServer::handleClient() or AutoConnect::handleClient()
<ahref="#7-use-either-esp8266webserverhandleclientwebserverhandleclient-or-autoconnecthandleclient"title="7. Use either ESP8266WebServer::handleClient()/WebServer::handleClient() or AutoConnect::handleClient()"class="md-nav__link">
7. Use either ESP8266WebServer::handleClient()/WebServer::handleClient() or AutoConnect::handleClient()
</a>
</li>
@ -431,8 +431,8 @@
</li>
<liclass="md-nav__item">
<ahref="#esp8266webserver-hosted-or-parasitic"title=" ESP8266WebServer hosted or parasitic"class="md-nav__link">
ESP8266WebServer hosted or parasitic
<ahref="#esp8266webserverwebserver-hosted-or-parasitic"title=" ESP8266WebServer/WebServer hosted or parasitic"class="md-nav__link">
<ahref="#4-alternate-esp8266webserverbegin-and-webserverbegin"title="4. Alternate ESP8266WebServer::begin() and WebServer::begin()"class="md-nav__link">
4. Alternate ESP8266WebServer::begin() and WebServer::begin()
</a>
</li>
@ -615,15 +615,15 @@
</li>
<liclass="md-nav__item">
<ahref="#6-use-esp8266webserveron-to-handle-url"title="6. Use ESP8266WebServer::on to handle URL"class="md-nav__link">
6. Use ESP8266WebServer::on to handle URL
<ahref="#6-use-esp8266webserveron-and-webserveron-to-handle-url"title="6. Use ESP8266WebServer::on and WebServer::on to handle URL"class="md-nav__link">
6. Use ESP8266WebServer::on and WebServer::on to handle URL
</a>
</li>
<liclass="md-nav__item">
<ahref="#7-use-either-esp8266webserverhandleclient-or-autoconnecthandleclient"title="7. Use either ESP8266WebServer::handleClient() or AutoConnect::handleClient()"class="md-nav__link">
7. Use either ESP8266WebServer::handleClient() or AutoConnect::handleClient()
<ahref="#7-use-either-esp8266webserverhandleclientwebserverhandleclient-or-autoconnecthandleclient"title="7. Use either ESP8266WebServer::handleClient()/WebServer::handleClient() or AutoConnect::handleClient()"class="md-nav__link">
7. Use either ESP8266WebServer::handleClient()/WebServer::handleClient() or AutoConnect::handleClient()
</a>
</li>
@ -634,8 +634,8 @@
</li>
<liclass="md-nav__item">
<ahref="#esp8266webserver-hosted-or-parasitic"title=" ESP8266WebServer hosted or parasitic"class="md-nav__link">
ESP8266WebServer hosted or parasitic
<ahref="#esp8266webserverwebserver-hosted-or-parasitic"title=" ESP8266WebServer/WebServer hosted or parasitic"class="md-nav__link">
<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.</p>
<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 <codeclass="codehilite">ESP8266WebServer</code> with <codeclass="codehilite">WebServer</code> and <codeclass="codehilite">ESP8266WiFi.h</code> with <codeclass="codehilite">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>
@ -682,22 +682,23 @@
<h4id="1-a-typical-logic-sequence">1. A typical logic sequence<aclass="headerlink"href="#1-a-typical-logic-sequence"title="Permanent link">¶</a></h4>
<divclass="admonition note">
<ol>
<li><strong>Include headers,</strong><codeclass="codehilite">ESP8266WebServer.h</code> and <codeclass="codehilite">AutoConnect.h</code></li>
<li><strong>Implements the URL handler with the <em>function()</em>.</strong></li>
<li><strong>Include headers,</strong><codeclass="codehilite">ESP8266WebServer.h</code>/<codeclass="codehilite">WebServer.h</code> and <codeclass="codehilite">AutoConnect.h</code></li>
<li><strong>Declare an ESP8266WebServer variable for ESP8266 or a WebServer variable for ESP32.</strong></li>
<li><strong>Declare an AutoConnect variable.</strong></li>
<li><strong>Implement the URL handlers provided for the </strong><codeclass="codehilite">on</code><strong> method of ESP8266WebServer/WebServer with the <em>function()</em>.</strong></li>
<li><strong>setup()</strong><br/>
5.1 <strong>Sets URL handler <em>function()</em> to ESP8266WebServer by</strong><codeclass="codehilite">ESP8266WebServer::on</code><strong>.</strong><br/>
5.1 <strong>Sets URL handler the <em>function()</em> to ESP8266WebServer/WebServer by</strong><codeclass="codehilite">ESP8266WebServer::on</code><strong>/</strong><codeclass="codehilite">WebServer::on</code><strong>.</strong><br/>
6.1 <strong>Invokes </strong><codeclass="codehilite">AutoConnect::handleClient()</code><strong>, or invokes </strong><codeclass="codehilite">ESP8266WebServer::handleClient()</code><strong> then </strong><codeclass="codehilite">AutoConnect::handleRequest()</code><strong>.</strong><br/>
6.2 <strong>Do the process for actual sketch.</strong></li>
6.1 <strong>Do the process for actual sketch.</strong><br/>
6.2 <strong>Invokes </strong><codeclass="codehilite">AutoConnect::handleClient()</code><strong>, or invokes </strong><codeclass="codehilite">ESP8266WebServer::handleClient()</code><strong>/</strong><codeclass="codehilite">WebServer::handleClient</code><strong> then </strong><codeclass="codehilite">AutoConnect::handleRequest()</code><strong>.</strong></li>
<p><ahref="#esp8266webserver-hosted-or-parasitic">Two options</a> are available for <ahref="../api/index.html#constructors">AutoConnect constructor</a>.</p>
<p><divclass="codehilite"><pre><span></span><spanclass="n">AutoConnect</span><spanclass="nf">VARIABLE</span><spanclass="p">(</span><spanclass="o">&</span><spanclass="n">ESP8266WebServer</span><spanclass="p">);</span><spanclass="c1">// For ESP8266</span>
<spanclass="n">AutoConnect</span><spanclass="nf">VARIABLE</span><spanclass="p">(</span><spanclass="o">&</span><spanclass="n">WebServer</span><spanclass="p">);</span><spanclass="c1">// For ESP32</span>
<p><strong>The parameter with an ESP8266WebServer variable:</strong> An ESP8266WebServer object variable must be declared. AutoConnect uses its variable to handles the <ahref="../menu/index.html">AutoConnect menu</a>.</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/index.html">AutoConnect menu</a>.</p>
</li>
<li>
<p><strong>With no parameter:</strong> The sketch does not declare ESP8266WebServer object. In this case, AutoConnect allocates an instance of the ESP8266WebServer internally. The logic sequence of the sketch is somewhat different as the above. To register a URL handler function by <em>ESP8266WebServer::on</em> should be performed after <ahref="../api/index.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/index.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><ahref="../api/index.html#begin"><em>AutoConnect::begin</em></a> executes <em>ESP8266WebServer::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> with the sketch.</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/index.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. When the WLAN connection establishes, then stops DNS server.</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>
</div>
<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.me#begin"><em>AutoConnect::begin</em></a>. ESP8266 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-to-handle-url">6. Use ESP8266WebServer::on to handle URL<aclass="headerlink"href="#6-use-esp8266webserveron-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>" function is the same as when using ESP8266WebServer natively.</p>
<h4id="7-use-either-esp8266webserverhandleclient-or-autoconnecthandleclient">7. Use either ESP8266WebServer::handleClient() or AutoConnect::handleClient()<aclass="headerlink"href="#7-use-either-esp8266webserverhandleclient-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 has limitations. Refer to the below section for details. </p>
<h3id="esp8266webserver-hosted-or-parasitic"><iclass="fa fa-caret-right"></i> ESP8266WebServer hosted or parasitic<aclass="headerlink"href="#esp8266webserver-hosted-or-parasitic"title="Permanent link">¶</a></h3>
<p>The interoperable process with an ESP8266WebServer depends on the parameters of the <ahref="../api/index.html#constructors">AutoConnect constructor</a>.</p>
<p>SSID and Password can also specify by <ahref="../api.me#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>
<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>
<p>The interoperable process with an ESP8266WebServer/WebServer depends on the parameters of the <ahref="../api/index.html#constructors">AutoConnect constructor</a>.</p>
<table>
<thead>
<tr>
<th>Declaration parameter for the constructor</th>
<th>Use ESP8266WebServer::handleClient only</th>
<th>Use ESP8266WebServer::handleClient or WebServer::handleClient only</th>
<td>AutoConnect menu not available.<br>To use AutoConnect menu, need <ahref="../api/index.html#handlerequest">AutoConnect::handleRequest()</a>.<br>also to use ESP8266WebServer natively, need <ahref="../api/index.html#host">AutoConnect::host()</a>.</td>
<td>AutoConnect menu available.<br>To use ESP8266WebServer natively, need <ahref="../api/index.html#host">AutoConnect::host()</a>.</td>
<td>AutoConnect menu not available.<br>To use AutoConnect menu, need <ahref="../api/index.html#handlerequest">AutoConnect::handleRequest()</a>.<br>also to use ESP8266WebServer/WebServer natively, need <ahref="../api/index.html#host">AutoConnect::host()</a>.</td>
<td>AutoConnect menu available.<br>To use ESP8266WebServer/WebServer natively, need <ahref="../api/index.html#host">AutoConnect::host()</a>.</td>
</tr>
<tr>
<td><ahref="../api/index.html#withparameter">Reference to ESP8266WebServer</a></td>
<td><ahref="../api/index.html#withparameter">Reference to ESP8266WebServer/WebServer</a></td>
<td>AutoConnect menu not available.<br>To use AutoConnect menu, need <ahref="../api/index.html#handlerequest">AutoConnect::handleRequest()</a>.</td>
<td>AutoConnect menu available.</td>
</tr>
@ -750,22 +751,22 @@ or</p>
</table>
<ul>
<li>
<p><strong>By declaration for the AutoConnect variable with no parameter</strong>: The ESP8266WebServer instance is hosted by AutoConnect automatically then the sketches use <ahref="../api/index.html#host"><em>AutoConnect::host</em></a> as API to get it after <ahref="../api/index.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/index.html#host"><em>AutoConnect::host</em></a> as API to get it after <ahref="../api/index.html#begin"><em>AutoConnect::begin</em></a> performed.</p>
</li>
<li>
<p><strong>By declaration for the AutoConnect variable with the reference of ESP8266WebServer</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()</strong>: AutoConnect menu can be dispatched but not works normally. It is necessary to call <ahref="../api/index.html#void-handlerequest"><em>AutoConnect::handleRequest</em></a> after <em>ESP8255WebServer::handleClient</em> invoking.</p>
<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/index.html#void-handlerequest"><em>AutoConnect::handleRequest</em></a> after <em>ESP8255WebServer::handleClient</em>/<em>WebServer::handleClient</em> invoking.</p>
</li>
<li>
<p><strong>In use <ahref="../api/index.html#void-handleclient">AutoConnect::handleClient()</a></strong>: The handleClient() process and the AutoConnect menu is available without calling <em>ESP8266WebServer::handleClient</em>.</p>
</li>
</ul>
<divclass="admonition info">
<pclass="admonition-title">Why AutoConnect::handleRequest is needed when using ESP8266::handleClient</p>
<p>The AutoConnect menu function may affect WiFi connection state. It follows that the menu process must execute outside <em>ESP8266WebServer::handleClient</em>.<br/>
<ahref="../api/index.html#void-handleclient"><em>AutoConnect::handleClient</em></a> is equivalent <em>ESP8266WebServer::handleClient</em> included <ahref="../api/index.html#void-handlerequest"><em>AutoConnect::handleRequest</em></a>.</p>
<pclass="admonition-title">Why AutoConnect::handleRequest is needed when using ESP8266WebServer::handleClient/WebServer::handleClient</p>
<p>The AutoConnect menu function may affect WiFi connection state. It follows that the menu process must execute outside <em>ESP8266WebServer::handleClient</em> and <em>WebServer::handleClient</em>.<br/>
<ahref="../api/index.html#void-handleclient"><em>AutoConnect::handleClient</em></a> is equivalent <em>ESP8266WebServer::handleClient</em>and <em>WEbServer::handleClient</em>included <ahref="../api/index.html#void-handlerequest"><em>AutoConnect::handleRequest</em></a>.</p>
<li>Fixed that crash may occur if the number of stored credentials in the EEPROM is smaller than the number of found WiFi networks.</li>
</ul>
<h4id="094-may-5-2018">[0.9.4] May 5, 2018.<aclass="headerlink"href="#094-may-5-2018"title="Permanent link">¶</a></h4>
<ul>
<li>Automatically focus passphrase after selecting SSID with Configure New AP.</li>
<li>Supports AutoConnectConfig::autoReconnect option, it will scan the WLAN when it can not connect to the default SSID, apply the applicable credentials if it is saved, and try reconnecting.</li>
<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 as the Web server. It has advantages for something WiFi client as well. For example, AutoConnect is also effective 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 effective 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>
<h2id="lets-do-the-most-simple-sketch">Let's do the most simple sketch<aclass="headerlink"href="#lets-do-the-most-simple-sketch"title="Permanent link">¶</a></h2>
<p>Open the Arduino IDE, write the following sketch and upload it. The feature of this sketch is that the SSID and Password are not coded.</p>
<divclass="codehilite"><pre><span></span><spanclass="cp">#include</span><spanclass="cpf"><ESP8266WiFi.h> // Replace with WiFi.h for ESP32</span><spanclass="cp"></span>
<spanclass="cp">#include</span><spanclass="cpf"><ESP8266WebServer.h> // Replace with WebServer.h for ESP32</span><spanclass="cp"></span>
<p>The above code can be applied to ESP8266. To apply to ESP32, replace <codeclass="codehilite">ESP8266WebServer</code> class with <codeclass="codehilite">WebServer</code> and include <codeclass="codehilite">WiFi.h</code> and <codeclass="codehilite">WebServer.h</code> of arduino-esp32 appropriately.</p>
</div>
<h3id="run-at-first"><iclass="fa fa-play-circle"></i> Run at first<aclass="headerlink"href="#run-at-first"title="Permanent link">¶</a></h3>
<p>After about 30 seconds, if the ESP8266 cannot connect to nearby Wi-Fi spot, you pull out your smartphone and open <em>Wi-Fi settings</em> from the <em>Settings</em> Apps. You can see the <strong>esp8266ap</strong> in the list of <em>"CHOOSE A NETWORK..."</em>. Then tap the esp8266ap and enter password <strong>12345678</strong>, a something screen pops up automatically as shown below.</p>
<p>After about 30 seconds, if the ESP8266 cannot connect to nearby Wi-Fi spot, you pull out your smartphone and open <em>Wi-Fi settings</em> from the <em>Settings</em> Apps. You can see the <strong>esp8266ap</strong><supid="fnref:1"><aclass="footnote-ref"href="#fn:1"rel="footnote">1</a></sup>in the list of <em>"CHOOSE A NETWORK..."</em>. Then tap the esp8266ap and enter password <strong>12345678</strong>, a something screen pops up automatically as shown below.</p>
<p>This is the AutoConnect statistics screen. This screen displays the current status of the established connection, WiFi mode, IP address, free memory size, and etc. Also, the <strong>hamburger icon</strong> is the control menu of AutoConnect seems at the upper right. By tap the hamburger icon, the control menu appears as the below.</p>
<h3id="join-to-the-new-access-point"><iclass="fa fa-cog"></i> Join to the new access point<aclass="headerlink"href="#join-to-the-new-access-point"title="Permanent link">¶</a></h3>
@ -592,6 +595,15 @@ Or, "<strong>RESET</strong>" can be selected. The ESP8266 resets and reboots. Af
Gifffer();
}
</script>
<divclass="footnote">
<hr/>
<ol>
<liid="fn:1">
<p>When applied to ESP32, SSID will appear as <strong>esp32ap</strong>. <aclass="footnote-backref"href="#fnref:1"rev="footnote"title="Jump back to footnote 1 in the text">↩</a></p>
<p>To the dynamic configuration for joining to WLAN with SSID and PSK accordingly. It an Arduino library united with <em>ESP8266WebServer</em> class.
Easy implementing the Web interface constituting the WLAN for ESP8266 WiFi connection. With this library to make a sketch easily which connects from ESP8266 to the access point at runtime by the web interface without hard-coded SSID and password.</p>
<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>
<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 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/index.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 EEPROM of ESP8266 and You can select the past SSID from the <ahref="menu/index.html">AutoConnect menu</a>.</span></p>
<p><spanclass="lead">The connection authentication data as credentials are saved automatically in EEPROM of ESP8266/ESP32 and You can select the past SSID from the <ahref="menu/index.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-the-your-sketches"><iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Lives with the your sketches<aclass="headerlink"href="#lives-with-the-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.</span></p>
<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.<br>This efficacy can also be applied to ESP32. The corresponding class for ESP32 will be the WebServer.</span></p>
<liclass="task-list-item"><inputtype="checkbox"disabledchecked/> And other ESP8266/ESP32 modules supported by the Additional Board Manager URLs of the Arduino-IDE.</li>
</ul>
<divclass="admonition info">
<pclass="admonition-title">About flash size on the module</p>
@ -694,15 +701,13 @@ Easy implementing the Web interface constituting the WLAN for ESP8266 WiFi conne
<p>AutoConnect targets sketches made on the assumption of <ahref="https://github.com/esp8266/Arduino">ESP8266 Community's Arduino core</a>. 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. The <ahref="https://github.com/espressif/arduino-esp32/releases/latest">latest release</a> is recommended.<br/>
Install third-party platform using the <em>Boards Manager</em> of Arduino IDE. You can add multiple URLs into <em>Additional Board Manager URLs</em> field, separating them with commas. Package URL is <ahref="https://dl.espressif.com/dl/package_esp32_index.json">https://dl.espressif.com/dl/package_esp32_index.json</a></p>
<p>The <ahref="https://github.com/Hieromon/PageBuilder">PageBuilder</a> library to build HTML for ESP8266WebServer is needed.<br/>
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 or 1.0.0 later is required.</p>
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 1.1.0 later for ESP32.</p>
<p><imgsrc="./images/lm.png"width="640"/></p>
<divclass="admonition warning">
<pclass="admonition-title">Library Manager of Arduino IDE</p>
<p>The version of PageBuilder may not have been updated yet. If the library manager shows only version 0.93.0, please install the latest PageBuilder version than 1.0.0 from the Github repository. <ahref="https://github.com/Hieromon/PageBuilder/releases/latest">The PageBuilder release</a> of the Github repository is the latest version. The <ahref="https://platformio.org/lib/show/2010/PageBuilder">PlatformIO library</a> has the latest version of 1.0.0.<br/>
In 0.93.0, the PageBuilder class has a compile error about without the 'cancel' method.</p>
</div>
<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>The AutoConnect menu is developed using the <ahref="https://github.com/balzss/luxbar">LuxBar</a> which is licensed under the MIT License. See the <ahref="../license/index.html">License</a>.</p>
</div>
<h2id="where-the-from"><iclass="fa fa-external-link"></i> Where the from<aclass="headerlink"href="#where-the-from"title="Permanent link">¶</a></h2>
<p>The AutoConnect menu appears when you access the <strong>AutoConnect root path</strong>. It is assigned "<strong>/_ac</strong>" located on ESP8266<em>local IP address</em> by default. This location can be changed in the sketch. The following screen will appear at access to <codeclass="codehilite">http://{localIP}/_ac</code> as the root path. This is the statistics of the current WiFi connection. You can access the menu from the here, to invoke it tap <iclass="fa fa-bars"></i> at right on top. (e.g. <codeclass="codehilite">http://192.168.244.1/_ac</code> for SoftAP mode.)</p>
<p>The AutoConnect menu appears when you access the <strong>AutoConnect root path</strong>. It is assigned "<strong>/_ac</strong>" located on the<em>local IP address</em> of ESP8266/ESP32 module by default. This location can be changed in the sketch. The following screen will appear at access to <codeclass="codehilite">http://{localIP}/_ac</code> as the root path. This is the statistics of the current WiFi connection. You can access the menu from the here, to invoke it tap <iclass="fa fa-bars"></i> at right on top. (e.g. <codeclass="codehilite">http://192.168.244.1/_ac</code> for SoftAP mode.)</p>
<h2id="configure-new-ap"><iclass="fa fa-bars"></i> Configure new AP<aclass="headerlink"href="#configure-new-ap"title="Permanent link">¶</a></h2>
<p>Scan all available access point and display it. Strength and security of the detected AP are marked. The <iclass="fa fa-lock"></i> is indicated for the SSID that needs a security key. "<strong>Hidden:</strong>" means the number of hidden SSIDs discovered.<br/>
Enter SSID and Passphrase and tap "<strong>apply</strong>" to starts a connection. </p>
<p>Scan all available access point in the vicinity and display it. Strength and security of the detected AP are marked. The <iclass="fa fa-lock"></i> is indicated for the SSID that needs a security key. "<strong>Hidden:</strong>" means the number of hidden SSIDs discovered.<br/>
Enter SSID and Passphrase and tap "<strong>apply</strong>" to starts WiFi connection. </p>
<h2id="open-ssids"><iclass="fa fa-bars"></i> Open SSIDs<aclass="headerlink"href="#open-ssids"title="Permanent link">¶</a></h2>
<p>Once it was established connection, its SSID and Password will be stored to the EEPROM of ESP8266 automatically. The <strong>Open SSIDs</strong> menu reads the saved SSID credentials from the EEPROM. The stored credential data are listed by the SSID as shown below. Its label is a clickable button. Tap the SSID button, starts connection it.</p>
<p>Once it was established WiFi connection, its SSID and password will be saved in EEPROM of ESP8266/ESP32 automatically. The <strong>Open SSIDs</strong> menu reads the saved SSID credentials from the EEPROM. The stored credential data are listed by the SSID as shown below. Its label is a clickable button. Tap the SSID button, starts WiFi connection it.</p>
<p>Disconnect ESP8266 from the current connection. It can also reset the ESP8266 automatically after disconnection by instructing with using <ahref="../api/index.html#autoreset">API</a> in the sketch.</p>
<p>Disconnect ESP8266/ESP32 from the current connection. It can also reset the ESP8266/ESP32 automatically after disconnection by instructing with using <ahref="../api/index.html#autoreset">API</a> in the sketch.</p>
<p>After tapping "Disconnect", you will not be able to reach the AutoConnect menu. Once disconnected, you will need to set the SSID again for connecting the WLAN. </p>
<p>Reset the ESP8266, it will start rebooting. After rebooting complete, the ESP8266 begins establishing the previous connection with WIFI_STA mode, and <em>esp8266ap</em> of an access point will disappear from WLAN.</p>
<p>Reset the ESP8266/ESP32 module, it will start rebooting. After rebooting complete, the ESP8266/ESP32 module begins establishing the previous connection with WIFI_STA mode, and <em>esp8266ap</em> or <em>esp32ap</em> of an access point will disappear from WLAN.</p>
<pclass="admonition-title">Not every module will be rebooted normally</p>
<p>The Reset menu is using the <strong>ESP.reset()</strong> function. 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/index.html#hang-up-after-reset">FAQ</a>.</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/index.html#hang-up-after-reset">FAQ</a>.</p>
sentence=ESP8266 WLAN configuration at runtime with web interface.
sentence=ESP8266/ESP32 WLAN configuration at runtime with web interface.
paragraph=A library for easy implementing the Web interface constituting the WLAN for ESP8266 WiFi connection. With this library to make a sketch which connects from ESP8266 to the access point at runtime by the web interface without hardcoded SSID and password.
Registering the "not found" handler is a different way than ESP8266WebServer. The *onNotFound* of ESP8266WebServer does not work with AutoConnect. AutoConnect overrides *ESP8266WebServer::onNotFound* to handle a captive portal. To register "not found" handler, use [*AutoConnect::onNotFound*](api.md#onnotfound).
Registering the "not found" handler is a different way than ESP8266WebServer/WebServer. The *onNotFound* of ESP8266WebServer/WebServer does not work with AutoConnect. AutoConnect overrides *ESP8266WebServer::onNotFound*/*WebServer::onNotFound* to handle a captive portal. To register "not found" handler, use [*AutoConnect::onNotFound*](api.md#onnotfound).
When the captive portal is started, SoftAP starts and the STA is disconnected. The current SSID setting memorized in ESP8266 will be lost.
When the captive portal is started, SoftAP starts and the STA is disconnected. The current SSID setting memorized in ESP8266 will be lost but then the reconnect behavior of ESP32 is somewhat different from this.
The [WiFiSTAClass::disconnect](https://github.com/espressif/arduino-esp32/blob/a0f0bd930cfd2d607bf3d3288f46e2d265dd2e11/libraries/WiFi/src/WiFiSTA.h#L46) function implemented in the arduino-esp32 has extended parameters than the ESP8266's arduino-core. The second parameter of WiFi.disconnect on the arduino-esp32 core that does not exist in the [ESP8266WiFiSTAClass](https://github.com/esp8266/Arduino/blob/7e1bdb225da8ab337373517e6a86a99432921a86/libraries/ESP8266WiFi/src/ESP8266WiFiSTA.cpp#L296) has the effect of deleting the currently connected WiFi configuration and its default value is "false". On the ESP32 platform, even if WiFi.disconnect is executed, WiFi.begin() without the parameters in the next turn will try to connect to that AP. That is, automatic reconnection is implemented in arduino-esp32 already. Although this behavior appears seemingly competent, it is rather a disadvantage in scenes where you want to change the access point each time. When explicitly disconnecting WiFi from the Disconnect menu, AutoConnect will erase the AP connection settings saved by arduino-esp32 core. AutoConnect's automatic reconnection is a mechanism independent from the automatic reconnection of the arduino-esp32 core.
If the [**autoReconnect**](api.md#autoreconnect) option of the [**AutoConnectConfig**](api.md#autoconnectconfig-api) class is enabled, it automatically attempts to reconnect to the disconnected past access point. When the autoReconnect option is specified, AutoConnect will not start SoftAP immediately if the first WiFi.begin fails. It will scan WiFi signal and the same connection information as the detected BSSID is stored in EEPROM as AutoConnect's credentials, explicitly apply it with WiFi.begin and rerun.
```arduino hl_lines="3"
@ -31,6 +32,9 @@ Portal.config(Config);
Portal.begin();
```
!!! note "In ESP32, the credentials for AutoConnect are not in NVS"
The credentials used by AutoConnect are not saved in NVS on ESP32 module. ESP-IDF saves the WiFi connection configuration to NVS, but AutoConnect stores it on the eeprom partition. You can find the partition table for default as [default.csv](https://github.com/espressif/arduino-esp32/blob/master/tools/partitions/default.csv)
The captive portal will only be activated if the first *WiFi::begin* fails. Sketch can detect with the [*AutoConnect::onDetect*](api.md#ondetect) function that the captive portal has started. For example, the sketch can be written like as follows that turns on the LED at the start captive portal.
@ -124,13 +128,13 @@ and
> EEPROM library uses one sector of flash located [just after the SPIFFS](http://arduino-esp8266.readthedocs.io/en/latest/libraries.html?highlight=SPIFFS#eeprom).
So in the default state, the credential storage area used by AutoConnect conflicts with data owned by the user sketch. It will be destroyed together saved data in EEPROM by user sketch and AutoConnect each other. But you can move the storage area to avoid this.
Also, the placement of the EEPROM area of ESP32 is described in the [partition table](https://github.com/espressif/arduino-esp32/blob/master/tools/partitions/default.csv). So in the default state, the credential storage area used by AutoConnect conflicts with data owned by the user sketch. It will be destroyed together saved data in EEPROM by user sketch and AutoConnect each other. But you can move the storage area to avoid this.
The [**boundaryOffset**](api.md#boundaryoffset) in [**AutoConnectConfig**](api.md#autoconnectconfig-api) specifies the start offset of the credentials storage area. The default value is 0.
### <iclass="fa fa-caret-right"></i> Refers the hosted ESP8266WebServer
### <iclass="fa fa-caret-right"></i> Refers the hosted ESP8266WebServer/WebServer
Constructing an AutoConnect object variable without parameters then creates and starts an ESP8266WebServer inside the AutoConnect. This object variable could be referred by [*AutoConnect::host()*](api.md#host) function to access ESP8266WebServer instance as like below.
Constructing an AutoConnect object variable without parameters then creates and starts an ESP8266WebServer/WebServer inside the AutoConnect. This object variable could be referred by [*AutoConnect::host()*](api.md#host) function to access ESP8266WebServer/WebServer instance as like below.
The host() can be referred at after *AutoConnect::begin*.
### <iclass="fa fa-caret-right"></i> Usage for automatically instantiated ESP8266WebServer
### <iclass="fa fa-caret-right"></i> Usage for automatically instantiated ESP8266WebServer/WebServer
The sketch can handle URL requests using ESP8266WebServer that AutoConnect started internally. ESP8266WebServer instantiated dynamically by AutoConnect can be referred to by [*AutoConnect::host*](api.md#host) function. The sketch can use the '**on**' function, '**send**' function, '**client**' function and others by ESP8266WebServer reference of its return value.
The sketch can handle URL requests using ESP8266WebServer or WebServer that AutoConnect started internally. ESP8266WebServer/WebServer instantiated dynamically by AutoConnect can be referred to by [*AutoConnect::host*](api.md#host) function. The sketch can use the '**on**' function, '**send**' function, '**client**' function and others by ESP8266WebServer/WebServer reference of its return value.
```arduino hl_lines="8 9 13 14 20 21 27"
#include<ESP8266WiFi.h>
@ -182,11 +186,11 @@ void loop() {
}
```
!!! note "ESP8266WebServer function should be called after AutoConnect::begin"
The sketch cannot refer to an instance of ESP8266WebServer until AutoConnect::begin completes successfully.
!!! note "ESP8266WebServer/WebServer function should be called after AutoConnect::begin"
The sketch cannot refer to an instance of ESP8266WebServer/WebServer until AutoConnect::begin completes successfully.
!!! warning "Do not use with ESP8266WebServer::begin"
ESP8266WebServer is already running inside the AutoConnect.
!!! warning "Do not use with ESP8266WebServer::begin or WebServer::begin"
ESP8266WebServer/WebServer is already running inside the AutoConnect.
### <iclass="fa fa-caret-right"></i> Use with the [PageBuilder](https://github.com/Hieromon/PageBuilder) library
@ -235,9 +239,9 @@ A home path of AutoConnect is **/\_ac** by default. You can access from the brow
### <iclass="fa fa-caret-right"></i> Static IP assignment [^1]
It is also possible to assign static IP Address to ESP8266 in STA mode. By default DHCP is enabled and it becomes the IP address assigned by the DHCP server with *WiFi.begin*.
It is also possible to assign static IP Address to ESP8266/ESP32 in STA mode. By default DHCP is enabled and it becomes the IP address assigned by the DHCP server with *WiFi.begin*.
To assign a static IP to ESP8266 with WIFI\_MODE\_STA, the following parameters are required:
To assign a static IP to ESP8266/ESP32 with WIFI\_MODE\_STA, the following parameters are required:
AutoConnect default constructor. This entry internally allocates the ESP8266WebServer and is activated internally.
AutoConnect default constructor. This entry internally allocates the ESP8266WebServer for ESP8266 or WebServer for ESP32 and is activated internally.
- For ESP8266
```cpp
AutoConnect(ESP8266WebServer& webServer)
```
Run the AutoConnect site using the externally ensured ESP8266WebServer.
- For ESP32
```cpp
AutoConnect(WebServer& webServer)
```
Run the AutoConnect site using the externally ensured ESP8266WebServer for ESP8266 or WebServer for ESP32.
The [**handleClient**](api.md#handleclient) function of AutoConnect can include the response of the URI handler added by the user using the "*on*" function of ESP8266WebServer. If ESP8266WebServer is assigned internally by AutoConnect, the sketch can obtain that reference with the [**host**](api.me#host) function.
The [**handleClient**](api.md#handleclient) function of AutoConnect can include the response of the URI handler added by the user using the "*on*" function of ESP8266WebServer/WebServer. If ESP8266WebServer/WebServer is assigned internally by AutoConnect, the sketch can obtain that reference with the [**host**](api.me#host) function.
<dlclass="apidl">
<dt>**Parameters**</dt>
<dd><spanclass="apidef">webServer</span>A reference of ESP8266WebServer instance.</dd>
<dd><spanclass="apidef">webServer</span>A reference of ESP8266WebServer or WebServer instance.</dd>
</dl>
### <iclass="fa fa-code"></i> Public member functions
@ -56,15 +64,14 @@ The [**handleClient**](api.md#handleclient) function of AutoConnect can include
bool begin(const char* ssid, const char* passphraase, unsinged long timeout)
bool begin(const char* ssid, const char* passphrase, unsigned long timeout)
```
Starts establishing the WiFi connection.
AutoConnect first invokes *WiFi.begin*. If the case of SSID and Password missing, its *WiFi.begin* has no SSID and Password. The WiFi mode at this time is WIFI_STA. Then ESP8266WebServer will be started immediately after the first *WiFi.beign* regardless of the result.
Starts establishing the WiFi connection. The WiFi mode at this time is WIFI_STA.
AutoConnect first invokes *WiFi.begin*. If the *ssid* and the *passphrase* are missing, its *WiFi.begin* has no SSID and Password. Regardless of the result, ESP8266WebServer/WebServer will start immediately after the first *WiFi.begin*.
The captive portal will not be started if the connection has been established with first *WiFi.begin*. If the connection cannot establish, switch to WIFI_AP_STA mode and activate SoftAP. Then DNS server starts.
<dlclass="apidl">
<dt>**Parameters**</dt>
@ -89,7 +96,7 @@ Set SoftAP's WiFi configuration and static IP configuration.
<dlclass="apidl">
<dt>**Parameters**</dt>
<dd><spanclass="apidef">config</span>Reference to [**AutoConnectConfig**](api.md#autoconnectconfig) containing SoftAP's parameters and static IP parameters.</dd>
<dd><spanclass="apidef">ap</span>SSID for SoftAP. The default value is **esp8266ap**.</dd>
<dd><spanclass="apidef">ap</span>SSID for SoftAP. The default value is **esp8266ap** for ESP8266, **esp32ap** for ESP32.</dd>
<dd><spanclass="apidef">password</span>Password for SodtAP. The default value is **12345678**.</dd>
Process the AutoConnect menu interface. It will be processed the client request too contained in the user sketch handler by calling from inside of AutoConnect to the hosted *ESP8266WebServer::handleClient*.
Process the AutoConnect menu interface. The handleClient() function of the ESP8266WebServer/WebServer hosted by AutoConnect is also called from within AutoConnect, and the client request handlers contained in the user sketch are also handled.
#### handleRequest
@ -124,7 +131,7 @@ void handleRequest()
Handling for the AutoConnect menu request.
!!! warning "About used in combination with handleClient"
The handleRequest function is not supposed to use with AutoConnect::handleClient. It should be used with ESP8266::handleClient.
The handleRequest function is not supposed to use with AutoConnect::handleClient. It should be used with ESP8266WebServer::handleClient or WebServer::handleClient.
#### home
@ -140,14 +147,22 @@ Put a user site's home URI. The URI specified by home is linked from "HOME" in t
#### host
Returns the reference of the ESP8266WebServer which is allocated in AutoConnect automatically.
Returns the reference of the ESP8266WebServer/WebServer which is allocated in AutoConnect automatically.
- For ESP8266
```cpp
ESP8266WebServer& host()
```
- For ESP32
```cpp
WebServer& host()
```
<dlclass="apidl">
<dt>**Return value**</dt>
<dd>A reference of the ESP8266WebServer.</dd>
<dd>A reference of the ESP8266WebServer/WebServer.</dd>
<dd><spanclass="apidef">ap</span>SSID for SoftAP. The length should be up to 31. The default value is **esp8266ap**.</dd>
<dd><spanclass="apidef">ap</span>SSID for SoftAP. The length should be up to 31. The default value is **esp8266ap** for ESP8266, **esp32ap** for ESP32.</dd>
<dd><spanclass="apidef">password</span>Password for SodtAP. The length should be from 8 to up to 63. The default value is **12345678**.</dd>
</dl>
@ -234,7 +257,7 @@ Sets IP address for Soft AP in captive portal. When AutoConnect fails the initia
#### autoReconnect
Automatically reconnect to past established access point (BSSID) when the current configured SSID in ESP8266 could not be connected. By enabling this option, *AutoConnect::begin()* function will attempt to reconnect to a known access point using credentials stored in the EEPROM, even if the connection failed by current SSID.
Automatically will try to reconnect with the past established access point (BSSID) when the current configured SSID in ESP8266/ESP32 could not be connected. By enabling this option, *AutoConnect::begin()* function will attempt to reconnect to a known access point using credentials stored in the EEPROM, even if the connection failed by current SSID.
If the connection fails, starts the captive portal in SoftAP + STA mode.
### <iclass="fa fa-edit"></i> Embed to the sketches
How embed the AutoConnect to the sketches you have. Most simple approach to applying AutoConnect for the existing sketches, follow the below steps.
How embed the AutoConnect to the sketches you have. Most simple approach to applying AutoConnect for the existing sketches, follow the below steps. The below sketch is for ESP8266. For ESP32, replace ```ESP8266WebServer``` with ```WebServer``` and ```ESP8266WiFi.h``` with ```WiFi.h``` respectively.
<imgsrc="../images/BeforeAfter.svg"/>
@ -31,24 +31,25 @@ Replacement the **handleClient** method is not indispensable. AutoConnect can st
#### 1. A typical logic sequence
!!! note ""
1. <strong>Include headers,</strong>`ESP8266WebServer.h` and `AutoConnect.h`
4. <strong>Implements the URL handler with the *function()*.</strong>
1. <strong>Include headers,</strong>`ESP8266WebServer.h`/`WebServer.h` and `AutoConnect.h`
2. <strong>Declare an ESP8266WebServer variable for ESP8266 or a WebServer variable for ESP32.</strong>
3. <strong>Declare an AutoConnect variable.</strong>
4. <strong>Implement the URL handlers provided for the </strong>`on`<strong> method of ESP8266WebServer/WebServer with the *function()*.</strong>
5. <strong>setup()</strong>
5.1 <strong>Sets URL handler *function()* to ESP8266WebServer by</strong>`ESP8266WebServer::on`<strong>.</strong>
5.1 <strong>Sets URL handler the *function()* to ESP8266WebServer/WebServer by</strong>`ESP8266WebServer::on`<strong>/</strong>`WebServer::on`<strong>.</strong>
6.1 <strong>Invokes </strong>`AutoConnect::handleClient()`<strong>, or invokes </strong>`ESP8266WebServer::handleClient()`<strong> then </strong>`AutoConnect::handleRequest()`<strong>.</strong>
6.2 <strong>Do the process for actual sketch.</strong>
6.1 <strong>Do the process for actual sketch.</strong>
6.2 <strong>Invokes </strong>`AutoConnect::handleClient()`<strong>, or invokes </strong>`ESP8266WebServer::handleClient()`<strong>/</strong>`WebServer::handleClient`<strong> then </strong>`AutoConnect::handleRequest()`<strong>.</strong>
#### 2. Declare AutoConnect object
[Two options](#esp8266webserver-hosted-or-parasitic) are available for [AutoConnect constructor](api.md#constructors).
```arduino
AutoConnect VARIABLE(&ESP8266WebServer);
AutoConnect VARIABLE(&ESP8266WebServer); // For ESP8266
AutoConnect VARIABLE(&WebServer); // For ESP32
```
or
@ -56,51 +57,51 @@ or
AutoConnect VARIABLE;
```
- **The parameter with an ESP8266WebServer variable:** An ESP8266WebServer object variable must be declared. AutoConnect uses its variable to handles the [AutoConnect menu](menu.md).
- **The parameter with an ESP8266WebServer/WebServer variable:** An ESP8266WebServer/WebServer object variable must be declared. AutoConnect uses its variable to handles the [AutoConnect menu](menu.md).
- **With no parameter:** The sketch does not declare ESP8266WebServer object. In this case, AutoConnect allocates an instance of the ESP8266WebServer internally. The logic sequence of the sketch is somewhat different as the above. To register a URL handler function by *ESP8266WebServer::on* should be performed after [*AutoConnect::begin*](api.md#begin).
- **With no parameter:** The sketch does not declare ESP8266WebServer/WebServer object. In this case, AutoConnect allocates an instance of the ESP8266WebServer/WebServer internally. The logic sequence of the sketch is somewhat different as the above. To register a URL handler function by *ESP8266WebServer::on* or *WebServer::on* should be performed after [*AutoConnect::begin*](api.md#begin).
#### 3. No need WiFI.begin(...)
AutoConnect internally performs *WiFi.begin* to establish a WiFi connection. There is no need for a general process to establish a connection using *WiFi.begin* with a sketch code.
#### 4. Alternate ESP8266WebServer::begin()
#### 4. Alternate ESP8266WebServer::begin() and WebServer::begin()
[*AutoConnect::begin*](api.md#begin) executes *ESP8266WebServer::begin* internally too and it starts the DNS server to behave as a Captive portal. So it is not needed to call *ESP8266WebServer::begin* with the sketch.
[*AutoConnect::begin*](api.md#begin) executes *ESP8266WebServer::begin*/*WebServer::begin* internally too and it starts the DNS server to behave as a Captive portal. So it is not needed to call *ESP8266WebServer::begin*/*WebServer::begin* in the sketch.
!!! info "Why DNS Server starts"
AutoConnect traps the detection of the captive portal and achieves a connection with the WLAN interactively by the AutoConnect menu. It responds SoftAP address to all DNS queries temporarily to trap. When the WLAN connection establishes, then stops DNS server.
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.
#### 5. AutoConnect::begin with SSID and Password
SSID and Password can also specify by [*AutoConnect::begin*](api.me#begin). ESP8266 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.
SSID and Password can also specify by [*AutoConnect::begin*](api.me#begin). ESP8266/ESP32 uses provided SSID and Password explicitly. If the connection false with specified SSID with Password then a captive portal is activated. SSID and Password are not present, ESP8266 SDK will attempt to connect using the still effectual SSID and password. Usually, it succeeds.
#### 6. Use ESP8266WebServer::on to handle URL
#### 6. Use ESP8266WebServer::on and WebServer::on to handle URL
AutoConnect is designed to coexist with the process for handling the web pages by user sketches. The page processing function which will send an HTML to the client invoked by the "*on::ESP8266WebServer*" function is the same as when using ESP8266WebServer natively.
AutoConnect is designed to coexist with the process for handling the web pages by user sketches. The page processing function which will send an HTML to the client invoked by the "*on::ESP8266WebServer*" or the "*on::WebServer*" function is the same as when using ESP8266WebServer/WebServer natively.
#### 7. Use either ESP8266WebServer::handleClient() or AutoConnect::handleClient()
#### 7. Use either ESP8266WebServer::handleClient()/WebServer::handleClient() or AutoConnect::handleClient()
Both classes member function name is the same: *handleClient*, but the behavior is different. Using the AutoConnect embedded along with ESP8266WebServer::handleClient has limitations. Refer to the below section for details.
Both classes member function name is the same: *handleClient*, but the behavior is different. Using the AutoConnect embedded along with ESP8266WebServer::handleClient/WebServer::handleClient has limitations. Refer to the below section for details.
### <iclass="fa fa-caret-right"></i> ESP8266WebServer hosted or parasitic
### <iclass="fa fa-caret-right"></i> ESP8266WebServer/WebServer hosted or parasitic
The interoperable process with an ESP8266WebServer depends on the parameters of the [AutoConnect constructor](api.md#constructors).
The interoperable process with an ESP8266WebServer/WebServer depends on the parameters of the [AutoConnect constructor](api.md#constructors).
Declaration parameter for the constructor | Use ESP8266WebServer::handleClient only | Use AutoConnect::handleClient
Declaration parameter for the constructor | Use ESP8266WebServer::handleClient or WebServer::handleClient only | Use AutoConnect::handleClient
----|----|---
[None](api.md#constructors) | AutoConnect menu not available.<br>To use AutoConnect menu, need [AutoConnect::handleRequest()](api.md#handlerequest).<br>also to use ESP8266WebServer natively, need [AutoConnect::host()](api.md#host). | AutoConnect menu available.<br>To use ESP8266WebServer natively, need [AutoConnect::host()](api.md#host).
[Reference to ESP8266WebServer](api.md#withparameter) | AutoConnect menu not available.<br>To use AutoConnect menu, need [AutoConnect::handleRequest()](api.md#handlerequest). | AutoConnect menu available.
[None](api.md#constructors) | AutoConnect menu not available.<br>To use AutoConnect menu, need [AutoConnect::handleRequest()](api.md#handlerequest).<br>also to use ESP8266WebServer/WebServer natively, need [AutoConnect::host()](api.md#host). | AutoConnect menu available.<br>To use ESP8266WebServer/WebServer natively, need [AutoConnect::host()](api.md#host).
[Reference to ESP8266WebServer/WebServer](api.md#withparameter) | AutoConnect menu not available.<br>To use AutoConnect menu, need [AutoConnect::handleRequest()](api.md#handlerequest). | AutoConnect menu available.
- **By declaration for the AutoConnect variable with no parameter**: The ESP8266WebServer instance is hosted by AutoConnect automatically then the sketches use [*AutoConnect::host*](api.md#host) as API to get it after [*AutoConnect::begin*](api.md#begin) performed.
- **By declaration for the AutoConnect variable with no parameter**: The ESP8266WebServer/WebServer instance is hosted by AutoConnect automatically then the sketches use [*AutoConnect::host*](api.md#host) as API to get it after [*AutoConnect::begin*](api.md#begin) performed.
- **By declaration for the AutoConnect variable with the reference of ESP8266WebServer**: AutoConnect will use it. The sketch can use it is too.
- **By declaration for the AutoConnect variable with the reference of ESP8266WebServer/WebServer**: AutoConnect will use it. The sketch can use it is too.
- **In use ESP8266WebServer::handleClient()**: AutoConnect menu can be dispatched but not works normally. It is necessary to call [*AutoConnect::handleRequest*](api.md#void-handlerequest) after *ESP8255WebServer::handleClient* invoking.
- **In use ESP8266WebServer::handleClient()/WebServer::handleClient()**: AutoConnect menu can be dispatched but not works normally. It is necessary to call [*AutoConnect::handleRequest*](api.md#void-handlerequest) after *ESP8255WebServer::handleClient*/*WebServer::handleClient* invoking.
- **In use [AutoConnect::handleClient()](api.md#void-handleclient)**: The handleClient() process and the AutoConnect menu is available without calling *ESP8266WebServer::handleClient*.
!!! info "Why AutoConnect::handleRequest is needed when using ESP8266::handleClient"
The AutoConnect menu function may affect WiFi connection state. It follows that the menu process must execute outside *ESP8266WebServer::handleClient*.
[*AutoConnect::handleClient*](api.md#void-handleclient) is equivalent *ESP8266WebServer::handleClient* included [*AutoConnect::handleRequest*](api.md#void-handlerequest).
!!! info "Why AutoConnect::handleRequest is needed when using ESP8266WebServer::handleClient/WebServer::handleClient"
The AutoConnect menu function may affect WiFi connection state. It follows that the menu process must execute outside *ESP8266WebServer::handleClient* and *WebServer::handleClient*.
[*AutoConnect::handleClient*](api.md#void-handleclient) is equivalent *ESP8266WebServer::handleClient*and *WEbServer::handleClient*included [*AutoConnect::handleRequest*](api.md#void-handlerequest).
@ -31,7 +31,7 @@ Declare only AutoConnect, performs handleClient.
## Used with MQTT as a client application
The effect of AutoConnect is not only for ESP8266 as the Web server. It has advantages for something WiFi client as well. For example, AutoConnect is also effective 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.
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 effective 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.
This example tries to publish the WiFi signal strength of ESP8266 with MQTT. It uses the [ThingSpeak](https://thingspeak.com/) for MQTT broker. ESP8266 publishes the RSSI value to the channel created on ThingSpeak as [MQTT client](https://github.com/knolleary/pubsubclient). 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.
Open the Arduino IDE, write the following sketch and upload it. The feature of this sketch is that the SSID and Password are not coded.
```arduino
#include<ESP8266WiFi.h>
#include<ESP8266WebServer.h>
#include<ESP8266WiFi.h> // Replace with WiFi.h for ESP32
#include<ESP8266WebServer.h> // Replace with WebServer.h for ESP32
#include<AutoConnect.h>
ESP8266WebServer Server;
ESP8266WebServer Server; // Replace with WebServer for ESP32
AutoConnect Portal(Server);
void rootPage() {
@ -31,9 +31,14 @@ void loop() {
}
```
!!! note ""
The above code can be applied to ESP8266. To apply to ESP32, replace ```ESP8266WebServer``` class with ```WebServer``` and include ```WiFi.h``` and ```WebServer.h``` of arduino-esp32 appropriately.
### <iclass="fa fa-play-circle"></i> Run at first
After about 30 seconds, if the ESP8266 cannot connect to nearby Wi-Fi spot, you pull out your smartphone and open *Wi-Fi settings* from the *Settings* Apps. You can see the **esp8266ap** in the list of *"CHOOSE A NETWORK..."*. Then tap the esp8266ap and enter password **12345678**, a something screen pops up automatically as shown below.
After about 30 seconds, if the ESP8266 cannot connect to nearby Wi-Fi spot, you pull out your smartphone and open *Wi-Fi settings* from the *Settings* Apps. You can see the **esp8266ap** [^1] in the list of *"CHOOSE A NETWORK..."*. Then tap the esp8266ap and enter password **12345678**, a something screen pops up automatically as shown below.
[^1]:When applied to ESP32, SSID will appear as **esp32ap**.
An Arduino library for ESP8266 WLAN configuration at run time with web interface.
An Arduino library for ESP8266/ESP32 WLAN configuration at run time with web interface.
## Overview
To the dynamic configuration for joining to WLAN with SSID and PSK accordingly. It an Arduino library united with *ESP8266WebServer* class.
Easy implementing the Web interface constituting the WLAN for ESP8266 WiFi connection. With this library to make a sketch easily which connects from ESP8266 to the access point at runtime by the web interface without hard-coded SSID and password.
To the dynamic configuration for joining to WLAN with SSID and PSK accordingly. It an Arduino library united with *ESP8266WebServer* class for ESP8266 or *WebServer* class for ESP32.
Easy implementing the Web interface constituting the WLAN for ESP8266/ESP32 WiFi connection. With this library to make a sketch easily which connects from ESP8266/ESP32 to the access point at runtime by the web interface without hard-coded SSID and password.
### <iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> No need pre-coded SSID & password
<spanclass="lead">It is no needed hard-coding in advance the SSID and Password into the sketch to connect between ESP8266 and WLAN. You can input SSID & Password from a smartphone via the web interface at runtime.</span>
<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>
@ -19,7 +19,7 @@ Easy implementing the Web interface constituting the WLAN for ESP8266 WiFi conne
### <iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Store the established connection
<spanclass="lead">The connection authentication data as credentials are saved automatically in EEPROM of ESP8266 and You can select the past SSID from the [AutoConnect menu](menu.md).</span>
<spanclass="lead">The connection authentication data as credentials are saved automatically in EEPROM of ESP8266/ESP32 and You can select the past SSID from the [AutoConnect menu](menu.md).</span>
### <iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Easy to embed in
@ -27,7 +27,7 @@ Easy implementing the Web interface constituting the WLAN for ESP8266 WiFi conne
### <iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Lives with the your sketches
<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.</span>
<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.<br>This efficacy can also be applied to ESP32. The corresponding class for ESP32 will be the WebServer.</span>
## Installation
@ -43,6 +43,13 @@ Easy implementing the Web interface constituting the WLAN for ESP8266 WiFi conne
* [X] Olimex MOD-WIFI-ESP8266
* [X] SparkFun Thing
* [X] SweetPea ESP-210
* [X] ESP32Dev Board (applying the Espressif's arduino-esp32 core)
* [X] SparkFun ESP32 Thing
* [X] WEMOS LOLIN D32
* [X] Ai-Thinker NodeMCU-32S
* [X] Heltec WiFi Kit 32
* [X] M5Stack
* [X] And other ESP8266/ESP32 modules supported by the Additional Board Manager URLs of the Arduino-IDE.
!!! info "About flash size on the module"
The AutoConnect sketch size is relatively large. Large flash capacity is necessary. 512Kbyte (4Mbits) flash inclusion module such as ESP-01 is not recommended.
@ -60,17 +67,18 @@ The current upstream at the 1.8 level or later is needed. Please install from th
AutoConnect targets sketches made on the assumption of [ESP8266 Community's Arduino core](https://github.com/esp8266/Arduino). The [latest release](https://github.com/esp8266/Arduino/releases/latest) is recommended.
Install third-party platform using the *Boards Manager* of Arduino IDE. Package URL is http://arduino.esp8266.com/stable/package_esp8266com_index.json
Also, to apply AutoConnect to ESP32, the [arduino-esp32 core](https://github.com/espressif/arduino-esp32) provided by Espressif is needed. The [latest release](https://github.com/espressif/arduino-esp32/releases/latest) is recommended.
Install third-party platform using the *Boards Manager* of Arduino IDE. You can add multiple URLs into *Additional Board Manager URLs* field, separating them with commas. Package URL is https://dl.espressif.com/dl/package_esp32_index.json
The [PageBuilder](https://github.com/Hieromon/PageBuilder) library to build HTML for ESP8266WebServer is needed.
To install the PageBuilder library into your Arduino IDE, you can use the *Library Manager*. Select the board of ESP8266 series in the Arduino IDE, open the library manager and search keyword '**PageBuilder**' with the topic '**Communication**', then you can see the *PageBuilder*. The latest version or 1.0.0 later is required.
To install the PageBuilder library into your Arduino IDE, you can use the *Library Manager*. Select the board of ESP8266 series in the Arduino IDE, open the library manager and search keyword '**PageBuilder**' with the topic '**Communication**', then you can see the *PageBuilder*. The latest version is required 1.1.0 later for ESP32.
<imgsrc="./images/lm.png"width="640"/>
!!! warning "Library Manager of Arduino IDE"
The version of PageBuilder may not have been updated yet. If the library manager shows only version 0.93.0, please install the latest PageBuilder version than 1.0.0 from the Github repository. [The PageBuilder release](https://github.com/Hieromon/PageBuilder/releases/latest) of the Github repository is the latest version. The [PlatformIO library](https://platformio.org/lib/show/2010/PageBuilder) has the latest version of 1.0.0.
In 0.93.0, the PageBuilder class has a compile error about without the 'cancel' method.
### Install the AutoConnect
Clone or download from the [AutoConnect GitHub repository](https://github.com/Hieromon/AutoConnect).
@ -82,7 +90,7 @@ When you select Download, you can import it to Arduino IDE immediately. After do
<imgsrc="./images/ins_lib.png"/>
!!! info "Supported by Library manager."
AutoConnect was added to the Arduino IDE library manager as of March 17, 2018. It can be used with the PlatformIO library also.
AutoConnect was added to the Arduino IDE library manager. It can be used with the PlatformIO library also.
## <iclass="fa fa-external-link"></i> Where the from
The AutoConnect menu appears when you access the **AutoConnect root path**. It is assigned "**/_ac**" located on ESP8266 *local IP address* by default. This location can be changed in the sketch. The following screen will appear at access to `http://{localIP}/_ac` as the root path. This is the statistics of the current WiFi connection. You can access the menu from the here, to invoke it tap <iclass="fa fa-bars"></i> at right on top. (e.g. `http://192.168.244.1/_ac` for SoftAP mode.)
The AutoConnect menu appears when you access the **AutoConnect root path**. It is assigned "**/_ac**" located on the *local IP address* of ESP8266/ESP32 module by default. This location can be changed in the sketch. The following screen will appear at access to `http://{localIP}/_ac` as the root path. This is the statistics of the current WiFi connection. You can access the menu from the here, to invoke it tap <iclass="fa fa-bars"></i> at right on top. (e.g. `http://192.168.244.1/_ac` for SoftAP mode.)
Scan all available access point and display it. Strength and security of the detected AP are marked. The <iclass="fa fa-lock"></i> is indicated for the SSID that needs a security key. "**Hidden:**" means the number of hidden SSIDs discovered.
Enter SSID and Passphrase and tap "**apply**" to starts a connection.
Scan all available access point in the vicinity and display it. Strength and security of the detected AP are marked. The <iclass="fa fa-lock"></i> is indicated for the SSID that needs a security key. "**Hidden:**" means the number of hidden SSIDs discovered.
Enter SSID and Passphrase and tap "**apply**" to starts WiFi connection.
Once it was established connection, its SSID and Password will be stored to the EEPROM of ESP8266 automatically. The **Open SSIDs** menu reads the saved SSID credentials from the EEPROM. The stored credential data are listed by the SSID as shown below. Its label is a clickable button. Tap the SSID button, starts connection it.
Once it was established WiFi connection, its SSID and password will be saved in EEPROM of ESP8266/ESP32 automatically. The **Open SSIDs** menu reads the saved SSID credentials from the EEPROM. The stored credential data are listed by the SSID as shown below. Its label is a clickable button. Tap the SSID button, starts WiFi connection it.
Disconnect ESP8266 from the current connection. It can also reset the ESP8266 automatically after disconnection by instructing with using [API](api.md#autoreset) in the sketch.
Disconnect ESP8266/ESP32 from the current connection. It can also reset the ESP8266/ESP32 automatically after disconnection by instructing with using [API](api.md#autoreset) in the sketch.
After tapping "Disconnect", you will not be able to reach the AutoConnect menu. Once disconnected, you will need to set the SSID again for connecting the WLAN.
## <iclass="fa fa-bars"></i> Reset...
Reset the ESP8266, it will start rebooting. After rebooting complete, the ESP8266 begins establishing the previous connection with WIFI_STA mode, and *esp8266ap* of an access point will disappear from WLAN.
Reset the ESP8266/ESP32 module, it will start rebooting. After rebooting complete, the ESP8266/ESP32 module begins establishing the previous connection with WIFI_STA mode, and *esp8266ap* or *esp32ap* of an access point will disappear from WLAN.
!!! warning "Not every module will be rebooted normally"
The Reset menu is using the **ESP.reset()** function. This is an almost hardware reset. In order to resume the sketch normally, the [state of GPIO0](https://github.com/esp8266/esp8266-wiki/wiki/Boot-Process#esp-boot-modes) is important. Since this depends on the circuit implementation for each module, not every module will be rebooted normally. See also [FAQ](faq.md#hang-up-after-reset).
!!! warning "Not every ESP8266 module will be rebooted normally"
The Reset menu is using the **ESP.reset()** function for ESP8266. This is an almost hardware reset. In order to resume the sketch normally, the [state of GPIO0](https://github.com/esp8266/esp8266-wiki/wiki/Boot-Process#esp-boot-modes) is important. Since this depends on the circuit implementation for each module, not every module will be rebooted normally. See also [FAQ](faq.md#hang-up-after-reset).
Hieromon Ikasamo
6 years ago
committed by
GitHub