Supports for AutoConnectTicker

mkdocs/advancedusage.md

@@ -492,3 +492,40 @@ portal.begin();
 - Up to 24 characters
 - Only the alphabet (a-z, A-Z), digits (0-9), minus sign (-)
 - No '-' as last character
+
+### <i class="fa fa-caret-right"></i> Ticker for WiFi status
+
+Flicker signal can be output from the ESP8266/ESP32 module according to WiFi connection status. If you connect the LED to the signal output pin, you can know the WiFi connection status during behavior inside AutoConnect::begin through the LED blink.
+
+[AutoConnectConfig::ticker](apiconfig.md#ticker) option specifies flicker signal output. The following sketch is an example of flashing the active-high LED connected to pin #16 according to WiFi connection during the AutoConnect::begin.
+
+```cpp
+AutoConnect        portal;
+AutoConnectConfig  Config;
+Config.ticker = true;
+config.tickerPort = 16;
+Config.tickerOn = HIGH;
+portal.config(Config);
+portal.begin();
+```
+
+The AutoConnect ticker indicates the WiFi connection status in the following three flicker patterns:
+
+- Short blink: The ESP module stays in APSTA mode.
+- Short-on and long-off: No STA connection state. (i.e. WiFi.status != WL_CONNECTED)
+- No blink: WiFi connection with access point established and data link enabled. (i.e. WiFi.status = WL_CONNECTED)
+
+The flicker cycle length is defined by some macros in `AutoConnectDefs.h` header file.
+
+```cpp
+#define AUTOCONNECT_FLICKER_PERIODAP  1000 // [ms]
+#define AUTOCONNECT_FLICKER_PERIODDC  (AUTOCONNECT_FLICKER_PERIODAP << 1) // [ms]
+#define AUTOCONNECT_FLICKER_WIDTHAP   96  // (8 bit resolution)
+#define AUTOCONNECT_FLICKER_WIDTHDC   16  // (8 bit resolution)
+```
+
+`AUTOCONNECTT_FLICKER_PERIODAP` assigns a flicker period when the ESP module stays in APSTA mode. `AUTOCONNECT_FLICKER_PERIODDC` assigns a flicker period when WiFi is disconnected. `AUTOCONNECT_FLICKER_WIDTHAP` and `AUTOCONNECT_FLICKER_WIDTHDC` specify the duty rate for each period[ms] in 8-bit resolution.
+
+[AutoConnectConfig::tickerPort](apiconfig.md#tickerport) specifies a port that outputs the flicker signal. If you are using an LED-equipped ESP module board, you can assign a LED pin to the tick-port for the WiFi connection monitoring without the external LED.
+
+[AutoConnectConfig::tickerOn](apiconfig.md#tickeron) specifies the active logic level of the flicker signal. This value indicates the active signal level when driving the ticker. For example, if the LED connected to tickPort lights by LOW, the tickerOn is **LOW**.

mkdocs/apiconfig.md

@@ -253,6 +253,35 @@ Set the subnetmask when using static IP address.
     <dd>IPAddress</dd>
 </dl>
 
+### <i class="fa fa-caret-right"></i> ticker
+
+Set flicker signal output according to WiFi connection status during AutoConnect::begin behavior.
+<dl class="apidl">
+    <dt>**Type**</dt>
+    <dd>bool</dd>
+    <dt>**Value**</dt>
+    <dd><span class="apidef">true</span><span class="apidesc">Output the flicker signal while [AutoConnect::begin](api.md#begin) operation. The **AUTOCONNECT_TICKER_PORT** macro in the `AutoConnectDefs.h` header file assigns pins for signal output. The default pin is arduino valiant's LED_BUILTIN. For boards without the LED_BUILTIN pin, assume pin #2.</span></dd>
+    <dd><span class="apidef">false</span>No flicker signal output.<span class="apidesc"></span></dd>
+</dl>
+
+### <i class="fa fa-caret-right"></i> tickerPort
+
+Specifies the GPIO port number to output the flicker signal of the ticker. The default assumes on the board dependent definition LED_BUILTIN macro redefined by **AUTOCONNECT_TICKER_PORT** in `AutoConnectDefs.h`.
+<dl class="apidl">
+    <dt>**Type**</dt>
+    <dd>uint8_t</dd>
+    <dd><span class="apidef">LOW</span>A flicker signal is an active-high.<span class="apidesc"></span></dd>
+    <dd><span class="apidef">HIGH</span>A flicker signal is an active-low.<span class="apidesc"></span></dd>
+</dl>
+
+### <i class="fa fa-caret-right"></i> tickerOn
+
+Specifies the active logic level of the flicker signal.
+<dl class="apidl">
+    <dt>**Type**</dt>
+    <dd>uint8_t</dd>
+</dl>
+
 ### <i class="fa fa-caret-right"></i> title
 
 Set the menu title.

src/AutoConnect.cpp

@@ -108,7 +108,7 @@ bool AutoConnect::begin(const char* ssid, const char* passphrase, unsigned long
   if (_apConfig.ticker) {
     _ticker.reset(new AutoConnectTicker(_apConfig.tickerPort, _apConfig.tickerOn));
     if (WiFi.status() != WL_CONNECTED)
-      _ticker->start(AUTOCONNECT_FLICKER_PERIOD, (uint8_t)AUTOCONNECT_FLICKER_WIDTHDC);
+      _ticker->start(AUTOCONNECT_FLICKER_PERIODDC, (uint8_t)AUTOCONNECT_FLICKER_WIDTHDC);
   }
 
   // Advance configuration for STA mode.
@@ -205,7 +205,7 @@ bool AutoConnect::begin(const char* ssid, const char* passphrase, unsigned long
 
       // Start ticker with AP_STA
       if (_ticker)
-        _ticker->start(AUTOCONNECT_FLICKER_PERIOD, (uint8_t)AUTOCONNECT_FLICKER_WIDTHAP);
+        _ticker->start(AUTOCONNECT_FLICKER_PERIODAP, (uint8_t)AUTOCONNECT_FLICKER_WIDTHAP);
 
       // Fork to the exit routine that starts captive portal.
       cs = _onDetectExit ? _onDetectExit(_currentHostIP) : true;

src/AutoConnectDefs.h

@@ -137,20 +137,28 @@
 #define AUTOCONNECT_SD_SPEED    4000000
 #endif // !AUTOCONNECT_SD_SPEED
 
-// Factors related to a flickering signal indicating WiFi connection status
-#ifndef AUTOCONNECT_FLICKER_PERIOD  // Flicker cycle [ms]
-#define AUTOCONNECT_FLICKER_PERIOD  2000
-#endif // !AUTOCONNECT_FLICKER_PERIOD
-#ifndef AUTOCONNECT_FLICKER_WIDTHAP // Flicking pulse width in APSTA
-#define AUTOCONNECT_FLICKER_WIDTHAP 128
+// Flicker signal related factors
+// Flicker cycle during AP operation [ms]
+#ifndef AUTOCONNECT_FLICKER_PERIODAP
+#define AUTOCONNECT_FLICKER_PERIODAP  1000
+#endif // !AUTOCONNECT_FLICKER_PERIODAP
+// Flicker cycle while WiFi is not connected [ms]
+#ifndef AUTOCONNECT_FLICKER_PERIODDC
+#define AUTOCONNECT_FLICKER_PERIODDC  (AUTOCONNECT_FLICKER_PERIODAP << 1)
+#endif // !AUTOCONNECT_FLICKER_PERIODDC
+// Flicker pulse width during AP operation (8bit resolution)
+#ifndef AUTOCONNECT_FLICKER_WIDTHAP
+#define AUTOCONNECT_FLICKER_WIDTHAP   96
 #endif // !AUTOCONNECT_FLICKER_WIDTHAPSTA
-#ifndef AUTOCONNECT_FLICKER_WIDTHDC // Flicking pulse width in disconnected
-#define AUTOCONNECT_FLICKER_WIDTHDC 25
+// Flicker pulse width while WiFi is not connected (8bit resolution)
+#ifndef AUTOCONNECT_FLICKER_WIDTHDC 
+#define AUTOCONNECT_FLICKER_WIDTHDC   16
 #endif // !AUTOCONNECT_FLICKER_WIDTHDISCON
+// Ticker port
 #ifndef AUTOCONNECT_TICKER_PORT
 #if defined(BUILDIN_LED) || defined(LED_BUILTIN)
 #define AUTOCONNECT_TICKER_PORT       LED_BUILTIN
-#else  // Native pin number
+#else  // Native pin for the arduino
 #define AUTOCONNECT_TICKER_PORT       2
 #endif
 #endif