Skip to content
This repository was archived by the owner on Feb 4, 2023. It is now read-only.

Commit 0de92a1

Browse files
khoih-progkhoih-prog
authored
Add files via upload
1 parent 2fdcba5 commit 0de92a1

15 files changed

+3624
-0
lines changed

‎Images/ConfigurationScreen.png

98.1 KB
Loading

‎Images/DefaultScreen.png

143 KB
Loading

‎README.md

+281
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
# ESP_WiFiManager
2+
3+
This library is based on, modified, bug-fixed and improved from:
4+
5+
1. Tzapu WiFiManager (https://github.com/tzapu/WiFiManager)
6+
2. Ken Taylor WiFiManager (https://github.com/kentaylor/WiFiManager)
7+
8+
to add support to ESP32 besides ESP8266.
9+
10+
This is an ESP32 / ESP8266 WiFi Connection manager with fallback web configuration portal.
11+
It's using a web configuration portal, served from the ESP32 / ESP8266, and operating as an access point.
12+
13+
The configuration portal is captive, so it will present the configuration dialogue regardless of the web address selected, excluding https requests.
14+
15+
This works with
16+
1. The ESP8266 Arduino platform with a recent stable release(2.6.2 or newer) https://github.com/esp8266/Arduino
17+
2. The ESP32 Arduino platform with a recent stable release(1.0.4 or newer) https://github.com/espressif/arduino-esp32
18+
19+
20+
## How It Works
21+
22+
- The [ConfigOnSwitch](examples/ConfigOnSwitch) example shows how it works and should be used as the basis for a sketch that uses this library.
23+
- The concept of ConfigOnSwitch is that a new ESP32 / ESP8266 will start a WiFi configuration portal when powered up and save the configuration data in non volatile memory. Thereafter, the configuration portal will only be started again if a button is pushed on the ESP32 / ESP8266 module.
24+
- Using any WiFi enabled device with a browser (computer, phone, tablet) connect to the newly created Access Point and type in any http address.
25+
- Because of the Captive Portal and the DNS server you will either get a 'Join to network' type of popup or get any domain you try to access redirected to the configuration portal.
26+
- All http web addresses will be redirected to wifi.urremote.com which will be at IP address 192.168.4.1 . This address is also a valid internet address where the user will see advice that they are connected to the wrong network.
27+
- Choose one of the access points scanned, enter password, click save.
28+
- ESP will try to connect. If successful, the IP address on the new network will be displayed in the configuration portal.
29+
- The configuration portal will now be visible on two networks, these being it's own network and the network to which it has connected. On it's own network it will have two IP addresses, the original 192.168.4.1 and the same IP address it has on the network to which it connected.
30+
- Selecting "close configuration portal" will shutdown the web server, shutdown the ESP8266 WiFi network and return control to the following sketch code.
31+
32+
## Quick Start
33+
34+
### Installing
35+
See ["Installing Arduino libraries"](https://www.arduino.cc/en/Guide/Libraries) and use the Importing a .zip Library method or preferably use manual installation as you can checkout the release from github and use that. This makes it easier to keep current with updates. Installing using the Library Manager currently does not work with this version of the library.
36+
37+
#### Compatibility
38+
Github version 1.0.1 currently works with :
39+
1. release 2.6.2 or newer of the [ESP8266 core for Arduino](https://github.com/esp8266/Arduino)
40+
2. release 1.0.4 or newer of the [ESP32 core for Arduino](https://github.com/espressif/arduino-esp32)
41+
42+
- Checkout [library](https://github.com/khoih-prog/ESP_WiFiManager) to your Arduino libraries folder. Must be [https://github.com/khoih-prog/ESP_WiFiManager](https://github.com/khoih-prog/ESP_WiFiManager) version.
43+
44+
### Using
45+
- Include in your sketch
46+
```cpp
47+
#ifdef ESP32
48+
#include <esp_wifi.h>
49+
#include <WiFi.h>
50+
#include <WiFiClient.h>
51+
52+
#define ESP_getChipId() ((uint32_t)ESP.getEfuseMac())
53+
54+
#define LED_ON HIGH
55+
#define LED_OFF LOW
56+
#else
57+
#include <ESP8266WiFi.h> //https://github.com/esp8266/Arduino
58+
//needed for library
59+
#include <DNSServer.h>
60+
#include <ESP8266WebServer.h>
61+
62+
#define ESP_getChipId() (ESP.getChipId())
63+
64+
#define LED_ON LOW
65+
#define LED_OFF HIGH
66+
#endif
67+
68+
// SSID and PW for Config Portal
69+
String ssid = "ESP_" + String(ESP_getChipId(), HEX);
70+
const char* password = "your_password";
71+
72+
// SSID and PW for your Router
73+
String Router_SSID;
74+
String Router_Pass;
75+
76+
#include <ESP_WiFiManager.h> //https://github.com/khoih-prog/ESP_WiFiManager
77+
```
78+
79+
- When you want open a config portal initialize library, add
80+
```cpp
81+
ESP_WiFiManager ESP_wifiManager;
82+
```
83+
84+
then call
85+
86+
```cpp
87+
ESP_wifiManager.startConfigPortal()
88+
```
89+
90+
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 save WiFi connection information in non volatile memory, reboot and connect.
91+
92+
93+
Once WiFi network information is saved in the ESP32 / ESP8266, it will try to connect to WiFi every time it is started without requiring any function calls in the sketch.
94+
95+
96+
Also see examples:
97+
1. [ConfigOnSwitch](examples/ConfigOnSwitch)
98+
2. [ConfigOnSwitchFS](examples/ConfigOnSwitchFS)
99+
3. [ConfigOnStartup](examples/ConfigOnStartup)
100+
4. [ConfigOnDoubleReset](examples/ConfigOnDoubleReset)
101+
102+
## Documentation
103+
104+
#### Password protect the configuration Access Point
105+
You can password protect the configuration access point. Simply add an SSID as the first parameter and the password as a second parameter to `startConfigPortal`. See the above examples.
106+
A short password seems to have unpredictable results so use one that's around 8 characters or more in length.
107+
The guidelines are that a wifi password must consist of 8 to 63 ASCII-encoded characters in the range of 32 to 126 (decimal)
108+
109+
```cpp
110+
ESP_wifiManager.startConfigPortal( SSID , password )
111+
```
112+
113+
#### Callbacks
114+
115+
##### Save settings
116+
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.
117+
118+
See [ConfigOnSwitchFS Example](examples/ConfigOnSwitchFS).
119+
```cpp
120+
ESP_wifiManager.setSaveConfigCallback(saveConfigCallback);
121+
```
122+
saveConfigCallback declaration and example
123+
```cpp
124+
//flag for saving data
125+
bool shouldSaveConfig = false;
126+
127+
//callback notifying us of the need to save config
128+
void saveConfigCallback () {
129+
Serial.println("Should save config");
130+
shouldSaveConfig = true;
131+
}
132+
```
133+
134+
#### Configuration Portal Timeout
135+
If you need to set a timeout so the ESP32 / ESP8266 doesn't hang waiting to be configured for ever.
136+
```cpp
137+
ESP_wifiManager.setConfigPortalTimeout(60);
138+
```
139+
which will wait 1 minutes (60 seconds). When the time passes, the startConfigPortal function will return and continue the sketch,
140+
unless you're accessing the Config Portal. In this case, the startConfigPortal function will stay until you save config data or exit
141+
the Config Portal.
142+
143+
144+
#### On Demand Configuration Portal
145+
146+
Example usage
147+
```cpp
148+
void loop()
149+
{
150+
// is configuration portal requested?
151+
if ((digitalRead(TRIGGER_PIN) == LOW) || (digitalRead(TRIGGER_PIN2) == LOW))
152+
{
153+
Serial.println("\nConfiguration portal requested.");
154+
digitalWrite(PIN_LED, LED_ON); // turn the LED on by making the voltage LOW to tell us we are in configuration mode.
155+
156+
//Local intialization. Once its business is done, there is no need to keep it around
157+
ESP_WiFiManager ESP_wifiManager;
158+
159+
//Check if there is stored WiFi router/password credentials.
160+
//If not found, device will remain in configuration mode until switched off via webserver.
161+
Serial.print("Opening configuration portal. ");
162+
Router_SSID = ESP_wifiManager.WiFi_SSID();
163+
if (Router_SSID != "")
164+
{
165+
ESP_wifiManager.setConfigPortalTimeout(60); //If no access point name has been previously entered disable timeout.
166+
Serial.println("Got stored Credentials. Timeout 60s");
167+
}
168+
else
169+
Serial.println("No stored Credentials. No timeout");
170+
171+
//it starts an access point
172+
//and goes into a blocking loop awaiting configuration
173+
if (!ESP_wifiManager.startConfigPortal((const char *) ssid.c_str(), password))
174+
{
175+
Serial.println("Not connected to WiFi but continuing anyway.");
176+
}
177+
else
178+
{
179+
//if you get here you have connected to the WiFi
180+
Serial.println("connected...yeey :)");
181+
}
182+
183+
digitalWrite(PIN_LED, LED_OFF); // Turn led off as we are not in configuration mode.
184+
}
185+
186+
// put your main code here, to run repeatedly
187+
check_status();
188+
189+
}
190+
```
191+
See [ConfigOnSwitch](examples/ConfigOnSwitch) example for a more complex version.
192+
193+
#### Custom Parameters
194+
Many applications need configuration parameters like MQTT host and port, [Blynk](http://www.blynk.cc) or [emoncms](http://emoncms.org) tokens, etc. While it is possible to use ESP_WiFiManager to collect additional parameters it is better to read these parameters from a web service once ESP_WiFiManager has been used to connect to the internet. This makes WiFiManager simple to code and use, parameters can be edited on a regular web server and can be changed remotely after deployment. A web service that can provide these parameters is at [configure.urremote.com](http://configure.urremote.com/).
195+
196+
To capture other parameters with ESP_WiFiManager is a lot more involved than all the other features and requires adding custom HTML to your form. If you want to do it with ESP_WiFiManager see the example [ConfigOnSwitchFS](examples/ConfigOnSwitchFS)
197+
198+
#### Custom IP Configuration
199+
You can set a custom IP for both AP (access point, config mode) and STA (station mode, client mode, normal project state)
200+
201+
##### Custom Access Point IP Configuration
202+
This will set your captive portal to a specific IP should you need/want such a feature. Add the following snippet before `startConfigPortal()`
203+
```cpp
204+
//set custom ip for portal
205+
ESP_wifiManager.setAPStaticIPConfig(IPAddress(10,0,1,1), IPAddress(10,0,1,1), IPAddress(255,255,255,0));
206+
```
207+
208+
##### Custom Station (client) Static IP Configuration
209+
This will use the specified IP configuration instead of using DHCP in station mode.
210+
```cpp
211+
ESP_wifiManager.setSTAStaticIPConfig(IPAddress(192,168,0,99), IPAddress(192,168,0,1), IPAddress(255,255,255,0));
212+
```
213+
214+
#### Custom HTML, CSS, Javascript
215+
There are various ways in which you can inject custom HTML, CSS or Javascript into the configuration portal.
216+
The options are:
217+
- inject custom head element
218+
You can use this to any html bit to the head of the configuration portal. If you add a `<style>` element, bare in mind it overwrites the included css, not replaces.
219+
220+
```cpp
221+
ESP_wifiManager.setCustomHeadElement("<style>html{filter: invert(100%); -webkit-filter: invert(100%);}</style>");
222+
```
223+
224+
- inject a custom bit of html in the configuration form
225+
226+
```cpp
227+
ESP_WMParameter custom_text("<p>This is just a text paragraph</p>");
228+
ESP_wifiManager.addParameter(&custom_text);
229+
```
230+
231+
- inject a custom bit of html in a configuration form element
232+
Just add the bit you want added as the last parameter to the custom parameter constructor.
233+
234+
```cpp
235+
ESP_WMParameter custom_mqtt_server("server", "mqtt server", "iot.eclipse", 40, " readonly");
236+
```
237+
238+
#### Filter Networks
239+
You can filter networks based on signal quality and show/hide duplicate networks.
240+
241+
- If you would like to filter low signal quality networks you can tell WiFiManager to not show networks below an arbitrary quality %;
242+
243+
```cpp
244+
ESP_wifiManager.setMinimumSignalQuality(10);
245+
```
246+
will not show networks under 10% signal quality. If you omit the parameter it defaults to 8%;
247+
248+
- You can also remove or show duplicate networks (default is remove).
249+
Use this function to show (or hide) all networks.
250+
251+
```cpp
252+
ESP_wifiManager.setRemoveDuplicateAPs(false);
253+
```
254+
255+
#### Debug
256+
Debug is enabled by default on Serial. To disable, add before `startConfigPortal()`
257+
258+
```cpp
259+
ESP_wifiManager.setDebugOutput(false);
260+
```
261+
262+
## Troubleshooting
263+
If you get compilation errors, more often than not, you may need to install a newer version of the ESP32 / ESP8266 core for Arduino.
264+
265+
Sometimes, the library will only work if you update the ESP32 / ESP8266 core to the latest version because I am using some newly added function.
266+
267+
If you connect to the created configuration Access Point but the configuration portal does not show up, just open a browser and type in the IP of the web portal, by default `192.168.4.1`.
268+
269+
270+
## Releases
271+
#### 1.0.1
272+
- forked from this version of the tzapu's WiFi Manager.
273+
274+
See [Tzapu's version](https://github.com/tzapu/WiFiManager) for previous release information.
275+
See [KenTaylor's version]( https://github.com/kentaylor/WiFiManager) for previous release information.
276+
277+
278+
### Contributions and thanks
279+
Forked from [Tzapu](https://github.com/tzapu/WiFiManager) and [KenTaylor's version]( https://github.com/kentaylor/WiFiManager)
280+
281+

0 commit comments

Comments
 (0)