diff --git a/mkdocs/advancedusage.md b/mkdocs/advancedusage.md index 30bd63b..93e9921 100644 --- a/mkdocs/advancedusage.md +++ b/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 + +### 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**. diff --git a/mkdocs/apiconfig.md b/mkdocs/apiconfig.md index e035518..742fa8c 100644 --- a/mkdocs/apiconfig.md +++ b/mkdocs/apiconfig.md @@ -253,6 +253,35 @@ Set the subnetmask when using static IP address.
IPAddress
+### ticker + +Set flicker signal output according to WiFi connection status during AutoConnect::begin behavior. +
+
**Type**
+
bool
+
**Value**
+
trueOutput 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.
+
falseNo flicker signal output.
+
+ +### 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`. +
+
**Type**
+
uint8_t
+
LOWA flicker signal is an active-high.
+
HIGHA flicker signal is an active-low.
+
+ +### tickerOn + +Specifies the active logic level of the flicker signal. +
+
**Type**
+
uint8_t
+
+ ### title Set the menu title. diff --git a/src/AutoConnect.cpp b/src/AutoConnect.cpp index 6d0918f..5b40347 100644 --- a/src/AutoConnect.cpp +++ b/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; diff --git a/src/AutoConnectDefs.h b/src/AutoConnectDefs.h index 7b39870..ab78898 100644 --- a/src/AutoConnectDefs.h +++ b/src/AutoConnectDefs.h @@ -137,21 +137,29 @@ #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 -#define AUTOCONNECT_TICKER_PORT 2 +#define AUTOCONNECT_TICKER_PORT LED_BUILTIN +#else // Native pin for the arduino +#define AUTOCONNECT_TICKER_PORT 2 #endif #endif