Skip to content

Commit 800727f

Browse files
committed
Replace outdate captive portal screen shot
1 parent 99b3d23 commit 800727f

File tree

2 files changed

+43
-23
lines changed

2 files changed

+43
-23
lines changed
33.9 KB
Loading

docs/modules/enduser-setup.md

Lines changed: 43 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -3,29 +3,43 @@
33
| :----- | :-------------------- | :---------- | :------ |
44
| 2015-09-02 | [Robert Foss](https://github.com/robertfoss) | [Robert Foss](https://github.com/robertfoss) | [enduser_setup.c](../../app/modules/enduser_setup.c)|
55

6-
This module provides a simple way of configuring ESP8266 chips without using a serial interface or pre-programming WiFi credentials onto the chip.
7-
8-
![enduser setup config dialog](../img/enduser-setup.jpg "enduser setup config dialog")
9-
10-
After running [`enduser_setup.start()`](#enduser_setupstart), a wireless network named "SetupGadget_XXXXXX" will start (this prefix can be overridden in `user_config.h` by defining
11-
`ENDUSER_SETUP_AP_SSID`). Connect to that SSID and then navigate to the root
12-
of any website (e.g., `http://example.com/` will work, but do not use `.local` domains because it will fail on iOS). A web page similar to the picture above will load, allowing the
13-
end user to provide their Wi-Fi information.
14-
15-
After an IP address has been successfully obtained, then this module will stop as if [`enduser_setup.stop()`](#enduser_setupstop) had been called. There is a 10-second delay before
16-
teardown to allow connected clients to obtain a last status message while the SoftAP is still active.
17-
18-
Alternative HTML can be served by placing a file called `enduser_setup.html` on the filesystem. Everything needed by the web page must be included in this one file. This file will be kept
19-
in RAM, so keep it as small as possible. The file can be gzip'd ahead of time to reduce the size (i.e., using `gzip -n` or `zopfli`), and when served, the End User Setup module will add
20-
the appropriate `Content-Encoding` header to the response.
21-
22-
*Note: If gzipped, the file can also be named `enduser_setup.html.gz` for semantic purposes. Gzip encoding is determined by the file's contents, not the filename.*
6+
This module provides a simple way of configuring ESP8266 chips without using a
7+
serial interface or pre-programming WiFi credentials onto the chip.
8+
9+
After running [`enduser_setup.start()`](#enduser_setupstart), a wireless
10+
network named "SetupGadget_XXXXXX" will starting. This prefix can be overridden
11+
in `user_config.h` by defining `ENDUSER_SETUP_AP_SSID`. Connect to that SSID
12+
and then navigate to the root of any website or to 192.168.4.1.
13+
`http://example.com/` will work, but do not use `.local` domains because it
14+
will fail on iOS. A web page similar to the one depicted below will load,
15+
allowing the end user to provide their Wi-Fi credentials.
16+
17+
![enduser setup config dialog](../img/enduser-setup-captive-portal.png "enduser setup config dialog")
18+
19+
After an IP address has been successfully obtained, then this module will stop
20+
as if [`enduser_setup.stop()`](#enduser_setupstop) had been called. There is a
21+
10-second delay before teardown to allow connected clients to obtain a last
22+
status message while the SoftAP is still active.
23+
24+
Alternative HTML can be served by placing a file called `enduser_setup.html` on
25+
the filesystem. Everything needed by the web page must be included in this one
26+
file. This file will be kept in RAM, so keep it as small as possible. The file
27+
can be gzip'd ahead of time to reduce the size (i.e., using `gzip -n` or
28+
`zopfli`), and when served, the End User Setup module will add the appropriate
29+
`Content-Encoding` header to the response.
30+
31+
*Note: If gzipped, the file can also be named `enduser_setup.html.gz` for
32+
semantic purposes. GZIP encoding is determined by the file's contents, not the
33+
filename.*
2334

2435
### Additional configuration parameters
2536

26-
You can also add some additional inputs in the `enduser_setup.html` (as long as you keep those needed for the wifi setup). The additional data will be written in a `eus_params.lua`
27-
file in the root filesystem of the ESP8266, which you can then load in your own code. In this case, the data will be saved as a set of variables with the name being the input name,
28-
and the value being a string representing what you put in the form.
37+
You can also add some additional inputs in the `enduser_setup.html` (as long as
38+
you keep those needed for the WiFi setup). The additional data will be written
39+
in a `eus_params.lua` file in the root filesystem of the ESP8266, which you can
40+
then load in your own code. In this case, the data will be saved as a set of
41+
variables with the name being the input name, and the value being a string
42+
representing what you put in the form.
2943

3044
For instance, if your HTML contains two additional inputs:
3145

@@ -70,20 +84,26 @@ print("Wifi device_name: " .. p.device_name)
7084

7185
Module functions are described below.
7286

73-
---
87+
7488

7589
## enduser_setup.manual()
7690

7791
Controls whether manual AP configuration is used.
7892

79-
By default the `enduser_setup` module automatically configures an open access point when starting, and stops it when the device has been successfully joined to a WiFi network. If manual mode has been enabled, neither of this is done. The device must be manually configured for `wifi.SOFTAP` mode prior to calling `enduser_setup.start()`. Additionally, the portal is not stopped after the device has successfully joined to a WiFi network.
93+
By default the `enduser_setup` module automatically configures an open access
94+
point when starting, and stops it when the device has been successfully joined
95+
to a WiFi network. If manual mode has been enabled, neither of this is done.
96+
The device must be manually configured for `wifi.SOFTAP` mode prior to calling
97+
`enduser_setup.start()`. Additionally, the portal is not stopped after the
98+
device has successfully joined to a WiFi network.
8099

81100

82101
#### Syntax
83102
`enduser_setup.manual([on_off])`
84103

85104
#### Parameters
86-
- `on_off` a boolean value indicating whether to use manual mode; if not given, the function only returns the current setting.
105+
- `on_off` a boolean value indicating whether to use manual mode; if not
106+
given, the function only returns the current setting.
87107

88108
#### Returns
89109
The current setting, true if manual mode is enabled, false if it is not.

0 commit comments

Comments
 (0)