ESPEasy

Introduction

The ESP Easy firmware can be used to turn the ESP module into an easy multifunction sensor device for Home Automation solutions like Domoticz. Configuration of the ESP Easy is entirely web based, so once you've got the firmware loaded, you don't need any other tool besides a common web browser.

The ESP Easy firmware is currently at build R120 an looks stable enough for production purposes as long as it's being used as a sensor device.

ESP Easy also offers limited "low level" actuator functions but due to system instability, this could be less useful in real life applications.

Get started

Getting started with the ESP Easy takes a few basic steps. In most cases your ESP module comes with the AT firmware or the NodeMCU LUA firmware. We need to replace the existing firmware with the ESP Easy firmware. We provide a (Windows only) flashtool to make this process an easy job.

Supported Hardware

ESP Easy can be installed/flashed on nearly every piece of Hardware that has an ESP8266 built-in, newest 2.0.0 version even does support the ESP8285 (basically an ESP8266 with buildtin 1M Flash):

This is a (not yet complete) list of Hardware which is known to be supported:

Wemos D1 mini

Very easy flashing, just need do be attached via USB.

Wemos D1 R2

Very easy flashing, just need do be attached via USB.

ITEAD Sonoff Basic

TBD

ITEAD Sonoff TH10

TBD

ITEAD Sonoff 4ch

Must be flashed with a firmware compiled for ESP8285 with 1MB. BEWARE, this device operates with HIGH VOLTAGE! To flash the case has to be opened, do not connect it to mains while flashing, it can be flashed while powered from the USB-TTL adapter.

ITEAD Sonoff S20 Smart Socket

BEWARE, this device operates with HIGH VOLTAGE! To flash the case has to be opened, do not connect it to mains while flashing, it can be flashed while powered from the USB-TTL adapter. Only has 1M Flash!

Ai-Thinker A20 Breakout

Based on a ESP8285 chip, so only 1M Flash, can be flashed with a stripped down build of latest mega build, GSM/GPRS and Camera not yet supported!

Flashing Instructions

To enable Flash mode for the esp8285:

1. power down the board
2. connect WI 00 to ground
3. connect power to the board.
4. flash using WRX0 and WTX0 for the Rx Tx connections

many more, this list is not yet finished....

TBD

Supported Sensors/Actuators

Sensors (Input)
PulseCounting	Temperature
TCR5000	Dallas DS18b20 MLX90614
Barometric Pressure	Light/Lux
BMP085/BMP180 BME280 BMP280 MS5611	BH1750 TSL2561 TCS34725 RGB Color Sensor
Humidity	RFID
DHT DHT12 SI7021/HTU21D SHT1X AM2320	Wiegand PN532
Distance	Switch
HC-SR04	Switch
Analog	More Analog
Analog	PCF8591 ADS1115
Digital inputs	Infrared Receivers
MCP23017 PCF8574	IR
Dust	Voltage & Current
GP2Y10	INA219
Weather	Motion
Ventus W266	MPU 6050
Soil Moisture	Gas Sensors
Soil moisture sensor	CO2 Sensor MH-Z19

Actuators (Output)
Digital output	Servo
Output pin Relays	Servo
IR-Transmit	Extra IO
IR Led	MCP23017 PCF8574
PWM	Motor Shield
PCA9685 PWM GPIO	Adafruit Motor Shield v2
Buzzer (RTTL)
RTTL

Other
LCD	OLED
LCD Display	OLED Display

Tutorials

• Using the flashtool to upload the ESP Easy firmware
• Using the Arduino IDE to upload the ESP Easy firmware
• Using the ESP Easy as a simple input switch in Domoticz
• Using the ESP Easy to control a LED of Relay from OpenHAB
• Rules, a modest way to locally control something in ESP Easy
• GlobalSync

Hardware Tips 'n Tricks

• Power stability
• Relays
• Breadboards
• WiFi interference

Examples

• Analog Pressure Sensor
• DC Voltage divider

Loading firmware

Stable

Firmware image R120

• ESP Easy firmware (image)

Release candidates

Firmware image R147_RC8

• ESP Easy firmware (image)

Tutorial_ESPEasy_Firmware_Upload

Protocol selection

The ESP Easy supports several Home Automation controllers or web-services that collect sensor data.

EasyProtocols

Configuration

To get you on track with the ESP Easy, we provide a tutorial to demonstrate the basics Tutorial_Domoticz_Switch For all further applications, please check their respective wiki page Applications

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. We will explain all configuration pages and settings:

Main page

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.

Config page

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.

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

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.

Hardware page

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

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.

Devices page

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...

Tools page

Some maintenance tools.

Tools Log page

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

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

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 I2C scan

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

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.txt

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.

* {
	font-family: verdana,sans-serif;
	font-size: 13px;
}
h1 {
	color: black;
	font-size: 16pt;
}

h1::after {
	content: " (Powersocket Livingroom)";  /* Give your Device an additional selfexplaing name after the topmost headline */
}

h6 {
	color: black;
	font-size: 10pt;
	text-align: center;
}
.button-menu {
	background: #3498db;
	background-image: -webkit-linear-gradient(top, #3498db, #2980b9);
	background-image: -moz-linear-gradient(top, #3498db, #2980b9);
	background-image: -ms-linear-gradient(top, #3498db, #2980b9);
	background-image: -o-linear-gradient(top, #3498db, #2980b9);
	background-image: linear-gradient(to bottom, #3498db, #2980b9);
	-webkit-border-radius: 7;
	-moz-border-radius: 7;
	border-radius: 7px;
	color: #ffffff;
	padding: 3px 10px 3px 10px;
	border: solid #1f628d 1px;
	text-decoration: none;
	margin:0px 2px;
}

.button-menu:hover {
	background: #8fd4ff;
	background-image: -webkit-linear-gradient(top, #8fd4ff, #3498db);
	background-image: -moz-linear-gradient(top, #8fd4ff, #3498db);
	background-image: -ms-linear-gradient(top, #8fd4ff, #3498db);
	background-image: -o-linear-gradient(top, #8fd4ff, #3498db);
	background-image: linear-gradient(to bottom, #8fd4ff, #3498db);
	text-decoration: none;
	margin:0px 2px;
}

.button-link {
	border: 1px solid;
	border-radius: 5px;
	background:ButtonFace;
	color:ButtonText;
	border-color:ButtonHighlight ButtonShadow ButtonShadow ButtonHighlight;
	padding: 5px 15px;
	text-decoration: none;
}
.button-link:hover {
	background-color:Highlight;
	color:HighlightText;
}
.button-link:active {
	border-color:ButtonShadow ButtonHighlight ButtonHighlight ButtonShadow;
}
th {
	background-color: #369;
	color: #ffffff;
	padding: 10px;
}
td {
	padding: 7px;
}
table {
	color: black;
	border-collapse:collapse;
}
.div_l {
	float: left;
}
.div_r {
	background-color: #080;
	border-radius: 7px;
	color: white;
	float: right;
	margin: 2px;
	padding: 1px 10px;
}
.div_br {
	clear: both;
}

Tools Firmware update using OTA

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

Command Reference

ESPEasy Command Reference

System variables Reference

ESPEasy System Variables

Tutorial Rules

Tutorial Rules

Most information on rules (=local logic on ESP without controller) can be found in the tutorial

Support and discussion

• Forum
• IRC: #espeasy @freenode

Source code development

Sources are on Github

Want to contribute? Anyone is invited to do so, but please read this first: ESPEasyDevelopmentGuidelines

If you're new to this, follow these guides:

• Install Atom and platformio: Tutorial Install Platformio
• If you want to be send us back your changes via github follow: Tutorial preparing to work with github (otherwise skip it)
• Then you're ready for: Tutorial building and uploading with platformio
• And eventually, if you did the github stuff: Tutorial Contributing Back To ESPEasy