|
SSID &
Password |
AutoConnectConfig
::principle |
Which credentials would be selected |
Static IPs |
AutoConnect
::begin |
NULL specified |
AC_PRINCIPLE_RECENT |
Nothing, depends on SDK saves |
Use the specified value of AutoConnectConfig
|
| AC_PRINCIPLE_RSSI |
Auto-selected credentials with max RSSI |
Restoring static IPs suitable for the SSID from saved credentials |
| Specified with the Sketch |
Not effective |
By AutoConnect::begin parameters |
Use the specified value of AutoConnectConfig |
| AutoReconnect |
Load from
saved credential |
AC_PRINCIPLE_RECENT |
Recently saved SSID would be chosen |
Restoring static IPs suitable for the SSID from saved credentials |
| AC_PRINCIPLE_RSSI |
Auto-selected credentials with max RSSI |
## Detects connection establishment to AP
The Sketch can detect that the ESP module has established a WiFi connection as a station to the access point. The [AutoConnect::begin](api.md#begin) or [AutoConnect::handleClient](api.md#handleclient) will transit the control temporarily to the function in the Sketch registered by [AutoConnect::onConnect](api.md#onconnect) when the ESP module establish a WiFi connection.
The **ConnectExit** function registered with [AutoConnect::onConnect](api.md#onconnect) should have the following types and arguments:
```cpp
void ConnectExit(IPAddress& ip)
```
The **ConnectExit** function is of type *void*. The argument *ip* is the IP address assigned to the ESP module by the connected AP. [AutoConnect::onConnect](api.md#onconnect) allows the Sketch registers a **ConnectExit** function to AutoConnect. Also, you can make the function using a [**lambda expression**](https://en.cppreference.com/w/cpp/language/lambda).
```cpp hl_lines="3 4 5 6 7 8 12"
AutoConnect Portal;
void onConnect(IPAddress& ipaddr) {
Serial.print("WiFi connected with ");
Serial.print(WiFi.SSID());
Serial.print(", IP:");
Serial.println(ipaddr.toString());
}
void setup() {
Serial.begin(115200);
Portal.onConnect(onConnect); // Register the ConnectExit function
Portal.begin();
}
void loop() {
Portal.handleClient();
}
```
In addition, a sketch that shuts down SoftAP when the ESP module connects to the access point can be described using a lambda expression as follows:
```cpp hl_lines="5 6 7 8 9 10 11 12"
AutoConnect Portal;
void setup() {
Serial.begin(115200);
Portal.onConnect([](IPAddress& ipaddr){
Serial.printf("WiiFi connected with %s, IP:%s\n", WiFi.SSID().c_str(), ipaddr.toString().c_str());
if (WiFi.getMode() & WIFI_AP) {
WiFi.softAPdisconnect(true);
WiFi.enableAP(false);
Serial.printf("SoftAP:%s shut down\n", WiFi.softAPSSID().c_str());
}
});
Portal.begin();
}
void loop() {
Portal.handleClient();
}
```
!!! note "It is not an event"
AutoConnect::onConnect has the same effect on the Sketch as the [WiFi.onStationModeConnected](https://arduino-esp8266.readthedocs.io/en/latest/esp8266wifi/generic-class.html#onevent), but AutoConnect does not use the event. Sketch can use `WiFi.onEvent` independently of AutoConnect.
## Match with known access points by SSID
By default, AutoConnect uses the **BSSID** to search for known access points. (Usually, it's the MAC address of the device) By using BSSID as the key to finding the WiFi network, AutoConnect can find even if the access point is hidden. However BSSIDs can change on some mobile hotspots, the BSSID-keyed searches may not be able to find known access points.
If you operate inconvenience in aiming at the access point by BSSID, you can change the collation key from BSSID to SSID by uncommenting `AUTOCONNECT_APKEY_SSID` macro definition in [`AutoConnectDefs.h`](https://github.com/Hieromon/AutoConnect/blob/master/src/AutoConnectDefs.h#L59) library source code.
```cpp
#define AUTOCONNECT_APKEY_SSID
```
Allow you to use [PlatformIO](https://platformio.org/platformio-ide) as a build system and give the following description to the [`platformio.ini`](https://docs.platformio.org/en/latest/projectconf/section_env_build.html?highlight=build_flags#build-flags), you can enable **AUTOCONNECT_APKEY_SSID** each build without modifying the library source code:
```ini
build_flags=-DAUTOCONNECT_APKEY_SSID
```
!!! info "Can't be found hidden APs in SSID-keyed"
The hidden access point's SSID will be blank on the broadcast. So if the seek key is an SSID, AutoConnect will not find it.
## Preserve AP mode
Sketch using AutoConnect can open a gateway to the Internet by connecting to a WiFi router even through use Espressif's peculiar WiFi protocol (eg. [ESP-MESH](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/mesh.html) or [ESP-NOW](https://www.espressif.com/en/products/software/esp-now)). These specific communication protocols require to keeps AP + STA as the WiFi mode. That is, to apply these protocols, it needs to launch SoftAP by a sketch itself and then call [AutoConnect::begin](api.md#begin). But the default behavior of [AutoConnect::begin](api.md#begin) will turn off SoftAP always then it will unable to open a connection.
[*AutoConnectConfig::preserveAPMode*](apiconfig.md#preserveAPMode) setting maintains WIFI_AP mode without disabling SoftAP inside [AutoConnect::begin](api.md#begin). The Sketch can utilize the WiFi connection via AutoConnect with ESP-MESH and ESP-NOW protocol by enabling this option.
The following diagram quoted from the [ESP-MESH documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/mesh.html#mesh-building-a-network) that illustrates the typical topology of the MESH network. The module located at the Root Node bridges between the mesh network and the router by an application that handles two protocols, TCP/IP and ESP-MESH. Its SoftAP communicates with the internal mesh network as an interface of the mesh layer. On the other hand, STA performs station communication with the WiFi router as an interface of the TCP/IP layer. AutoConnect allows assists the connection between the router and the STA of the Root Node using [*AutoConnectConfig::preserveAPMode*](apiconfig.md#preserveapmode) and starting the SoftAP via Sketch separately.
Also in general, the Sketch should set **false** to [*AutoConnectConfig::autoRise*](apiconfig.md#autorise), **true** to [*AutoConnectConfig::immediateStart*](apiconfig.md#immediatestart) when applying to those protocols.
## Timeout settings for a connection attempt
AutoConnect uses [*AutoConnectConfig::beginTimeout*](apiconfig.md#begintimeout) value to limit time to attempt when connecting the ESP module to the access point as a WiFi station. The default value is **AUTOCONNECT_TIMEOUT** defined in [`AutoConnectDefs.h`](https://github.com/Hieromon/AutoConnect/blob/master/src/AutoConnectDefs.h#L132) and the initial value is 30 seconds. (actually specified in milliseconds)
For example, the following sketch sets the connection timeout to 15 seconds:
```cpp hl_lines="5"
AutoConnect Portal;
AutoConnectConfig Config;
void setup() {
Config.beginTimeout = 15000; // Timeout sets to 15[s]
Portal.config(Config);
Portal.begin();
}
void loop () {
Portal.handleClient();
}
```
In addition, the limit of the waiting time for connection attempts can be specified by the [AutoConnect::begin](api.md#begin) parameter too. The *timeout* parameter specified in [AutoConnect::begin](api.md#begin) takes precedence over [*AutoConnectConfig::beginTimeout*](apiconfig.md#begintimeout).
!!! note "The beginTimeout has an effect on handleClient"
The [**beginTimeout**](apiconfig.md#begintimeout) value will be applied with [**handleClient**](api.md#handleclient) when requesting a connection from the captive portal and when attempting to reconnect with [**autoReconnect**](apiconfig.md#autoreconnect).