@ -96,7 +96,7 @@ Full documentation is available on https://Hieromon.github.io/AutoConnect, some
## Change log
### [0.9.7] Jan. 1, 2019
### [0.9.7] Jan. 10, 2019
- Fixed crash in some environments. Thank you @ageurtse
- Supports AutoConnect menu extention by user sketch with **AutoConnectAux**.
- Supports loading and saving of user-defined parameters with JSON format.
@ -105,6 +105,7 @@ Full documentation is available on https://Hieromon.github.io/AutoConnect, some
- Improved boot uri after reset. **AutoConnectConfig::bootUri** can be specified either /_ac or HOME path as the uri to be accessed after invoking Reset from AutoConnect menu.
- Improved source code placement of predefined macros. Defined common macros have been moved to ```AutoConnectDefs.h```.
- Supports **AutoConnectConfig::hostName**. It activates ```WiFi.hostname()```.
- Supports the captive portal time-out. It can be controlled by **AutoConnectConfig::portalTimeout** and **AutoConnectConfig::retainPortal**.
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.
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"
@ -62,6 +64,92 @@ void loop() {
Portal.handleClient();
}
```
### <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). Default value is macro defined by [**AUTOCONNECT_TIMEOUT**](api.md#defined-macros) in the `AutoConnectDef.h` file.
The other is timeout control 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.
The timeout of the captive portal is specified together with [**AutoConnectConfig::portalTimeout**](apiconfig.md#portaltimeout) as follows.
```cpp hl_lines="9"
#include<ESP8266WiFi.h>
#include<ESP8266WebServer.h>
#include<AutoConnect.h>
AutoConnect portal;
AutoConnectConfig config;
void setup() {
config.portalTimeout = 60000; // It will time out in 60 seconds
portal.config(config);
portal.begin();
}
void loop() {
if (WiFi.status() == WL_CONNECTED) {
// Some sketck code for the connected scene is here.
}
else {
// Some sketch code for not connected scene is here.
}
portal.handleClient();
}
```
Also, if you want to stop AutoConnect completely when the captive portal is timed out, you need to call the [**AutoConnect::end**](api.md#end) function. It looks like the following code:
```cpp
bool acEnable;
void setup() {
config.portalTimeout = 60000; // It will time out in 60 seconds
portal.config(config);
acEnable = portal.begin();
if (!acEnable) {
portal.end();
}
}
void loop() {
if (WiFi.status() == WL_CONNECTED) {
// Some sketck code for the connected scene is here.
}
else {
// Some sketch code for not connected scene is here.
}
if (acEnable) {
portal.handleClient();
}
}
```
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#retainlportal) 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. The following code is its example. It can enable the captive portal after timed-out without changing sketch skeleton compared to the above code which does not specify an option.
```cpp hl_lines="10"
#include<ESP8266WiFi.h>
#include<ESP8266WebServer.h>
#include<AutoConnect.h>
AutoConnect portal;
AutoConnectConfig config;
void setup() {
config.portalTimeout = 60000; // It will time out in 60 seconds
config.retainPortal = true;
portal.config(config);
portal.begin();
}
void loop() {
if (WiFi.status() == WL_CONNECTED) {
// Some sketck code for the connected scene is here.
}
else {
// Some sketch code for not connected scene is here.
}
portal.handleClient();
}
```
### <iclass="fa fa-caret-right"></i> Combination with mDNS
@ -243,6 +331,8 @@ AutoConnect will activate SoftAP at failed the first *WiFi.begin*. It SoftAP set
- Hidden attribute.
- Auto save credential.
- Offset address of the credentials storage area in EEPROM.
<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>
<dd><spanclass="apidef">timeout</span>The timeout value of the captive portal in [ms] units. The default value is 0.</dd>
<dd><spanclass="apidef">channel</span>The channel number of WIFi when SoftAP starts. The default values is 1.</dd>
</dl>
## <iclass="fa fa-code"></i> Public member variables
### apid
### <iclass="fa fa-caret-right"></i>apid
SoftAP's SSID.
<dlclass="apidl">
@ -24,7 +32,7 @@ SoftAP's SSID.
<dd>String</dd>
</dl>
### apip
### <iclass="fa fa-caret-right"></i>apip
Sets IP address for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this.
<dlclass="apidl">
@ -32,7 +40,7 @@ Sets IP address for Soft AP in captive portal. When AutoConnect fails the initia
<dd><spanclass="apidef"style="width:230px;">IPAddress</span>The default value is **192.168.244.1**</dd>
</dl>
### autoReconnect
### <iclass="fa fa-caret-right"></i>autoReconnect
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.
@ -49,7 +57,7 @@ When the autoReconnect option is enabled, an automatic connection will behave if
- Invokes *AutoConnect::begin* without user name and password parameter as ```begin()```.
- If one of the saved BSSIDs (not the SSID) of the credentials matches the BSSID detected by the network scan.
### autoReset
### <iclass="fa fa-caret-right"></i>autoReset
Reset ESP8266 module automatically after WLAN disconnected.
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.
<dlclass="apidl">
@ -71,7 +79,7 @@ Captive portal activation switch. False for disabling the captive portal. It pre
<dd><spanclass="apidef"style="width:230px;">false</span>Disable the captive portal.</dd>
</dl>
### autoSave
### <iclass="fa fa-caret-right"></i>autoSave
The credential saved automatically at the connection establishment.
<dlclass="apidl">
@ -82,7 +90,7 @@ The credential saved automatically at the connection establishment.
<dd><spanclass="apidef"style="width:230px;">AC_SAVECREDENTIAL_NEVER</span>The credential no saved.</dd>
</dl>
### bootUri
### <iclass="fa fa-caret-right"></i>bootUri
Specify the location to be redirected after module reset in the AutoConnect menu. It is given as an enumeration value of **AC_ONBOOTURI_t** indicating either the AutoConnect root path or the user screen home path.
<dlclass="apidl">
@ -93,7 +101,7 @@ Specify the location to be redirected after module reset in the AutoConnect menu
<dd><spanclass="apidef"style="width:230px;">AC_ONBOOTURI_HOME</span>It is redirected to the uri specified by [**AutoConnectConfig::homeUri**](apiconfig.md#homeuri).</dd>
Sets the offset address of the credential storage area for EEPROM. This value must be between greater than 4 and less than flash sector size. (4096 by SDK)
The default value is 0.
@ -105,7 +113,7 @@ The default value is 0.
!!! 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.
### channel
### <iclass="fa fa-caret-right"></i>channel
The channel number of WIFi when SoftAP starts.
<dlclass="apidl">
@ -118,7 +126,7 @@ The channel number of WIFi when SoftAP starts.
!!! info "How do I choose Channel"
Espressif Systems had announced the [application note](https://www.espressif.com/sites/default/files/esp8266_wi-fi_channel_selection_guidelines.pdf) about Wi-Fi channel selection.
### dns1
### <iclass="fa fa-caret-right"></i>dns1
Set primary DNS server address when using static IP address.
<dlclass="apidl">
@ -126,7 +134,7 @@ Set primary DNS server address when using static IP address.
<dd>IPAddress</dd>
</dl>
#### dns2
###<iclass="fa fa-caret-right"></i> dns2
Set secondary DNS server address when using static IP address.
<dlclass="apidl">
@ -134,7 +142,7 @@ Set secondary DNS server address when using static IP address.
<dd>IPAddress</dd>
</dl>
### gateway
### <iclass="fa fa-caret-right"></i>gateway
Sets gateway address for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this.
<dlclass="apidl">
@ -142,7 +150,7 @@ Sets gateway address for Soft AP in captive portal. When AutoConnect fails the i
<dd><spanclass="apidef"style="width:230px;">IPAddress</span>The default value is **192.168.244.1**</dd>
</dl>
### hidden
### <iclass="fa fa-caret-right"></i>hidden
Sets SoftAP to hidden SSID.
<dlclass="apidl">
@ -153,7 +161,7 @@ Sets SoftAP to hidden SSID.
<dd><spanclass="apidef"style="width:230px;">1</span>SSID will be hidden.</dd>
</dl>
### homeUri
### <iclass="fa fa-caret-right"></i>homeUri
Sets the home path of user sketch. This path would be linked from 'HOME' in the AutoConnect menu. The default for homeUri is "/".
<dlclass="apidl">
@ -161,7 +169,7 @@ Sets the home path of user sketch. This path would be linked from 'HOME' in the
<dd>String</dd>
</dl>
### hostName
### <iclass="fa fa-caret-right"></i>hostName
Sets the station host name of ESP8266/ESP32.
<dlclass="apidl">
@ -169,7 +177,7 @@ 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.
<dlclass="apidl">
@ -180,7 +188,7 @@ Disable the first WiFi.begin() and start the captive portal. If this option is e
<dd><spanclass="apidef"style="width:230px;">false</span>Enable the first WiFi.begin() and it will start captive portal when connection failed. This is default.</dd>
</dl>
### netmask
### <iclass="fa fa-caret-right"></i>netmask
Sets subnet mask for Soft AP in captive portal. When AutoConnect fails the initial WiFi.begin, it starts the captive portal with the IP address specified this.
<dlclass="apidl">
@ -188,7 +196,15 @@ Sets subnet mask for Soft AP in captive portal. When AutoConnect fails the initi
<dd><spanclass="apidef"style="width:230px;">IPAddress</span>The default value is **255.255.255.0**</dd>
Specify the timeout value of the captive portal in [ms] units. It is valid when the station is not connected and does not time out if the station is connected to the ESP module in SoftAP mode (ie Attempting WiFi connection with the portal function). If 0, the captive portal will not be timed-out.
<dlclass="apidl">
<dt>**Type**</dt>
<dd><spanclass="apidef"style="width:230px;">unsigned long</span>Captive portal timeout value. The default value is 0.</dd>
</dl>
### <iclass="fa fa-caret-right"></i> psk
Sets password for SoftAP. The length should be from 8 to up to 63. The default value is **12345678**.
<dlclass="apidl">
@ -196,7 +212,21 @@ Sets password for SoftAP. The length should be from 8 to up to 63. The default v
Specify whether to continue the portal function even if the captive portal timed out. If the true, when a timeout occurs, the [**AutoConnect::begin**](api.md#begin) function is exited with returns false, but the portal facility remains alive. So SoftAP remains alive and you can invoke AutoConnect while continuing sketch execution. The default is false.
<dlclass="apidl">
<dt>**Type**</dt>
<dd>bool</dd>
<dt>**Value**</dt>
<dd><spanclass="apidef"style="width:230px;">true</span>Continue the portal function even if the captive portal times out. The STA + SoftAP mode of the ESP module continues and accepts the connection request to the AP.</dd>
<dd><spanclass="apidef"style="width:230px;">false</span>When the captive portal times out, STA + SoftAP mode of the ESP module is stopped. This is default.</dd>
</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().
### <iclass="fa fa-caret-right"></i> staip
Set a static IP address. The IP will behave with STA mode.
<dlclass="apidl">
@ -204,7 +234,7 @@ Set a static IP address. The IP will behave with STA mode.
<dd>IPAddress</dd>
</dl>
### staGateway
### <iclass="fa fa-caret-right"></i>staGateway
Set the gateway address when using static IP address.
<dlclass="apidl">
@ -212,7 +242,7 @@ Set the gateway address when using static IP address.