@ -6,7 +6,7 @@ Registering the "not found" handler is a different way than ESP8266WebServer (We
### <iclass="fa fa-caret-right"></i> Access to saved credentials
AutoConnect stores the established WiFi connection in the flash of the ESP8266/ESP32 module and equips the class to access it from the sketch. You can read, write or erase the credentials using this class individually. It's [AutoConnectCredential](credit.md#autoconnectcredential) class which provides the access method to the saved credentials in the flash. Refer to section [Saved credentials access](credit.md) for details.
AutoConnect stores the established WiFi connection in the flash of the ESP8266/ESP32 module and equips the class to access it from the Sketch. You can read, write or erase the credentials using this class individually. It's [AutoConnectCredential](credit.md#autoconnectcredential) class which provides the access method to the saved credentials in the flash. Refer to section [Saved credentials access](credit.md) for details.
!!! note "Where to store credentials in ESP32 with AutoConnect v1.0.0 or later"
Since v1.0.0, credentials are stored in nvs of ESP32. AutoConnect v1.0.0 or later accesses the credentials area using the **Preferences** class with the arduino esp-32 core. So in ESP32, the credentials are not in the EEPROM, it is in the namespace **AC_CREDT** of the nvs. See [Saved credentials access](credit.md) for details.
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.
The captive portal will only be activated if 1st-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.
```cpp hl_lines="3 13"
AutoConnect Portal;
@ -100,9 +100,36 @@ void loop() {
}
```
### <iclass="fa fa-caret-right"></i> Captive portal starting control
Basically, the captive portal launch is subject to 1st-WiFi.begin result, but Sketch can control it. The Sketch can direct the following four actions by configuring AutoConnect with two parameters, [*AutoConnectConfig::immediateStart*](apiconfig.md#immediatestart) and [*AutoConnectConfig::autoRise*](apiconfig.md#autorise).
<td>Skip 1st-WiFi.begin<br>ESP module becomes SoftAP and the captive portal starts immediately.<br></td>
<td>Not attempt WiFi connection.<br>Only WebServer will start in STA mode.</td>
</tr>
<tr>
<td>false</td>
<td>Attempts WiFi connection in STA mode.<br>In some cases, the autoReconnect may restore the connection even if 1st-WiFiBeing fails.<br>If the connection is completely lost, the captive portal will be launched.<br><b>This is the default.</b></td>
<td>Attempts WiFi connection in STA mode.<br>In some cases, the autoReconnect may restore the connection even if 1st-WiFiBeing fails.<br>ESP module stays in STA mode and WebServer will start.</td>
</tr>
</table>
### <iclass="fa fa-caret-right"></i> Captive portal timeout control
AutoConnect has two parameters for timeout control. One is a timeout value used when trying to connect to the specified AP. It behaves the same as general timeout control in connection attempt by WiFi.begin. This control is specified by the third parameter of [*AutoConnect::begin*](api.md#begin). The default value is macro defined by [**AUTOCONNECT_TIMEOUT**](api.md#defined-macros) in the **AutoConnectDefs.h** file.
Once AutoConnect has entered the captive portal state due to the above conditions, it will not exit until a WiFi connection can be established. (But that is the default behavior)
The Sketch can abort the [*AutoConnect::begin*](api.md#begin) by setting the captive portal timeout and returns control to Sketch. AutoConnect has two parameters for timeout control. One is a timeout value used when trying to connect to the specified AP. It behaves the same as general timeout control in connection attempt by WiFi.begin. This control is specified by the third parameter of [*AutoConnect::begin*](api.md#begin). The default value is macro defined by [**AUTOCONNECT_TIMEOUT**](api.md#defined-macros) in the **AutoConnectDefs.h** file.
The other timeout control is for the captive portal itself. It is useful when you want to continue sketch execution with offline even if the WiFi connection is not possible. You can also combine it with the [**immediateStart**](#on-demand-start-the-captive-portal) option to create sketches with high mobility.
@ -159,7 +186,7 @@ void loop() {
}
```
There is another option related to timeout in AutoConnectConfig. It can make use of the captive portal function even after a timeout. The [*AutoConnectConfig::retainPortal*](apiconfig.md#retainportal) option will not stop the SoftAP when the captive portal is timed out. If you enable the ratainPortal option, you can try to connect to the AP at any time while continuing to sketch execution with offline even after the captive portal timed-out. Compared to the above code specified no option with the following example code, the captive portal will remain available even after a timeout without changing the logic of the sketch.
There is another option related to timeout in AutoConnectConfig. It can make use of the captive portal function even after a timeout. The [*AutoConnectConfig::retainPortal*](apiconfig.md#retainportal) option will not stop the SoftAP when the captive portal is timed out. If you enable the ratainPortal option, you can try to connect to the AP at any time while continuing to sketch execution with offline even after the captive portal timed-out. Compared to the above code specified no option with the following example code, the captive portal will remain available even after a timeout without changing the logic of the Sketch.
```cpp hl_lines="10"
#include<ESP8266WiFi.h>
@ -251,7 +278,7 @@ You can change the label text for each menu item but cannot change them at run t
1. Overwrite the label literal of library source code directly.
You can change the label of the AutoConnect menu item by rewriting the default label literal in [AutoConnectLabels.h](https://github.com/Hieromon/AutoConnect/blob/master/src/AutoConnectLabels.h) macros. However, changing menu items literal influences all the sketch's build scenes.
You can change the label of the AutoConnect menu item by rewriting the default label literal in [AutoConnectLabels.h](https://github.com/Hieromon/AutoConnect/blob/master/src/AutoConnectLabels.h) macros. However, changing menu items literal influences all the Sketch's build scenes.
```cpp
#define AUTOCONNECT_MENULABEL_CONFIGNEW "Configure new AP"
@ -276,7 +303,7 @@ You can change the label text for each menu item but cannot change them at run t
### <iclass="fa fa-caret-right"></i> Combination with mDNS
With [mDNS library](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266mDNS), you can access to ESP8266 by name instead of IP address after connection. The sketch can start the MDNS responder after [*AutoConnect::begin*](api.md#begin).
With [mDNS library](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266mDNS), you can access to ESP8266 by name instead of IP address after connection. The Sketch can start the MDNS responder after [*AutoConnect::begin*](api.md#begin).
```cpp hl_lines="8 9"
#include<ESP8266WiFi.h>
@ -329,7 +356,7 @@ Combining these two parameters allows you to filter the destination AP when mult
<td>Restoring static IPs suitable for the SSID from saved credentials</td>
</tr>
<tr>
<td>Specified with the sketch</td>
<td>Specified with the Sketch</td>
<td>Not efective</td>
<td>By AutoConnect::begin parameters</td>
<td>Use the specified value of AutoConnectConfig</td>
@ -359,7 +386,7 @@ You can output AutoConnect monitor messages to the **Serial**. A monitor message
### <iclass="fa fa-caret-right"></i> Disable the captive portal
It can also prevent the captive portal from starting even if the connection at the first *WiFi.begin* fails. In this case, [*AutoConnect::begin*](api.md#begin) behaves same as *WiFi.begin*.
It can also prevent the captive portal from starting even if the connection at the 1st-WiFi.begin fails. In this case, [*AutoConnect::begin*](api.md#begin) behaves same as *WiFi.begin*.
For disabling the captive portal, [**autoRise**](apiconfig.md#autorise) sets to false with [AutoConnectConfig](apiconfig.md).
### <iclass="fa fa-caret-right"></i> Usage for automatically instantiated ESP8266WebServer/WebServer
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.
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.
```cpp hl_lines="8 9 13 14 20 21 27"
#include<ESP8266WiFi.h>
@ -551,7 +578,7 @@ void loop() {
```
!!! 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.
The Sketch cannot refer to an instance of ESP8266WebServer/WebServer until AutoConnect::begin completes successfully.
!!! warning "Do not use with ESP8266WebServer::begin or WebServer::begin"
ESP8266WebServer/WebServer is already running inside the AutoConnect.
@ -591,7 +618,7 @@ AutoConnectConfig can specify the following runtime behavior:
<imgsrc="images/menu_home.png"/>
The sketch HOME path is closely related to the [bootUri](apiconfig.md#booturi) that specifies the access path on module restart. AutoConnect has the following three parameters concerning control the URIs:
The Sketch HOME path is closely related to the [bootUri](apiconfig.md#booturi) that specifies the access path on module restart. AutoConnect has the following three parameters concerning control the URIs:
- **AUTOCONNECT_URI**
The **ROOT** of AutoConnect. It is defined in `AutoConnectDefs.h` and is assigned an [AutoConnect statistics screen](menu.md#where-the-from) by default.
@ -670,7 +697,7 @@ But this method is not recommended. The broadcast radio of SSID emitted from Sof
### <iclass="fa fa-caret-right"></i> Configuration for Soft AP and captive portal
AutoConnect will activate SoftAP at failed the first *WiFi.begin*. It SoftAP settings are stored in [**AutoConnectConfig**](apiconfig.md#autoconnectconfig) as the following parameters. The sketch could be configured SoftAP using these parameters, refer the [AutoConnectConfig API](apiconfig.md#public-member-variables) for details.
AutoConnect will activate SoftAP at failed the 1st-WiFi.begin. It SoftAP settings are stored in [**AutoConnectConfig**](apiconfig.md#autoconnectconfig) as the following parameters. The Sketch could be configured SoftAP using these parameters, refer the [AutoConnectConfig API](apiconfig.md#public-member-variables) for details.
Captive portal activation switch. False for disabling the captive portal. It prevents starting the captive portal even if the connection at the first *WiFi.begin* fails.
Captive portal activation switch. False for disabling the captive portal. It prevents starting the captive portal even if the connection at the 1st-WiFi.begin fails.
<dlclass="apidl">
<dt>**Type**</dt>
<dd>bool</dd>
@ -112,7 +112,7 @@ This option is valid only for ESP8266 or ESP32 arduino core 1.0.2 earlier.
</dl>
!!! warning "It will conflict with user data."
If the sketch leaves this offset at zero, it will conflict the storage area of credentials with the user sketch owned data. It needs to use the behind of credential area.
If the Sketch leaves this offset at zero, it will conflict the storage area of credentials with the user sketch owned data. It needs to use the behind of credential area.
### <iclass="fa fa-caret-right"></i> channel
@ -180,13 +180,13 @@ Sets the station host name of ESP8266/ESP32.
Disable the first WiFi.begin() and start the captive portal. If this option is enabled, the module will be in AP_STA mode and the captive portal will be activated regardless of [**AutoConnectConfig::autoRise**](apiconfig.md#autorise) specification.
Disable the 1st-WiFi.begin and start the captive portal. If this option is enabled, the module will be in AP_STA mode and the captive portal. The evaluation rank of this parameter is lower than the [**AutoConnectConfig::autoRise**](apiconfig.md#autorise). Even if immediateStart is true, the captive portal will not launch if autoRise is false.
<dlclass="apidl">
<dt>**Type**</dt>
<dd>bool</dd>
<dt>**Value**</dt>
<dd><spanclass="apidef">true</span><spanclass="apidesc">Start the captive portal with [**AutoConnect::begin**](api.md#begin).</span></dd>
<dd><spanclass="apidef">false</span><spanclass="apidesc">Enable the first WiFi.begin() and it will start captive portal when connection failed. This is default.</span></dd>
<dd><spanclass="apidef">false</span><spanclass="apidesc">Enable the 1st-WiFi.begin and it will start captive portal when connection failed. This is default.</span></dd>
</dl>
### <iclass="fa fa-caret-right"></i> menuItems
@ -232,7 +232,7 @@ Sets subnet mask for Soft AP in captive portal. When AutoConnect fails the initi
### <iclass="fa fa-caret-right"></i> ota
Specifies to import the built-in OTA update class into the sketch. When this option is enabled, an **Update** item will appear in the AutoConnect menu, and the OTA update via Web browser will be automatically embedded to the Sketch.
Specifies to import the built-in OTA update class into the Sketch. When this option is enabled, an **Update** item will appear in the AutoConnect menu, and the OTA update via Web browser will be automatically embedded to the Sketch.
<dlclass="apidl">
<dt>**Type**</dt>
<dd>AC_OTA_t</dd>
@ -281,7 +281,7 @@ Specify whether to continue the portal function even if the captive portal timed
</dl>
!!! hint "Connection request after timed-out"
With the **retainPortal**, even if AutoConnect::begin in the setup() is timed out, you can execute the sketch and the portal function as a WiFi connection attempt by calling AutoConnect::handleClient in the loop().
With the **retainPortal**, even if AutoConnect::begin in the setup() is timed out, you can execute the Sketch and the portal function as a WiFi connection attempt by calling AutoConnect::handleClient in the loop().
!!! info "All unresolved addresses redirects to /_ac"
If you enable the **retainPortal** option, **all unresolved URIs will be redirected to `SoftAPIP/_ac`**. It happens frequently as client devices repeat captive portal probes in particular. To avoid this, you need to exit from the WiFi connection Apps on your device once.
@ -362,7 +362,7 @@ Config.autoSave = AC_SAVECREDENTIAL_NEVER; // No save credential
Config.boundaryOffset = 64; // Reserve 64 bytes for the user data in EEPROM.
Config.portalTimeout = 60000; // Sets timeout value for the captive portal
Config.retainPortal = true; // Retains the portal function after timed-out
Config.homeUri = "/index.html"; // Sets home path of the sketch application
Config.homeUri = "/index.html"; // Sets home path of Sketch application
Config.title ="My menu"; // Customize the menu title
Config.staip = IPAddress(192,168,10,10); // Sets static IP
The following parameters of [AutoConnectConfig](apiconfig.md) affect the behavior and control a logic sequence of [AutoConnect::begin](api.md#begin) function. These parameters are evaluated on a case-by-case basis and may not be valid in all situations. The Sketch must consider the role of these parameters and the conditions under which they will work as intended. You need to understand what happens when using these parameters in combination.
- [immediateStart](apiconfig.md#immediatestart) : The captive portal start immediately, without the 1st-WiFi.begin.
- [autoReconenct](apiconfig.md#autoreconnect) : Attempt re-connect with past SSID by saved credential.
- [autoReconnect](apiconfig.md#autoreconnect) : Attempts re-connect with past SSID by saved credential.
- [autoRise](apiconfig.md#autorise) : Controls starting the captive portal.
- [immediateStart](apiconfig.md#immediatestart) : Starts the captive portal immediately, without the 1st-WiFi.begin.
- [portalTimeout](apiconfig.md#portaltimeout) : Time out limit for the portal.
- [retainPortal](apiconfig.md#retainportal) : Keep DNS server functioning for the captive portal.
Hieromon Ikasamo
4 years ago
