@ -444,6 +444,7 @@ AutoConnect will activate SoftAP at failed the first *WiFi.begin*. It SoftAP set
- Home URL of the user sketch application.
- Menu title.
- Ticker signal output.
- Built-in OTA update.
!!! note "AutoConnect::config before AutoConnect::begin"
*AutoConnect::config* must be executed before *AutoConnect::begin*.
@ -454,6 +455,22 @@ AutoConnect will activate SoftAP at failed the first *WiFi.begin*. It SoftAP set
<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:
- **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.
Which page appears at the captive portal, AUTOCONNECT_URI or the homeUri. Its page will pop up automatically when you visit the captive portal.
| The definition of **HOME** | Behavior | Specified by | Default value | Possible value |
|---|---|---|---|---|
| **ROOT** of AutoConnect | Default for AC_ONBOOTURI_ROOT | `#define AUTOCONNECT_URI` in `AutoConnectDefs.h` | `/_ac` | URI string |
| **HOME** for Application-specific | Listed on the **menu list** as **HOME**<br>Also, It may be linked from the **menu title** and is **redundant** with the HOME menu item.<br>eg. Case of bootURI = AC_ONBOOTURI_HOME | AutoConnectConfig::homeURI | `/` | URI string |
| Which page **loads** at the boot time, ROOT or HOME | Appears after module reboot by **RESET** button with AutoConnect menu | AutoConnectConfig::bootURI | AC_ONBOOTURI_ROOT | AC_ONBOOTURI_HOME |
| Which page **appears** at the captive portal, ROOT or HOME | Auto pop-up | AutoConnectConfig::bootURI | AC_ONBOOTURI_ROOT | AC_ONBOOTURI_HOME |
### <iclass="fa fa-caret-right"></i> Change SSID and Password for SoftAP
An **esp8266ap** is default SSID name for SoftAP of captive portal and password is **12345678** for ESP8266. Similarly, **esp32ap** and **12345678** for ESP32. You can change both by setting [apid](apiconfig.md#apid) and [psk](apiconfig.md#psk).
### <iclass="fa fa-caret-right"></i> Built-in OTA update feature
AutoConnect features a built-in OTA function to update ESP module firmware. You can easily make the Sketch that equips OTA and able to operate with the AutoConnect menu.
@ -194,13 +194,14 @@ Disable the first WiFi.begin() and start the captive portal. If this option is e
Configure applying items of the [AutoConnect menu](menu.md). You can arbitrarily combine valid menus by coordinating the menuItems value.
<dlclass="apidl">
<dt>**Type**</dt>
<dd><spanclass="apidef">uint16_t</span><spanclass="apidesc">It provides the combined **AC_MENUITEM_t** value of the item to apply to the AutoConnect menu.<br>Specify the value calculated from the **logical OR** by the AC_MENUITEM_t value of each item applied as a menu. It affects not only disappear the items from the menu also invalidates the URI they have. As a consequence, even if it accesses the URL directly will occur a 404 error.<br>The default value is logical OR of AC_MENUITEM_CONFIGNEW, AC_MENUITEM_OPENSSIDS, AC_MENUITEM_DISCONNECT, AC_MENUITEM_RESET and AC_MENUITEM_HOME.</span></dd>
<dd><spanclass="apidef">uint16_t</span><spanclass="apidesc">It provides the combined **AC_MENUITEM_t** value of the item to apply to the AutoConnect menu.<br>Specify the value calculated from the **logical OR** by the AC_MENUITEM_t value of each item applied as a menu. It affects not only disappear the items from the menu also invalidates the URI they have. As a consequence, even if it accesses the URL directly will occur a 404 error.<br>The default value is logical OR of AC_MENUITEM_CONFIGNEW, AC_MENUITEM_OPENSSIDS, AC_MENUITEM_DISCONNECT, AC_MENUITEM_RESET, AC_MENUITEM_UPDATE and AC_MENUITEM_HOME.</span></dd>
<dt>**Value**</dt>
<dd><spanclass="apidef">AC_MENUITEM_NONE</span><spanclass="apidesc"></span><spanclass="apidef"> </span><spanclass="apidesc">No assign items except for the AutoConnectAux page item.</span></dd>
<dd><spanclass="apidef">AC_MENUITEM_CONFIGNEW</span><spanclass="apidesc"></span><spanclass="apidef"> </span><spanclass="apidesc">Appends [Configure new AP](menu.md#config-new-ap) item.</span></dd>
<dd><spanclass="apidef">AC_MENUITEM_DEVINFO</span><spanclass="apidesc"></span><spanclass="apidef"> </span><spanclass="apidesc">Appends the **Device info** item which links to [AutoConnect statistics page](menu.md##where-the-from).</span></dd>
</dl>
@ -221,6 +222,18 @@ Sets subnet mask for Soft AP in captive portal. When AutoConnect fails the initi
<dd><spanclass="apidef">IPAddress</span><spanclass="apidesc">The default value is **255.255.255.0**</span></dd>
</dl>
### <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.
<dlclass="apidl">
<dt>**Type**</dt>
<dd>AC_OTA_t</dd>
<dt>**Value**</dt>
<dd><spanclass="apidef">AC_OTA_EXTRA</span><spanclass="apidesc"></span><spanclass="apidef"> </span><spanclass="apidesc">AutoConnect does not import AutoConnectOTA. This is the default.</span></dd>
<dd><spanclass="apidef">AC_OTA_BUILTIN</span><spanclass="apidesc"></span><spanclass="apidef"> </span><spanclass="apidesc">Specifies to include AutoConnectOTA in the Sketch.</span></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 (i.e. Attempting WiFi connection with the portal function). If 0, the captive portal will not be timed-out.
d="M 110.00865,33.59853 H 97.95942 c -0.26445,0 -0.47887,0.21442 -0.47887,0.47887 v 2.23473 c 0,0.26446 0.21442,0.47887 0.47887,0.47887 h 12.04923 v 1.83803 c 0,0.85327 1.03161,1.28058 1.63499,0.67724 l 3.43426,-3.43426 c 0.37404,-0.37404 0.37404,-0.98045 0,-1.35444 l -3.43426,-3.43427 c -0.60334,-0.60333 -1.63499,-0.17602 -1.63499,0.67725 z"
y="178.21082">Update class of Arduino core</tspan></text>
<path
id="path1371-5-3-0-2-8"
d="m 165.10961,86.653036 c 0,0.85326 1.03161,1.28057 1.63499,0.67723 l 3.43425,-3.43425 c 0.37404,-0.37405 0.37404,-0.98046 0,-1.35445 l -3.43425,-3.43427 c -0.60334,-0.60333 -1.63499,-0.17602 -1.63499,0.67725 -0.0135,2.99825 0,4.18637 0,6.86849 z"
d="m 165.10961,83.478034 c 0,0.85326 1.03161,1.28057 1.63499,0.67723 l 3.43425,-3.43425 c 0.37404,-0.37405 0.37404,-0.98046 0,-1.35445 l -3.43425,-3.43427 c -0.60334,-0.60333 -1.63499,-0.17602 -1.63499,0.67725 -0.0135,2.99825 0,4.18637 0,6.86849 z"
inkscape:connector-curvature="0"
style="fill:#3366cc;stroke-width:0.26458332"
sodipodi:nodetypes="ccccccc"
@ -504,7 +498,7 @@
inkscape:export-ydpi="115.2" />
<path
id="path1371-5-3-0-2-84"
d="m 180.30222,126.23079 v -17.38126 c 0,-0.26445 -0.21445,-0.56964 -0.47888,-0.57241 l -2.23472,-0.0234 c -0.26445,-0.003 -0.47888,0.34281 -0.47888,0.60751 v 17.36954 h -1.83803 c -0.85326,0 -1.28057,1.03161 -0.67723,1.63499 l 3.43425,3.43425 c 0.37405,0.37404 0.98046,0.37404 1.35445,0 l 3.43427,-3.43425 c 0.60333,-0.60334 0.17602,-1.63499 -0.67725,-1.63499 z"
d="m 180.30222,123.05577 v -17.38126 c 0,-0.26445 -0.21445,-0.56964 -0.47888,-0.57241 l -2.23472,-0.0234 c -0.26445,-0.003 -0.47888,0.34281 -0.47888,0.60751 v 17.36954 h -1.83803 c -0.85326,0 -1.28057,1.03161 -0.67723,1.63499 l 3.43425,3.43425 c 0.37405,0.37404 0.98046,0.37404 1.35445,0 l 3.43427,-3.43425 c 0.60333,-0.60334 0.17602,-1.63499 -0.67725,-1.63499 z"
### <iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Quick and easy to equip the [OTA update feature](otaupdate.md) <sup><sub>ENHANCED w/v1.0.0</sub></sup>
### <iclass="fa fa-arrow-circle-right"aria-hidden="true"></i> Quick and easy to equip the [OTA update feature](otaupdate.md) <sup><sub>UPDATED w/v1.1.5</sub></sup>
<spanclass="lead">You can quickly and easily equip the OTA update feature to your sketch and also you can operate the firmware update process via OTA from AutoConnect menu.</span>
@ -18,6 +18,7 @@ Currently, AutoConnect supports four menus. Undermost menu as "HOME" returns to
- **Open SSIDs**: Opens the past SSID which has been established connection from the flash.
- **Disconnect**: Disconnects current connection.
- **Reset...**: Rest the ESP8266/ESP32 module.
- **Update**: OTA updates. (Optional)
- **HOME**: Return to user home page.
<imgsrc="images/menu.png"style="width:280px;"/>
@ -66,6 +67,13 @@ Resetting the ESP8266/ESP32 module will initiate a reboot. When the module resta
If the sketch has custom Web pages, the AutoConnect menu lines them up with the AutoConnect's items. Details for [Custom Web pages in AutoConnect menu](acintro.md#custom-web-pages-in-autoconnectmenu).
## <iclass="fa fa-bars"></i> Update
If you specify [AutoConnectConfig::ota](apiconfig.md#ota) to import the OTA update feature into Sketch, an item will appear in the menu list as **Update**.
!!! note "The Update menu item will appear only AutoConnectOTA enabled"
The Update item is displayed automatically in the menu only when [AutoConnectConfig::ota](apiconfig.md#ota) is specified with **AC_OTA_BUILTIN** or [AutoConnectUpdate](otaserver.md#how-to-embed-autoconnectupdate-to-your-sketch) is attached.
## <iclass="fa fa-bars"></i> HOME
A **HOME** item at the bottom of the menu list is a link to the home path, and the default URI is `/` which is defined by `AUTOCONNECT_HOMEURI` in **AutoConnectDefs.h** header file.
## Updates with the Web Browser <sup><sub>UPDATED w/v1.1.5</sub></sup>
You can implement the user sketch as described in the [ESP8266 Arduino Core documentation](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#implementation-overview) to realize using the web browser as an update client. By incorporating the ESP8266HTTPUpdateServer class into AutoConnect, you can operate the dialog page for selecting the updating binary sketch file owned by ESP8266HTTPUpdateServer from the AutoConnect menu.
AutoConnect features a built-in OTA function to update ESP module firmware. You can easily make the Sketch that equips OTA and able to operate with the AutoConnect menu. As the **AutoConnectOTA** class, which is compliant with OTA updates using a web browser as described in the [ESP8266 Arduino Core documentation](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#implementation-overview).
Update feature with a web browser is implemented using ESP8266HTTPUpdateServer class and ESP8266mDNS class. However, **ESP32 Arduino core does not provide a class implementation equivalent to ESP8266HTTPUpdateServer**. Therefore, it is necessary to implement an HTTPUpdateServer class for ESP32 to realize the update using a Web browser. **The AutoConnect library includes an implementation of the HTTPUpdateServer class for ESP32 to make it easy for you to experience**. [^1]
You will be able to import the AutoConnectOTA class into your sketch just by specifying [AutoConnectConfig::ota](apiconfig.md#ota). By incorporating the AutoConnectOTA class into your Sketch, you can have an OTA updating feature which able to updating binary sketch from the AutoConnect menu.
[^1]: You can find the implementation of the **HTTPUpdateServer** class in the **WebUpdate** folder included in the **AutoConnect library examples folder**.
The AutoConnectOTA feature is implemented based on the [Updater class](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#updater-class) of the ESP8266 arduino core library. Its Updater class is also supported by the ESP32 Arduino core, so you can commonly import AutoConnectOTA into the Sketch without being aware of the differences between ESP8266 and ESP32 modules.
<imgsrc="images/webupdate.png"width="480"/>
!!! warning "For the client devices equipped with Android OS"
Depending on the state of Android OS configuration, Bonjour service may not be incorporated. This method does not work with some Android devices as the client.
!!! info "Limitation of AutoConnectOTA with authentication"
AutoConnectOTA does not support authentication in v1.1.5 yet. It is planned for inclusion in AutoConnect v1.2.0, which will support HTTP authentication.
### <iclass="fa fa-edit"></i> How to embed AutoConnectOTA in your sketch
To embed the AutoConnectOTA class into your sketch, basically follow these steps:
1. Include `ESP8266WiFi.h`, `ESP8266WebServer.h` and `AutoConnect.h` as usual.[^1]
2. Declare an ESP8266WebServer object. It's optional. (as WebServer for ESP32)
3. Declare an AutoConnect object, with an argument as ESP8266WebServer if separate the declarations.
4. Declare an AutoConnectConfig object.
5. Declare an AutoConnectAux object for your sketch own if needed.
6. Perform the following procedure steps in the `setup()` function:
1. Set [AutoConnectConfig::ota](apiconfig.md#ota) to **AC_OTA_BUILTIN** and configure AutoConnect.
2. Load the AutoConnectAux pages declared in step #4 for your application.
{ "name": "content", "type": "ACText", "value": "In this page, place the custom web page handled by the sketch application." } ]
}
)"; // Step #5
void setup() {
config.ota = AC_OTA_BUILTIN; // Step #6.a
portal.config(config); // Step #6.a
hello.load(HELLO_PAGE); // Step #6.b
portal.join({ hello }); // Step #6.c
portal.begin(); // Step #6.d
}
void loop() {
portal.handleClient(); // Step #7
}
```
[^1]:For ESP32, change the following items:
- Change the include directives appropriately for the ESP32 environment.
- Change ESP8266WebServer to Web.
!!! faq "How LED ticking during updates"
AutoConnectOTA applies LED ticking during updates automatically. The destination LED port and ticker drive depends on [AutoConnectConfig::tickerPort](apiconfig.md#tickerport) and [AutoConnectConfig::tickerOn](apiconfig.md#tickeron) specifying.
**IMPORTANT**
The AutoConnectOTA activates the ticker constantly regardless of the [AutoConnectConfig::ticker](apiconfig.md#ticker) value. If you want to stop the ticker output to GPIO during updates, give `0xff` to [AutoConnectConfig::tickerPort](apiconfig.md#tickerport).
### <iclass="fa fa-wrench"></i> AutoConnectOTA allocation URI
AutoConnectOTA has implemented using AutoConnectAUX. So it occupies two URIs by default. An update operation page is assigned to **AUTOCONNECT_URI_UPDATE** and the binary file uploader for the update is assigned to **AUTOCONNECT_URI_UPDATE_ACT**. These symbols are defined in the `AutoConnectDefs.h` header file as follows:
Therefore, the normal Sketch that imports AutoConnectOTA while keeping the default, you cannot use the two URIs `/_ac/update` and `/_ac/update_act` for your specific. If you want to use the URIs for any purpose other than AutoConnectOTA, you need to override the `AutoConnectDefs.h` definition at compile time. It can be overwritten by giving the build flags for platformio.ini as follows with the PlatformIO environment for example.
```ini
build_flags =
-DAUTOCONNECT_URI_UPDATE='"/YOURURI"'
-DAUTOCONNECT_URI_UPDATE_ACT='"/YOURURIACT"'
```
### <iclass="fa fa-wrench"></i> Timing of AutoConnectOTA instantiation
It will be born during [AutoConnect::handleClient](api.md#handleclient) process. AutoConnect will evaluate the enabled state of [AutoConnectConfig::ota](apiconfig.md#ota) each time the handleClient is executed, and if OTA is enabled then it creates an AutoConnectAux internally and assigns it to the update page. At this time, AutoConnectOTA is also instantiated together. The generated AUX page containing AutoConnectOTA is bound to AutoConnect inside the AutoConnect::handleClient process.
If you want to attach AutoConnectOTA dynamically with an external trigger, you can sketch like this:
_This sketch imports the OTA update feature with an external switch assigned to the GPIO pin. While the trigger not occurs, AutoConnect OTA will not be imported into Sketch and will not appear on the menu list._
```cpp
#include<ESP8266WiFi.h>
#include<ESP8266WebServer.h>
#include<AutoConnect.h>
#define TRIGGER 4 // pin assigned to external trigger switch
Once imported, AutoConnectOTA cannot be removed from the Sketch. It can be only excluded from the menu by overriding [AutoConnectConfig::menuItems](apiconfig.md#menuitems). In this case, the AutoConnectOTA instance remains as a residue.
### <iclass="fa fa-wrench"></i> How to make the binary sketch
Binary sketch files for updating can be retrieved using the Arduino IDE. Open the **Sketch** menu and select the **Export compiled Binary**, then starts compilation.
<imgsrc="images/export_binary.png"width="450"/>
When the compilation is complete, a binary sketch will save with the extension `.bin` in the same folder as the sketch.
### <iclass="fa fa-edit"></i> How to embed ESP8266HTTPUpdateServer in AutoConnect
### <iclass="fa fa-edit"></i>OTA updates w/browser without using AutoConnectOTA
The legacy OTA method based on ESP8266HTTPUpdateServer without AutoConnectOTA is still valid.
To embed the ESP8266HTTPUpdateServer class with AutoConnect into your sketch, basically follow these steps:
1. Include `ESP8266mDNS.h` and `ESP8266HTTPUpdateServer.h`, also `WiFiClient.h`, in addition to the usual directives as `ESP8266WebServer.h` and `AutoConnect.h`.
1. Include `ESP8266HTTPUpdateServer.h`, also `WiFiClient.h`, in addition to the usual directives as `ESP8266WebServer.h` and `AutoConnect.h`.
2. Declare an ESP8266WebServer object. (In ESP32, as WebServer)
3. Declare an ESP8266HTTPUpdateServer object.
4. Declare an AutoConnect object with an ESP8266WebServer object as an argument.
@ -28,16 +148,12 @@ To embed the ESP8266HTTPUpdateServer class with AutoConnect into your sketch, ba
2. Load the AutoConnectAux pages declared in step #8 for your application. (Except the update dialog page)
3. Join these pages to AutoConnect along with the update dialog page declared in step #5.
This procedure is equally applicable to ESP32. If the target module is ESP32, change the following items:
- Change the include directives appropriately for the ESP32 environment.
- Change ESP8266HTTPUpdaetServer to HTTPUpdateServer using an implementation provided from AutoConnect library example code.
- Remove `MDNS.update` line from the sketch code.
!!! example "Share an ESP8266WebServer"
AutoConnect shares the ESP8266WebServer instance with the ESP8266HTTPUpdateServer class. You can give the same instance as ESP8266WebServer instance given to AutoConnect to ESP8266HTTPUpdateServer class.
```cpp
ESP8266WebServer httpServer;
ESP8266HTTPUpdateServer updateServer;
AutoConnect portal(httpServer);
updateServer(&httpServer);
```
This sharing specification is the same for ESP32.
The result of the above sketch should be as follows. [^2]
[^2]: The authentication dialog is displayed first.
You **cannot** get the ticker with LED during updates by using this way. It is since the current implementation of the ESP8266HTTPUpdateServer class of the Arduino core **library does not assign an LED PIN** to the ESP8266HTTPUpdate class.
### <iclass="fa fa-wrench"></i> How to make the binary sketch
Binary sketch files for updating can be retrieved using the Arduino IDE. Open the **Sketch** menu and select the **Export compiled Binary**, then starts compilation.
<imgsrc="images/export_binary.png"width="450"/>
When the compilation is complete, a binary sketch will save with the extension `.bin` in the same folder as the sketch.
AutoConnect provides **two type platforms** for updating the binary sketch in the ESP8266 or ESP32 module via OTA. They correspond to the [Web Browser Update](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#web-browser) and [HTTP Server Update](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#http-server) whiches mentioned in the [ESP8266 Arduino Core documentation](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html#ota-updates).
[**The update behavior using a web browser**](otabrowser.md) as the client that supplies the binary sketch file for update follows the scenario assumed by the ESP8266 Arduino core. Therefore, the user sketch must meet the requirements described in the ESP8266 Arduino Core documentation, but you can easily embed the update feature that able to handle with the web browser by AutoConnect. All you need to do is that [join](api.md#join) the [AutoConnectAux](apiaux.md) with embedded **ESP8266HTTPUpdateServer**[^1] of the core library to AutoConnect.
[**The update behavior using a web browser**](otabrowser.md) as the client that supplies the binary sketch file for update follows the scenario assumed by the ESP8266 Arduino core. Therefore, the user sketch must meet the requirements described in the ESP8266 Arduino Core documentation, but you can easily embed the OTA update feature that able to operate via the web browser by AutoConnect menu. All you need to do is that specify [AutoConnectConfig](apiconfig.md#ota).
[^1]: The AutoConnect library provides an implementation of the **HTTPUpdateServer** class that ported from ESP8266HTTPUpdateServer class for ESP32 intention. It is contained the **WebUpdate** under the examples folder.
Hieromon Ikasamo
5 years ago
