ESPEasy
|
Please see ESPEasy ReadTheDocs for more up to date documentation. As not all documentation has been transferred to RTD, this Wiki can still be useful. However, always check the RTD documentation first.
There may be links to older builds online. See GitHub nightly builds for latest builds and releases.
Contents
- 1 Introduction
- 2 Get started
- 3 Supported Hardware
- 4 Supported Sensors/Actuators
- 5 Modded Hardware Products
- 6 Tutorials
- 7 Loading firmware
- 8 Protocol selection
- 9 Configuration
- 10 ESP Easy web interface
- 11 Command Reference
- 12 System variables Reference
- 13 Tutorial Rules
- 14 Hardware Tips 'n Tricks
- 15 Examples
- 16 Support and discussion
- 17 Hardware page
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.
ESP Easy also offers limited "low level" actuator functions but due to system instability, this could be less useful in real life applications.
ESP Easy is under continuous development as can be seen on the GitHub page and on the Forum.
There are so called "nightly builds" which can be found on the Releases page.
We need support
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". We later switched this to the correct name. The current master branch on GitHub is where all the development goes into. The legacy branch is the archive, a point zero if you like, which is the exact copy of the source code before we started the re-write. Once we have reached all the milestones for version 2.0.0 we will freeze the source from that point and fork that into a branch called v2.0, only bug fixes is going into that branch. New features that cannot wait until next v2.1 release will be branched into v2.0.1 (this might not happen if no ground breaking feature is added). New features, and experimental stuff, is poured into the development branch (master). 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.
N.B. this table is outdated and needs to be updated.
| Branch | Tag | 2017 | 2018 | 2019 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Q1 | Q2 | Q3 | Q4 | Q1 | Q2 | Q3 | Q4 | Q1 | Q2 | Q3 | Q4 | ||
| legacy | R147 | L | |||||||||||
| development | Mega/Knox/Carta | D | |||||||||||
| v2.0 | v2.0.0 | FF | R | ||||||||||
| v2.1 | v2.1.0 | FF | R | ||||||||||
| v3.0 | v3.0.0 | FF? | |||||||||||
Tag names
Stable releases will have a version number similar to "v2.0.0" but focusing areas for development will have short tag names such as "Mega" which indicate the focus for the next big release. A preliminary list for the future focus areas are:
Mega which will become v2.0.0 - getting more plugins and much more features (thus the tag "mega" which indicates that a bigger memory is needed for the generic FW)
Knox which will become v2.1.0 - focusing on security
Carta which will become v2.2.0 - focusing on communication unit2unit and unit2controller
As of release mega we will also try to get more hardware specific builds for especially Sonoff units. These will have much less plugins by default since they are not needed for these units, this makes flashing units with less than 1MB possible.
Release names
Nightly builds are always generated if something has been updated in the source code. So the master branch will always have many more releases than the frozen stable releases which will only have one (until a bug fix release is generated). To explain this we provide these examples:
Master is updated on 2018-04.07 with new code, next morning you will be able to download the release "master-20180408" (current tag name for that release is "mega").
Master is branched into an official stable release named "v2.0" on 2018-05-07, next morning you can download "v2.0-20180508".
v2.0 is bug fixed on 2018-05-23, next morning you can download "v2.0-20180524" which then supersede the older v2.0.0 version.
So how do you know which one is the latest?
That's where this wiki is here for (among many other things). We will list all the current states from v2.0.0 and onward. Releases named "master" should always be seen as not stable and only for users that wish to experiment with new releases and test stuff to help the development of future releases.
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 192.168.4.1
↓
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.
Tutorials
- Using the flashtool to upload the ESP Easy firmware
- Using the Arduino IDE to upload the ESP Easy firmware
- How to setup ESPEasy after flashing it.
- 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
Loading firmware
- New release candidates are on github: ESPEasy version 2.0 and higher
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.
- Old releases: ESPEasy R120 (will be replaced by v2.0.0!)
- Old release candidate: ESPEasy R147_RC8 (is now part of the dev build for v2.0.0)
2.0+ firmware on 1MB modules
- 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:
Tutorial_ESPEasy_Firmware_Upload
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.
Configuration
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
System variables Reference
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
Examples
Support and discussion
- Forum
- IRC: #espeasy @freenode
- Slack (for Wiki talk): ESP Easy Wiki
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
Hardware page
For older versions, the Hardware page has now moved to: ESP Easy web interface#Hardware page!
