From Let's Control It
Revision as of 08:04, 10 March 2018 by Grovkillen (talk | contribs) (Version names, numbers, and branches)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Welcome to ESP Easy,
the open source firmware for ESP8266.


ESP-01S - Warning
At this time ESP-01S are sold with a flash chip marked "PUYA". These flash chips have a problem with using SPIFFS memory and do not work with ESP Easy. The problem is under investigation. At this time there is no given solution besides using other ESP-01 if available or changing the flash chip on the ESP-01S. UPDATE: A fix seems to be on the horizon. Stay tuned!


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 and is stable enough for production purposes as long as it's being used as a sensor device. Next version called v2.0.0 is due to be released within 2018Q1.

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

Version names, numbers, and branches

Well, this is a short version of our naming convention here at the ESP Easy initiative. We started to call the extensive re-write of the source code "Mega", which is an hint of the size needed for the next big stable release. Prior to mega we allowed smaller mem-sizes (sub-megabyte, aka 512kb) for the official releases. This is a bit tight for our goal to add many more useful features to the firmware. So after a somewhat bad decision in the early days of the re-write project we started to call the development branch "Mega" instead of the more accepted name "Master". The current master branch on GitHub is essentially a legacy branch, a point zero if you like, which is the exact copy of the source code before we started the re-write. Two handfuls of months later we froze the source for new features and made it a branch we call v2.0, this branch is pretty much the exact copy of what will later be the official v2.0.0 release. Only bug fixes is going into that branch (and occasionally some really good features as well). New features, and experimental stuff, is poured into the mega branch. Below you will find a explanation on how we intend to do the branching and releases of future firmware versions. Please observe that this table is not the road map, just an example to explain the different names and numbers.

Explanation L: legacy freeze (R147 code) D: development (cutting edge) FF: feature freeze R: release of new stable
Branch Name 2017 2018 2019
Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4 Q1 Q2 Q3 Q4
master Master L
mega Mega D
v2.0 v2.0.0 FF R
v2.1 v2.1.0 FF R
v3.0 v3.0.0 FF?

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. Below you find the general flow of this but an in depth guide is found here.

1. Download firmware as binary including flash tool

2. Connect the ESP to Windows PC
Using either USB/UART of board or separate USB/TTL adapter

3. Write firmware using flash tool
Note necessity for GPIO to be LOW to enter flashmode

4. Restart ESP. WiFi AP "ESP_Easy_0" will appear, password: configesp
(prior to 2.0 the AP was named ESP_0)
If you're not automatically taken to the log-in page, browse to

5. Search for you routers WiFi and connect
(if you have multiple AP they will all show up with the same SSID name multiple times)

6. Reconnect to your WiFi and enter IP adress shown on previous screen

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 built-in 1M Flash).
Please see the list here for more in depth detail about the hardware.

Supported Sensors/Actuators

The in depth list of devices (sensors and actuators) is found here.

Modded Hardware Products

A list of (officially) modded hardware products is found here.


Loading firmware

  • Old release candidate: ESPEasy R147_RC8 (is now part of the dev build for v2.0.0)
 On the linked page you will find two daily builds of ESPEasy.
 For some clarification:
 Release V2.0-<date>: Beta version of the next stable release, no new features, bugfixes only.
 Release mega-<date>: Bleeding edge of development.

2.0+ firmware on 1MB modules

2.0+ firmware on 1MB modules - Warning
If you are running the stock Mega edition firmware on 1MB modules, you will find that you can no longer load newer images because there's insufficient free space to upload the image (344kB as of 2.0.0.-Dev 9 edition). You can compile smaller images to solve this issue or use a small image that has been build just to upload newer images. So you would always have to use a two-step process to renew using OTA on 1MB modules. Using the uploader image as an in-between step, you can use images up to 604kB.
  • Only devices with 1Mb or more flash are supported.
  • To use OTA you need more then 1Mb of flash. (otherwise your device will get unreachable via wireless and you need to fix it via serial)
  • You lose all your config settings if you upgrade from an Rxxx version. (from before ESPEasy v2.0)


The uploader uses SPIFFS so it uses the same configuration regarding SSID, WPA key and IP. It will connect to your Wifi network as usual, but it will only present this small web page:



Compile your own firmware (Platformio)

If you want to compile your own firmware (with unreleased plugins etc.) you do pretty much the same as the development method except that you only need to download extra plugins on the side. Just follow the official guide found here.

Protocol selection

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



The ESP8266 boards are generally easy to use and understand but some precautions need to be taken when it comes to the different GPIOs available. This section tells you more about the ESPeasy setup and the ESP unit's need to know settings (GPIO boot states etc.).

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 explain all configuration pages and settings here.

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!

Command Reference

ESPEasy Command Reference

System variables Reference

ESPEasy System Variables

Tutorial Rules

Most information on rules (=local logic on ESP without controller) can be found in the tutorials. Rules are a great way of tweaking the ESP Easy firmware to do exactly what you want without the need to tinker with any source code.

More on how is found on the Tutorial Rules page.

Hardware Tips 'n Tricks


Support and discussion

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:

Hardware page

For older versions, the Hardware page has now moved to: ESP Easy web interface#Hardware page!