Config page

Main Settings

Unit Name

The name of this node. This is mainly used when connecting to a MQTT broker or in p2p communications. It is also used to generate a hostname in the local network, for example when using mDNS.

2023-01-27: Variables like %unit_0%, %ip4% etc. can be used as (part of) the Name, and will be expanded anywhere the name is used. If the Append Unit Number to hostname setting is enabled, the name will not get the unit number appended, but the Hostname will have the unit number appended.

Unit Number

The number of this node. It can be appended to the hostname.

The main use of the unit number is in ESPEasy p2p communications. When used in p2p communications, make sure not to use unit number 0 or 255 as those are reserved.

Range: 0 … 255

Append Unit Number to hostname

A flag to indicate how the hostname must be generated from Unit Name and Unit Number.

N.B. currently it is used in all occurences where a hostname is needed, but this appeared to be not working well for some MQTT brokers. So expect it to be changed later to split this flag for every occasion where a hostname is needed.

Admin Password

A password to prevent altering settings in the web interface.

Default password is empty.

N.B. when asked for a login prompt, the user name is admin

WiFi Settings

A WiFi capable device can operate in two modes:

  • Station mode (STA), device needs to connect to an access point.

  • Access Point mode (AP), other STA devices can connect to this device.

An AP will broadcast an identifier string, called the SSID.

For an STA device to connect to an AP, two parameters are needed:

  • SSID - The identifier string of an AP.

  • WPA key - The password or pass phrase to make a connection.

N.B. when using the mentioned commands to set SSID/key, don’t forget to call the save command.

SSID

The AP identifier string to connect to. This is needed when running in STA mode.

Can also be set via the command wifissid.

WPA Key

The password or pass phrase to connect to the AP with given SSID.

Can also be set via the command wifikey.

Fallback SSID / WPA Key

This is an alternate to the first configured SSID/key.

There are various use cases to have multiple AP configurations stored on a node. For example to be able to move to anothe location where only another AP can be reached. Or as a backup, for example to let the node connect to a local hotspot on your phone.

Can also be set via the commands:

  • wifissid2

  • wifikey2

WPA AP Mode Key

It is possible a node cannot connect to an AP:

  • When there is no SSID configured

  • The configured AP’s are not in reach

  • The configured AP’s do not allow the node to connect

In these situations the ESP node will start its own local AP.

As SSID the Unit Name will be used, which is by default ESP_Easy_0

The default WPA key to connect to this AP is configesp, but can be changed here.

This is often used to perform the initial configuration like connecting to the local network.

Can also be set via the command WiFiAPKey.

Don’t force /setup in AP-Mode

Allow optional usage of ESPEasy without WIFI avaiable.

When checked you can use ESPEasy in AP-Mode without beeing forced to /setup.

Do Not Start AP

Usually the AP will be started when no WiFi is defined, or the defined one cannot be found. This flag may prevent to start an AP.

Since this flag can lock out a user, there is a restricted command to uncheck this.

WifiAllowAP will uncheck this flag in the settings until a reboot. If the settings are saved, this flag will remain unchecked.

N.B. Restricted means, not accepted from a remote source, only local or via serial.

Custom Build WiFi credentials

For custom builds, one can set default WiFi credentials by defining some default credentials at build. See the examples in Custom-sample.h:

  • #define DEFAULT_SSID  "MyHomeSSID"            // Enter your network SSID

  • #define DEFAULT_KEY   "MySuperSecretPassword" // Enter your network WPA key

  • #define DEFAULT_SSID2 ""                      // Enter your fallback network SSID

  • #define DEFAULT_KEY2  ""                      // Enter your fallback network WPA key

Custom builds can also be customized a bit more to allow for a deployment SSID configuration and an emergency fallback.

Deployment & Support SSID will be used only when the configured SSIDs are not reachable and/or no credentials are set. This to make deployment or support of large number of nodes easier. This configured set of credentials will be considered a “low priority” set, thus it will be tried as last resort. Therefore it may take a while for a unit to connect to it if there are lots of ‘hidden SSID’ APs and connecting to hidden SSIDs is allowed.

  • #define CUSTOM_DEPLOYMENT_SSID ""  // Enter SSID not shown in UI, to be used on custom builds to ease deployment

  • #define CUSTOM_DEPLOYMENT_KEY  ""  // Enter key not shown in UI, to be used on custom builds to ease deployment

  • #define CUSTOM_SUPPORT_SSID    ""  // Enter SSID not shown in UI, to be used on custom builds to ease support

  • #define CUSTOM_SUPPORT_KEY     ""  // Enter key not shown in UI, to be used on custom builds to ease support

Emergency fallback SSID will only be attempted in the first 10 minutes after reboot. When found, the unit will connect to it and depending on the built in flag, it will either just connect to it, or clear set credentials.

Use case: User connects to a public AP which does need to agree on an agreement page for the rules of conduct (e.g. open APs) This is seen as a valid connection, so the unit will not reconnect to another node and thus becomes inaccessible. The AP configured with these fallback credentials will then act as a master key to regain access to a node.

These will never be set in nightly builds and only allowed for custom builds for obvious reasons.

  • #define CUSTOM_EMERGENCY_FALLBACK_SSID ""  // Enter SSID not shown in UI, to be used to regain access to the node

  • #define CUSTOM_EMERGENCY_FALLBACK_KEY  ""  // Enter key not shown in UI, to be used to regain access to the node

  • #define CUSTOM_EMERGENCY_FALLBACK_RESET_CREDENTIALS  false

  • #define CUSTOM_EMERGENCY_FALLBACK_START_AP           false

  • #define CUSTOM_EMERGENCY_FALLBACK_ALLOW_MINUTES_UPTIME 10

Client IP filtering

Sometimes it can be useful to only allow access to the web interface of a node from a specific range of IP-addresses.

For example if a node should only be configured from the local subnet.

Client IP block level

  • Allow All - No filtering applied, the web interface can be accessed from any IP able to reach the node. (default)

  • Allow Local Subnet - Only allow access to the web interface from the local subnet.

  • Allow IP range - Only allow access to the web interface from a specific IP range.

Access IP lower range

When Allow IP range is set, this field defines the lower bound of the range.

Access IP upper range

When Allow IP range is set, this field defines the upper bound of the range.

WiFi/Ethernet IP Settings

For both WiFi and Ethernet a node can be configured to receive an IP automatically via DHCP, or use a static IP.

If all fields for IP, GW, subnet mask and DNS are left empty, the configuration offered via DHCP will be used.

  • IP The static IPv4 address to use for this node

  • Gateway IPv4 address of the gateway to reach hosts outside this subnet. (typically the IP of the router)

  • Subnetmask Mask applied to define the local subnet. (typically: 255.255.255.0 )

  • DNS IPv4 address of a DNS server to use. (typically the IP of the router or some assigned by the ISP)

Sleep Mode

Description

The ESP can be put into deep sleep for a set amount of time.

On an ESP8266, GPIO-16 must be connected to the RST pin to be able to wake up again.

As long as the node is in deep sleep mode, you can’t connect to the web interface. In fact, the ESP is turned off and only a dedicated timer circuit is still powered to wake up the main ESP core.

There are three ways to get out of sleep mode:

Cold boot

Power off the ESP and reconnect power. You will have 30 seconds to connect to the Web interface and disable the Sleep Mode function. (You will get feedback in the serial interface)

Temporary disable Deep Sleep via jumper setting

If 30 seconds is too short for you, you can use this method.

  • Disconnect GPIO-16 from RST and connect it to GND. Restart your ESP if neccesary.

  • Now deep sleep will be disabled and your ESP will function normally, until you connect GPIO-16 to RST again.

This requires ESPEasy v2.0.0-dev6 or newer.

Factory reset

If all else fails, just do a factory reset. You will lose all your settings!

  • Connect the RX and TX pin together while you restart your ESP. (will clear all stored settings)

  • Power off the device.

  • Remove the connector across the RX and TX pins.

  • Restart and then configure the ESPEasy firmware again. (at restart factory default settings will be loaded)

If this doesn’t work:

  • Try loading the blank image to match the size of the memory installed on the device.

  • Reboot and wait 5 minutes.

  • Then load on the firmware you are wanting to use.

  • Reboot and wait 5 minutes.

Sleep awake time

This setting defines the minimum time in seconds a node should be awake from deep sleep.

If set to 0, the node will not go into deep sleep automatically.

At boot from deep sleep, a timer is started based on this setting. If this timer expires, the node will enter deep sleep again.

As soon as the node has a successful WiFi connection, the timer will be restarted to allow to send out sensor data.

N.B. It is possible to put a node into deepsleep via the command deepsleep, regardless this setting.

Sleep time

The duration in seconds for a node to go into deep sleep.

Typical max. duration is 4294 seconds (Roughly 71 minutes)

N.B. the maximum possible duration depends on the used core library version and is mentioned at the configuration page.

Sleep on connection failure

CDN (Content delivery network)

The Custom CDN URL can be set to a server url (https preferred, they are downloaded by the browser, not by the ESPEasy unit) that hosts all files as listed on External Hosted Static Files (System variables can be used to customize the URL).

To reduce the build size where possible, some builds fetch the javascript (.js) and .css UI files from an external server, as this is used in the browser only. The default location for this data is the Content Delivery Network (CDN) of jsdelivr.net, where these file are uploaded for specific releases.

For users that want to host these files in their local network, or if the files on jsdeliver.net have expired, an alternative location for these .js and .css file can be configured.

Setting this location will override the default CDN url, except for your Custom build that may already have the CDN url set, then this setting won’t be available!

Warning: If an invalid location is set, the UI will be distorted, though should still be usable.