170 lines
7.0 KiB
Markdown
170 lines
7.0 KiB
Markdown
# enduser setup Module aka Captive Portal aka WiFi Manager
|
|
| Since | Origin / Contributor | Maintainer | Source |
|
|
| :----- | :-------------------- | :---------- | :------ |
|
|
| 2015-09-02 | [Robert Foss](https://github.com/robertfoss) | [Robert Foss](https://github.com/robertfoss) | [enduser_setup.c](../../app/modules/enduser_setup.c)|
|
|
|
|
This module provides a simple way of configuring ESP8266 chips without using a
|
|
serial interface or pre-programming WiFi credentials onto the chip.
|
|
|
|
After running [`enduser_setup.start()`](#enduser_setupstart), a wireless
|
|
network named "NodeMCU_XXXXXX" will start. This prefix can be overridden
|
|
in `user_config.h` by defining `ENDUSER_SETUP_AP_SSID` or by supplying the whole SSID to the
|
|
`enduser_setup.start` method. Connect to that SSID and captive portal detection on the client
|
|
should automatically open the configuration dialog. If not, then
|
|
navigate to the root of any website or to 192.168.4.1.
|
|
`http://example.com/` will work, but do not use `.local` domains because it
|
|
will fail on iOS. A web page similar to the one depicted below will load,
|
|
allowing the end user to provide their Wi-Fi credentials.
|
|
|
|
|
|
|
|
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 teardown to allow connected clients to obtain a last
|
|
status message while the SoftAP is still active.
|
|
|
|
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 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 the appropriate
|
|
`Content-Encoding` header to the response.
|
|
|
|
*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.*
|
|
|
|
### Additional configuration parameters
|
|
|
|
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` 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, and the value being a string
|
|
representing what you put in the form.
|
|
|
|
For instance, if your HTML contains two additional inputs:
|
|
|
|
```html
|
|
<input name=timeout_delay type=text placeholder="Delay in seconds" />
|
|
<input name=device_name type=text placeholder="Unique device name" />
|
|
```
|
|
|
|
Then the `eus_params.lua` file will contain the following:
|
|
|
|
```lua
|
|
-- those wifi_* are the base parameters that are saved anyway
|
|
local p = {}
|
|
p.wifi_ssid="ssid"
|
|
p.wifi_password="password"
|
|
-- your own parameters:
|
|
p.timeout_delay="xxx"
|
|
p.device_name="yyy"
|
|
return p
|
|
```
|
|
|
|
### How to use the eus_params.lua file
|
|
|
|
Simply include the file by using the `dofile` function:
|
|
```lua
|
|
p = dofile('eus_params.lua')
|
|
-- now use the parameters in the Lua table
|
|
print("Wifi device_name: " .. p.device_name)
|
|
```
|
|
|
|
### HTTP endpoints:
|
|
|
|
|Path|Method|Description|
|
|
|----|------|-----------|
|
|
|/|GET|Returns HTML for the web page. Will return the contents of `enduser_setup.html` if it exists on the filesystem, otherwise will return a page embedded into the firmware image.|
|
|
|/aplist|GET|Forces the ESP8266 to perform a site survey across all channels, reporting access points that it can find. Return payload is a JSON array: `[{"ssid":"foobar","rssi":-36,"chan":3}]`|
|
|
|/status|GET|Returns plaintext status description, used by the web page|
|
|
|/status.json|GET|Returns a JSON payload containing the ESP8266's chip id in hexadecimal format and the status code: 0=Idle, 1=Connecting, 2=Wrong Password, 3=Network not Found, 4=Failed, 5=Success|
|
|
|/setwifi|POST|HTML form post for setting the WiFi credentials. Expects HTTP content type `application/x-www-form-urlencoded`. Supports sending and storing additinal configuration parameters (as input fields). Returns the same payload as `/status.json` instead of redirecting to `/`. See also: `/update`.|
|
|
|/update|GET|Data submission target. Example: `http://example.com/update?wifi_ssid=foobar&wifi_password=CorrectHorseBatteryStaple`. Will redirect to `/` when complete. Note that will NOT update the `eus_params.lua` file i.e. it does NOT support sending arbitrary parameters. See also: `/setwifi`. |
|
|
|
|
Module functions are described below.
|
|
|
|
|
|
|
|
## enduser_setup.manual()
|
|
|
|
Controls whether manual AP configuration is used.
|
|
|
|
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.
|
|
|
|
|
|
#### Syntax
|
|
`enduser_setup.manual([on_off])`
|
|
|
|
#### Parameters
|
|
- `on_off` a boolean value indicating whether to use manual mode; if not
|
|
given, the function only returns the current setting.
|
|
|
|
#### Returns
|
|
The current setting, true if manual mode is enabled, false if it is not.
|
|
|
|
#### Example
|
|
```lua
|
|
wifi.setmode(wifi.STATIONAP)
|
|
wifi.ap.config({ssid="MyPersonalSSID", auth=wifi.OPEN})
|
|
enduser_setup.manual(true)
|
|
enduser_setup.start(
|
|
function()
|
|
print("Connected to WiFi as:" .. wifi.sta.getip())
|
|
end,
|
|
function(err, str)
|
|
print("enduser_setup: Err #" .. err .. ": " .. str)
|
|
end
|
|
)
|
|
```
|
|
|
|
## enduser_setup.start()
|
|
|
|
Starts the captive portal.
|
|
|
|
*Note: Calling start() while EUS is already running is an error, and will result in stop() to be invoked to shut down EUS.*
|
|
|
|
#### Syntax
|
|
`enduser_setup.start([AP_SSID,] [onConnected()], [onError(err_num, string)], [onDebug(string)])`
|
|
|
|
#### Parameters
|
|
- `AP_SSID` the (optional) SSID to use for the AP. This defaults to `NodeMCU_<device id>`.
|
|
- `onConnected()` callback will be fired when an IP-address has been obtained, just before the enduser_setup module will terminate itself
|
|
- `onError()` callback will be fired if an error is encountered. `err_num` is a number describing the error, and `string` contains a description of the error.
|
|
- `onDebug()` callback is disabled by default (controlled by `#define ENDUSER_SETUP_DEBUG_ENABLE` in `enduser_setup.c`). It is intended to be used to find internal issues in the module. `string` contains a description of what is going on.
|
|
|
|
#### Returns
|
|
`nil`
|
|
|
|
#### Example
|
|
```lua
|
|
enduser_setup.start(
|
|
function()
|
|
print("Connected to WiFi as:" .. wifi.sta.getip())
|
|
end,
|
|
function(err, str)
|
|
print("enduser_setup: Err #" .. err .. ": " .. str)
|
|
end,
|
|
print -- Lua print function can serve as the debug callback
|
|
)
|
|
```
|
|
|
|
## enduser_setup.stop()
|
|
|
|
Stops the captive portal.
|
|
|
|
#### Syntax
|
|
`enduser_setup.stop()`
|
|
|
|
#### Parameters
|
|
none
|
|
|
|
#### Returns
|
|
`nil`
|