From 5400779bd5e1a2547db9433289c769e6cdbb8237 Mon Sep 17 00:00:00 2001 From: Hieromon Ikasamo Date: Wed, 14 Mar 2018 16:01:58 +0900 Subject: [PATCH] Added autoRise with AutoConnectConfig --- docs/api/index.html | 25 ++++++++++++ docs/css/paragraph.css | 6 +++ docs/search/search_index.json | 30 +++++++++----- docs/usage/index.html | 74 +++++++++++++++++++++++----------- mkdocs/api.md | 13 ++++++ mkdocs/css/paragraph.css | 6 +++ mkdocs/usage.md | 53 ++++++++++++++++--------- src/AutoConnect.cpp | 75 +++++++++++++++++++---------------- src/AutoConnect.h | 12 ++++-- 9 files changed, 205 insertions(+), 89 deletions(-) diff --git a/docs/api/index.html b/docs/api/index.html index 0886d3d..d64ac71 100644 --- a/docs/api/index.html +++ b/docs/api/index.html @@ -545,6 +545,13 @@ autoReset + + +
  • + + autoRise + +
  • @@ -882,6 +889,13 @@ autoReset +
    • + +
  • + + autoRise + +
  • @@ -989,7 +1003,9 @@ #define AUTOCONNECT_AP_NM 0x00FFFFFF // Default subnet mask #define AUTOCONNECT_DNSPORT 53 // Default DNS port at captive portal #define AUTOCONNECT_MENU_TITLE "AutoConnect" // Default AutoConnect menu title +#define AUTOCONNECT_STARTUPTIME 10 // Default waiting time[s] for after reset #define AUTOCONNECT_URI "/_ac" // Default AutoConnect root path +#define AUTOCONNECT_TIMEOUT 30000 // Default connection timeout[ms]

    AutoConnect API

    @@ -1151,6 +1167,15 @@ Register the handler function for undefined URL request detected.
    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 a default.
    +
    falseDisable the captive portal.
    +

    autoSave

    The credential saved automatically at the connection establishment.

    diff --git a/docs/css/paragraph.css b/docs/css/paragraph.css index 130e8df..0f8f66a 100644 --- a/docs/css/paragraph.css +++ b/docs/css/paragraph.css @@ -35,4 +35,10 @@ .apidl { margin-left: 20px; +} + +.ulsty-edit > li:before { + font-family: 'FontAwesome'; + content: '\f044'; + margin:0 0.8em 0 -1.8em; } \ No newline at end of file diff --git a/docs/search/search_index.json b/docs/search/search_index.json index c7caa72..f81d44f 100644 --- a/docs/search/search_index.json +++ b/docs/search/search_index.json @@ -132,7 +132,7 @@ }, { "location": "/usage/index.html", - "text": "Simple usage\n\u00b6\n\n\n Embed to the sketches\n\u00b6\n\n\nHow embed the AutoConnect to the sketches you have. Most simple approach to applying AutoConnect for the existing sketches, follow the below steps.\n\n\n\n\n Insert \n#include\n \n\n to behind of \n#include\n \n\n.\n\n\n Insert \nAutoConnect\nPORTAL(WEBSERVER);\n to behind of \nESP8266WebServer\nWEBSERVER;\n declaration.\n1\n\n\n Remove \nWiFi.begin(\nSSID\n,\nPSK\n)\n and the subsequent logic for the connection status check.\n\n\n Replace \nWEBSERVER\n.begin\n()\n to \nPORTAL\n.begin\n()\n.\n2\n\n\n Replace \nWEBSERVER\n.handleClient\n()\n to \nPORTAL\n.handleClient\n()\n.\n3\n\n\n If the connection successful logic is needed, you can check the return value as \ntrue\n or \nfalse\n of \nPORTAL\n.begin\n()\n.\n\n\nBasic usage\n\u00b6\n\n\n Basic logic sequence for the user sketches\n\u00b6\n\n\n1. A typical logic sequence\n\u00b6\n\n\n\n\n\n\nInclude headers,\n \nESP8266WebServer.h\n and \nAutoConnect.h\n \n\n\nDeclare ESP8266WebServer variable.\n \n\n\nDeclare AutoConnect variable.\n \n\n\nImplements the URL handler \nfunction()\n.\n \n\n\nsetup()\n\n 5.1 \nSets URL handler \nfunction()\n to ESP8266WebServer by\nESP8266WebServer::on\n.\n\n 5.2 \nStarts \nAutoConnect::begin()\n.\n\n 5.3 \nCheck connection status.\n \n\n\nloop()\n\n 6.1 \nInvokes \nAutoConnect::handleClient()\n,\nor invokes \nESP8266WebServer::handleClient()\n then \nAutoConnect::handleRequest()\n.\n\n 6.2 \nDo the process for actual sketch.\n \n\n\n\n\n\n\n2. Declare AutoConnect object\n\u00b6\n\n\nTwo options\n are available for \nAutoConnect constructor\n.\n\n\nAutoConnect\n \nVARIABLE\n(\n&\nESP8266WebServer\n);\n\n\n\nor\n\n\nAutoConnect\n \nVARIABLE\n;\n\n\n\n\n\n\n\n\n\nParameter with ESP8266WebServer variable:\n An ESP8266WebServer object variable must be declared in the sketch. AutoConnect uses its variable for handling the AutoConnect menu.\n\n\n\n\n\n\nWith no parameter:\n The sketch does not declare ESP8266WebServer object. In this case, AutoConnect allocates an instance of the ESP8266WebServer internally and the logic sequence of the sketch is somewhat different as the above. To register a URL handler function by \nESP8266WebServer::on\n should be performed after \nAutoConnect::begin\n.\n\n\n\n\n\n\n3. No need WiFI.begin(...)\n\u00b6\n\n\nAutoConnect performs \nWiFi.begin\n for establishing a connection with WLAN internally. There is no need for a general process to establish a connection with \nWiFi.begin\n in a sketch.\n\n\n4. Alternate ESP8266WebServer::begin()\n\u00b6\n\n\nAutoConnect::begin\n internally executes \nESP8266WebServer::begin\n too and it starts DNS server to behave as a captive portal. So the sketch does not need to call \nESP8266WebServer::begin\n.\n\n\n\n\nWhy DNS Server Starts\n\n\nAutoConnect traps the detection of captive portals and directs them to the AutoConnect menu to achieve a connection with the WLAN interactively. In order to trap, it temporarily responds SoftAP address to all DNS queries. When the connection with the WLAN is successfully established, the DNS server will stop.\n\n\n\n\n5. AutoConnect::begin with SSID and Password\n\u00b6\n\n\nSSID and Password can also specify by \nAutoConnect::begin\n. ESP8266 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.\n\n\n6. Use ESP8266WebServer::on to handle URL\n\u00b6\n\n\nAutoConnect is designed to coexist with the process for handling the web pages by user sketches. The page processing function which will send an HTML to the client invoked by the \"\non\n\" function is the same as when using ESP8266WebServer natively.\n\n\n7. Use either ESP8266WebServer::handleClient() or AutoConnect::handleClient()\n\u00b6\n\n\nBoth classes member function name is the same: \nhandleClient\n, but behavior is different. Using the AutoConnect embedded along with ESP8266WebServer::handleClient has limitations. Refer to the below section for details. \n\n\n ESP8266WebServer hosted or parasitic\n\u00b6\n\n\nThe interoperable process with an ESP8266WebServer depends on the parameters of the \nAutoConnect constructor\n.\n\n\n\n\n\n\n\n\nDeclaration parameter\n\n\nUse ESP8266WebServer::handleClient\n\n\nUse AutoConnect::handleClient\n\n\n\n\n\n\n\n\n\n\nNone\n\n\nAutoConnect menu not available.\nhost() is needed.\n\n\nAutoConnect menu available.\nhost() is needed.\n\n\n\n\n\n\nReference to ESP8266WebServer\n\n\nAutoConnect menu not available.\nhost() not necessary.\n\n\nAutoConnect menu available.\nhost() not necessary.\n\n\n\n\n\n\n\n\n\n\n\n\nBy declaration for the AutoConnect variable with no parameter\n: The ESP8266WebServer instance is hosted by AutoConnect automatically then the sketches use \nAutoConnect::host\n as API to get it after \nAutoConnect::begin\n performed.\n\n\n\n\n\n\nBy declaration for the AutoConnect variable with the reference of ESP8266WebServer\n: AutoConnect will use it. The sketch can use it is too.\n\n\n\n\n\n\nIn use ESP8266WebServer::handleClient()\n: AutoConnect menu can be dispatched but not works normally. It is necessary to call \nAutoConnect::handleRequest\n after \nESP8255WebServer::handleClient\n invoking.\n\n\n\n\n\n\nIn use \nAutoConnect::handleClient()\n: The handleClient() process and the AutoConnect menu is available without calling \nESP8266WebServer::handleClient\n.\n\n\n\n\n\n\n\n\nWhy AutoConnect::handleRequest is needed when using ESP8266::handleClient\n\n\nThe AutoConnect menu function may affect WiFi connection state. It follows that the menu process must execute outside \nESP8266WebServer::handleClient\n.\n\n\nAutoConnect::handleClient\n is equivalent \nESP8266WebServer::handleClient\n included \nAutoConnect::handleRequest\n.\n\n\n\n\nAdvanced usage\n\u00b6\n\n\n 404 handler\n\u00b6\n\n\nRegistering the \"not found\" handler is a different way than ESP8266. The \nonNotFound\n of ESP8266WebServer does not work with AutoConnect. AutoConnect overrides \nESP8266WebServer::onNotFound\n to handle a captive portal. To register \"not found\" handler, use \nAutoConnect::onNotFound\n.\n\n\n Captive portal start detection\n\u00b6\n\n\nThe captive portal will only be activated if the first \nWiFi::begin\n fails. Sketch can detect with the \nonDetect\n funciton 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.\n\n\nAutoConnect\n \nPortal\n;\n\n\n\nbool\n \nstartCP\n(\nIPAddress\n \nip\n)\n \n{\n\n\n \ndigitalWrite\n(\nBUILTIN_LED\n,\n \nHIGH\n);\n\n \nSerial\n.\nprintln\n(\n\"C.P. started, IP:\"\n \n+\n \nWiFi\n.\nlocalIP\n().\ntoString\n());\n\n \nreturn\n \ntrue\n;\n\n\n}\n\n\n\nvoid\n \nsetup\n()\n \n{\n\n \nSerial\n.\nbegin\n(\n115200\n);\n\n \npinMode\n(\nBUILTIN_LED\n,\n \noutput\n);\n\n \ndigitalWrite\n(\nBUILTIN_LED\n,\n \nLOW\n);\n\n\n \nPortal\n.\nonDetect\n(\nstartCP\n);\n\n\n \nif\n \n(\nPortal\n.\nbegin\n())\n \n{\n\n \ndigitalWrite\n(\nBUILTIN_LED\n,\n \nLOW\n);\n\n \n}\n\n\n}\n\n\n\nvoid\n \nloop\n()\n \n{\n\n \nPortal\n.\nhandleClient\n();\n\n\n}\n\n\n\n\n\n Combination with mDNS\n\u00b6\n\n\nWith \nmDNS library\n, you can access to ESP8266 by name instead of IP address after connection. The sketch can start the MDNS responder after AutoConnect::begin.\n\n\n#include\n \n\n\n\n#include\n \n\n\n\n#include\n \n\n\n\nAutoConnect\n \nPortal\n;\n\n\n\nvoid\n \nsetup\n()\n \n{\n\n \nif\n \n(\nPortal\n.\nbegin\n())\n \n{\n\n\n \nif\n \n(\nMDNS\n.\nbegin\n(\n\"esp8266\"\n))\n \n{\n\n\n \nMDNS\n.\naddService\n(\n\"http\"\n,\n \n\"tcp\"\n,\n \n80\n);\n\n\n \n}\n\n \n}\n\n\n}\n\n\n\nvoid\n \nloop\n()\n \n{\n\n \nPortal\n.\nhandleClient\n();\n\n\n}\n\n\n\n\n\n Credential data\n\u00b6\n\n\nBy default, AutoConnect saves the credentials of the established connection in EEPROM. You can disable it with the \nautoSave\n parameter specified by \nAutoConnect::config\n.\n\n\nAutoConnect\n \nPortal\n;\n\n\nAutoConnectConfig\n \nConfig\n;\n\n\nConfig\n.\nautoSave\n \n=\n \nAC_SAVECREDENTIAL_NEVER\n;\n\n\nPortal\n.\nconfig\n(\nConfig\n);\n\n\nPortal\n.\nbegin\n();\n\n\n\n\n\n\n\nAutoConnect::config before AutoConnect::begin\n\n\nAutoConnect::config\n must be executed before \nAutoConnect::begin\n.\n\n\n\n\n Debug print\n\u00b6\n\n\nYou can output AutoConnect monitor messages to the \nSerial\n. A monitor message activation switch is in an include header file \nAutoConnect.h\n of library source. Define \nAC_DEBUG\n macro to output monitor messages.\n\n\n#define AC_DEBUG\n\n\n\n\n\n Refers the hosted ESP8266WebServer\n\u00b6\n\n\nConstructing an AutoConnect object variable without parameters then creates and starts an ESP8266WebServer inside the AutoConnect. This object variable could be referred by \nAutoConnect::host()\n function to access ESP8266WebServer instance as like below.\n\n\nAutoConnect\n \nPortal\n;\n\n\n\nPortal\n.\nbegin\n();\n\n\nESP8266WebServer\n&\n \nserver\n \n=\n \nPortal\n.\nhost\n();\n\n\nserver\n.\nsend\n(\n200\n,\n \n\"text/plain\"\n,\n \n\"Hello, world\"\n);\n\n\n\n\n\n\n\nWhen host() is valid\n\n\nThe host() can be referred at after \nAutoConnect::begin\n.\n\n\n\n\n Usage for automatically instantiated ESP8266WebServer\n\u00b6\n\n\nThe sketch can handle URL requests using ESP8266WebServer that AutoConnect started internally. ESP8266WebServer instantiated dynamically by AutoConnect can be referred to by \nAutoConnect::host\n function. The sketch can use the '\non\n' function, '\nsend\n' function, '\nclient\n' function and others by ESP8266WebServer reference of its return value.\n\n\n#include\n \n\n\n\n#include\n \n\n\n\n#include\n \n\n\n\n\nAutoConnect\n \nPortal\n;\n\n\n\nvoid\n \nhandleRoot\n()\n \n{\n\n\n \nESP8266WebServer\n&\n \nIntServer\n \n=\n \nPortal\n.\nhost\n();\n\n\n \nIntServer\n.\nsend\n(\n200\n,\n \n\"text/html\"\n,\n \n\"Hello, world\"\n);\n\n\n}\n\n\n\nvoid\n \nhandleNotFound\n()\n \n{\n\n\n \nESP8266WebServer\n&\n \nIntServer\n \n=\n \nPortal\n.\nhost\n();\n\n\n \nIntServer\n.\nsend\n(\n404\n,\n \n\"text/html\"\n,\n \n\"Unknown.\"\n);\n\n\n}\n\n\n\nvoid\n \nsetup\n()\n \n{\n\n \nbool\n \nr\n \n=\n \nPortal\n.\nbegin\n();\n\n \nif\n \n(\nr\n)\n \n{\n\n\n \nESP8266WebServer\n&\n \nIntServer\n \n=\n \nPortal\n.\nhost\n();\n\n\n \nIntServer\n.\non\n(\n\"/\"\n,\n \nhandleRoot\n);\n\n\n \nPortal\n.\nonNotFound\n(\nhandleNotFound\n);\n \n// For only onNotFound.\n\n \n}\n\n\n}\n\n\n\nvoid\n \nloop\n()\n \n{\n\n\n \nPortal\n.\nhost\n().\nhandleClient\n();\n\n\n \nPortal\n.\nhandleRequest\n();\n\n \n/* or following one line code is equ.\n\n\n Portal.handleClient();\n\n\n */\n\n\n}\n\n\n\n\n\n\n\nESP8266WebServer function should be called after AutoConnect::begin\n\n\nThe sketch cannot refer to an instance of ESP8266WebServer until AutoConnect::begin completes successfully.\n\n\n\n\n\n\nDo not use with ESP8266WebServer::begin\n\n\nESP8266WebServer is already running inside the AutoConnect.\n\n\n\n\n Use with the \nPageBuilder\n library\n\u00b6\n\n\nIn ordinary, the URL handler will respond the request by sending some HTML. \nPageBuilder\n library is HTML assembly aid. it can handle predefined HTML as like a template and simplify an HTML string assemble logic, and also the generated HTML send automatically.\n\n\nAn example sketch used with the PageBuilder as follows and it explains how it aids for the HTML generating. Details for \nGithub repository\n.\n\n\n\n\nConfiguration functions\n\u00b6\n\n\n Configuration for Soft AP\n\u00b6\n\n\nAutoConnect will activate SoftAP at failed initial WiFi.Begin. It SoftAP settings are stored in \nAutoConnectConfig\n as the following parameters. The sketch could be configured SoftAP using these parameters, refer \nAutoConnectConfig API\n for details.\n\n\n\n\nIP address of SoftAP activated.\n\n\nGateway IP address.\n\n\nSubnet mask.\n\n\nSSID for SoftAP.\n\n\nPassword for SoftAP.\n\n\nChannel.\n\n\nHidden attribute.\n\n\nAuto save credential.\n\n\nAuto reset after connection establishment.\n\n\nHome URL of the user sketch application.\n\n\n\n\n Assign user sketch's home path\n\u00b6\n\n\n\"\nHOME\n\" for returning to the user's sketch homepage is displayed at the bottom of the AutoConnect menu. It could be set using the \nAutoConnect::home\n function.\n\n\n\n\n Relocate the AutoConnect home path\n\u00b6\n\n\nA home path of AutoConnect is \n_ac\n by default. You can access from the browser with http://IPADDRESS/_ac. You can change the home path by revising \nAUTOCONNECT_URI\n macro in the include header file as \nAutoConnect.h\n.\n\n\n#define AUTOCONNECT_URI \"/_ac\"\n\n\n\n\n\n\n\n\n\n\n\n\n\nEach \nVARIABLE\n conforms to the actual declaration in the sketches.\u00a0\n\u21a9\n\n\n\n\n\n\nWiFi SSID and Password can be specified AutoConnect::begin() too.\u00a0\n\u21a9\n\n\n\n\n\n\nReplacement the \nhandleClient\n method is not indispensable. AutoConnect can still connect with the captive portal as it is ESP8266WebServer::handleClient. But it can \nnot valid AutoConnect menu\n.\u00a0\n\u21a9", + "text": "Simple usage\n\u00b6\n\n\n Embed to the sketches\n\u00b6\n\n\nHow embed the AutoConnect to the sketches you have. Most simple approach to applying AutoConnect for the existing sketches, follow the below steps.\n\n\n\n\n\n \nInsert \n#include\n \n\n to behind of \n#include\n \n\n.\n\n \nInsert \nAutoConnect\n \nPORTAL(WEBSERVER);\n to behind of \nESP8266WebServer\n \nWEBSERVER;\n declaration.\n1\n\n \nRemove \nWiFi.\nbegin\n(\nSSID\n,\nPSK\n)\n and the subsequent logic for the connection status check.\n\n \nReplace \nWEBSERVER\n.\nbegin\n()\n to \nPORTAL\n.\nbegin\n()\n.\n2\n\n \nReplace \nWEBSERVER\n.\nhandleClient\n()\n to \nPORTAL\n.\nhandleClient\n()\n.\n3\n\n \nIf the connection checks logic is needed, you can check the return value according to \nPORTAL\n.\nbegin\n()\n with \ntrue\n or \nfalse\n.\n\n\n\n\n\nBasic usage\n\u00b6\n\n\n Basic logic sequence for the user sketches\n\u00b6\n\n\n1. A typical logic sequence\n\u00b6\n\n\n\n\n\n\nInclude headers,\n \nESP8266WebServer.h\n and \nAutoConnect.h\n \n\n\nDeclare ESP8266WebServer variable.\n \n\n\nDeclare AutoConnect variable.\n \n\n\nImplements the URL handler \nfunction()\n.\n \n\n\nsetup()\n\n 5.1 \nSets URL handler \nfunction()\n to ESP8266WebServer by\nESP8266WebServer::on\n.\n\n 5.2 \nStarts \nAutoConnect::begin()\n.\n\n 5.3 \nCheck connection status.\n \n\n\nloop()\n\n 6.1 \nInvokes \nAutoConnect::handleClient()\n,\nor invokes \nESP8266WebServer::handleClient()\n then \nAutoConnect::handleRequest()\n.\n\n 6.2 \nDo the process for actual sketch.\n \n\n\n\n\n\n\n2. Declare AutoConnect object\n\u00b6\n\n\nTwo options\n are available for \nAutoConnect constructor\n.\n\n\nAutoConnect\n \nVARIABLE\n(\n&\nESP8266WebServer\n);\n\n\n\nor\n\n\nAutoConnect\n \nVARIABLE\n;\n\n\n\n\n\n\n\n\n\nParameter with ESP8266WebServer variable:\n An ESP8266WebServer object variable must be declared in the sketch. AutoConnect uses its variable for handling the AutoConnect menu.\n\n\n\n\n\n\nWith no parameter:\n The sketch does not declare ESP8266WebServer object. In this case, AutoConnect allocates an instance of the ESP8266WebServer internally and the logic sequence of the sketch is somewhat different as the above. To register a URL handler function by \nESP8266WebServer::on\n should be performed after \nAutoConnect::begin\n.\n\n\n\n\n\n\n3. No need WiFI.begin(...)\n\u00b6\n\n\nAutoConnect performs \nWiFi.begin\n for establishing a connection with WLAN internally. There is no need for a general process to establish a connection with \nWiFi.begin\n in a sketch.\n\n\n4. Alternate ESP8266WebServer::begin()\n\u00b6\n\n\nAutoConnect::begin\n internally executes \nESP8266WebServer::begin\n too and it starts DNS server to behave as a captive portal. So the sketch does not need to call \nESP8266WebServer::begin\n.\n\n\n\n\nWhy DNS Server Starts\n\n\nAutoConnect traps the detection of captive portals and directs them to the AutoConnect menu to achieve a connection with the WLAN interactively. In order to trap, it temporarily responds SoftAP address to all DNS queries. When the connection with the WLAN is successfully established, the DNS server will stop.\n\n\n\n\n5. AutoConnect::begin with SSID and Password\n\u00b6\n\n\nSSID and Password can also specify by \nAutoConnect::begin\n. ESP8266 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.\n\n\n6. Use ESP8266WebServer::on to handle URL\n\u00b6\n\n\nAutoConnect is designed to coexist with the process for handling the web pages by user sketches. The page processing function which will send an HTML to the client invoked by the \"\non\n\" function is the same as when using ESP8266WebServer natively.\n\n\n7. Use either ESP8266WebServer::handleClient() or AutoConnect::handleClient()\n\u00b6\n\n\nBoth classes member function name is the same: \nhandleClient\n, but behavior is different. Using the AutoConnect embedded along with ESP8266WebServer::handleClient has limitations. Refer to the below section for details. \n\n\n ESP8266WebServer hosted or parasitic\n\u00b6\n\n\nThe interoperable process with an ESP8266WebServer depends on the parameters of the \nAutoConnect constructor\n.\n\n\n\n\n\n\n\n\nDeclaration parameter\n\n\nUse ESP8266WebServer::handleClient\n\n\nUse AutoConnect::handleClient\n\n\n\n\n\n\n\n\n\n\nNone\n\n\nAutoConnect menu not available.\nhost() is needed.\n\n\nAutoConnect menu available.\nhost() is needed.\n\n\n\n\n\n\nReference to ESP8266WebServer\n\n\nAutoConnect menu not available.\nhost() not necessary.\n\n\nAutoConnect menu available.\nhost() not necessary.\n\n\n\n\n\n\n\n\n\n\n\n\nBy declaration for the AutoConnect variable with no parameter\n: The ESP8266WebServer instance is hosted by AutoConnect automatically then the sketches use \nAutoConnect::host\n as API to get it after \nAutoConnect::begin\n performed.\n\n\n\n\n\n\nBy declaration for the AutoConnect variable with the reference of ESP8266WebServer\n: AutoConnect will use it. The sketch can use it is too.\n\n\n\n\n\n\nIn use ESP8266WebServer::handleClient()\n: AutoConnect menu can be dispatched but not works normally. It is necessary to call \nAutoConnect::handleRequest\n after \nESP8255WebServer::handleClient\n invoking.\n\n\n\n\n\n\nIn use \nAutoConnect::handleClient()\n: The handleClient() process and the AutoConnect menu is available without calling \nESP8266WebServer::handleClient\n.\n\n\n\n\n\n\n\n\nWhy AutoConnect::handleRequest is needed when using ESP8266::handleClient\n\n\nThe AutoConnect menu function may affect WiFi connection state. It follows that the menu process must execute outside \nESP8266WebServer::handleClient\n.\n\n\nAutoConnect::handleClient\n is equivalent \nESP8266WebServer::handleClient\n included \nAutoConnect::handleRequest\n.\n\n\n\n\nAdvanced usage\n\u00b6\n\n\n 404 handler\n\u00b6\n\n\nRegistering the \"not found\" handler is a different way than ESP8266. The \nonNotFound\n of ESP8266WebServer does not work with AutoConnect. AutoConnect overrides \nESP8266WebServer::onNotFound\n to handle a captive portal. To register \"not found\" handler, use \nAutoConnect::onNotFound\n.\n\n\n Auto save Credential\n\u00b6\n\n\nBy default, AutoConnect saves the credentials of the established connection in EEPROM. You can disable it with the \nautoSave\n parameter specified by \nAutoConnect::config\n.\n\n\nAutoConnect\n \nPortal\n;\n\n\nAutoConnectConfig\n \nConfig\n;\n\n\nConfig\n.\nautoSave\n \n=\n \nAC_SAVECREDENTIAL_NEVER\n;\n\n\nPortal\n.\nconfig\n(\nConfig\n);\n\n\nPortal\n.\nbegin\n();\n\n\n\n\n\n Captive portal start detection\n\u00b6\n\n\nThe captive portal will only be activated if the first \nWiFi::begin\n fails. Sketch can detect with the \nonDetect\n funciton 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.\n\n\nAutoConnect\n \nPortal\n;\n\n\n\nbool\n \nstartCP\n(\nIPAddress\n \nip\n)\n \n{\n\n\n \ndigitalWrite\n(\nBUILTIN_LED\n,\n \nHIGH\n);\n\n \nSerial\n.\nprintln\n(\n\"C.P. started, IP:\"\n \n+\n \nWiFi\n.\nlocalIP\n().\ntoString\n());\n\n \nreturn\n \ntrue\n;\n\n\n}\n\n\n\nvoid\n \nsetup\n()\n \n{\n\n \nSerial\n.\nbegin\n(\n115200\n);\n\n \npinMode\n(\nBUILTIN_LED\n,\n \noutput\n);\n\n \ndigitalWrite\n(\nBUILTIN_LED\n,\n \nLOW\n);\n\n\n \nPortal\n.\nonDetect\n(\nstartCP\n);\n\n\n \nif\n \n(\nPortal\n.\nbegin\n())\n \n{\n\n \ndigitalWrite\n(\nBUILTIN_LED\n,\n \nLOW\n);\n\n \n}\n\n\n}\n\n\n\nvoid\n \nloop\n()\n \n{\n\n \nPortal\n.\nhandleClient\n();\n\n\n}\n\n\n\n\n\n Combination with mDNS\n\u00b6\n\n\nWith \nmDNS library\n, you can access to ESP8266 by name instead of IP address after connection. The sketch can start the MDNS responder after AutoConnect::begin.\n\n\n#include\n \n\n\n\n#include\n \n\n\n\n#include\n \n\n\n\nAutoConnect\n \nPortal\n;\n\n\n\nvoid\n \nsetup\n()\n \n{\n\n \nif\n \n(\nPortal\n.\nbegin\n())\n \n{\n\n\n \nif\n \n(\nMDNS\n.\nbegin\n(\n\"esp8266\"\n))\n \n{\n\n\n \nMDNS\n.\naddService\n(\n\"http\"\n,\n \n\"tcp\"\n,\n \n80\n);\n\n\n \n}\n\n \n}\n\n\n}\n\n\n\nvoid\n \nloop\n()\n \n{\n\n \nPortal\n.\nhandleClient\n();\n\n\n}\n\n\n\n\n\n\n\nAutoConnect::config before AutoConnect::begin\n\n\nAutoConnect::config\n must be executed before \nAutoConnect::begin\n.\n\n\n\n\n Debug print\n\u00b6\n\n\nYou can output AutoConnect monitor messages to the \nSerial\n. A monitor message activation switch is in an include header file \nAutoConnect.h\n of library source. Define \nAC_DEBUG\n macro to output monitor messages.\n\n\n#define AC_DEBUG\n\n\n\n\n\n Disable the captive portal\n\u00b6\n\n\nIt can also prevent the captive portal from starting even if the connection at the first \nWiFi.begin\n fails. In this case, the behavior of \nAutoConnect::begin\n is the same as \nWiFi.begin\n.\n\n\nFor disabling the captive portal, \nautoRise\n sets to false with AutoConnectConfig.\n\n\nAutoConnect\n \nportal\n;\n\n\nAutoConnectConfig\n \nacConfig\n;\n\n\n\nacConfig\n.\nautoRaise\n \n=\n \nfalse\n;\n\n\nportal\n.\nconfig\n(\nacConfig\n);\n\n\nportal\n.\nbegin\n();\n\n\n\n\n\n Refers the hosted ESP8266WebServer\n\u00b6\n\n\nConstructing an AutoConnect object variable without parameters then creates and starts an ESP8266WebServer inside the AutoConnect. This object variable could be referred by \nAutoConnect::host()\n function to access ESP8266WebServer instance as like below.\n\n\nAutoConnect\n \nPortal\n;\n\n\n\nPortal\n.\nbegin\n();\n\n\nESP8266WebServer\n&\n \nserver\n \n=\n \nPortal\n.\nhost\n();\n\n\nserver\n.\nsend\n(\n200\n,\n \n\"text/plain\"\n,\n \n\"Hello, world\"\n);\n\n\n\n\n\n\n\nWhen host() is valid\n\n\nThe host() can be referred at after \nAutoConnect::begin\n.\n\n\n\n\n Usage for automatically instantiated ESP8266WebServer\n\u00b6\n\n\nThe sketch can handle URL requests using ESP8266WebServer that AutoConnect started internally. ESP8266WebServer instantiated dynamically by AutoConnect can be referred to by \nAutoConnect::host\n function. The sketch can use the '\non\n' function, '\nsend\n' function, '\nclient\n' function and others by ESP8266WebServer reference of its return value.\n\n\n#include\n \n\n\n\n#include\n \n\n\n\n#include\n \n\n\n\n\nAutoConnect\n \nPortal\n;\n\n\n\nvoid\n \nhandleRoot\n()\n \n{\n\n\n \nESP8266WebServer\n&\n \nIntServer\n \n=\n \nPortal\n.\nhost\n();\n\n\n \nIntServer\n.\nsend\n(\n200\n,\n \n\"text/html\"\n,\n \n\"Hello, world\"\n);\n\n\n}\n\n\n\nvoid\n \nhandleNotFound\n()\n \n{\n\n\n \nESP8266WebServer\n&\n \nIntServer\n \n=\n \nPortal\n.\nhost\n();\n\n\n \nIntServer\n.\nsend\n(\n404\n,\n \n\"text/html\"\n,\n \n\"Unknown.\"\n);\n\n\n}\n\n\n\nvoid\n \nsetup\n()\n \n{\n\n \nbool\n \nr\n \n=\n \nPortal\n.\nbegin\n();\n\n \nif\n \n(\nr\n)\n \n{\n\n\n \nESP8266WebServer\n&\n \nIntServer\n \n=\n \nPortal\n.\nhost\n();\n\n\n \nIntServer\n.\non\n(\n\"/\"\n,\n \nhandleRoot\n);\n\n\n \nPortal\n.\nonNotFound\n(\nhandleNotFound\n);\n \n// For only onNotFound.\n\n \n}\n\n\n}\n\n\n\nvoid\n \nloop\n()\n \n{\n\n\n \nPortal\n.\nhost\n().\nhandleClient\n();\n\n\n \nPortal\n.\nhandleRequest\n();\n\n \n/* or following one line code is equ.\n\n\n Portal.handleClient();\n\n\n */\n\n\n}\n\n\n\n\n\n\n\nESP8266WebServer function should be called after AutoConnect::begin\n\n\nThe sketch cannot refer to an instance of ESP8266WebServer until AutoConnect::begin completes successfully.\n\n\n\n\n\n\nDo not use with ESP8266WebServer::begin\n\n\nESP8266WebServer is already running inside the AutoConnect.\n\n\n\n\n Use with the \nPageBuilder\n library\n\u00b6\n\n\nIn ordinary, the URL handler will respond the request by sending some HTML. \nPageBuilder\n library is HTML assembly aid. it can handle predefined HTML as like a template and simplify an HTML string assemble logic, and also the generated HTML send automatically.\n\n\nAn example sketch used with the PageBuilder as follows and it explains how it aids for the HTML generating. Details for \nGithub repository\n.\n\n\n\n\nConfiguration functions\n\u00b6\n\n\n Configuration for Soft AP\n\u00b6\n\n\nAutoConnect will activate SoftAP at failed initial WiFi.Begin. It SoftAP settings are stored in \nAutoConnectConfig\n as the following parameters. The sketch could be configured SoftAP using these parameters, refer \nAutoConnectConfig API\n for details.\n\n\n\n\nIP address of SoftAP activated.\n\n\nGateway IP address.\n\n\nSubnet mask.\n\n\nSSID for SoftAP.\n\n\nPassword for SoftAP.\n\n\nChannel.\n\n\nHidden attribute.\n\n\nAuto save credential.\n\n\nAuto reset after connection establishment.\n\n\nHome URL of the user sketch application.\n\n\n\n\n Assign user sketch's home path\n\u00b6\n\n\n\"\nHOME\n\" for returning to the user's sketch homepage is displayed at the bottom of the AutoConnect menu. It could be set using the \nAutoConnect::home\n function.\n\n\n\n\n Relocate the AutoConnect home path\n\u00b6\n\n\nA home path of AutoConnect is \n_ac\n by default. You can access from the browser with http://IPADDRESS/_ac. You can change the home path by revising \nAUTOCONNECT_URI\n macro in the include header file as \nAutoConnect.h\n.\n\n\n#define AUTOCONNECT_URI \"/_ac\"\n\n\n\n\n\n\n\n\n\n\n\n\n\nEach \nVARIABLE\n conforms to the actual declaration in the sketches.\u00a0\n\u21a9\n\n\n\n\n\n\nWiFi SSID and Password can be specified AutoConnect::begin() too.\u00a0\n\u21a9\n\n\n\n\n\n\nReplacement the \nhandleClient\n method is not indispensable. AutoConnect can still connect with the captive portal as it is ESP8266WebServer::handleClient. But it can \nnot valid AutoConnect menu\n.\u00a0\n\u21a9", "title": "Usage the library" }, { @@ -142,7 +142,7 @@ }, { "location": "/usage/index.html#embed-to-the-sketches", - "text": "How embed the AutoConnect to the sketches you have. Most simple approach to applying AutoConnect for the existing sketches, follow the below steps. Insert #include to behind of #include . Insert AutoConnect PORTAL(WEBSERVER); to behind of ESP8266WebServer WEBSERVER; declaration. 1 Remove WiFi.begin( SSID , PSK ) and the subsequent logic for the connection status check. Replace WEBSERVER .begin () to PORTAL .begin () . 2 Replace WEBSERVER .handleClient () to PORTAL .handleClient () . 3 If the connection successful logic is needed, you can check the return value as true or false of PORTAL .begin () .", + "text": "How embed the AutoConnect to the sketches you have. Most simple approach to applying AutoConnect for the existing sketches, follow the below steps. \n Insert #include to behind of #include . \n Insert AutoConnect PORTAL(WEBSERVER); to behind of ESP8266WebServer WEBSERVER; declaration. 1 \n Remove WiFi. begin ( SSID , PSK ) and the subsequent logic for the connection status check. \n Replace WEBSERVER . begin () to PORTAL . begin () . 2 \n Replace WEBSERVER . handleClient () to PORTAL . handleClient () . 3 \n If the connection checks logic is needed, you can check the return value according to PORTAL . begin () with true or false .", "title": " Embed to the sketches" }, { @@ -205,6 +205,11 @@ "text": "Registering the \"not found\" handler is a different way than ESP8266. The onNotFound of ESP8266WebServer does not work with AutoConnect. AutoConnect overrides ESP8266WebServer::onNotFound to handle a captive portal. To register \"not found\" handler, use AutoConnect::onNotFound .", "title": " 404 handler" }, + { + "location": "/usage/index.html#auto-save-credential", + "text": "By default, AutoConnect saves the credentials of the established connection in EEPROM. You can disable it with the autoSave parameter specified by AutoConnect::config . AutoConnect Portal ; AutoConnectConfig Config ; Config . autoSave = AC_SAVECREDENTIAL_NEVER ; Portal . config ( Config ); Portal . begin ();", + "title": " Auto save Credential" + }, { "location": "/usage/index.html#captive-portal-start-detection", "text": "The captive portal will only be activated if the first WiFi::begin fails. Sketch can detect with the onDetect funciton 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. AutoConnect Portal ; bool startCP ( IPAddress ip ) { digitalWrite ( BUILTIN_LED , HIGH ); \n Serial . println ( \"C.P. started, IP:\" + WiFi . localIP (). toString ()); \n return true ; } void setup () { \n Serial . begin ( 115200 ); \n pinMode ( BUILTIN_LED , output ); \n digitalWrite ( BUILTIN_LED , LOW ); Portal . onDetect ( startCP ); if ( Portal . begin ()) { \n digitalWrite ( BUILTIN_LED , LOW ); \n } } void loop () { \n Portal . handleClient (); }", @@ -212,19 +217,19 @@ }, { "location": "/usage/index.html#combination-with-mdns", - "text": "With mDNS library , you can access to ESP8266 by name instead of IP address after connection. The sketch can start the MDNS responder after AutoConnect::begin. #include #include #include AutoConnect Portal ; void setup () { \n if ( Portal . begin ()) { if ( MDNS . begin ( \"esp8266\" )) { MDNS . addService ( \"http\" , \"tcp\" , 80 ); } \n } } void loop () { \n Portal . handleClient (); }", + "text": "With mDNS library , you can access to ESP8266 by name instead of IP address after connection. The sketch can start the MDNS responder after AutoConnect::begin. #include #include #include AutoConnect Portal ; void setup () { \n if ( Portal . begin ()) { if ( MDNS . begin ( \"esp8266\" )) { MDNS . addService ( \"http\" , \"tcp\" , 80 ); } \n } } void loop () { \n Portal . handleClient (); } AutoConnect::config before AutoConnect::begin AutoConnect::config must be executed before AutoConnect::begin .", "title": " Combination with mDNS" }, - { - "location": "/usage/index.html#credential-data", - "text": "By default, AutoConnect saves the credentials of the established connection in EEPROM. You can disable it with the autoSave parameter specified by AutoConnect::config . AutoConnect Portal ; AutoConnectConfig Config ; Config . autoSave = AC_SAVECREDENTIAL_NEVER ; Portal . config ( Config ); Portal . begin (); AutoConnect::config before AutoConnect::begin AutoConnect::config must be executed before AutoConnect::begin .", - "title": " Credential data" - }, { "location": "/usage/index.html#debug-print", "text": "You can output AutoConnect monitor messages to the Serial . A monitor message activation switch is in an include header file AutoConnect.h of library source. Define AC_DEBUG macro to output monitor messages. #define AC_DEBUG", "title": " Debug print" }, + { + "location": "/usage/index.html#disable-the-captive-portal", + "text": "It can also prevent the captive portal from starting even if the connection at the first WiFi.begin fails. In this case, the behavior of AutoConnect::begin is the same as WiFi.begin . For disabling the captive portal, autoRise sets to false with AutoConnectConfig. AutoConnect portal ; AutoConnectConfig acConfig ; acConfig . autoRaise = false ; portal . config ( acConfig ); portal . begin ();", + "title": " Disable the captive portal" + }, { "location": "/usage/index.html#refers-the-hosted-esp8266webserver", "text": "Constructing an AutoConnect object variable without parameters then creates and starts an ESP8266WebServer inside the AutoConnect. This object variable could be referred by AutoConnect::host() function to access ESP8266WebServer instance as like below. AutoConnect Portal ; Portal . begin (); ESP8266WebServer & server = Portal . host (); server . send ( 200 , \"text/plain\" , \"Hello, world\" ); When host() is valid The host() can be referred at after AutoConnect::begin .", @@ -262,7 +267,7 @@ }, { "location": "/api/index.html", - "text": "Include headers\n\u00b6\n\n\n AutoConnect.h\n\u00b6\n\n\n#include\n \n\n\n\n\n\n\nDefine macros\n\u00b6\n\n\n#define AC_DEBUG \n// Monitor message output activation\n\n\n#define AC_DEBUG_PORT Serial \n// Default message output device\n\n\n#define AUTOCONNECT_AP_IP 0x01F4A8C0 \n// Default SoftAP IP\n\n\n#define AUTOCONNECT_AP_GW 0x01F4A8C0 \n// Default SoftAP Gateway IP\n\n\n#define AUTOCONNECT_AP_NM 0x00FFFFFF \n// Default subnet mask\n\n\n#define AUTOCONNECT_DNSPORT 53 \n// Default DNS port at captive portal\n\n\n#define AUTOCONNECT_MENU_TITLE \"AutoConnect\" \n// Default AutoConnect menu title\n\n\n#define AUTOCONNECT_URI \"/_ac\" \n// Default AutoConnect root path\n\n\n\n\n\nAutoConnect API\n\u00b6\n\n\n Constructors\n\u00b6\n\n\nAutoConnect\n\u00b6\n\n\nAutoConnect\n()\n\n\n\n\n\nAutoConnect default constructor. This entry activates WebServer internally and the web server is allocated internal.\n\n\nAutoConnect\n(\nESP8266WebServer\n&\n \nwebServer\n)\n\n\n\n\n\nRun the AutoConnect site using the externally ensured ESP 8266 WebServer. User's added URI handler response can be included in handleClient method.\n\n\n \nParameters\n\n \nwebServer\nA reference of ESP8266WebServer instance.\n\n\n\n\n Public member functions\n\u00b6\n\n\nbegin\n\u00b6\n\n\nbool\n \nbegin\n()\n\n\n\n\nbool\n \nbegin\n(\nconst\n \nchar\n*\n \nssid\n,\n \nconst\n \nchar\n*\n \npassphraase\n)\n\n\n\n\nbool\n \nbegin\n(\nconst\n \nchar\n*\n \nssid\n,\n \nconst\n \nchar\n*\n \npassphraase\n,\n \nunsinged\n \nlong\n \ntimeout\n)\n\n\n\n\nStarts establishing WiFi connection. Before establishing, start the Web server and DNS server for the captive portal. Then begins connection establishment in WIFI_STA mode. If connection can not established with the specified SSID and password, switch to WIFI_AP_STA mode and activate SoftAP.\n\n\n \nParameters\n\n \nssid\nSSID to be connected.\n\n \npassphrase\nPassword for connection.\n\n \ntimeout\nA time out value in milliseconds for waiting connection.\n\n \nReturn value\n\n \ntrue\nConnection established, AutoConnect service started with WIFI_STA mode.\n\n \nfalse\nCould not connected, Captive portal started with WIFI_AP_STA mode.\n\n\n\n\nconfig\n\u00b6\n\n\nbool\n \nconfig\n(\nAutoConnectConfig\n&\n \nconfig\n)\n\n\n\n\nbool\n \nconfig\n(\nconst\n \nchar\n*\n \nap\n,\n \nconst\n \nchar\n*\n \npassword\n \n=\n \nnullptr\n)\n\n\n\n\nSets SoftAP's WiFi configuration. \n\n\n \nParameters\n\n \nconfig\nReference to AutoConnectConfig containing SoftAP's parameters.\n\n \nap\nSSID for SoftAP. The default value is \nesp8266ap\n.\n\n \npassword\nPassword for SodtAP. The default value is \n12345678\n.\n\n \nReturn value\n\n \ntrue\nSuccessfully configured.\n\n \nfalse\nConfiguration parameter is invalid, some values out of range.\n\n\n\n\nend\n\u00b6\n\n\nvoid\n \nend\n()\n\n\n\n\n\nStops AutoConnect captive portal service. Release ESP8266WebServer and DNSServer. \n\n\n\n\nAttention to end\n\n\nThe end function releases the instance of ESP8266WebServer and DNSServer. It can not process them after the end function.\n\n\n\n\nhandleClient\n\u00b6\n\n\nvoid\n \nhandleClient\n()\n\n\n\n\n\nHandling for the AutoConnect web interface. Invoke the handleClient of the parent web server to process client request of the AutoConnect WEB interface. No effects when the web server is not available.\n\n\nhandleRequest\n\u00b6\n\n\nvoid\n \nhandleRequest\n()\n\n\n\n\n\nHandling for the AutoConnect menu request.\n\n\n\n\nAbout used in combination with handleClient\n\n\nThe handleRequest function is not supposed to use with AutoConnect::handleClient. It should be used with ESP8266::handleClient.\n\n\n\n\nhome\n\u00b6\n\n\nvoid\n \nhome\n(\nString\n \nuri\n)\n\n\n\n\n\nPut a user site's home URI. The URI specified by home is linked from \"HOME\" in the AutoConnect portal menu.\n\n\n \nParameters\n\n \nuri\n A URI string of user site's home path.\n\n\n\n\nhost\n\u00b6\n\n\nReturns the reference of the ESP8266WebServer which is allocated in AutoConnect automatically.\n\n\nESP8266WebServer\n&\n \nhost\n()\n\n\n\n\n\n \nReturn value\n\n \nA reference of the ESP8266WebServer.\n\n\n\n\n\n\n&reference is not a pointer\n\n\nA reference cannot be re-assigned, and must be assigned at initialization. It's like as bind as alias. \n\n\nESP8266WebServer\n&\n \nserver\n \n=\n \nportal\n.\nhost\n();\n\n\nserver\n.\nhandleClient\n();\n\n\n\nor\n\n\nportal\n.\nhost\n().\nhandleClient\n();\n\n\n\n\n\n\nonDetect\n\u00b6\n\n\nvoid\n \nonDetect\n(\nDetectExit_ft\n \nfn\n)\n\n\n\nRegister the function which will call from AutoConnect at the start of the captive portal.\n\n\n \nParameters\n\n \nfn\nFunction called at the captive portal start.\n\n\n\n\n\nAn \nfn\n specifies the function called when the captive portal starts. Its prototype declaration is defined as \"\nDetectFunc_ft\n\".\n\n\ntypedef\n \nstd\n::\nfunction\n<\nbool\n(\nIPAddress\n \nsoftapIP\n)\n>\n \nDetectExit_ft\n\n\n\n\n\n \nParameters\n\n \nsoftapIP\nAn IP address of SoftAP for the captive portal.\n\n \nRetuen value\n\n \ntrue\nContinues captive portal handling.\n\n \nfalse\nCancel the captive portal. AutoConnect::begin function will return with a false.\n\n\n\n\nonNotFound\n\u00b6\n\n\nvoid\n \nonNotFound\n(\nESP8266WebServer\n::\nTHandlerFunction\n \nfn\n)\n\n\n\nRegister the handler function for undefined URL request detected.\n\n\n \nParameters\n\n \nfn\nA function of the \"not found\" handler.\n\n\n\n\nAutoConnectConfig API\n\u00b6\n\n\n Constructor\n\u00b6\n\n\nAutoConnectConfig\n\u00b6\n\n\nAutoConnectConfig\n();\n\n\n\n\nAutoConnectConfig\n(\nconst\n \nchar\n*\n \nap\n,\n \nconst\n \nchar\n*\n \npassword\n);\n\n\n\n\n\n \nParameters\n\n \nap\nSSID for SoftAP. The length should be up to 31. The default value is \nesp8266ap\n.\n\n \npassword\nPassword for SodtAP. The length should be from 8 to up to 63. The default value is \n12345678\n.\n\n\n\n\n Public member variables\n\u00b6\n\n\napid\n\u00b6\n\n\nSoftAP's SSID.\n\n\n \nType\n\n \nString\n\n\n\n\napip\n\u00b6\n\n\nSets 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.\n\n\n \nType\n\n \nIPAddress\n\n\n\n\nautoReset\n\u00b6\n\n\nReset ESP8266 module automatically when WLAN disconnected.\n\n\n \nType\n\n \nbool\n\n \nValue\n\n \ntrue\nReset after WiFi disconnected automatically.\n\n \nfalse\nNo reset.\n\n\n\n\nautoSave\n\u00b6\n\n\nThe credential saved automatically at the connection establishment.\n\n\n \nType\n\n \nAC_SAVECREDENTIAL_t\n\n \nValue\n\n \nAC_SAVECREDENTIAL_AUTO\nThe credential saved automatically.\n\n \nAC_SAVECREDENTIAL_NEVER\nThe credential no saved.\n\n\n\n\nchannel\n\u00b6\n\n\nThe channel number of WIFi when SoftAP starts.\n\n\n \nType\n\n \nuint8_t\n\n \nValue\n\n \n1 ~ 14. The default value is 1.\n\n\n\n\n\n\nSee Application note\n\n\nEspressif Systems had announced the \napplication note\n about Wi-Fi channel selection.\n\n\n\n\ngateway\n\u00b6\n\n\nSets 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.\n\n\n \nType\n\n \nIPAddress\n\n\n\n\nhidden\n\u00b6\n\n\nSets SoftAP to hidden SSID.\n\n\n \nType\n\n \nuint8_t\n\n \nValue\n\n \n0\nSSID will be appeared. This is the default.\n\n \n1\nSSID will be hidden.\n\n\n\n\nhomeUri\n\u00b6\n\n\nSets the home path of user sketch. This path would be linked from 'HOME' in the AutoConnect menu.\n\n\n \nType\n\n \nString\n\n\n\n\nnetmask\n\u00b6\n\n\nSets 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.\n\n\n \nType\n\n \nIPAddress\n\n\n\n\npsk\n\u00b6\n\n\nSets password for SoftAP. The length should be from 8 to up to 63. The default value is \n12345678\n.\n\n\n \nType\n\n \nString\n\n\n\n\n AutoConnectConfig example\n\u00b6\n\n\nAutoConenct\n \nPortal\n;\n\n\nAutoConenctConfig\n \nConfig\n(\n\"\"\n,\n \n\"passpass\"\n);\n \n// SoftAp name is determined at runtime\n\n\nConfig\n.\napid\n \n=\n \nESP\n.\nhostname\n();\n \n// Retrieve host name to SotAp identification\n\n\nConfig\n.\napip\n \n=\n \nIPAddress\n(\n192\n,\n168\n,\n10\n,\n101\n);\n \n// Sets SoftAP IP address\n\n\nConfig\n.\ngateway\n \n=\n \nIPAddress\n(\n192\n,\n168\n,\n10\n,\n1\n);\n \n// Sets WLAN router IP address\n\n\nConfig\n.\nnetmask\n \n=\n \nIPAddress\n(\n255\n,\n255\n,\n255\n,\n0\n);\n \n// Sets WLAN scope\n\n\nConfig\n.\nautoSave\n \n=\n \nAC_SAVECREDENTIAL_NEVER\n;\n \n// No save credential\n\n\nConfig\n.\nhomeUri\n \n=\n \n\"/index.html\"\n \n// Sets home path of the sketch application\n\n\nPortal\n.\nconfig\n(\nConfig\n);\n \n// Configure AutoConnect\n\n\nPortal\n.\nbegin\n();\n \n// Starts and behaves captive portal\n\n\n\n\n\n Something extra\n\u00b6\n\n\nThe library presents two PNG icons which can be used to embed a hyperlink to the AutoConnect menu.\n\n\n\n\nBar type \n\n\nCog type \n\n\n\n\nTo reference the icon, use the \nAUTOCONNECT_LINK\n macro in the sketch. It expands into the string literal as an HTML \n\n tag with PNG embedded of the AutoConnect menu hyperlinks. Icon type is specified by the parameter of the macro.\n\n\n\n \nBAR_32\nBars icon, 32x32.\n\n \nBAR_48\nBars icon, 48x48.\n\n \nCOG_24\nCog icon, 24x24.\n\n \nCOG_32\nCog icon, 32x32.\n\n\n\n\n\n\n\nUsage\n\n\nString\n \nhtml\n \n=\n \n\"\"\n;\n\n\nhtml\n \n+=\n \nAUTOCONNECT_LINK\n(\nBAR_32\n);\n\n\nhtml\n \n+=\n \n\"\"\n;\n\n\nserver\n.\nsend\n(\n200\n,\n \n\"text/html\"\n,\n \nhtml\n);", + "text": "Include headers\n\u00b6\n\n\n AutoConnect.h\n\u00b6\n\n\n#include\n \n\n\n\n\n\n\nDefine macros\n\u00b6\n\n\n#define AC_DEBUG \n// Monitor message output activation\n\n\n#define AC_DEBUG_PORT Serial \n// Default message output device\n\n\n#define AUTOCONNECT_AP_IP 0x01F4A8C0 \n// Default SoftAP IP\n\n\n#define AUTOCONNECT_AP_GW 0x01F4A8C0 \n// Default SoftAP Gateway IP\n\n\n#define AUTOCONNECT_AP_NM 0x00FFFFFF \n// Default subnet mask\n\n\n#define AUTOCONNECT_DNSPORT 53 \n// Default DNS port at captive portal\n\n\n#define AUTOCONNECT_MENU_TITLE \"AutoConnect\" \n// Default AutoConnect menu title\n\n\n#define AUTOCONNECT_STARTUPTIME 10 \n// Default waiting time[s] for after reset\n\n\n#define AUTOCONNECT_URI \"/_ac\" \n// Default AutoConnect root path\n\n\n#define AUTOCONNECT_TIMEOUT 30000 \n// Default connection timeout[ms]\n\n\n\n\n\nAutoConnect API\n\u00b6\n\n\n Constructors\n\u00b6\n\n\nAutoConnect\n\u00b6\n\n\nAutoConnect\n()\n\n\n\n\n\nAutoConnect default constructor. This entry activates WebServer internally and the web server is allocated internal.\n\n\nAutoConnect\n(\nESP8266WebServer\n&\n \nwebServer\n)\n\n\n\n\n\nRun the AutoConnect site using the externally ensured ESP 8266 WebServer. User's added URI handler response can be included in handleClient method.\n\n\n \nParameters\n\n \nwebServer\nA reference of ESP8266WebServer instance.\n\n\n\n\n Public member functions\n\u00b6\n\n\nbegin\n\u00b6\n\n\nbool\n \nbegin\n()\n\n\n\n\nbool\n \nbegin\n(\nconst\n \nchar\n*\n \nssid\n,\n \nconst\n \nchar\n*\n \npassphraase\n)\n\n\n\n\nbool\n \nbegin\n(\nconst\n \nchar\n*\n \nssid\n,\n \nconst\n \nchar\n*\n \npassphraase\n,\n \nunsinged\n \nlong\n \ntimeout\n)\n\n\n\n\nStarts establishing WiFi connection. Before establishing, start the Web server and DNS server for the captive portal. Then begins connection establishment in WIFI_STA mode. If connection can not established with the specified SSID and password, switch to WIFI_AP_STA mode and activate SoftAP.\n\n\n \nParameters\n\n \nssid\nSSID to be connected.\n\n \npassphrase\nPassword for connection.\n\n \ntimeout\nA time out value in milliseconds for waiting connection.\n\n \nReturn value\n\n \ntrue\nConnection established, AutoConnect service started with WIFI_STA mode.\n\n \nfalse\nCould not connected, Captive portal started with WIFI_AP_STA mode.\n\n\n\n\nconfig\n\u00b6\n\n\nbool\n \nconfig\n(\nAutoConnectConfig\n&\n \nconfig\n)\n\n\n\n\nbool\n \nconfig\n(\nconst\n \nchar\n*\n \nap\n,\n \nconst\n \nchar\n*\n \npassword\n \n=\n \nnullptr\n)\n\n\n\n\nSets SoftAP's WiFi configuration. \n\n\n \nParameters\n\n \nconfig\nReference to AutoConnectConfig containing SoftAP's parameters.\n\n \nap\nSSID for SoftAP. The default value is \nesp8266ap\n.\n\n \npassword\nPassword for SodtAP. The default value is \n12345678\n.\n\n \nReturn value\n\n \ntrue\nSuccessfully configured.\n\n \nfalse\nConfiguration parameter is invalid, some values out of range.\n\n\n\n\nend\n\u00b6\n\n\nvoid\n \nend\n()\n\n\n\n\n\nStops AutoConnect captive portal service. Release ESP8266WebServer and DNSServer. \n\n\n\n\nAttention to end\n\n\nThe end function releases the instance of ESP8266WebServer and DNSServer. It can not process them after the end function.\n\n\n\n\nhandleClient\n\u00b6\n\n\nvoid\n \nhandleClient\n()\n\n\n\n\n\nHandling for the AutoConnect web interface. Invoke the handleClient of the parent web server to process client request of the AutoConnect WEB interface. No effects when the web server is not available.\n\n\nhandleRequest\n\u00b6\n\n\nvoid\n \nhandleRequest\n()\n\n\n\n\n\nHandling for the AutoConnect menu request.\n\n\n\n\nAbout used in combination with handleClient\n\n\nThe handleRequest function is not supposed to use with AutoConnect::handleClient. It should be used with ESP8266::handleClient.\n\n\n\n\nhome\n\u00b6\n\n\nvoid\n \nhome\n(\nString\n \nuri\n)\n\n\n\n\n\nPut a user site's home URI. The URI specified by home is linked from \"HOME\" in the AutoConnect portal menu.\n\n\n \nParameters\n\n \nuri\n A URI string of user site's home path.\n\n\n\n\nhost\n\u00b6\n\n\nReturns the reference of the ESP8266WebServer which is allocated in AutoConnect automatically.\n\n\nESP8266WebServer\n&\n \nhost\n()\n\n\n\n\n\n \nReturn value\n\n \nA reference of the ESP8266WebServer.\n\n\n\n\n\n\n&reference is not a pointer\n\n\nA reference cannot be re-assigned, and must be assigned at initialization. It's like as bind as alias. \n\n\nESP8266WebServer\n&\n \nserver\n \n=\n \nportal\n.\nhost\n();\n\n\nserver\n.\nhandleClient\n();\n\n\n\nor\n\n\nportal\n.\nhost\n().\nhandleClient\n();\n\n\n\n\n\n\nonDetect\n\u00b6\n\n\nvoid\n \nonDetect\n(\nDetectExit_ft\n \nfn\n)\n\n\n\nRegister the function which will call from AutoConnect at the start of the captive portal.\n\n\n \nParameters\n\n \nfn\nFunction called at the captive portal start.\n\n\n\n\n\nAn \nfn\n specifies the function called when the captive portal starts. Its prototype declaration is defined as \"\nDetectFunc_ft\n\".\n\n\ntypedef\n \nstd\n::\nfunction\n<\nbool\n(\nIPAddress\n \nsoftapIP\n)\n>\n \nDetectExit_ft\n\n\n\n\n\n \nParameters\n\n \nsoftapIP\nAn IP address of SoftAP for the captive portal.\n\n \nRetuen value\n\n \ntrue\nContinues captive portal handling.\n\n \nfalse\nCancel the captive portal. AutoConnect::begin function will return with a false.\n\n\n\n\nonNotFound\n\u00b6\n\n\nvoid\n \nonNotFound\n(\nESP8266WebServer\n::\nTHandlerFunction\n \nfn\n)\n\n\n\nRegister the handler function for undefined URL request detected.\n\n\n \nParameters\n\n \nfn\nA function of the \"not found\" handler.\n\n\n\n\nAutoConnectConfig API\n\u00b6\n\n\n Constructor\n\u00b6\n\n\nAutoConnectConfig\n\u00b6\n\n\nAutoConnectConfig\n();\n\n\n\n\nAutoConnectConfig\n(\nconst\n \nchar\n*\n \nap\n,\n \nconst\n \nchar\n*\n \npassword\n);\n\n\n\n\n\n \nParameters\n\n \nap\nSSID for SoftAP. The length should be up to 31. The default value is \nesp8266ap\n.\n\n \npassword\nPassword for SodtAP. The length should be from 8 to up to 63. The default value is \n12345678\n.\n\n\n\n\n Public member variables\n\u00b6\n\n\napid\n\u00b6\n\n\nSoftAP's SSID.\n\n\n \nType\n\n \nString\n\n\n\n\napip\n\u00b6\n\n\nSets 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.\n\n\n \nType\n\n \nIPAddress\n\n\n\n\nautoReset\n\u00b6\n\n\nReset ESP8266 module automatically when WLAN disconnected.\n\n\n \nType\n\n \nbool\n\n \nValue\n\n \ntrue\nReset after WiFi disconnected automatically.\n\n \nfalse\nNo reset.\n\n\n\n\nautoRise\n\u00b6\n\n\nCaptive portal activation switch. False for disabling the captive portal. It prevents starting the captive portal even if the connection at the first \nWiFi.begin\n fails.\n\n\n \nType\n\n \nbool\n\n \nValue\n\n \ntrue\nEnable the captive portal. This is a default.\n\n \nfalse\nDisable the captive portal.\n\n\n\n\nautoSave\n\u00b6\n\n\nThe credential saved automatically at the connection establishment.\n\n\n \nType\n\n \nAC_SAVECREDENTIAL_t\n\n \nValue\n\n \nAC_SAVECREDENTIAL_AUTO\nThe credential saved automatically.\n\n \nAC_SAVECREDENTIAL_NEVER\nThe credential no saved.\n\n\n\n\nchannel\n\u00b6\n\n\nThe channel number of WIFi when SoftAP starts.\n\n\n \nType\n\n \nuint8_t\n\n \nValue\n\n \n1 ~ 14. The default value is 1.\n\n\n\n\n\n\nSee Application note\n\n\nEspressif Systems had announced the \napplication note\n about Wi-Fi channel selection.\n\n\n\n\ngateway\n\u00b6\n\n\nSets 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.\n\n\n \nType\n\n \nIPAddress\n\n\n\n\nhidden\n\u00b6\n\n\nSets SoftAP to hidden SSID.\n\n\n \nType\n\n \nuint8_t\n\n \nValue\n\n \n0\nSSID will be appeared. This is the default.\n\n \n1\nSSID will be hidden.\n\n\n\n\nhomeUri\n\u00b6\n\n\nSets the home path of user sketch. This path would be linked from 'HOME' in the AutoConnect menu.\n\n\n \nType\n\n \nString\n\n\n\n\nnetmask\n\u00b6\n\n\nSets 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.\n\n\n \nType\n\n \nIPAddress\n\n\n\n\npsk\n\u00b6\n\n\nSets password for SoftAP. The length should be from 8 to up to 63. The default value is \n12345678\n.\n\n\n \nType\n\n \nString\n\n\n\n\n AutoConnectConfig example\n\u00b6\n\n\nAutoConenct\n \nPortal\n;\n\n\nAutoConenctConfig\n \nConfig\n(\n\"\"\n,\n \n\"passpass\"\n);\n \n// SoftAp name is determined at runtime\n\n\nConfig\n.\napid\n \n=\n \nESP\n.\nhostname\n();\n \n// Retrieve host name to SotAp identification\n\n\nConfig\n.\napip\n \n=\n \nIPAddress\n(\n192\n,\n168\n,\n10\n,\n101\n);\n \n// Sets SoftAP IP address\n\n\nConfig\n.\ngateway\n \n=\n \nIPAddress\n(\n192\n,\n168\n,\n10\n,\n1\n);\n \n// Sets WLAN router IP address\n\n\nConfig\n.\nnetmask\n \n=\n \nIPAddress\n(\n255\n,\n255\n,\n255\n,\n0\n);\n \n// Sets WLAN scope\n\n\nConfig\n.\nautoSave\n \n=\n \nAC_SAVECREDENTIAL_NEVER\n;\n \n// No save credential\n\n\nConfig\n.\nhomeUri\n \n=\n \n\"/index.html\"\n \n// Sets home path of the sketch application\n\n\nPortal\n.\nconfig\n(\nConfig\n);\n \n// Configure AutoConnect\n\n\nPortal\n.\nbegin\n();\n \n// Starts and behaves captive portal\n\n\n\n\n\n Something extra\n\u00b6\n\n\nThe library presents two PNG icons which can be used to embed a hyperlink to the AutoConnect menu.\n\n\n\n\nBar type \n\n\nCog type \n\n\n\n\nTo reference the icon, use the \nAUTOCONNECT_LINK\n macro in the sketch. It expands into the string literal as an HTML \n\n tag with PNG embedded of the AutoConnect menu hyperlinks. Icon type is specified by the parameter of the macro.\n\n\n\n \nBAR_32\nBars icon, 32x32.\n\n \nBAR_48\nBars icon, 48x48.\n\n \nCOG_24\nCog icon, 24x24.\n\n \nCOG_32\nCog icon, 32x32.\n\n\n\n\n\n\n\nUsage\n\n\nString\n \nhtml\n \n=\n \n\"\"\n;\n\n\nhtml\n \n+=\n \nAUTOCONNECT_LINK\n(\nBAR_32\n);\n\n\nhtml\n \n+=\n \n\"\"\n;\n\n\nserver\n.\nsend\n(\n200\n,\n \n\"text/html\"\n,\n \nhtml\n);", "title": "Library APIs" }, { @@ -277,7 +282,7 @@ }, { "location": "/api/index.html#define-macros", - "text": "#define AC_DEBUG // Monitor message output activation #define AC_DEBUG_PORT Serial // Default message output device #define AUTOCONNECT_AP_IP 0x01F4A8C0 // Default SoftAP IP #define AUTOCONNECT_AP_GW 0x01F4A8C0 // Default SoftAP Gateway IP #define AUTOCONNECT_AP_NM 0x00FFFFFF // Default subnet mask #define AUTOCONNECT_DNSPORT 53 // Default DNS port at captive portal #define AUTOCONNECT_MENU_TITLE \"AutoConnect\" // Default AutoConnect menu title #define AUTOCONNECT_URI \"/_ac\" // Default AutoConnect root path", + "text": "#define AC_DEBUG // Monitor message output activation #define AC_DEBUG_PORT Serial // Default message output device #define AUTOCONNECT_AP_IP 0x01F4A8C0 // Default SoftAP IP #define AUTOCONNECT_AP_GW 0x01F4A8C0 // Default SoftAP Gateway IP #define AUTOCONNECT_AP_NM 0x00FFFFFF // Default subnet mask #define AUTOCONNECT_DNSPORT 53 // Default DNS port at captive portal #define AUTOCONNECT_MENU_TITLE \"AutoConnect\" // Default AutoConnect menu title #define AUTOCONNECT_STARTUPTIME 10 // Default waiting time[s] for after reset #define AUTOCONNECT_URI \"/_ac\" // Default AutoConnect root path #define AUTOCONNECT_TIMEOUT 30000 // Default connection timeout[ms]", "title": "Define macros" }, { @@ -380,6 +385,11 @@ "text": "Reset ESP8266 module automatically when WLAN disconnected. \n Type \n bool \n Value \n true Reset after WiFi disconnected automatically. \n false No reset.", "title": "autoReset" }, + { + "location": "/api/index.html#autorise", + "text": "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. \n Type \n bool \n Value \n true Enable the captive portal. This is a default. \n false Disable the captive portal.", + "title": "autoRise" + }, { "location": "/api/index.html#autosave", "text": "The credential saved automatically at the connection establishment. \n Type \n AC_SAVECREDENTIAL_t \n Value \n AC_SAVECREDENTIAL_AUTO The credential saved automatically. \n AC_SAVECREDENTIAL_NEVER The credential no saved.", diff --git a/docs/usage/index.html b/docs/usage/index.html index 765fd8f..79edd72 100644 --- a/docs/usage/index.html +++ b/docs/usage/index.html @@ -451,6 +451,13 @@ 404 handler +
    • + +
  • + + Auto save Credential + +
  • @@ -468,15 +475,15 @@
  • - - Credential data + + Debug print
  • - - Debug print + + Disable the captive portal
    • @@ -733,6 +740,13 @@ 404 handler + + +
  • + + Auto save Credential + +
  • @@ -750,15 +764,15 @@
  • - - Credential data + + Debug print
  • - - Debug print + + Disable the captive portal
    • @@ -846,12 +860,15 @@

    Embed to the sketches

    How embed the AutoConnect to the sketches you have. Most simple approach to applying AutoConnect for the existing sketches, follow the below steps.

    -

    Insert #include <AutoConnect.h> to behind of #include <ESP8266WebServer.h>.
    - Insert AutoConnectPORTAL(WEBSERVER); to behind of ESP8266WebServerWEBSERVER; declaration.1
    - Remove WiFi.begin(SSID,PSK) and the subsequent logic for the connection status check.
    - Replace WEBSERVER.begin() to PORTAL.begin().2
    - Replace WEBSERVER.handleClient() to PORTAL.handleClient().3
    - If the connection successful logic is needed, you can check the return value as true or false of PORTAL.begin().

    + +

    Basic usage

    Basic logic sequence for the user sketches

    1. A typical logic sequence

    @@ -945,6 +962,15 @@ or

    Advanced usage

    404 handler

    Registering the "not found" handler is a different way than ESP8266. The onNotFound of ESP8266WebServer does not work with AutoConnect. AutoConnect overrides ESP8266WebServer::onNotFound to handle a captive portal. To register "not found" handler, use AutoConnect::onNotFound.

    +

    Auto save Credential

    +

    By default, AutoConnect saves the credentials of the established connection in EEPROM. You can disable it with the autoSave parameter specified by AutoConnect::config.

    +
    AutoConnect       Portal;
+AutoConnectConfig Config;
+Config.autoSave = AC_SAVECREDENTIAL_NEVER;
+Portal.config(Config);
+Portal.begin();
+
    +

    Captive portal start detection

    The captive portal will only be activated if the first WiFi::begin fails. Sketch can detect with the onDetect funciton 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.

    AutoConnect Portal;
@@ -990,15 +1016,6 @@ or
    
 }
    -

    Credential data

    -

    By default, AutoConnect saves the credentials of the established connection in EEPROM. You can disable it with the autoSave parameter specified by AutoConnect::config.

    -
    AutoConnect       Portal;
-AutoConnectConfig Config;
-Config.autoSave = AC_SAVECREDENTIAL_NEVER;
-Portal.config(Config);
-Portal.begin();
-
    -

    AutoConnect::config before AutoConnect::begin

    AutoConnect::config must be executed before AutoConnect::begin.

    @@ -1008,6 +1025,17 @@ or

    #define AC_DEBUG
    +

    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, the behavior of AutoConnect::begin is the same as WiFi.begin.

    +

    For disabling the captive portal, autoRise sets to false with AutoConnectConfig.

    +
    AutoConnect       portal;
+AutoConnectConfig acConfig;
+
+acConfig.autoRaise = false;
+portal.config(acConfig);
+portal.begin();
+
    +

    Refers the hosted ESP8266WebServer

    Constructing an AutoConnect object variable without parameters then creates and starts an ESP8266WebServer inside the AutoConnect. This object variable could be referred by AutoConnect::host() function to access ESP8266WebServer instance as like below.

    AutoConnect Portal;
diff --git a/mkdocs/api.md b/mkdocs/api.md
index 28873b9..6155fba 100644
--- a/mkdocs/api.md
+++ b/mkdocs/api.md
@@ -16,7 +16,9 @@
 #define AUTOCONNECT_AP_NM       0x00FFFFFF      // Default subnet mask
 #define AUTOCONNECT_DNSPORT     53              // Default DNS port at captive portal
 #define AUTOCONNECT_MENU_TITLE  "AutoConnect"   // Default AutoConnect menu title
+#define AUTOCONNECT_STARTUPTIME 10              // Default waiting time[s] for after reset
 #define AUTOCONNECT_URI         "/_ac"          // Default AutoConnect root path
+#define AUTOCONNECT_TIMEOUT     30000           // Default connection timeout[ms]
 ```
 
 ## AutoConnect API
@@ -233,6 +235,17 @@ Reset ESP8266 module automatically when WLAN disconnected.
     
    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 a default.
    
+    
    falseDisable the captive portal.
    
+
    
+
 #### autoSave
 
 The credential saved automatically at the connection establishment.
diff --git a/mkdocs/css/paragraph.css b/mkdocs/css/paragraph.css
index 130e8df..0f8f66a 100644
--- a/mkdocs/css/paragraph.css
+++ b/mkdocs/css/paragraph.css
@@ -35,4 +35,10 @@
 
 .apidl {
   margin-left: 20px;
+}
+
+.ulsty-edit > li:before {
+  font-family: 'FontAwesome';
+  content: '\f044';
+  margin:0 0.8em 0 -1.8em;
 }
\ No newline at end of file
diff --git a/mkdocs/usage.md b/mkdocs/usage.md
index 1c2bdd6..3fd694e 100644
--- a/mkdocs/usage.md
+++ b/mkdocs/usage.md
@@ -6,12 +6,14 @@ How embed the AutoConnect to the sketches you have. Most simple approach to appl
 
 
 
- Insert `#include ` to behind of `#include `.  
- Insert `AutoConnect`*`PORTAL(WEBSERVER);`* to behind of `ESP8266WebServer`*`WEBSERVER;`* declaration.[^1]  
- Remove `WiFi.begin(`*`SSID`*`,`*`PSK`*`)` and the subsequent logic for the connection status check.  
- Replace *`WEBSERVER`*`.begin()` to *`PORTAL`*`.begin()`.[^2]  
- Replace *`WEBSERVER`*`.handleClient()` to *`PORTAL`*`.handleClient()`.[^3]  
- If the connection successful logic is needed, you can check the return value as `true` or `false` of *`PORTAL`*`.begin()`.
+
      
+  
    • Insert #include <AutoConnect.h> to behind of #include <ESP8266WebServer.h>.
      • 
+  
    • Insert AutoConnect PORTAL(WEBSERVER); to behind of ESP8266WebServer WEBSERVER; declaration.1
      • 
+  
    • Remove WiFi.begin(SSID,PSK) and the subsequent logic for the connection status check.
      • 
+  
    • Replace WEBSERVER.begin() to PORTAL.begin().2
      • 
+  
    • Replace WEBSERVER.handleClient() to PORTAL.handleClient().3
      • 
+  
    • If the connection checks logic is needed, you can check the return value according to PORTAL.begin() with true or false.
      • 
+
    
 
 [^1]:
 Each *VARIABLE* conforms to the actual declaration in the sketches.  
@@ -108,6 +110,18 @@ Reference to ESP8266WebServer | AutoConnect menu not available.
    host() not ne
 
 Registering the "not found" handler is a different way than ESP8266. The *onNotFound* of ESP8266WebServer does not work with AutoConnect. AutoConnect overrides *ESP8266WebServer::onNotFound* to handle a captive portal. To register "not found" handler, use [*AutoConnect::onNotFound*](api.md#onnotfound).
 
+###  Auto save Credential
+
+By default, AutoConnect saves the credentials of the established connection in EEPROM. You can disable it with the **autoSave** parameter specified by [*AutoConnect::config*](api.md#config).
+
+```arduino hl_lines="3"
+AutoConnect       Portal;
+AutoConnectConfig Config;
+Config.autoSave = AC_SAVECREDENTIAL_NEVER;
+Portal.config(Config);
+Portal.begin();
+```
+
 ###  Captive portal start detection
 
 The captive portal will only be activated if the first *WiFi::begin* fails. Sketch can detect with the [*onDetect*](api.md#ondetect) funciton 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.
@@ -159,18 +173,6 @@ void loop() {
 }
 ```
 
-###  Credential data
-
-By default, AutoConnect saves the credentials of the established connection in EEPROM. You can disable it with the **autoSave** parameter specified by [*AutoConnect::config*](api.md#config).
-
-```arduino hl_lines="3"
-AutoConnect       Portal;
-AutoConnectConfig Config;
-Config.autoSave = AC_SAVECREDENTIAL_NEVER;
-Portal.config(Config);
-Portal.begin();
-```
-
 !!! note "AutoConnect::config before AutoConnect::begin"
     *AutoConnect::config* must be executed before *AutoConnect::begin*.
 
@@ -182,6 +184,21 @@ You can output AutoConnect monitor messages to the **Serial**. A monitor message
 #define AC_DEBUG
 ```
 
+###  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, the behavior of *AutoConnect::begin* is the same as *WiFi.begin*.
+
+For disabling the captive portal, **autoRise** sets to false with AutoConnectConfig.
+
+```arduino hl_lines="4"
+AutoConnect       portal;
+AutoConnectConfig acConfig;
+
+acConfig.autoRaise = false;
+portal.config(acConfig);
+portal.begin();
+```
+
 ###  Refers the hosted ESP8266WebServer
 
 Constructing an AutoConnect object variable without parameters then creates and starts an ESP8266WebServer inside the AutoConnect. This object variable could be referred by [*AutoConnect::host()*](api.md#host) function to access ESP8266WebServer instance as like below.
diff --git a/src/AutoConnect.cpp b/src/AutoConnect.cpp
index 827b953..77aa666 100644
--- a/src/AutoConnect.cpp
+++ b/src/AutoConnect.cpp
@@ -99,46 +99,53 @@ bool AutoConnect::begin(const char* ssid, const char* passphrase) {
   cs = _waitForConnect(_portalTimeout) == WL_CONNECTED;
   _currentHostIP = WiFi.localIP();
 
-  // Rushing into the portal.
+  // It doesn't matter the connection status for launching the Web server.
   _startWebServer();
+
+  // Rushing into the portal.
   if (!cs) {
-    // Change WiFi working mode, Enable AP with STA
-    WiFi.setAutoConnect(false);
-    WiFi.disconnect();
-    WiFi.mode(WIFI_AP_STA);
-    delay(100);
 
-    // Connection unsuccessful, launch the captive portal.
-    if (!(_apConfig.apip == IPAddress(0, 0, 0, 0) || _apConfig.gateway == IPAddress(0, 0, 0, 0) || _apConfig.netmask == IPAddress(0, 0, 0, 0))) {
-      _config();
-    }
-    WiFi.softAP(_apConfig.apid.c_str(), _apConfig.psk.c_str(), _apConfig.channel, _apConfig.hidden);
-    while (WiFi.softAPIP() == IPAddress(0, 0, 0, 0))
-      yield();
-    _currentHostIP = WiFi.softAPIP();
-    AC_DBG("SoftAP %s/%s CH(%d) H(%d) IP:%s\n", _apConfig.apid.c_str(), _apConfig.psk.c_str(), _apConfig.channel, _apConfig.hidden, WiFi.softAPIP().toString().c_str());
-
-    // Fork to the exit routine that starts captive portal.
-    cs = _onDetectExit ? _onDetectExit(_currentHostIP) : true; 
-    
-    // Start captive portal without cancellation by DetectExit.
-    if (cs) {
-      // Prepare for redirecting captive portal detection.
-      // Pass all URL requests to _captivePortal to disguise the captive portal.
-      _startDNSServer();
-
-      // Start the captive portal to make a new connection
-      while (WiFi.status() != WL_CONNECTED && !_rfReset) {
-        handleClient();
-        // Force execution of queued processes.
-        yield();
+    // The captive portal is effective at the autoRise is valid only.
+    if (_apConfig.autoRise) {
+
+      // Change WiFi working mode, Enable AP with STA
+      WiFi.setAutoConnect(false);
+      WiFi.disconnect();
+      WiFi.mode(WIFI_AP_STA);
+      delay(100);
+
+      // Connection unsuccessful, launch the captive portal.
+      if (!(_apConfig.apip == IPAddress(0, 0, 0, 0) || _apConfig.gateway == IPAddress(0, 0, 0, 0) || _apConfig.netmask == IPAddress(0, 0, 0, 0))) {
+        _config();
       }
-      cs = WiFi.status() == WL_CONNECTED;
+      WiFi.softAP(_apConfig.apid.c_str(), _apConfig.psk.c_str(), _apConfig.channel, _apConfig.hidden);
+      while (WiFi.softAPIP() == IPAddress(0, 0, 0, 0))
+        yield();
+      _currentHostIP = WiFi.softAPIP();
+      AC_DBG("SoftAP %s/%s CH(%d) H(%d) IP:%s\n", _apConfig.apid.c_str(), _apConfig.psk.c_str(), _apConfig.channel, _apConfig.hidden, WiFi.softAPIP().toString().c_str());
 
-      // If WLAN successfully connected, release DNS server.
+      // Fork to the exit routine that starts captive portal.
+      cs = _onDetectExit ? _onDetectExit(_currentHostIP) : true; 
+      
+      // Start captive portal without cancellation by DetectExit.
       if (cs) {
-        _dnsServer->stop();
-        _dnsServer.reset();
+        // Prepare for redirecting captive portal detection.
+        // Pass all URL requests to _captivePortal to disguise the captive portal.
+        _startDNSServer();
+
+        // Start the captive portal to make a new connection
+        while (WiFi.status() != WL_CONNECTED && !_rfReset) {
+          handleClient();
+          // Force execution of queued processes.
+          yield();
+        }
+        cs = WiFi.status() == WL_CONNECTED;
+
+        // If WLAN successfully connected, release DNS server.
+        if (cs) {
+          _dnsServer->stop();
+          _dnsServer.reset();
+        }
       }
     }
   }
diff --git a/src/AutoConnect.h b/src/AutoConnect.h
index 5f700e4..6d05b5a 100644
--- a/src/AutoConnect.h
+++ b/src/AutoConnect.h
@@ -110,8 +110,9 @@ class AutoConnectConfig {
     channel(1),
     hidden(0),
     autoSave(AC_SAVECREDENTIAL_AUTO),
-    autoReset(true),
     uptime(AUTOCONNECT_STARTUPTIME),
+    autoRise(true),
+    autoReset(true),
     homeUri(AUTOCONNECT_HOMEURI) {}
   /**
    *  Configure by SSID for the captive portal access point and password.
@@ -125,8 +126,9 @@ class AutoConnectConfig {
     channel(1),
     hidden(0),
     autoSave(AC_SAVECREDENTIAL_AUTO),
-    autoReset(true),
     uptime(AUTOCONNECT_STARTUPTIME),
+    autoRise(true),
+    autoReset(true),
     homeUri(AUTOCONNECT_HOMEURI) {}
 
   ~AutoConnectConfig() {}
@@ -140,8 +142,9 @@ class AutoConnectConfig {
     channel = o.channel;
     hidden = o.hidden;
     autoSave = o.autoSave;
-    autoReset = o.autoReset;
     uptime = o.uptime;
+    autoRise = o.autoRise;
+    autoReset = o.autoReset;
     homeUri = o.homeUri;
     return *this;
   }
@@ -154,8 +157,9 @@ class AutoConnectConfig {
   uint8_t   channel;    /**< SoftAP used wifi channel */
   uint8_t   hidden;     /**< SoftAP SSID hidden */
   AC_SAVECREDENTIAL_t  autoSave;  /**< Auto save credential */
-  bool      autoReset;  /**< Reset ESP8266 module automatically when WLAN disconnected. */
   int       uptime;     /**< Length of start up time */
+  bool      autoRise;   /**< automatic starting the captive portal */
+  bool      autoReset;  /**< Reset ESP8266 module automatically when WLAN disconnected. */
   String    homeUri;    /**< A URI of user site */
 };