From 217faa43a3aa53390930a79e1d5788affeed7da1 Mon Sep 17 00:00:00 2001 From: Alex Tudorache Date: Wed, 13 Jan 2016 11:48:52 +0200 Subject: [PATCH] 0.6 release updated readme --- README.md | 145 ++++++++++++++++++++++++++++++++++++++------- WiFiManager.cpp | 4 +- library.json | 2 +- library.properties | 2 +- 4 files changed, 127 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 2431963..986b49b 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,28 @@ First attempt at a library. Lots more changes and fixes to do. Contributions are #### This works with the ESP8266 Arduino platform with a recent stable release(2.0.0 or newer) https://github.com/esp8266/Arduino -## How It works +## Contents + - [How it works](#how-it-works) + - [Wishlist](#wishlist) + - [Quick start](#quick-start) + - Installing + - [Through Boards Manager](#install-through-boards-manager) + - [From Github](#checkout-from-github) + - [Using](#using) + - [Documentation](#documentation) + - [Access Point Password](#password-protect-the-configuration-access-point) + - [Callbacks](#callbacks) + - [Timeout](#timeout) + - [On Demand Configuration](#on-demand-configuration-portal) + - [Custom Parameters](#custom-parameters) + - [Custom IP Configuration](#custom-ip-configuration) + - [Filter Low Quality Networks](#filter-networks) + - [Debug Output](#debug) + - [Releases](#releases) + - [Contributors](#contributions-and-thanks) + + +## How It Works - when your ESP starts up, it sets it up in Station mode and tries to connect to a previously saved Access Point - if this is unsuccessful (or no previous network saved) it moves the ESP into Access Point mode and spins up a DNS and WebServer (default ip 192.168.4.1) - using any wifi enabled device with a browser (computer, phone, tablet) connect to the newly created Access Point @@ -15,12 +36,15 @@ First attempt at a library. Lots more changes and fixes to do. Contributions are - choose one of the access points scanned, enter password, click save - ESP will try to connect. If successful, it relinquishes control back to your app. If not, reconnect to AP and reconfigure. +## How It Looks +![ESP8266 WiFi Captive Portal Homepage](http://i.imgur.com/YPvW9eql.png) ![ESP8266 WiFi Captive Portal Configuration](http://i.imgur.com/oicWJ4gl.png) + ## Wishlist - ~~remove dependency on EEPROM library~~ - ~~move HTML Strings to PROGMEM~~ -- cleanup and streamline code +- ~~cleanup and streamline code~~ (although this is ongoing) - if timeout is set, extend it when a page is fetched in AP mode -- add ability to configure more parameters than ssid/password +- ~~add ability to configure more parameters than ssid/password~~ - maybe allow setting ip of ESP after reboot - ~~add to Arduino Boards Manager~~ - add to PlatformIO @@ -29,23 +53,24 @@ First attempt at a library. Lots more changes and fixes to do. Contributions are ## Quick Start +### Installing You can either install through the Arduino Boards Manager or checkout the latest changes or a release from github #### Install through Boards Manager -__Currently version 0.5 works with release 2.0.0 or newer of the [ESP8266 core for Arduino](https://github.com/esp8266/Arduino)__ +__Currently version 0.6 works with release 2.0.0 or newer of the [ESP8266 core for Arduino](https://github.com/esp8266/Arduino)__ - in Arduino IDE got to Sketch/Include Library/Manage Libraries ![Manage Libraries](http://i.imgur.com/9BkEBkR.png) - search for WiFiManager ![WiFiManager package](http://i.imgur.com/18yIai8.png) - - click Install and start using it + - click Install and start [using it](#using) #### Checkout from github __Github version works with release 2.0.0 or newer of the [ESP8266 core for Arduino](https://github.com/esp8266/Arduino)__ - Checkout library to your Arduino libraries folder -#### Using +### Using - Include in your sketch ```cpp #include @@ -75,9 +100,11 @@ wifiManager.autoConnect(); After you write your sketch and start the ESP, it will try to connect to WiFi. If it fails it starts in Access Point mode. While in AP mode, connect to it then open a browser to the gateway IP, default 192.168.4.1, configure wifi, save and it should reboot and connect. -Also see examples. +Also see [examples](https://github.com/tzapu/WiFiManager/tree/master/examples). -### Password protect the configuration Access Point +## Documentation + +#### Password protect the configuration Access Point You can and should password protect the configuration access point. Simply add the password as a second parameter to `autoConnect`. A short password seems to have unpredictable results so use one that's around 8 characters or more in length. The guidelines are that a wifi password must consist of 8 to 63 ASCII-encoded characters in the range of 32 to 126 (decimal) @@ -85,7 +112,7 @@ The guidelines are that a wifi password must consist of 8 to 63 ASCII-encoded ch wifiManager.autoConnect("AutoConnectAP", "password") ``` -### Callbacks +#### Callbacks ##### Enter Config mode Use this if you need to do something when your device enters configuration mode on failed WiFi connection attempt. Before `autoConnect()` @@ -94,13 +121,32 @@ wifiManager.setAPCallback(configModeCallback); ``` `configModeCallback` declaration and example ```cpp -void configModeCallback () { +void configModeCallback (WiFiManager *myWiFiManager) { Serial.println("Entered config mode"); Serial.println(WiFi.softAPIP()); + + Serial.println(myWiFiManager->getConfigPortalSSID()); } ``` -### Timeout +##### Save settings +This gets called when custom parameters have been set **AND** a connection has been established. Use it to set a flag, so when all the configuration finishes, you can save the extra parameters somewhere. See [AutoConnectWithFSParameters Example](https://github.com/tzapu/WiFiManager/tree/master/examples/AutoConnectWithFSParameters). +```cpp +wifiManager.setSaveConfigCallback(saveConfigCallback); +``` +`saveConfigCallback` declaration and example +```cpp +//flag for saving data +bool shouldSaveConfig = false; + +//callback notifying us of the need to save config +void saveConfigCallback () { + Serial.println("Should save config"); + shouldSaveConfig = true; +} +``` + +#### Timeout If you need to set a timeout so the ESP doesn't hang waiting to be configured, for instance after a power failure, you can add ```cpp wifiManager.setTimeout(180); @@ -108,11 +154,46 @@ wifiManager.setTimeout(180); which will wait 3 minutes (180 seconds). When the time passes, the autoConnect function will return, no matter the outcome. Check for connection and if it's still not established do whatever is needed (on some modules I restart them to retry, on others I enter deep sleep) -### Debug -Debug is enabled by default on Serial. To disable add before autoConnect +#### On Demand Configuration Portal +If you would rather start the configuration portal on demand rather than automatically on a failed connection attempt, then this is for you. + +Instead of calling `autoConnect()` which does all the connecting and failover configuration portal setup for you, you need to use `startConfigPortal()` +Example usage ```cpp -wifiManager.setDebugOutput(false); +void loop() { + // is configuration portal requested? + if ( digitalRead(TRIGGER_PIN) == LOW ) { + WiFiManager wifiManager; + wifiManager.startConfigPortal("OnDemandAP"); + Serial.println("connected...yeey :)"); + } +} ``` +See example for a more complex version. [OnDemandConfigPortal](https://github.com/tzapu/WiFiManager/tree/master/examples/OnDemandConfigPortal) + +### Custom Parameters +You can use WiFiManager to collect more parameters than just SSID and password. +This could be helpful for configuring stuff like MQTT host and port, [blynk](http://www.blynk.cc) or [emoncms](http://emoncms.org) tokens, just to name a few. +**You are responsible for saving and loading these custom values.** The library just collects and displays the data for you as a convenience. +Usage scenario would be: +- load values from somewhere (EEPROM/FS) or generate some defaults +- add the custom parameters to WiFiManager using + ```cpp + // id/name, placeholder/prompt, default, length + WiFiManagerParameter custom_mqtt_server("server", "mqtt server", mqtt_server, 40); + wifiManager.addParameter(&custom_mqtt_server); + + ``` +- if connection to AP fails, configuration portal starts and you can set /change the values (or use on demand configuration portal) +- once configuration is done and connection is established [save config callback]() is called +- once WiFiManager returns control to your application, read and save the new values using the `WiFiManagerParameter` object. + ```cpp + mqtt_server = custom_mqtt_server.getValue(); + ``` +This feature is a lot more involved than all the others, so here are some examples to fully show how it is done +- Save and load custom parameters to file system in json form [AutoConnectWithFSParameters](https://github.com/tzapu/WiFiManager/tree/master/examples/AutoConnectWithFSParameters) +- *Save and load custom parameters to EEPROM* (not done yet) + ### Custom IP Configuration This will set your captive portal to a specific IP should you need/want such a feature. Add the following snippet before `autoConnect()` @@ -120,14 +201,32 @@ This will set your captive portal to a specific IP should you need/want such a f //set custom ip for portal wifiManager.setAPConfig(IPAddress(10,0,1,1), IPAddress(10,0,1,1), IPAddress(255,255,255,0)); ``` +#### Filter Networks +If you would like to filter low signal quality networks you can tell WiFiManager to not show networks below an arbitrary quality %; +``` +wifiManager.setMinimumSignalQuality(10); +``` +will not show networks under 10% signal quality. If you omit the parameter it defaults to 8%; + +#### Debug +Debug is enabled by default on Serial. To disable add before autoConnect +```cpp +wifiManager.setDebugOutput(false); +``` ## Releases -#### 0.5 +#### 0.6 + - custom parameters + - prettier + - on demand config portal + - commit #100 :D + +##### 0.5 - Added to Arduino Boards Manager - Thanks Max - moved most stuff to PROGMEM - added signal quality and a nice little padlock to show which networks are encrypted -##### v0.4 - user contributed changes - Thank you +##### v0.4 - all of it user contributed changes - Thank you - added ability to password protect the configuration Access Point - callback for enter configuration mode - memory allocation improvements @@ -139,28 +238,30 @@ wifiManager.setAPConfig(IPAddress(10,0,1,1), IPAddress(10,0,1,1), IPAddress(255, ##### v0.2 needs the latest staging version (or at least a recent release of the staging version) to work +This is jsut random textTo show the lagginess. +[the editor is completly](behing the typing) ##### v0.1 works with the staging release ver. 1.6.5-1044-g170995a, built on Aug 10, 2015 of the ESP8266 Arduino library. - ### Contributions and thanks The support and help I got from the community has been nothing short of phenomenal. I can't thank you guys enough. This is my first real attept in developing open source stuff and I must say, now I understand why people are so dedicated to it, it is because of all the wonderful people involved. __THANK YOU__ [Maximiliano Duarte](https://github.com/domonetic) - [alltheblinkythings](https://github.com/alltheblinkythings) - [Niklas Wall](https://github.com/niklaswall) - [Jakub Piasecki](https://github.com/zaporylie) - [Peter Allan](https://github.com/alwynallan) - [John Little](https://github.com/j0hnlittle) +[markaswift](https://github.com/markaswift) +[franklinvv](https://github.com/franklinvv) +[Alberto Ricci Bitti](https://github.com/riccibitti) +[SebiPanther](https://github.com/SebiPanther) + +Sorry if i have missed anyone. #### Inspiration - http://www.esp8266.com/viewtopic.php?f=29&t=2520 diff --git a/WiFiManager.cpp b/WiFiManager.cpp index c7f91ad..f118517 100644 --- a/WiFiManager.cpp +++ b/WiFiManager.cpp @@ -137,7 +137,7 @@ boolean WiFiManager::startConfigPortal(char const *apName, char const *apPasswo connect = false; setupConfigPortal(); - DEBUG_WM("start loop"); + while (timeout == 0 || millis() < start + timeout) { //DNS dnsServer->processNextRequest(); @@ -169,7 +169,7 @@ boolean WiFiManager::startConfigPortal(char const *apName, char const *apPasswo server.reset(); dnsServer.reset(); - DEBUG_WM("end loop"); + return WiFi.status() == WL_CONNECTED; } diff --git a/library.json b/library.json index badf097..e6e5435 100644 --- a/library.json +++ b/library.json @@ -14,6 +14,6 @@ }, "frameworks": "arduino", "platforms": "esp8266" - "version": "0.5", + "version": "0.6", "architecture": "esp8266", } diff --git a/library.properties b/library.properties index 55f390a..c43b894 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=WiFiManager -version=0.5 +version=0.6 author=tzapu maintainer=tzapu sentence=ESP8266 WiFi Connection manager with fallback web configuration portal