From 98c78a29291c0a983c7110b0761382bd17b2235c Mon Sep 17 00:00:00 2001 From: Shawn A Date: Thu, 15 Feb 2018 09:57:51 -0600 Subject: [PATCH] documenting source --- WiFiManager.cpp | 123 +++++++++++++++++++++++++++++++++++++++--------- WiFiManager.h | 55 ++++++++++++---------- 2 files changed, 131 insertions(+), 47 deletions(-) diff --git a/WiFiManager.cpp b/WiFiManager.cpp index 96e9603..e507e24 100644 --- a/WiFiManager.cpp +++ b/WiFiManager.cpp @@ -161,6 +161,9 @@ boolean WiFiManager::autoConnect(char const *apName, char const *apPassword) { WiFi_enableSTA(true); _usermode = WIFI_STA; + // no getter for autoreconnectpolicy before this + // https://github.com/esp8266/Arduino/pull/4359 + // so we must force it on else, if not connectimeout then waitforconnectionresult gets stuck endless loop WiFi_autoReconnect(); // if already connected, or try stored connect @@ -392,7 +395,12 @@ uint8_t WiFiManager::handleConfigPortal(){ DEBUG_WM(F("Connect to new AP [FAILED]")); if (_shouldBreakAfterConfig) { - // this is more of an exiting callback than a save + // do save callback + // @todo this is more of an exiting callback than a save, clarify when this should actually occur + // confirm or verify data was saved to make this more accurate callback + if ( _savecallback != NULL) { + _savecallback(); + } stopConfigPortal(); return WL_CONNECT_FAILED; // fail } @@ -410,12 +418,6 @@ uint8_t WiFiManager::handleConfigPortal(){ boolean WiFiManager::stopConfigPortal(){ if(webPortalActive) return false; - // do save callback, @todo move out of here - if ( _savecallback != NULL) { - //todo: confirm or verify data was saved - _savecallback(); - } - //DNS handler dnsServer->processNextRequest(); //HTTP handler @@ -1302,57 +1304,124 @@ void WiFiManager::reportStatus(String &page){ // MORE SETTERS -//start up config portal callback +/** + * setAPCallback, set a callback when softap is started + * @param {[type]} void (*func)(WiFiManager* myWiFiManager) [description] + */ void WiFiManager::setAPCallback( void (*func)(WiFiManager* myWiFiManager) ) { _apcallback = func; } -//start up save config callback +/** + * setSaveConfigCallback, set a save config callback after closing configportal + * @todo only calls if configportal stopped + * @param {[type]} void (*func)(void) [description] + */ void WiFiManager::setSaveConfigCallback( void (*func)(void) ) { _savecallback = func; } -//sets a custom element to add to head, like a new style tag +/** + * set custom head html + * custom element will be added to head, eg. new style tag etc. + * @param char element + */ void WiFiManager::setCustomHeadElement(const char* element) { _customHeadElement = element; } //if this is true, remove duplicated Access Points - defaut true +/** + * toggle wifiscan hiding of duplicate ssid names + * if enabled, then the webportal wifiscan page will show all aps + * @param boolean removeDuplicates [true] + */ void WiFiManager::setRemoveDuplicateAPs(boolean removeDuplicates) { _removeDuplicateAPs = removeDuplicates; } -//if this is true, remove duplicated Access Points - defaut true +/** + * toggle configportal blocking loop + * if enabled, then the configportal will enter a blocking loop and wait for configuration + * if disabled use with process() to manually process webserver + * @since $dev + * @param boolean shoudlBlock [false] + */ void WiFiManager::setConfigPortalBlocking(boolean shoudlBlock) { _configPortalIsBlocking = shoudlBlock; } -//setter for ESP wifi.persistent so we can remember it and restore user preference, as WIFi._persistent is protected +/** + * toggle restore persistent, track internally + * sets ESP wifi.persistent so we can remember it and restore user preference on destruct + * there is no getter in esp8266 platform prior to https://github.com/esp8266/Arduino/pull/3857 + * @since $dev + * @param boolean persistent [true] + */ void WiFiManager::setRestorePersistent(boolean persistent) { _userpersistent = persistent; if(!persistent) DEBUG_WM(F("persistent is off")); } +/** + * toggle showing static ip form fields + * if enabled, then the static ip, gateway, subnet fields will be visible, even if not set in code + * @since $dev + * @param boolean alwaysShow [false] + */ void WiFiManager::setShowStaticFields(boolean alwaysShow){ _staShowStaticFields = alwaysShow; } +/** + * toggle captive portal + * if enabled, then devices that use captive portal checks will be redirected to root + * if not you will automatically have to navigate to ip [192.168.4.1] + * @since $dev + * @param boolean enabled [true] + */ void WiFiManager::setCaptivePortalEnable(boolean enabled){ _enableCaptivePortal = enabled; } +/** + * toggle wifi autoreconnect policy + * if enabled, then wifi will autoreconnect automatically always + * On esp8266 we force this on when autoconnect is called, see notes + * On esp32 this is handled on SYSTEM_EVENT_STA_DISCONNECTED since it does not exist in core yet + * @since $dev + * @param boolean enabled [true] + */ void WiFiManager::setWiFiAutoReconnect(boolean enabled){ _wifiAutoReconnect = enabled; } +/** + * toggle configportal timeout wait for station client + * if enabled, then the configportal will start timeout when no stations are connected to softAP + * disabled by default as rogue stations can keep it open if there is no auth + * @since $dev + * @param boolean enabled [false] + */ void WiFiManager::setCaptivePortalClientCheck(boolean enabled){ _cpClientCheck = enabled; } +/** + * toggle configportal timeout wait for web client + * if enabled, then the configportal will restart timeout when client requests come in + * @since $dev + * @param boolean enabled [true] + */ void WiFiManager::setWebPortalClientCheck(boolean enabled){ _webClientCheck = enabled; } +/** + * toggle wifiscan percentages or quality icons + * @since $dev + * @param boolean enabled [false] + */ void WiFiManager::setScanDispPerc(boolean enabled){ _scanDispOptions = true; } @@ -1504,6 +1573,11 @@ bool WiFiManager::WiFi_Mode(WiFiMode_t m) { return WiFi_Mode(m,false); } +/** + * disconnect + * @since $dev + * @return bool success + */ bool WiFiManager::disconnect(){ return WiFi_Disconnect(); } @@ -1558,18 +1632,21 @@ bool WiFiManager::WiFi_enableSTA(bool enable) { bool WiFiManager::WiFi_eraseConfig(void) { #ifdef ESP8266 - return ESP.eraseConfig(); - // https://github.com/esp8266/Arduino/pull/3635 - // erase config BUG polyfill - // const size_t cfgSize = 0x4000; - // size_t cfgAddr = ESP.getFlashChipSize() - cfgSize; + #ifndef FIXERASECONFIG + return ESP.eraseConfig(); + #else + // erase config BUG polyfill + // https://github.com/esp8266/Arduino/pull/3635 + const size_t cfgSize = 0x4000; + size_t cfgAddr = ESP.getFlashChipSize() - cfgSize; - // for (size_t offset = 0; offset < cfgSize; offset += SPI_FLASH_SEC_SIZE) { - // if (!ESP.flashEraseSector((cfgAddr + offset) / SPI_FLASH_SEC_SIZE)) { - // return false; - // } - // } - // return true; + for (size_t offset = 0; offset < cfgSize; offset += SPI_FLASH_SEC_SIZE) { + if (!ESP.flashEraseSector((cfgAddr + offset) / SPI_FLASH_SEC_SIZE)) { + return false; + } + } + return true; + #endif #elif defined(ESP32) WiFi.mode(WIFI_AP_STA); // cannot erase if not in STA mode return WiFi.disconnect(true); diff --git a/WiFiManager.h b/WiFiManager.h index 3b5ce41..9a9ce8c 100644 --- a/WiFiManager.h +++ b/WiFiManager.h @@ -100,22 +100,30 @@ class WiFiManager WiFiManager(); ~WiFiManager(); + // auto connect to saved wifi, or custom, and start config portal on failures boolean autoConnect(); boolean autoConnect(char const *apName, char const *apPassword = NULL); - //if you want to always start the config portal, without trying to connect first - boolean startConfigPortal(); + //manually start the config portal, autoconnect does this automatically on connect failure + boolean startConfigPortal(); // auto generates apname boolean startConfigPortal(char const *apName, char const *apPassword = NULL); - boolean process(); + + //manually start the web portal, autoconnect does this automatically on connect failure void startWebPortal(); + //manually stop the web portal if started manually void stopWebPortal(); + // Run webserver processing, if setConfigPortalBlocking(false) + boolean process(); // get the AP name of the config portal, so it can be used in the callback String getConfigPortalSSID(); + // erase wifi credentials void resetSettings(); + // reboot esp void reboot(); - bool disconnect(); // non persistent disconnect + // disconnect wifi, without persistent saving or erasing + bool disconnect(); //sets timeout before AP,webserver loop ends and exits even if there has been no setup. //useful for devices that failed to connect at some point and got stuck in a webserver loop @@ -125,7 +133,7 @@ class WiFiManager //sets timeout for which to attempt connecting, useful if you get a lot of failed connects void setConnectTimeout(unsigned long seconds); - + // toggle debug output void setDebugOutput(boolean debug); //defaults to not showing anything under 8% signal quality if called void setMinimumSignalQuality(int quality = 8); @@ -141,7 +149,7 @@ class WiFiManager bool addParameter(WiFiManagerParameter *p); //if this is set, it will exit after config, even if connection is unsuccessful. void setBreakAfterConfig(boolean shouldBreak); - //if this is set, portal will be blocking and wait until save or exit, is false user must manually process to handle config portal + //if this is set, portal will be blocking and wait until save or exit, is false user must manually `process()` to handle config portal void setConfigPortalBlocking(boolean shouldBlock); //if this is set, customise style void setCustomHeadElement(const char* element); @@ -161,8 +169,9 @@ class WiFiManager void setWiFiAutoReconnect(boolean enabled); // if true, wifiscan will show percentage instead of quality icons, until we have better templating void setScanDispPerc(boolean enabled); - + // debug output the softap config void debugSoftAPConfig(); + // debug output platform info and versioning void debugPlatformInfo(); private: @@ -174,8 +183,6 @@ class WiFiManager std::unique_ptr server; #endif - //const int WM_DONE = 0; - //const int WM_WAIT = 10; // ip configs IPAddress _ap_static_ip; IPAddress _ap_static_gw; @@ -192,29 +199,29 @@ class WiFiManager String _pass = ""; // options flags - unsigned long _configPortalTimeout = 0; - unsigned long _connectTimeout = 0; - unsigned long _configPortalStart = 0; - unsigned long _webPortalAccessed = 0; + unsigned long _configPortalTimeout = 0; // close config portal loop if set (depending on _cp/webClientCheck options) + unsigned long _connectTimeout = 0; // stop trying to connect to ap if set + unsigned long _configPortalStart = 0; // config portal start time (updated for timeouts) + unsigned long _webPortalAccessed = 0; // last web access time WiFiMode_t _usermode = WIFI_OFF; - String _wifissidprefix = FPSTR(S_ssidpre); + String _wifissidprefix = FPSTR(S_ssidpre); // auto apname prefix prefix+chipid // option parameters - int _minimumQuality = -1; - boolean _removeDuplicateAPs = true; - boolean _shouldBreakAfterConfig = false; - boolean _tryWPS = false; - boolean _configPortalIsBlocking = true; - boolean _staShowStaticFields = false; - boolean _enableCaptivePortal = true; - boolean _userpersistent = true; - boolean _wifiAutoReconnect = true; // there is no getter for this, we must assume its true and make it so + int _minimumQuality = -1; // filter wifiscan ap by this rssi + boolean _removeDuplicateAPs = true; // remove dup aps from wifiscan + boolean _shouldBreakAfterConfig = false; // stop configportal on save failure + boolean _tryWPS = false; // try WPS on save failure, unsupported + boolean _configPortalIsBlocking = true; // configportal enters blocking loop + boolean _staShowStaticFields = false; // always show static ip fields, even if not set in code + boolean _enableCaptivePortal = true; // enable captive portal redirection + boolean _userpersistent = true; // users preffered persistence to restore + boolean _wifiAutoReconnect = true; // there is no platform getter for this, we must assume its true and make it so boolean _cpClientCheck = false; // keep cp alive if cp have station boolean _webClientCheck = true; // keep cp alive if web have client boolean _scanDispOptions = false; // show percentage in scans not icons - const char* _customHeadElement = ""; + const char* _customHeadElement = ""; // store custom head element html from user void setupConfigPortal(); void startWPS();