ESP Easy web interface

ESP Easy web interface

The ESP Easy has a user-friendly web interface for all configuration settings. They are locally stored in flash memory and retained on power-off.

Do NOT expose the ESP Easy web interface directly to the internet, always make sure that the web interface is only reachable from "trusted/local" networks!

We will explain all configuration pages and settings:

Main page

URL:<espeasyip>

This is an informational page that provides some technical and operational parameters. The bottom half shows a node list of all known ESP units that are running in your network (this is optional and needs to be configured in tools/advanced)

The list only shows live systems. Age is number of days it has been connected.

Free Mem is available memory, this should be above 20 000 (byte) for the ESP to feel happy.

Config page

URL:<espeasyip>/config

Main settings can be found under "Config" page.

Name Can be set to an easy to remember name for this system. Can also be used in MQTT communication templates.

Admin Password Can be set if you want to protect your system config with a password. Default is null (none).

SSID Wifi network SSID

WPA Key The key used on your Wifi Access Point

WPA AP Mode Key The key that ESP Easy will use if it starts as a Wifi Access Point to set the first time configuration. Default is "configesp".

Unit nr Each ESP Easy unit needs a unique number in the range 1-31. This is important for MQTT connections and the Node list! Do not forget to set this field to a non-zero value, not conflicting with other units.

Protocol Select the protocol for your Home Automation controller or webservice like ThingSpeak.

Locate Controller You can set the controller based on it's DNS hostname or it's IP address.

Controller IP/Hostname Set IP or hostname for the controller

Controller Port Set the TCP port used on your controller or webservice.

Sensor Delay Set the delay between sensor reporting in seconds.

Sleep Mode Tick this field to use the ESP in deepsleep mode for low power operation. Read more: SleepMode

---

Optional

ESP IP You can set a static IP for this ESP unit. Set to 0.0.0.0 to use DHCP

ESP GW If using a static IP, enter the gateway (not needed if no connection to internet is needed!)

ESP Subnet Enter the local used subnet, usually 255.255.255.0

ESP DNS Enter you local DNS server IP address. Usually the IP of your local internet router.

---

Extra information

The AP name will be constructed of Name and Unit nr and default would this be "ESP_Easy_0". In other word <name>_<unit number>.

Controllers page (version 2.0+)

URL:<espeasyip>/controllers

It is possible to have multiple controllers/brokers activated.

Settings page (below), as of current status the OpenHAB MQTT is the most generic one. But remember to remove the / in the beginning of the subscribe and publish topic string.

Default settings: Controller Subscribe: %sysname%/#
Controller Publish: %sysname%/%tskname%/%valname%

Hardware page

URL:<espeasyip>/hardware

Status LED (version 2.0 only) Select the data pin used for a low active LED to show the status of the firmware. Use D4 (GPIO2) for the on-board blue LED.

SDA Select the data pin used for I2C communications.

SCL Select the clock pin used for I2C communications.

Pin mode x Select an optional boot state for this pin, either output low or high (but please understand that problems might occur with these settings as they sometime clash with internal need for low or high settings. For example GPIO 9 has been reported not to obey these settings on some boards). See Configuration for more information regarding the GPIOs!

I2C is a well known standard to let multiple devices communicate over just two wires (and ground). We use it to connect sensors to ESP Easy. You can connect multiple sensors to the same two wires. Don't forget to use pull-up resistors on both SDA and SCL, unless one of your sensors already has them mounted on board.

Rules page

URL:<espeasyip>/rules

Here's where the rules goes. More on how to use rules is found here.

Notifications page (version 2.0+)

URL:<espeasyip>/notifications

It is possible to have the ESP unit send emails or giving you notifications using a buzzer.

Devices page

URL:<espeasyip>/devices

This is a list of tasks that the ESP Easy will perform. A sensor needs to be defined here to get the values send to your controller.

After selecting a new device, press the ? button to get specific help on this device!

Most common mistake if your values remain 0: The ESP Easy mainly targets Domoticz and the internal framework is entirely build upon the IDX field. This needs to match Domoticz. If you run a different protocol, it can be any value but must be non-zero. Just choose '1' in those cases... (IDX is not generally need in version 2.0+)

Why only 12 tasks?

A common question is why the maximum tasks/devices are set to 12. This has to do with the architecture of the firmware. The firmware config file is a fixed size (every bit is occupied) and this means that the firmware need to know which bits that are used for what purpose. 12 is therefor a chosen number of max tasks/devices, not to many and not to few. If you were to extend this number you might happen to write over bits that are used elsewhere. It is possible to compile your own version of ESP Easy with more than 12 tasks but beware of this fact. More devices might corrupt your system.

Device plugins (official used in main)

Here you find a list of all the available plugins that are in the official release of ESP Easy.

Tools page

URL:<espeasyip>/tools

Some maintenance tools. You can send commands using the input box. See more on commands here.

Tools Log page

URL:<espeasyip>/log

This page can be used for debugging issues. The debug level is set to '2' by default and will show sensor readings. Debugging levels can be changed under Tools/Advanced.

If your system runs fine, you can set the level to '0' to turn of logging. This will save valuable RAM!

Tools Advanced page

URL:<espeasyip>/advanced

Subscribe Template Used for MQTT subscription. Selecting a MQTT protocol will automatically fill this field

Publish Template Used for MQTT publishing. Selecting a MQTT protocol will automatically fill this field It is also used for the Generic HTTP protocol. Create your custom template here.

MQTT Retain Msg Will send the MQTT message with a retain flag. This makes the broker holding the last received message in memory. Good for monitoring the broker using a MQTT scanner etc.

Message Delay To prevent overloading your controller or webservice, a delay between reports can be set. Defaults to 1000 milliseconds. For ThingSpeak, you need to set this to 15000! to have multiple sensor readings working

Fixed IP Octet Special network config where the ESP starts with DHCP to get the basic network config and then sets the last octet to a fixed IP.

Use NTP To enable internal software clock, synchronized using internet time.

NTP Hostname Can be left empty as it defaults to pool.ntp.org. Can be changed here if needed.

Timezone Offset Offset in minutes to GMT. In the Netherlands this should be '60'

DST Daylight Saving Time. Must be set manually when DST is active to adjust the time.

Syslog IP Enter your syslog server IP if you have one running and want to debug something.

Syslog level Level of log messaging to the syslog server. Can be set between 0 - 4 (0=no logging, 1=error, 2=error+info, 3=error+info+debug, 4=error+info+more debug)

UDP port This is used for communication between ESP unit's. 65500 is just a sample. Use a number that does not conflict with other systems on your network as the ESP uses broadcast messages. If you have a syslog server running, do not enter 514 here!. This fields needs to be non-zero to have the node list running.

Enable Serial Port Enable/disable the serial port.

Serial log level Level of log messaging to the serial port. Can be set between 0 - 4 (0=no logging, 1=error, 2=error+info, 3=error+info+debug, 4=error+info+more debug)

Web log level Level of log messaging to the web gui. Can be set between 0 - 4 (0=no logging, 1=error, 2=error+info, 3=error+info+debug, 4=error+info+more debug)

Baud Rate Serial port baud rate

WD I2C Address I2C address to send watchdog messages to. Experimental feature to feed a ATTiny based external watchdog.

Custom CSS Tick this box to use a custom CSS (style sheet). You must first upload a "esp.css" file one to use this. The CSS filesize can not exceed 4 kbyte!.

Use SSDP SSDP is a network protocol based on the Internet Protocol Suite for advertisement and discovery of network services and presence information. This option toggles this service.

Rules Tick this checkbox to enable the Rules section for scripting the device. Else the rules aren't visible and editable and won't be processed at all.

I2C ClockStrechLimit

Global Sync

Tools Wifi scan

URL:<espeasyip>/wifiscanner

Here's a list of all accessible wifi networks and their signal strength.

Tools I2C scan

URL:<espeasyip>/i2cscanner

If one or more I2C devices are connected to the ESP Easy, you can use this scan feature to verify if devices can be located using their I2C address. If no device is shown, you likely made a mistake on wiring or the I2C configuration in the Hardware page.

If the I2C scanner lists an address, it will also list some well known devices that are fixed or typically found on that address. It does NOT mean that the detected device is verified to work in any way. I2C devices use a 7 bit address and the ESP will just scan all 127 possible addresses. If a device listens to some address it will acknowledge this to the ESP. It does not report the type of device so the ESP can only tell that something is listening!

Tools Settings up/download

URL:<espeasyip>/upload (for uploading settings)

URL:<espeasyip>/download (for downloading settings, not a webpage but a direct download)

The ESP Easy settings can be saved to your computer so you can restore them if they are lost or you just want to restore them after some experimenting. You can also upload a custom style sheet.

The system recognizes only two filenames:

config.dat

This file contains the ESP main configuration settings, except security data. The filesize should be 32k. You can exchange this file with other people if you like, because WPA keys and config password are not stored into this file.

Security data cannot be saved or restored from file!

esp.css (Custom Style Sheet, max 4 kb !)

If you want to customize the web gui you can upload (a small) css file. Remember that the webgui is only there for configuration so customization is limited. You may use the following stylesheet as an working example or template for further customization. And don't forget to activate the uploaded stylesheet in the TOOLS>ADVANCED section by enabling the "Custom CSS" option. Read more about customization in the ESP web interface customization portal.

Tools Firmware update using OTA

URL:<espeasyip>/update

Once your first ESP Easy firmware is loaded using the serial interface, subsequent updates can be loaded using the Wifi connection (if your unit has 1MB flash or more!). More details on OTA firmware update: EasyOTA

Tools File List (version 2.0+)

URL:<espeasyip>/filelist

Access to the ESP's files. Possible to download for backup, or upload your own files.

Tools SD CARD File List (version 2.0+)

URL:<espeasyip>/SDfilelist

Access to the ESP's files stored on the SD card (if any SD card). Possible to download for backup, or upload your own files.

Tools Pin State Buffer (version 2.0+)

URL:<espeasyip>/pinstates

Here you can see what plugins are using what pins. Experimental as of now.

Plugin: is the plugin number that is using the GPIO. You find the corresponding plugin in this list.

Index/Pin: is the GPIO number.

Mode: is the type of signal (input/output).

Value/State: is the current state of the GPIO.

Tools System Info (version 2.0+)

URL:<espeasyip>/sysinfo

This page is a summarize of information regarding the system (firmware version, size, plugins etc. etc.)

Load: this is the current load of the unit. LC is the loop count, how many times the loop() function has been run.

Free Mem: this is the free memory count, anything above 20 000 is good (20kb).

JSON page (hidden prior to version 2.0+)

URL:<espeasyip>/json

If you want to get the ESP units variables in a JSON package this is where you want to go. The page is not accessible through any webpage button like the other pages.

To only get a specific task's values you may use this URL:

<espeasyip>/json?tasknr=<tasknumber>

where the task number is found on the device page.

Customization

You can customize the look and feel using your own template css file. More on that is found in the specific ESP web interface customization page.

Backup and restore

To make backups of your settings, rules and perhaps custom css you may use one or more of the following procedures:

The one place, get them all - way

BACKUP
Using the "File list" page you can click on the files that you want to backup.
config.dat the main settings file
security.dat the wifi settings and passwords
rules1.txt the first page rules (does not exist if no rules is put into this page)
rules2.txt the second page rules (does not exist if no rules is put into this page)
rules3.txt the third page rules (does not exist if no rules is put into this page)
rules4.txt the fourth page rules (does not exist if no rules is put into this page)
esp.css the customization file for the web interface (does not exist if no customization is done)

RESTORE
You can upload the files using the same procedure through the upload button found in the "File list" page. Make sure that the config file is renamed to config.dat if you have downloaded it through the "The official settings backup way" procedure.

The official settings backup way

BACKUP
Using the "Settings Save" button will download the config.dat file and rename it according to this nomenclature:
<espname>_<year>-<month>-<day>.dat
example: Kitchen_2017-01-22.dat or ESPunit001_2018-12-24.dat

Rules are not possible to backup (or restore) this way.

RESTORE
You need to rename the dat file to config.dat and then upload it using the "Settings Load" button.

The hardcode way

BACKUP
If you know the IP address you can backup your settings, rules and customizations like this:
<espeasyip>/config.dat
<espeasyip>/security.dat
<espeasyip>/rules1.txt (will not work if no rules exists)
<espeasyip>/rules2.txt (will not work if no rules exists)
<espeasyip>/rules3.txt (will not work if no rules exists)
<espeasyip>/rules4.txt (will not work if no rules exists)
<espeasyip>/esp.css (will not work if no customization exists)

RESTORE
Not possible using this procedure.

Reset the unit

The config file will not be over written if you re-flash your device. If you want a clean unit you need to use the "reset" command. Can be done on the tools page (just type the command and hit submit).