# 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. ![enduser setup config dialog](../img/enduser-setup-captive-portal.png "enduser setup config dialog") 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 ``` 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_`. - `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`