|
3 | 3 | | :----- | :-------------------- | :---------- | :------ |
|
4 | 4 | | 2015-09-02 | [Robert Foss](https://github.com/robertfoss) | [Robert Foss](https://github.com/robertfoss) | [enduser_setup.c](../../app/modules/enduser_setup.c)|
|
5 | 5 |
|
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 |
| - |
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 | + |
| 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.* |
23 | 34 |
|
24 | 35 | ### Additional configuration parameters
|
25 | 36 |
|
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. |
29 | 43 |
|
30 | 44 | For instance, if your HTML contains two additional inputs:
|
31 | 45 |
|
@@ -70,20 +84,26 @@ print("Wifi device_name: " .. p.device_name)
|
70 | 84 |
|
71 | 85 | Module functions are described below.
|
72 | 86 |
|
73 |
| ---- |
| 87 | + |
74 | 88 |
|
75 | 89 | ## enduser_setup.manual()
|
76 | 90 |
|
77 | 91 | Controls whether manual AP configuration is used.
|
78 | 92 |
|
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. |
80 | 99 |
|
81 | 100 |
|
82 | 101 | #### Syntax
|
83 | 102 | `enduser_setup.manual([on_off])`
|
84 | 103 |
|
85 | 104 | #### 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. |
87 | 107 |
|
88 | 108 | #### Returns
|
89 | 109 | The current setting, true if manual mode is enabled, false if it is not.
|
|
0 commit comments