diff --git a/mkdocs.yml b/mkdocs.yml index 8e55049..fe8f920 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,13 +8,23 @@ site_url: 'https://Hieromon.github.io/AutoConnect/' docs_dir: 'mkdocs' # Pages -pages: +nav: - 'Overview' : index.md - 'Getting started' : gettingstarted.md - 'AutoConnect menu' : menu.md - 'Basic usage' : basicusage.md - 'Advanced usage' : advancedusage.md - - 'Library APIs' : api.md + - 'Custom Web pages' : + - 'Custom Web pages with AutoConnect' : acintro.md + - 'AutoConnectElements' : acelements.md + - 'AutoConnectAux with JSON' : acjson.md + - 'Handling AutoConnectAux' : achandling.md + - 'Library APIs' : + - 'AutoConnect API': api.md + - 'AutoConnectConfig API': apiconfig.md + - 'AutoConnectAux API': apiaux.md + - 'AutoConnectElements API': apielements.md + - 'Something extra': apiextra.md - 'Examples' : examples.md - 'FAQ' : faq.md - 'Change log' : changelog.md @@ -62,10 +72,12 @@ google_analytics: # Extensions markdown_extensions: + - attr_list - admonition - footnotes - pymdownx.betterem: smart_enable: all + - pymdownx.caret - pymdownx.critic - pymdownx.details - pymdownx.inlinehilite diff --git a/mkdocs/acelements.md b/mkdocs/acelements.md new file mode 100644 index 0000000..45fa474 --- /dev/null +++ b/mkdocs/acelements.md @@ -0,0 +1,35 @@ +## The elements for the custome Web pages + +Representative HTML elements for making the custom Web page are provided as AutoConnectElements. + +- AutoConnectButton: Labeled action button +- AutoConnectCheckbox: Labeled checkbox +- AutoConnectElement: General tag +- AutoConnectInput: Labeled text input box +- AutoConnectRadio: Labeled radio button +- AutoConnectSelect: Selection list +- AutoConnectSubmit: Submit button +- AutoConnectText: Style attributed text + +Each element has a common attribute and its own attributes. + +## Layout on custom Web page + +You can specify the direction to arrange the radio buttons as **AutoConnectRadio** vertically or horizontally. The checkbox as **AutoConnectCheckbox** is not divided in a line by each element. In order to arrange vertically, it is necessary to clearly indicate the **<br>** tag. Other elements are aligned vertically. This basic layout depends on the CSS of the AutoConnect menu so it can not be changed drastically. + +## AutoConnectElement - A basic class of elements + +## AutoConnectButton + +## AutoConnectCheckbox + +## AutoConnectInput + +## AutoConnectRadio + +## AutoConnectSelect + +## AutoConnectSubmit + +## AutoConnectText + diff --git a/mkdocs/achandling.md b/mkdocs/achandling.md new file mode 100644 index 0000000..860d924 --- /dev/null +++ b/mkdocs/achandling.md @@ -0,0 +1,7 @@ + + +## loading and saving AutoConnectElements + +## page transition + +## Parameter handling diff --git a/mkdocs/acintro.md b/mkdocs/acintro.md new file mode 100644 index 0000000..61871c8 --- /dev/null +++ b/mkdocs/acintro.md @@ -0,0 +1,82 @@ +## What it is + + +AutoConnect can handle custom Web pages prepared by user sketches individually. Custom Web pages are displayed in the [AutoConnect menu](menu.md) and can be used from there. It can also have input-output parameters and handle it with sketches. For example, you can program some sketches that publish messages by entering the URI or unique ID of the MQTT broker on a custom page. You do not need to code the processing to handle the web page, it retrieves the input parameters and passes to the MQTT broker connection API is only. + +## How it works + +Custom Web pages are dynamically created by AutoConnect. The Classes and APIs necessary for dynamic creation are provided. **AutoConnectAux** is an object dependent on AutoConnect, which provides an easy way to incorporate custom Web pages like the one on the right figure into AutoConnect. The elements that make up a custom web page are provided as an [**AutoConnectElement**](acelements.md) class. Furthermore, an input box, a check box, a submit button, etc. are implemented by classes derived from AutoConnectElement. + + + +AutoConnectAux is a container for AutoConnectElements. To make a custom Web page, create elements that make up the page and put it in the AutoConnectAux object. Joining that AutoConnectAux object to AutoConnect will integrate the custom Web page into the AutoConnect menu. + + + +The above figure shows a code sequence that declares AutoConnectElements and put in the AutoConnectAux container and integrates those into AutoConnect. Declare two text elements named '*header*', '*caption*' and add those to the AutoConnectAux object *aux*. Bind it to an AutoConnect object called the '*portal*'. It's basic procedure for configuring the custom Web page. Also, further explanation of AutoConnectElements is the [documentation](acelements.md). + +## Custom Web pages in AutoConnect menu + + + +[^1]:There is no overlay in the actual menu. + +## Multiple custom Web pages + +You can create multiple custom pages, integrate them into the AutoConnect menu, and specify pages to invokes from the menu. The following code combines three AutoConnectAuxs to a AutoConnect object as '*portal*'. + + + + + +## Basic steps to use custom Web pages + +So, the basic procedure is as follows. + +1. Create or define AutoConnectAux. +2. Create or define [AutoConnectElement(s)](acelements.md). +3. Add [AutoConnectElement(s)](acelements.md) to AutoConnectAux. +4. Create more AutoConnectAux containing [AutoConnectElement(s)](acelements.md), if necessary. +5. Join prepared AutoConnectAux(s) to [AutoConnect](api.md#autoconnect-api). +6. Invoke [AutoConnect::begin()](api.md#begin). + +[^2]: + The sketch is actually this: + ```cpp + #include + #include + #include + + AutoConnect portal; + + ACText(header, "MQTT broker settings"); + ACText(caption1, "Publishing the WiFi..."); + ACSubmit(save, "SAVE", "/mqtt_save"); + AutoConnectAux aux1("/mqtt_setting", "MQTT Setting", { header, caption1, save }); + + ACText(caption2, "Save parameters"); + ACSubmit(start, "START", "/mqtt_start"); + AutoConnectAux aux2("/mqtt_save", "MQTT Setting", false, { caption2, start }); + + AutoConnectAux aux3("/mqtt_start", "MQTT Start"); + + void setup() { + portal.join({ aux1, aux2, aux3 }); + portal.begin(); + } + + void loop() { + portal.handleClient(); + } + ``` + + diff --git a/mkdocs/acjson.md b/mkdocs/acjson.md new file mode 100644 index 0000000..58e8174 --- /dev/null +++ b/mkdocs/acjson.md @@ -0,0 +1 @@ +To process the described AutoConnect element written in the JSON is you need to install the ArduinoJson library. \ No newline at end of file diff --git a/mkdocs/advancedusage.md b/mkdocs/advancedusage.md index a4e0fcf..621edb5 100644 --- a/mkdocs/advancedusage.md +++ b/mkdocs/advancedusage.md @@ -134,6 +134,31 @@ Also, the placement of the EEPROM area of ESP32 is described in the [partition t 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. +### On-demand start the captive portal + +If you do not usually connect to WiFi and need to establish a WiFi connection if necessary, you can combine the [**autoRise**](api.md#autorise) option with the [**immediateStart**](api.md#immediatestart) option to achieve on-demand connection. This behavior is similar to the [WiFiManager's startConfigPortal](https://github.com/tzapu/WiFiManager#on-demand-configuration-portal) function. In order to do this, you usually configure only with AutoConnectConfig in *setup()* and [*AutoConnect::begin()*](api.md#begin) handles in *loop()*. + +```arduino hl_lines="5 6" +AutoConnect Portal; +AutoConnectConfig Config; + +void setup() { + Config.autoRise = false; + Config.immediateStart = true; + Portal.config(Config); +} + +void loop() { + if (digitalRead(TRIGGER_PIN) == LOW) { + while (digitalRead(TRIGGER_PIN) == LOW) + yield(); + Portal.begin(); + } + Portal.handleClient(); +} +``` +The above example does not connect to WiFi until TRIGGER\_PIN goes LOW. When TRIGGER\_PIN goes LOW, the captive portal starts and you can connect to WiFi. Even if you reset the module, it will not automatically reconnect. + ### Refers the hosted ESP8266WebServer/WebServer 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. @@ -204,7 +229,7 @@ An example sketch used with the PageBuilder as follows and it explains how it ai ## Configuration functions -### Configuration for Soft AP +### Configuration for Soft AP and captive portal AutoConnect will activate SoftAP at failed the first *WiFi.begin*. It SoftAP settings are stored in [**AutoConnectConfig**](api.md#autoconnectconfig) as the following parameters. The sketch could be configured SoftAP using these parameters, refer the [AutoConnectConfig API](api.md#autoconnectconfig-api) for details. @@ -214,11 +239,13 @@ AutoConnect will activate SoftAP at failed the first *WiFi.begin*. It SoftAP set - SSID for SoftAP. - Password for SoftAP. - Channel. +- SoftAP name. - Hidden attribute. - Auto save credential. - Offset address of the credentials storage area in EEPROM. - Length of start up time after reset. - Automatic starting the captive portal. +- Start the captive portal forcely. - Auto reset after connection establishment. - Home URL of the user sketch application. @@ -265,3 +292,7 @@ portal.begin(); ``` [^2]:Static IP address assignment is available from version 0.9.3. + +### Station host name + + diff --git a/mkdocs/api.md b/mkdocs/api.md index f6d11f2..eb28adf 100644 --- a/mkdocs/api.md +++ b/mkdocs/api.md @@ -1,12 +1,14 @@ -## Include headers +## Include headers -### AutoConnect.h +### AutoConnect.h ```cpp #include ``` -#### Defined macros +## Defined macros + +They contain in ```AutoConnectDefs.h```. ```cpp #define AC_DEBUG // Monitor message output activation @@ -26,11 +28,9 @@ !!! note "Macros placement moved" Source code placement of the above macros provided for user sketch changed from v0.9.7. The new code is in ```AutoConnectDefs.h```. -## AutoConnect API - -### Constructors +## Constructors -#### AutoConnect +### AutoConnect ```cpp AutoConnect() @@ -54,15 +54,28 @@ 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/WebServer. If ESP8266WebServer/WebServer 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.md#host) function.
**Parameters**
webServerA reference of ESP8266WebServer or WebServer instance.
-### Public member functions +## Public member functions -#### begin +### aux + +```cpp +AutoConnectAux* aux(const String& uri) const +``` +Returns a pointer to AutoConnectAux with the URI specified by *uri*. If AutoConnectAux with that URI is not bound, it returns **nullptr**. +
+
**Parameters**
+
uriURI string.
+
**Return value**
+
A Pointer of the AutoConnectAux instance.
+
+ +### begin ```cpp bool begin() @@ -87,7 +100,7 @@ The captive portal will not be started if the connection has been established wi
falseCould not connected, Captive portal started with WIFI_AP_STA mode.
-#### config +### config ```cpp bool config(AutoConnectConfig& config) @@ -107,7 +120,7 @@ Set SoftAP's WiFi configuration and static IP configuration.
falseConfiguration parameter is invalid, some values out of range.
-#### end +### end ```cpp void end() @@ -118,7 +131,7 @@ Stops AutoConnect captive portal service. Release ESP8266WebServer/WebServer and !!! warning "Attention to end" The end function releases the instance of ESP8266WebServer/WebServer and DNSServer. It can not process them after the end function. -#### handleClient +### handleClient ```cpp void handleClient() @@ -126,7 +139,7 @@ void 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 +### handleRequest ```cpp void handleRequest() @@ -137,7 +150,7 @@ 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 ESP8266WebServer::handleClient or WebServer::handleClient. -#### home +### home ```cpp void home(String uri) @@ -149,9 +162,7 @@ Put a user site's home URI. The URI specified by home is linked from "HOME" in t
uri A URI string of user site's home path.
-#### host - -Returns the reference of the ESP8266WebServer/WebServer which is allocated in AutoConnect automatically. +### host - For ESP8266 @@ -164,6 +175,8 @@ ESP8266WebServer& host() ```cpp WebServer& host() ``` + +Returns the reference of the ESP8266WebServer/WebServer which is allocated in AutoConnect automatically.
**Return value**
A reference of the ESP8266WebServer/WebServer.
@@ -180,7 +193,43 @@ WebServer& host() portal.host().handleClient(); ``` -#### onDetect +### join + +```cpp +void join(AutoConnectAux& aux) +``` +```cpp +void join(std::vector> aux) +``` +Join the AutoConnectAux object to AutoConnect. AutoConnectAux objects can be joined one by one, or joined altogether. The AutoConnectAux object joined by the join function can be handled from the AutoConnect menu. +
+
**Parameters**
+
auxReference to AutoConnectAux. It can be std::vector of std::reference_wrapper of AutoConnectAux with [list initialization](https://en.cppreference.com/w/cpp/language/list_initialization).
+
+ +### load + +```cpp +bool load(const String& aux) +``` +```cpp +bool load(const __FlashStringHelper* aux) +``` +```cpp +bool load(Stream& aux) +``` +Load + +### on + +```cpp +bool on(const String& uri, const AuxHandlerFunctionT handler, AutoConnectExitOrder_t order = AC_EXIT_AHEAD) +``` + +!!! caution "It is not ESP8266WebServer::on, not WebServer::on for ESP32." + This function effects to AutoConnectAux only. However, it coexists with that of ESP8266WebServer::on or WebServer::on of ESP32. + +### onDetect ```cpp void onDetect(DetectExit_ft fn) @@ -205,7 +254,7 @@ typedef std::function DetectExit_ft
falseCancel the captive portal. AutoConnect::begin function will return with a false.
-#### onNotFound +### onNotFound - For ESP8266 @@ -223,243 +272,3 @@ Register the handler function for undefined URL request detected.
**Parameters**
fnA function of the "not found" handler.
- -## AutoConnectConfig API - -### Constructor - -#### AutoConnectConfig - -```cpp -AutoConnectConfig(); -``` -```cpp -AutoConnectConfig(const char* ap, const char* password); -``` -
-
**Parameters**
-
apSSID for SoftAP. The length should be up to 31. The default value is **esp8266ap** for ESP8266, **esp32ap** for ESP32.
-
passwordPassword for SodtAP. The length should be from 8 to up to 63. The default value is **12345678**.
-
- -### Public member variables - -#### apid -SoftAP's SSID. -
-
**Type**
-
String
-
- -#### 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. -
-
**Type**
-
IPAddressThe default value is **192.168.244.1**
-
- -#### 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. -
-
**Type**
-
bool
-
**Value**
-
trueReconnect automatically.
-
falseStarts Captive Portal in SoftAP + STA mode without trying to reconnect. This is the default.
-
- -When the autoReconnect option is enabled, an automatic connection will behave if the following conditions are satisfied. - -- 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 - -Reset ESP8266 module automatically after WLAN disconnected. -
-
**Type**
-
bool
-
**Value**
-
trueReset after WiFi disconnected automatically.
-
falseNo reset.
-
- -#### autoRise - -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. -
-
**Type**
-
bool
-
**Value**
-
trueEnable the captive portal. This is the default.
-
falseDisable the captive portal.
-
- -#### autoSave - -The credential saved automatically at the connection establishment. -
-
**Type**
-
AC_SAVECREDENTIAL_t
-
**Value**
-
AC_SAVECREDENTIAL_AUTOThe credential saved automatically. This is the default.
-
AC_SAVECREDENTIAL_NEVERThe credential no saved.
-
- -#### boundaryOffset - -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. -
-
**Type**
-
uint16_t
-
- -!!! 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 - -The channel number of WIFi when SoftAP starts. -
-
**Type**
-
uint8_t
-
**Value**
-
1 ~ 14. The default value is 1.
-
- -!!! 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 - -Set primary DNS server address when using static IP address. -
-
**Type**
-
IPAddress
-
- -#### dns2 - -Set secondary DNS server address when using static IP address. -
-
**Type**
-
IPAddress
-
- -#### 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. -
-
**Type**
-
IPAddressThe default value is **192.168.244.1**
-
- -#### hidden - -Sets SoftAP to hidden SSID. -
-
**Type**
-
uint8_t
-
**Value**
-
0SSID will be appeared. This is the default.
-
1SSID will be hidden.
-
- -#### homeUri - -Sets the home path of user sketch. This path would be linked from 'HOME' in the AutoConnect menu. -
-
**Type**
-
String
-
- -#### 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. -
-
**Type**
-
IPAddressThe default value is **255.255.255.0**
-
- -#### psk - -Sets password for SoftAP. The length should be from 8 to up to 63. The default value is **12345678**. -
-
**Type**
-
String
-
- -#### staip - -Set a static IP address. The IP will behave with STA mode. -
-
**Type**
-
IPAddress
-
- -#### staGateway - -Set the gateway address when using static IP address. -
-
**Type**
-
IPAddress
-
- -#### staNetmask - -Set the subnetmask when using static IP address. -
-
**Type**
-
IPAddress
-
- -### AutoConnectConfig example - -```arduino -AutoConenct Portal; -AutoConenctConfig Config("", "passpass"); // SoftAp name is determined at runtime -Config.apid = ESP.hostname(); // Retrieve host name to SotAp identification -Config.apip = IPAddress(192,168,10,101); // Sets SoftAP IP address -Config.gateway = IPAddress(192,168,10,1); // Sets WLAN router IP address -Config.netmask = IPAddress(255,255,255,0); // Sets WLAN scope -Config.autoReconnect = true; // Enable auto-reconnect -Config.autoSave = AC_SAVECREDENTIAL_NEVER; // No save credential -COnfig.boundaryOffet = 64; // Reserve 64 bytes for the user data in EEPROM. -Config.homeUri = "/index.html" // Sets home path of the sketch application -Config.staip = IPAddress(192,168,10,10); // Sets static IP -Config.staGateway = IPAddress(192,168,10,1); // Sets WiFi router address -Config.staNetmask = IPAddress(255,255,255,0); // Sets WLAN scope -Config.dns1 = IPAddress(192,168,10,1); // Sets primary DNS address -Portal.config(Config); // Configure AutoConnect -Portal.begin(); // Starts and behaves captive portal -``` - -## Something extra - -The library presents two PNG icons which can be used to embed a hyperlink to the AutoConnect menu. - -- Bar type AutoConnect menu -- Cog type AutoConnect menu - -To reference the icon, use the **AUTOCONNECT_LINK** macro in the sketch. It expands into the string literal as an HTML `````` tag with PNG embedded of the AutoConnect menu hyperlinks. Icon type is specified by the parameter of the macro. - -
-
BAR_24Bars icon, 24x24.
-
BAR_32Bars icon, 32x32.
-
BAR_48Bars icon, 48x48.
-
COG_24Cog icon, 24x24.
-
COG_32Cog icon, 32x32.
-
- -!!! note "Usage" - ```arduino - String html = ""; - html += AUTOCONNECT_LINK(BAR_32); - html += ""; - server.send(200, "text/html", html); - ``` - diff --git a/mkdocs/apiaux.md b/mkdocs/apiaux.md new file mode 100644 index 0000000..68203d0 --- /dev/null +++ b/mkdocs/apiaux.md @@ -0,0 +1,37 @@ +## Constructor + +### AutoConnectAux + +```cpp +AutoConnectAux(const String& uri = String(""), const String& title = String(""), const bool menu = true, const AutoConnectElementVT addons = AutoConnectElementVT()) +``` + +## Public member functions + +### add + +```cpp +void add(AutoConnectElement& addon) +``` +```cpp +void add(AutoConnectElementVT addons) +``` +Add an element to the auxiliary page. Add the element set to the auxiliary page. + + + template + T& getElement(const String& name); + AutoConnectElement* getElement(const String& name); /**< Get registered AutoConnectElement as specified name */ + void menu(const bool post) { _menu = post; } /**< Set or reset the display as menu item for this aux */ + bool release(const String& name); /**< Release an AutoConnectElement */ + bool setElementValue(const String& name, const String value); /**< Set value to specified element */ + bool setElementValue(const String& name, std::vector const& values); /**< Set values collection to specified element */ + void setTitle(const String title) { _title = title; } /**< Set a title of the auxiliary page */ + void on(const AuxHandlerFunctionT handler, const AutoConnectExitOrder_t order = AC_EXIT_AHEAD) { _handler = handler; _order = order; } /**< Set user handler */ + bool load(const String& in); /**< Load whole elements to AutoConnectAux Page */ + bool load(const __FlashStringHelper* in); /**< Load whole elements to AutoConnectAux Page */ + bool load(Stream& in); /**< Load whole elements to AutoConnectAux Page */ + bool loadElement(const String& in, const String& name = String("")); /**< Load specified element */ + bool loadElement(const __FlashStringHelper* in, const String& name = String("")); /**< Load specified element */ + bool loadElement(Stream& in, const String& name = String("")); /**< Load specified element */ + size_t saveElement(Stream& out, std::vector const& names = {}); /**< Write elements of AutoConnectAux to the stream */ diff --git a/mkdocs/apiconfig.md b/mkdocs/apiconfig.md new file mode 100644 index 0000000..10be39a --- /dev/null +++ b/mkdocs/apiconfig.md @@ -0,0 +1,241 @@ +## Constructor + +### AutoConnectConfig + +```cpp +AutoConnectConfig(); +``` +```cpp +AutoConnectConfig(const char* ap, const char* password); +``` +
+
**Parameters**
+
apSSID for SoftAP. The length should be up to 31. The default value is **esp8266ap** for ESP8266, **esp32ap** for ESP32.
+
passwordPassword for SodtAP. The length should be from 8 to up to 63. The default value is **12345678**.
+
+ +## Public member variables + +### apid +SoftAP's SSID. +
+
**Type**
+
String
+
+ +### 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. +
+
**Type**
+
IPAddressThe default value is **192.168.244.1**
+
+ +### 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. +
+
**Type**
+
bool
+
**Value**
+
trueReconnect automatically.
+
falseStarts Captive Portal in SoftAP + STA mode without trying to reconnect. This is the default.
+
+ +When the autoReconnect option is enabled, an automatic connection will behave if the following conditions are satisfied. + +- 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 + +Reset ESP8266 module automatically after WLAN disconnected. +
+
**Type**
+
bool
+
**Value**
+
trueReset after WiFi disconnected automatically.
+
falseNo reset.
+
+ +### autoRise + +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. +
+
**Type**
+
bool
+
**Value**
+
trueEnable the captive portal. This is the default.
+
falseDisable the captive portal.
+
+ +### autoSave + +The credential saved automatically at the connection establishment. +
+
**Type**
+
AC_SAVECREDENTIAL_t
+
**Value**
+
AC_SAVECREDENTIAL_AUTOThe credential saved automatically. This is the default.
+
AC_SAVECREDENTIAL_NEVERThe credential no saved.
+
+ +### 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. +
+
**Type**
+
AC_ONBOOTURI_t
+
**Value**
+
AC_ONBOOTURI_ROOTResetting the module redirects it to the AutoConnect root path. The root path is assumed to be AUTOCONNECT_URI defined in AutoConnectDefs.h.
+
AC_ONBOOTURI_HOMEIt is redirected to the uri specified by [**AutoConnectConfig::homeUri**](api.md#homeuri).
+
+ +### boundaryOffset + +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. +
+
**Type**
+
uint16_t
+
+ +!!! 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 + +The channel number of WIFi when SoftAP starts. +
+
**Type**
+
uint8_t
+
**Value**
+
1 ~ 14. The default value is 1.
+
+ +!!! 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 + +Set primary DNS server address when using static IP address. +
+
**Type**
+
IPAddress
+
+ +#### dns2 + +Set secondary DNS server address when using static IP address. +
+
**Type**
+
IPAddress
+
+ +### 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. +
+
**Type**
+
IPAddressThe default value is **192.168.244.1**
+
+ +### hidden + +Sets SoftAP to hidden SSID. +
+
**Type**
+
uint8_t
+
**Value**
+
0SSID will be appeared. This is the default.
+
1SSID will be hidden.
+
+ +### homeUri + +Sets the home path of user sketch. This path would be linked from 'HOME' in the AutoConnect menu. The default for homeUri is "/". +
+
**Type**
+
String
+
+ +### hostName + +Sets the station host name of ESP8266/ESP32. +
+
**Type**
+
String
+
+ +### immediateStart + +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 [**autoRise::AutoConnectConfig**](api.md#autorise) specification. +
+
**Type**
+
bool
+
**Value**
+
trueStart the captive portal with [**AutoConnect::begin**](api.md#begin).
+
falseEnable the first WiFi.begin() and it will start captive portal when connection failed. This is default.
+
+ +### 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. +
+
**Type**
+
IPAddressThe default value is **255.255.255.0**
+
+ +### psk + +Sets password for SoftAP. The length should be from 8 to up to 63. The default value is **12345678**. +
+
**Type**
+
String
+
+ +### staip + +Set a static IP address. The IP will behave with STA mode. +
+
**Type**
+
IPAddress
+
+ +### staGateway + +Set the gateway address when using static IP address. +
+
**Type**
+
IPAddress
+
+ +### staNetmask + +Set the subnetmask when using static IP address. +
+
**Type**
+
IPAddress
+
+ +## AutoConnectConfig example + +```arduino +AutoConenct Portal; +AutoConenctConfig Config("", "passpass"); // SoftAp name is determined at runtime +Config.apid = ESP.hostname(); // Retrieve host name to SotAp identification +Config.apip = IPAddress(192,168,10,101); // Sets SoftAP IP address +Config.gateway = IPAddress(192,168,10,1); // Sets WLAN router IP address +Config.netmask = IPAddress(255,255,255,0); // Sets WLAN scope +Config.autoReconnect = true; // Enable auto-reconnect +Config.autoSave = AC_SAVECREDENTIAL_NEVER; // No save credential +COnfig.boundaryOffet = 64; // Reserve 64 bytes for the user data in EEPROM. +Config.homeUri = "/index.html" // Sets home path of the sketch application +Config.staip = IPAddress(192,168,10,10); // Sets static IP +Config.staGateway = IPAddress(192,168,10,1); // Sets WiFi router address +Config.staNetmask = IPAddress(255,255,255,0); // Sets WLAN scope +Config.dns1 = IPAddress(192,168,10,1); // Sets primary DNS address +Portal.config(Config); // Configure AutoConnect +Portal.begin(); // Starts and behaves captive portal +``` diff --git a/mkdocs/apiextra.md b/mkdocs/apiextra.md new file mode 100644 index 0000000..588f110 --- /dev/null +++ b/mkdocs/apiextra.md @@ -0,0 +1,24 @@ +## Icons + +The library presents two PNG icons which can be used to embed a hyperlink to the AutoConnect menu. + +- Bar type AutoConnect menu +- Cog type AutoConnect menu + +To reference the icon, use the **AUTOCONNECT_LINK** macro in the sketch. It expands into the string literal as an HTML `````` tag with PNG embedded of the AutoConnect menu hyperlinks. Icon type is specified by the parameter of the macro. + +
+
BAR_24Bars icon, 24x24.
+
BAR_32Bars icon, 32x32.
+
BAR_48Bars icon, 48x48.
+
COG_24Cog icon, 24x24.
+
COG_32Cog icon, 32x32.
+
+ +!!! note "Usage" + ```arduino + String html = ""; + html += AUTOCONNECT_LINK(BAR_32); + html += ""; + server.send(200, "text/html", html); + ``` diff --git a/mkdocs/basicusage.md b/mkdocs/basicusage.md index f906318..74eb458 100644 --- a/mkdocs/basicusage.md +++ b/mkdocs/basicusage.md @@ -74,7 +74,7 @@ AutoConnect internally performs *WiFi.begin* to establish a WiFi connection. The #### 5. AutoConnect::begin with SSID and Password -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. +SSID and Password can also specify by [*AutoConnect::begin*](api.md#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 and WebServer::on to handle URL diff --git a/mkdocs/changelog.md b/mkdocs/changelog.md index a7d4bc1..7e8bff4 100644 --- a/mkdocs/changelog.md +++ b/mkdocs/changelog.md @@ -1,3 +1,14 @@ +### [0.9.7] Jan. 1, 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. +- Improved the WiFi connection sequence at the first WiFi.begin. Even if [**AutoConnectConfig::autoReconnect**](api.md#autoreconnect) is disabled when SSID and PSK are not specified, it will use the information of the last established access point. The autoReconnect option will achieve trying the connect after a previous connection failed. +- Supports the [**AutoConnectConfig::immediateStart**](api.md#immediatestart) option and immediately starts the portal without first trying WiFi.begin. You can start the captive portal at any time in combination with the [**AutoConnectConfig::autoRise**](api.md#autorise) option. +- Improved boot uri after reset. [**AutoConnectConfig::bootUri**](api.md#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**](api.md#hostname). It activates ```WiFi.hostname()```/```WiFi.setHostName()```. + #### [0.9.6] Sep.27, 2018. - Improvement of RSSI detection for saved SSIDs. diff --git a/mkdocs/css/paragraph.css b/mkdocs/css/paragraph.css index 0f8f66a..bea77fc 100644 --- a/mkdocs/css/paragraph.css +++ b/mkdocs/css/paragraph.css @@ -41,4 +41,14 @@ font-family: 'FontAwesome'; content: '\f044'; margin:0 0.8em 0 -1.8em; +} + +.horizontal-list { + list-style-type: none; + overflow: hidden; +} + +.horizontal-list > li { + float: left; + display: block; } \ No newline at end of file diff --git a/mkdocs/examples.md b/mkdocs/examples.md index 808346c..469f3ee 100644 --- a/mkdocs/examples.md +++ b/mkdocs/examples.md @@ -125,5 +125,5 @@ For the client sketches, the code required to connect to WiFi is the following f diff --git a/mkdocs/gettingstarted.md b/mkdocs/gettingstarted.md index 07d72be..831fe93 100644 --- a/mkdocs/gettingstarted.md +++ b/mkdocs/gettingstarted.md @@ -68,5 +68,5 @@ The IP address of ESP8266 would be displayed on the serial monitor after connect \ No newline at end of file diff --git a/mkdocs/images/ac_auxjoin_multi.svg b/mkdocs/images/ac_auxjoin_multi.svg new file mode 100644 index 0000000..e444ab7 --- /dev/null +++ b/mkdocs/images/ac_auxjoin_multi.svg @@ -0,0 +1,233 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + AutoConnect portal;AutoConnectAux aux1("/mqtt_setting", "MQTT Setting");AutoConnectAux aux2("/mqtt_save", "MQTT Setting", false);AutoConnectAux aux3("/mqtt_start", "MQTT Start");portal.join({ aux1, aux2, aux3 }); + + + + + + + + + + + + + diff --git a/mkdocs/images/ac_auxmenu.png b/mkdocs/images/ac_auxmenu.png new file mode 100644 index 0000000..af84ac3 Binary files /dev/null and b/mkdocs/images/ac_auxmenu.png differ diff --git a/mkdocs/images/ac_auxmenu_multi.png b/mkdocs/images/ac_auxmenu_multi.png new file mode 100644 index 0000000..a845549 Binary files /dev/null and b/mkdocs/images/ac_auxmenu_multi.png differ diff --git a/mkdocs/images/ac_declaration.svg b/mkdocs/images/ac_declaration.svg new file mode 100644 index 0000000..2f458a0 --- /dev/null +++ b/mkdocs/images/ac_declaration.svg @@ -0,0 +1,677 @@ + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + AutoConnect portal;AutoConnectAux aux("/mqtt_setting", "MQTT Setting");ACText(header, "MQTT broker settings");ACText(caption, "Publishing the WiFi...");void setup() { aux.add({ header, caption }); portal.join(aux); portal.begin();} + + + + + + + + diff --git a/mkdocs/images/ac_objects.svg b/mkdocs/images/ac_objects.svg new file mode 100644 index 0000000..15b83b2 --- /dev/null +++ b/mkdocs/images/ac_objects.svg @@ -0,0 +1,1401 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + AutoConnectAux + AutoConnectText + AutoConnectInput + AutoConnectElement + AutoConnectCheckbox + AutoConnectSubmit + AutoConnectRadio + + + + + + + + + + + + + diff --git a/mkdocs/images/aux_menu.gif b/mkdocs/images/aux_menu.gif new file mode 100644 index 0000000..b7dcce6 Binary files /dev/null and b/mkdocs/images/aux_menu.gif differ diff --git a/mkdocs/images/aux_ov.gif b/mkdocs/images/aux_ov.gif new file mode 100644 index 0000000..f371da9 Binary files /dev/null and b/mkdocs/images/aux_ov.gif differ diff --git a/mkdocs/index.md b/mkdocs/index.md index 8fb6692..60a791f 100644 --- a/mkdocs/index.md +++ b/mkdocs/index.md @@ -29,6 +29,13 @@ Easy implementing the Web interface constituting the WLAN for ESP8266/ESP32 WiFi 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.
This efficacy can also be applied to ESP32. The corresponding class for ESP32 will be the WebServer. +### Easy to add custom web screenENHANCED w/v0.9.7 + +You can easily add your own web screen that can consist of representative HTML elements as the styled TEXT, INPUT, BUTTON, CHECKBOX, RADIO, SELECT, SUBMIT into the menu. It can be invoked from the AutoConnect menu and parameters can be passed. Custom screens can be written easily with JSON and can be loaded from PROGMEM, SPIFFS or SD. + + + + ## Installation ### Requirements @@ -75,15 +82,15 @@ Install third-party platform using the *Boards Manager* of Arduino IDE. You can Additional necessary library 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 is required 1.2.0 later for ESP32.[^1] +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.2.3 later for ESP32.[^1] -[^1]:Since AutoConnect v0.9.7, PageBuilder v1.2.0 later is required. +[^1]:Since AutoConnect v0.9.7, PageBuilder v1.2.3 later is required. Optional required library -The [ArduinoJson](https://github.com/bblanchon/ArduinoJson) library is necessary to be able to process AutoConnect elements with JSON description. Since AutoConnect v0.9.7, you can insert user owned screens that can consist of representative HTML elements as the styled TEXT, INPUT, BUTTON, CHECKBOX, SUBMIT to the AutoConnect menu. These HTML elements can also be programmatic added from user sketches using the AutoConnect API, but they can be easily loaded from JSON description stored in PROGMEM, SPIFFS or SD. [ArduinoJson version 5](https://arduinojson.org/v5/doc/) is required to use this function. +The [ArduinoJson](https://github.com/bblanchon/ArduinoJson) library is necessary to be able to process the *AutoConnectElement* with JSON description. Since AutoConnect v0.9.7, you can insert user owned screens that can consist of representative HTML elements as the styled TEXT, INPUT, BUTTON, CHECKBOX, SELECT, SUBMIT to the AutoConnect menu. These HTML elements can also be added from user sketches using the AutoConnect API, but they can be easily loaded JSON description stored in PROGMEM, SPIFFS or SD. [ArduinoJson version 5](https://arduinojson.org/v5/doc/) is required to use this function. !!! info "ArduinoJson version 6 is still in beta" The Arduino Library Manager installs the ArduinoJson version 6 by default. Open the Arduino Library Manager and make sure that ArduinoJson version 5 is installed. @@ -104,5 +111,5 @@ When you select Download, you can import it to Arduino IDE immediately. After do