automatically updated release notes for mega-20201022

Merge pull request #3329 from TD-er/bugfix/3317_PluginWrite
Don't call PLUGIN_WRITE on inactive tasks (#3317)
2026-07-28 04:07:47 +00:00 · 2020-10-22 16:46:23 +02:00 · 2020-10-21 22:16:59 +02:00 · 2020-10-21 16:22:25 +02:00 · 2020-10-21 13:51:28 +02:00 · 2020-10-21 11:52:03 +02:00
3484 changed files with 541823 additions and 186804 deletions
@@ -1,18 +1,68 @@
-**NOTE: This is not a support forum! For questions and support go here: https://www.letscontrolit.com/forum/viewforum.php?f=1**
+### Checklist
+- [ ] The title of this issue is "to the point" and descriptive.
+- [ ] This issue describes what is happening.
+- [ ] This issue describes what components are affected (e.g. name of plugin/controller)
+- [ ] This issue describes how to reproduce it.
+- [ ] This issue describes when it was introduced (when known) and what version is now showing the problem.

-### Steps to reproduce
-How can we trigger this problem?
+### I have...
+- [ ] searched the [issue tracker](https://github.com/letscontrolit/ESPEasy/issues) or the [forum](https://www.letscontrolit.com/forum/viewforum.php?f=1) for a similar issue. (include links when applicable)
+- [ ] entered a system description using "Copy info to clipboard" on the sysinfo page. (when possible)
+- [ ] entered the full filename of the used version (e.g. `ESP_Easy_mega-20181001_test_ESP8266_4096_VCC.bin` )
+- [ ] given a list of active plugins or controllers when applicable.
+- [ ] filled out all applicable fields below.

-Does the problem persists after powering off and on? (just resetting isn't enough sometimes)
+### Steps already tried...
+- [ ] Tried a clean install (empty `.bin` files are included in the ZIP)
+- [ ] Tested previous/other build (mention which one already tested)
+- [ ] Tested on other node to make sure hardware isn't defective.
+- [ ] Verified if the problem is limited to a single plugin/controller
+
+
+
+### If you self compile, please state this and PLEASE try to ONLY REPORT ISSUES WITH OFFICIAL BUILDS! ###
+<!--- If you self compile, please state this and PLEASE try to ONLY REPORT ISSUES WITH OFFICIAL BUILDS!  --->
+<!--- NOTE: This is not a support forum! For questions and support go here: --->
+<!--- https://www.letscontrolit.com/forum/viewforum.php?f=1 --->
+<!--- Remove topics that are not applicable to your feature request of issue --->
+<!--- Remember to have a "to the point" TITLE --->
+
+
+### Summarize of the problem/feature request
+<!--- Describe the problem or feature request --->
+YOUR TEXT GOES HERE

 ### Expected behavior
-Tell us what should happen?
+<!--- Tell us what should happen? --->
+YOUR TEXT GOES HERE

 ### Actual behavior
-Tell us what happens instead?
+<!--- Tell us what happens instead? --->
+YOUR TEXT GOES HERE

+### Steps to reproduce
+<!--- How can we trigger this problem? --->
+1. 
+2. 
+3. 
+
+<!--- Does the problem persists after powering off and on? (just resetting isn't enough sometimes) --->
+<!--- Please document if you have restarted the unit and if the problem is then gone etc. etc. --->
 ### System configuration
-
+<!--- Please add as much information and screenshots as possible  --->
 Hardware:

-Software or git version:
+<!--- You should also provide links to hardware pages etc where we can find more info  --->
+<!--- If you self compile, please state this and PLEASE try to ONLY REPORT ISSUES WITH OFFICIAL BUILDS!  --->
+ESP Easy version: 
+
+<!--- In order to have a better readablity of your issue then you should place screenshots here  --->
+<!--- Simply drag and drop them onto this template, move the text string below the "ESP Easy settings/screenshots" topic  --->
+ESP Easy settings/screenshots: 
+
+### Rules or log data
+<!--- place your code/rules between the two ``` rows  --->
+<!--- remove if not applicable!  --->
+```
+
+```
@@ -0,0 +1,17 @@
+# Number of days of inactivity before an issue becomes stale
+daysUntilStale: 60
+# Number of days of inactivity before a stale issue is closed
+daysUntilClose: 14
+# Issues with these labels will never be considered stale
+exemptLabels:
+  - pinned
+  - security
+# Label to use when marking an issue as stale
+staleLabel: stale
+# Comment to post when marking an issue as stale. Set to `false` to disable
+markComment: >
+  This issue has been automatically marked as stale because it has not had
+  recent activity. It will be closed if no further activity occurs. Thank you
+  for your contributions.
+# Comment to post when closing a stale issue. Set to `false` to disable
+closeComment: true
@@ -1,18 +1,50 @@
-## OS Specific Hidden Files ####
-
-# MacOSX Finder *****
-.DS_Store
-
-# Fuse FileSystem ***
-.fuse_hidden*
-
-
-## PlatformIO ##################
-.pioenvs
-.clang_complete
-.gcc-flags.json
-.piolibdeps
-
-## Project #####################
-lib/readme.txt
-src/Custom.h
+## OS Specific Hidden Files ####
+
+# MacOSX Finder *****
+.DS_Store
+
+# Fuse FileSystem ***
+.fuse_hidden*
+
+
+## PlatformIO ##################
+.pioenvs
+.clang_complete
+.gcc-flags.json
+.piolibdeps
+pre_extra_script.py
+*.code-workspace
+.pio
+
+## Project #####################
+lib/readme.txt
+src/Custom.h
+/ESPEasy
+test/output_export.cpp
+.vscode
+.vscode/.browse.c_cpp.db*
+.vscode/c_cpp_properties.json
+.vscode/launch.json
+src/ESPEasy.ino.cpp
+
+docs/build/
+
+\.pio/
+
+docs/source/_build/
+
+venv/
+
+.idea/
+
+tools/vagrant/.vagrant/
+
+tools/vagrant/build/
+
+tools/vagrant/Custom.h
+
+
+.buildcache/
+
+
+
@@ -0,0 +1,10 @@
+FROM gitpod/workspace-full
+                    
+USER gitpod
+
+# Install custom tools, runtime, etc. using apt-get
+# For example, the command below would install "bastet" - a command line tetris clone:
+#
+# RUN sudo apt-get -q update && #     sudo apt-get install -yq bastet && #     sudo rm -rf /var/lib/apt/lists/*
+#
+# More information: https://www.gitpod.io/docs/config-docker/
@@ -0,0 +1,13 @@
+tasks:
+  - before: pip install -U platformio && brew install uncrustify && pip3 install -r ./requirements.txt
+
+image:
+  file: .gitpod.Dockerfile
+
+vscode:
+  extensions:
+    - ms-vscode.cpptools@0.26.3:u3GsZ5PK12Ddr79vh4TWgQ==
+    - eamodio.gitlens@10.2.1:e0IYyp0efFqVsrZwsIe8CA==
+    - LaurentTreguier.uncrustify@2.18.0:/k8Osjj/XSuz09F+pEu7wg==
+    - Atishay-Jain.All-Autocomplete@0.0.23:fbZNfSpnd8XkAHGfAPS2rA==
+    - 2gua.rainbow-brackets@0.0.6:Tbu8dTz0i+/bgcKQTQ5b8g==
@@ -0,0 +1,3 @@
+{
+    "extensions.showRecommendationsOnlyOnDemand": true
+}
@@ -1,42 +1,90 @@
 language: python
 python:
-  - '2.7'
+  - '3.8'

-#we want a newer cppcheck, so use trusty
-dist: trusty
+dist: bionic

 sudo: false

-cache:
-  directories:
-  - "~/.platformio"
-  - "./.pioenvs"
-
-
+cache: false

 addons:
  apt:
    packages:
    - cppcheck
-
-
+    - binutils

 install:
-  - pip install -U platformio
+  - pip install -U platformio sphinx recommonmark sphinx_bootstrap_theme
+  - pip install -r requirements.txt
+  - platformio update
+  - cd patches; ./check_puya_patch; cd ..
+
+env:
+  - ENV=custom_ESP32_4M316k
+  - ENV=custom_ESP32_4M316k_ETH
+  #- ENV=custom_ESP8266_1M
+  - ENV=custom_ESP8266_4M1M
+  #- ENV=custom_ESP8266_4M2M
+  #- ENV=custom_ESP8266_4M2M_LittleFS
+  #- ENV=custom_alt_wifi_ESP8266_1M
+  - ENV=custom_alt_wifi_ESP8266_4M1M
+  #- ENV=custom_beta_ESP8266_1M
+  #- ENV=custom_beta_ESP8266_4M1M
+  - ENV=custom_sdk3_ESP8266_4M1M
+  - ENV=dev_ESP8266_4M1M
+  - ENV=hard_SONOFF_POW_4M1M
+  - ENV=hard_Shelly_1_2M256
+  - ENV=hard_Shelly_PLUG_S_2M256
+  - ENV=hard_Ventus_W266
+  - ENV=hard_LCtech_relay_x2_1M
+  - ENV=hard_other_POW_ESP8285_1M
+  - ENV=minimal_IRext_ESP8266_1M
+  - ENV=minimal_IRext_ESP8266_4M1M
+  - ENV=minimal_IRext_ESP8266_4M2M
+  #- ENV=minimal_core_242_ESP8266_1M_OTA
+  #- ENV=minimal_core_242_ESP8285_1M_OTA
+  - ENV=minimal_core_274_ESP8266_1M_OTA_Domoticz
+  - ENV=minimal_core_274_ESP8266_1M_OTA_FHEM_HA
+  - ENV=minimal_core_274_ESP8285_1M_OTA_Domoticz
+  - ENV=minimal_core_274_ESP8285_1M_OTA_FHEM_HA
+  #- ENV=minimal_core_274_sdk3_ESP8266_1M_OTA_Domoticz
+  #- ENV=minimal_core_274_sdk3_ESP8266_1M_OTA_FHEM_HA
+  #- ENV=minimal_core_274_sdk3_ESP8285_1M_OTA_Domoticz
+  #- ENV=minimal_core_274_sdk3_ESP8285_1M_OTA_FHEM_HA
+  #- ENV=normal_ESP8266_16M_LittleFS
+  - ENV=normal_ESP8266_1M
+  - ENV=normal_ESP8266_1M_VCC
+  - ENV=normal_ESP8266_4M1M
+  - ENV=normal_ESP8266_4M1M_VCC
+  - ENV=normal_ESP8285_1M
+  - ENV=normal_IRext_no_rx_ESP8266_4M2M
+  - ENV=normal_WROOM02_2M256
+  - ENV=normal_WROOM02_2M
+  - ENV=normal_alt_wifi_ESP8266_1M
+  - ENV=normal_alt_wifi_ESP8266_1M_VCC
+  - ENV=normal_alt_wifi_ESP8266_4M1M
+  #- ENV=normal_sdk3_ESP8266_1M
+  #- ENV=spec_debug_beta_custom_ESP8266_4M1M
+  #- ENV=spec_debug_custom_ESP32_4M316k
+  #- ENV=spec_debug_custom_ESP8266_4M1M
+  #- ENV=spec_memanalyze_ESP8266
+  - ENV=test_ESP32-wrover-kit_4M316k
+  - ENV=test_ESP32-wrover-kit_4M316k_ETH
+  - ENV=test_ESP32_4M316k
+  - ENV=test_ESP32_4M316k_ETH
+  - ENV=test_ESP32_lolin-d32-pro
+  - ENV=test_ESP8266_4M1M_VCC
+  #- ENV=test_ESP8266_4M1M_VCC_MDNS_SD
+  - ENV=test_alt_wifi_ESP8266_4M1M_VCC
+  #- ENV=test_beta_ESP8266_16M_LittleFS
+  - ENV=test_beta_ESP8266_4M1M

 script:
-  # - cppcheck --enable=warning src/*.ino -q --force -I src --include=src/ESPEasy.ino --error-exitcode=1
-  # - ./memanalyzer.py ~/.platformio/packages/toolchain-xtensa/bin/xtensa-lx106-elf-objdump
-  - PLATFORMIO_BUILD_FLAGS="-D CONTINUOUS_INTEGRATION" platformio run 
-
-  # patch platformio core libs for PUYA bug (https://github.com/letscontrolit/ESPEasy/issues/650)
-  - cd patches; ./check_puya_patch; cd ..
-  - PLATFORMIO_BUILD_FLAGS="-D CONTINUOUS_INTEGRATION" platformio run -s --environment dev_ESP8266PUYA_1024
-
+  - PLATFORMIO_BUILD_FLAGS="-D CONTINUOUS_INTEGRATION" platformio run -e $ENV

 before_deploy:
  - ./before_deploy
-  - export RELEASE_FILE=$(ls ESPEasy*.zip)

 deploy:
  provider: releases
@@ -44,7 +92,7 @@ deploy:
  api_key:
    secure: bZeuKI7evXeZYmGayfcvIC1fThBGcksAyOrCbZ8kAGeTbHGJqFLBBy8to5UpNBSZVfeDWo25Iqy8Pfbyb7p2c1hg6fG9jS0UzQkLnoUNMxpUM1dJACkZxvFdP4Br3Y3vUPWtrWUbo8rN/b3E6tjSNLE7vQiwsarj+eWTO2V6BGcsN0eHc04/UCM2+DcHvJ4y7Ec36yIUaClNAWMal1osBYaViruylOdBKT/WDs1ZMoJMceXCfxMQ/8J2moYvymKfSkXSmoMGmzlTuq8v5N4AweutjpC4Zba2BbxIJv+PwWjhfIgTviHFggSU90UPTKVWYv13vms92VVKz1CDVrUQNn+YQes9+ROPUnrMc9bJ+q7E1lWJRZeDMqGECB+8BjUtUk6H81K+XhOnW1mtZiMnvMCwkmE0OT1eBObGMcpR962/DUBoQDmulMs2IieB0dLobmUBhpc1syrKEPKxjY7yhhQMr6In82jODVLR3qDkNQ8xtIfevzCo/ocUjiOrXW4b/pDMy28Yh109DMb/KSWEsjjkkpXhsT1YVy2MwOa7FRhHFW+SNKX4Us8T75H+pO4mQ4afnPEtjYKodj7XD92zqNxKfMx3elEx5RK6HKekHjpXdYtuXzGONB9StA+2T43/2llt3n5fzv4BRfCumBEJ77/ufB0U/uhsCe6lVwJf34U=
  file_glob: true
-  file: "${RELEASE_FILE}"
+  file: ESPEasy*.zip

  skip_cleanup: true
  on:
@@ -0,0 +1,8 @@
+The scripts in this directory are so called GIT hooks.
+Purpose is to do automatic changes after merge, commit and checkout.
+
+Those files are for a Linux-like environment with basic tools ln, grep, sed and bash.
+
+Windows users can see them as template.
+
+To use them simply copy those files into your ESPEasy/.git/hooks directory.
@@ -1,13 +1,17 @@
+|Latest Nightly  | Build Status | Downloads | Docs | Patreon | Ko-Fi | PayPal |
+|-------|-------|-------|-------|-------|-------|-------|
+| [![GitHub version](https://img.shields.io/github/release/letscontrolit/ESPEasy/all.svg)](https://github.com/letscontrolit/ESPEasy/releases/latest) | [![Build Status](https://travis-ci.org/letscontrolit/ESPEasy.svg?branch=mega)](https://travis-ci.org/letscontrolit/ESPEasy) | [![Downloads](https://img.shields.io/github/downloads/letscontrolit/ESPEasy/total.svg)](https://github.com/letscontrolit/ESPEasy/releases) | [![Documentation Status](https://readthedocs.org/projects/espeasy/badge/?version=latest)](https://espeasy.readthedocs.io/en/latest/?badge=latest) | [![donate](https://img.shields.io/badge/donate-Patreon-blue.svg)](https://www.patreon.com/GrovkillenTDer) | [![donate](https://img.shields.io/badge/donate-KoFi-blue.svg)](https://ko-fi.com/grovkillentder) | [![donate](https://img.shields.io/badge/donate-PayPal-blue.svg)](https://www.paypal.me/espeasy) |
+
+For ways to *support* us, see [this announcement on the forum](https://www.letscontrolit.com/forum/viewtopic.php?f=14&t=5787), or have a look at the [Patreon](https://www.patreon.com/GrovkillenTDer), [Ko-Fi](https://ko-fi.com/grovkillentder) or [PayPal](https://www.paypal.me/espeasy) links above.
+
 # ESPEasy (development branch)

-Build status: [![Build Status](https://travis-ci.org/letscontrolit/ESPEasy.svg?branch=mega)](https://travis-ci.org/letscontrolit/ESPEasy)

 Introduction and wiki: https://www.letscontrolit.com/wiki/index.php/ESPEasy#Introduction

 **MEGA**
 :warning:This is the development branch of ESPEasy. All new untested features go into this branch. If you want to do a bugfix, do it on the stable branch, we will merge the fix to the development branch as well.:warning:

-Next stable branch: https://github.com/letscontrolit/ESPEasy/tree/v2.0  (bug fixes only, since oct 2017))

 Check here to learn how to use this branch and help us improving ESPEasy: http://www.letscontrolit.com/wiki/index.php/ESPEasy#Source_code_development

@@ -16,24 +20,31 @@ Check here to learn how to use this branch and help us improving ESPEasy: http:/

 Every night our build-bot will build a new binary release: https://github.com/letscontrolit/ESPEasy/releases

-The releases are named something like 'mega-20180102' (last number is the build date)
+The releases are named something like 'mega-20190225' (last number is the build date)

 Depending on your needs, we release different types of files:

 Firmware name                                 | Hardware                | Included plugins            |
 ----------------------------------------------|-------------------------|-----------------------------|
-ESPEasy_mega-20180102_normal_ESP8266_1024.bin  | ESP8266 with 1Mb flash  | Stable                      |
-ESPEasy_mega-20180102_test_ESP8266_1024.bin    | ESP8266 with 1Mb flash  | Stable + Test               |
-ESPEasy_mega-20180102_dev_ESP8266_1024.bin     | ESP8266 with 1Mb flash  | Stable + Test + Development |
-ESPEasy_mega-20180102_normal_ESP8266_4096.bin  | ESP8266 with 4Mb flash  | Stable                      |
-ESPEasy_mega-20180102_test_ESP8266_4096.bin    | ESP8266 with 4Mb flash  | Stable + Test               |
-ESPEasy_mega-20180102_dev_ESP8266_4096.bin     | ESP8266 with 4Mb flash  | Stable + Test + Development |
-ESPEasy_mega-20180102_normal_ESP8285_1024.bin  | ESP8285 with 1Mb flash  | Stable                      |
-ESPEasy_mega-20180102_test_ESP8285_1024.bin    | ESP8285 with 1Mb flash  | Stable + Test               |
-ESPEasy_mega-20180102_dev_ESP8285_1024.bin     | ESP8285 with 1Mb flash  | Stable + Test + Development |
+ESPEasy_mega-20190225_normal_ESP8266_1M.bin  | ESP8266 with 1MB flash  | Stable                      |
+ESPEasy_mega-20190225_test_ESP8266_1M.bin    | ESP8266 with 1MB flash  | Stable + Test               |
+ESPEasy_mega-20190225_dev_ESP8266_1M.bin     | ESP8266 with 1MB flash  | Stable + Test + Development |
+ESPEasy_mega-20190225_normal_ESP8266_4M.bin  | ESP8266 with 4MB flash  | Stable                      |
+ESPEasy_mega-20190225_test_ESP8266_4M.bin    | ESP8266 with 4MB flash  | Stable + Test               |
+ESPEasy_mega-20190225_dev_ESP8266_4M.bin     | ESP8266 with 4MB flash  | Stable + Test + Development |
+ESPEasy_mega-20190225_normal_ESP8285_1M.bin  | ESP8285 with 1MB flash  | Stable                      |
+ESPEasy_mega-20190225_test_ESP8285_1M.bin    | ESP8285 with 1MB flash  | Stable + Test               |
+ESPEasy_mega-20190225_dev_ESP8285_1M.bin     | ESP8285 with 1MB flash  | Stable + Test + Development |

-## More info
+## Documentation & more info

-Details and discussion are on the Experimental forum: https://www.letscontrolit.com/forum/viewforum.php?f=18
+Our new, in-depth documentation can be found at [ESPEasy.readthedocs.io](https://espeasy.readthedocs.io/en/latest/). Automatically built, so always up-to-date according to the contributed contents. The old Wiki documention can be found at [letscontrolit.com/wiki](https://www.letscontrolit.com/wiki/index.php?title=ESPEasy).

-We're also on IRC: #ESPEasy @freenode
+Additional details and discussion are on the "Experimental" section of the forum: https://www.letscontrolit.com/forum/viewforum.php?f=18
+
+[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/letscontrolit/ESPEasy) 
+
+
+## Icons used
+
+Icons on courtesy of [ICONS8](https://icons8.com/).
@@ -1,42 +1,88 @@
 #!/bin/bash

 VERSION=$(git describe)
+TMP_DIST=`mktemp -d`
+CURPATH=`pwd`
+BUILD_LOG=`echo "${TMP_DIST}/buildlog.txt"`
+
+# PIO 3.x :
+# BINARY_PATH=".pioenvs"
+
+# PIO 4.0 and newer:
+BINARY_PATH=".pio/build"
+
+while getopts d: option
+do
+case "${option}"
+in
+d) VERSION=${OPTARG};;
+esac
+done
+
+
+if [ ! -d ${TMP_DIST} ]; then
+  # Could not create temp dir, so exit
+  exit 1
+fi
+
+echo "### Creating zip archives"

 #Naming convention:
 # ESP_Easy_[github version]_[plugin set]_[chip type]_[flash memory].bin

+if [ -d "build_output/reject" ]; then
+  zip -qq ${CURPATH}/ESPEasy_ELF_files_$VERSION.zip build_output/reject/*
+fi

-for ENV in \
-  normal_ESP8266_1024 \
-  normal_ESP8266_4096 \
-  normal_ESP8285_1024 \
-  test_ESP8266_1024\
-  test_ESP8266_4096\
-  test_ESP8266_4096_VCC\
-  test_ESP8285_1024\
-  dev_ESP8266_1024\
-  dev_ESP8266_4096\
-  dev_ESP8285_1024\
-  dev_ESP8266PUYA_1024\
-  dev_ESP8266PUYA_1024_VCC;\
-do
-  echo
-  echo "### Deploying environment $ENV for version $VERSION"
-  BIN=.pioenvs/$ENV/firmware.bin
-  python2 crc2.py $BIN
-  cp $BIN dist/"ESP_Easy_$VERSION""_$ENV.bin"
-done
+zip -qq ${CURPATH}/ESPEasy_ELF_files_$VERSION.zip build_output/debug/*
+echo "### Created ESPEasy_ELF_files_$VERSION.zip"


+mkdir -p ${TMP_DIST}
+cp -r dist/* ${TMP_DIST}/
+
+if [ -d "docs/build" ]; then
+  # Docs have been created
+  zip -r -qq ${CURPATH}/ESPEasy_docs_$VERSION.zip docs/build/*
+  echo "### Created ESPEasy_docs_$VERSION.zip"
+fi
+
 #create a source structure that is the same as the original ESPEasy project (and works with the howto on the wiki)
-rm -rf dist/Source 2>/dev/null
-mkdir dist/Source
-cp -r lib dist/Source/
-cp -r src dist/Source/
-cp platformio.ini dist/Source/
+#rm -rf dist/Source 2>/dev/null

-cd dist
+mkdir -p ${TMP_DIST}/source
+cp -r lib ${TMP_DIST}/source/
+cp -r src ${TMP_DIST}/source/
+cp -r misc ${TMP_DIST}/source/
+cp -r static ${TMP_DIST}/source/
+cp -r tools ${TMP_DIST}/source/
+cp platformio*.ini ${TMP_DIST}/source/
+cp *.txt ${TMP_DIST}/source/
+cp *.csv ${TMP_DIST}/source/
+cp README* ${TMP_DIST}/source/

-echo
-echo "### Creating zip archive"
-zip ../ESPEasy_$VERSION.zip -r .
+cp -r build_output/bin/* ${TMP_DIST}/bin
+rm -f ${TMP_DIST}/bin/*ESP32*
+
+cd ${TMP_DIST}
+
+if [ "$(ls -A ${TMP_DIST}/bin/)"  ]; then
+  echo
+  zip -qq ${CURPATH}/ESPEasy_ESP82xx_$VERSION.zip -r .
+  echo "### Created ESPEasy_ESP82xx_$VERSION.zip"
+fi
+
+cd ${CURPATH}
+rm -f ${TMP_DIST}/bin/*
+cp -r build_output/bin/*ESP32* ${TMP_DIST}/bin
+
+cd ${TMP_DIST}
+
+if [ "$(ls -A ${TMP_DIST}/bin/)"  ]; then
+  echo
+  zip -qq ${CURPATH}/ESPEasy_ESP32_$VERSION.zip -r .
+  echo "### Created ESPEasy_ESP32_$VERSION.zip"
+fi
+
+rm -Rf ${TMP_DIST}/* 2>/dev/null
+rmdir ${TMP_DIST}
@@ -1,14 +1,14 @@
-
+
 import sys
 import binascii
 import struct
-import md5
+from hashlib import md5
 import os
 MD5DUMMY      = "MD5_MD5_MD5_MD5_BoundariesOfTheSegmentsGoHere..." #48 chars
-FILENAMEDUMMY = "ThisIsTheDummyPlaceHolderForTheBinaryFilename..." #48 chars
+FILENAMEDUMMY = "ThisIsTheDummyPlaceHolderForTheBinaryFilename64ByteLongFilenames" #64 chars

 MemorySegmentStart,MemorySegmentEnd,MemoryContent=[],[],[]
- 
+
 ##################################################################
 # this subroutine shows the segments of a  part
 ##################################################################
@@ -18,7 +18,7 @@ def showSegments (fileContent,offset):
    herestr =""
    herestr2 =""
    MemorySegmentStart.append(struct.pack("I",header[0]))
-    MemorySegmentEnd.append(struct.pack("I",header[0]+header[1])) 
+    MemorySegmentEnd.append(struct.pack("I",header[0]+header[1]))
    MemoryContent.append(fileContent[offset+8:offset+8+header[1]])
    if  fileContent.find( MD5DUMMY, offset+8, offset+8+header[1]) >0 :
        herestr= " <-- CRC is here."
@@ -42,23 +42,32 @@ def showParts(fileContent, offset):
    return nextSegmentOffset

 ##################################################################
-# MAIN 
+# MAIN
 ##################################################################

 #if len(sys.argv) !=2 :
 #    print ("please give a filename")
 #    k=input("press close to exit")
 #    sys.exit(1)
-FileName = sys.argv[1]#"C:/ArduinoPortable/sketchbooks/build/sketch_jan15a.ino.bin"
+FileName = sys.argv[1]
 #FileName =  "C:/ArduinoPortable/sketchbooks/build/sketch_jan15a.ino.bin"
 print( "\n\nReplacing dummy MD5 checksum in .bin file")

-
-
 with open(FileName, mode='rb') as file: # b is important -> binary
-    nextpos =0;
    fileContent = file.read()
-    while nextpos >=0:
+
+firmware_esp8266 = fileContent.find("ID_EASY_ESP8266") >= 0
+firmware_esp32   = fileContent.find("ID_EASY_ESP32") >= 0
+
+if firmware_esp8266:
+  print("ESP8266 build")
+if firmware_esp32:
+  print("ESP32 build")
+
+# TODO: showParts does not work for esp32
+if firmware_esp8266:
+  nextpos =0;
+  while nextpos >=0:
        nextpos = showParts(fileContent,nextpos)

 startArray,endArray,hashString = "","",""
@@ -70,47 +79,48 @@ includeStr = "hash includes segments:"
 # 3: RAM (initialized by bin file. Can be read but changes as you go :-( )
 # 4: RAM

-for i in (1,2 ):     # use only stable segments, must be 4 in total. We use 2.
-    startArray =startArray + MemorySegmentStart[i] 
-    endArray =  endArray   + MemorySegmentEnd[i] 
+if firmware_esp8266:
+  for i in (1,2 ):     # use only stable segments, must be 4 in total. We use 2.
+    startArray =startArray + MemorySegmentStart[i]
+    endArray =  endArray   + MemorySegmentEnd[i]
    hashString =hashString + MemoryContent[i]
    with open(FileName+str(i), mode='wb') as file: # b is important -> binary
      file.write(MemoryContent[i])
    includeStr = includeStr +" "+ str(i)
-print (includeStr)
-# IMPORTANT: pad array with zeros if you use only 3 segments (see above)    
-while len(startArray) < 16 : 
-	startArray =startArray + struct.pack("I",0) 
-	endArray =  endArray   + struct.pack("I",0) 
-# debug print (binascii.hexlify(startArray)) 
-# debug print (binascii.hexlify(endArray))
-if (len(endArray) + len (startArray)) != 32 :
-    print("ERROR: please make sure you add / remove padding if you change the semgents.") 
+  print (includeStr)
+  
+  # IMPORTANT: pad array with zeros if you use only 3 segments (see above)
+  while len(startArray) < 16 :
+    startArray =startArray + struct.pack("I",0)
+    endArray =  endArray   + struct.pack("I",0)
+  # debug print (binascii.hexlify(startArray))
+  # debug print (binascii.hexlify(endArray))
+  if (len(endArray) + len (startArray)) != 32 :
+    print("ERROR: please make sure you add / remove padding if you change the semgents.")

-BinaryFileName = "";
 if  fileContent.find( FILENAMEDUMMY) < 0:
    print("ERROR: FILENAMEDUMMY dummy not found in binary")
 else:
-	BinaryFileName=os.path.basename(FileName) +"\0"
-	if len(BinaryFileName) >48:								# check that filename is <48 chars
-		BinaryFileName=BinaryFileName[0:48]					# truncate if necessary. 49th char in ESP is zero already
-	else:
-		BinaryFileName= BinaryFileName.ljust(48,'\0');		# pad with zeros. 	
-			
-
-if  fileContent.find( MD5DUMMY) < 0:
-    print("ERROR: MD5 dummy not found in binary")
-else:
-    hashString=hashString.replace (MD5DUMMY,"",1) 
-    m = md5.new()
-    m.update (hashString) #use segment 1
-    md5hash = m.digest()
-    print("MD5 hash: "+ m.hexdigest())
-    print("\nwriting output file:\n" + FileName)
-	
-    fileContent=fileContent.replace(MD5DUMMY,md5hash+startArray+endArray)
+    BinaryFileName=os.path.basename(FileName) +"\0"
+    if len(BinaryFileName) >64:								# check that filename is <48 chars
+        BinaryFileName=BinaryFileName[0:64]					# truncate if necessary. 49th char in ESP is zero already
+    else:
+        BinaryFileName= BinaryFileName.ljust(64,'\0');		# pad with zeros.
+    
    fileContent=fileContent.replace(FILENAMEDUMMY,BinaryFileName)

-    with open(FileName, mode='wb') as file: # b is important -> binary
-      file.write(fileContent)
-#k=input("press close to exit") 
+if firmware_esp8266:
+  if  fileContent.find( MD5DUMMY) < 0:
+    print("ERROR: MD5 dummy not found in binary")
+  else:
+    hashString=hashString.replace (MD5DUMMY,"",1)
+    m = md5(hashString) #use segment 1
+    md5hash = m.digest()
+    print("MD5 hash: "+ m.hexdigest())
+    fileContent=fileContent.replace(MD5DUMMY,md5hash+startArray+endArray)
+
+print("\nwriting output file:\n" + FileName)
+with open(FileName, mode='wb') as file: # b is important -> binary
+  file.write(fileContent)
+
+#k=input("press close to exit")
@@ -1,63 +0,0 @@
-plugin                        |cache IRAM |init RAM   |r.o. RAM   |uninit RAM |Flash ROM
-src/_C001.ino                 |0          |0          |272        |0          |3520
-src/_C002.ino                 |0          |4          |528        |32         |6064
-src/_C003.ino                 |0          |0          |64         |0          |1072
-src/_C004.ino                 |0          |0          |56         |8          |1280
-src/_C005.ino                 |0          |4          |56         |8          |1424
-src/_C006.ino                 |0          |0          |64         |0          |1296
-src/_C007.ino                 |0          |4          |32         |0          |1664
-src/_C008.ino                 |0          |0          |80         |0          |2272
-src/_C009.ino                 |0          |4          |352        |16         |4896
-src/_C010.ino                 |0          |0          |48         |0          |1136
-src/_C011.ino                 |0          |0          |152        |8          |5248
-src/_N001_Email.ino           |0          |0          |72         |8          |1808
-src/_N002_Buzzer.ino          |288        |12         |8          |264        |1184
-src/_P001_Switch.ino          |1028       |8          |104        |280        |7248
-src/_P002_ADC.ino             |0          |0          |16         |0          |336
-src/_P003_Pulse.ino           |167        |0          |144        |192        |2544
-src/_P004_Dallas.ino          |0          |0          |64         |16         |2496
-src/_P005_DHT.ino             |0          |0          |56         |8          |1520
-src/_P006_BMP085.ino          |0          |4          |48         |8          |2112
-src/_P007_PCF8591.ino         |0          |0          |8          |8          |400
-src/_P008_RFID.ino            |101        |0          |56         |8          |624
-src/_P009_MCP.ino             |0          |0          |104        |24         |3232
-src/_P010_BH1750.ino          |0          |0          |56         |8          |2688
-src/_P011_PME.ino             |0          |4          |96         |0          |3040
-src/_P012_LCD.ino             |0          |4          |120        |8          |3520
-src/_P013_HCSR04.ino          |90         |0          |64         |16         |1552
-src/_P014_SI7021.ino          |0          |4          |48         |0          |1824
-src/_P015_TSL2561.ino         |0          |0          |56         |8          |3488
-src/_P016_IR.ino              |288        |0          |72         |480        |3600
-src/_P017_PN532.ino           |0          |0          |88         |72         |2016
-src/_P018_Dust.ino            |0          |0          |56         |8          |512
-src/_P019_PCF8574.ino         |0          |0          |104        |24         |2848
-src/_P020_Ser2Net.ino         |0          |0          |88         |40         |3456
-src/_P021_Level.ino           |0          |4          |136        |24         |1872
-src/_P022_PCA9685.ino         |0          |4          |32         |0          |1216
-src/_P023_OLED.ino            |0          |4          |80         |0          |4448
-src/_P024_MLX90614.ino        |0          |4          |56         |8          |992
-src/_P025_ADS1115.ino         |0          |0          |72         |8          |1184
-src/_P026_Sysinfo.ino         |0          |0          |72         |8          |864
-src/_P027_INA219.ino          |0          |0          |56         |24         |1840
-src/_P028_BME280.ino          |128        |0          |48         |80         |3488
-src/_P029_Output.ino          |0          |4          |8          |8          |256
-src/_P030_BMP280.ino          |128        |0          |48         |48         |3024
-src/_P031_SHT1X.ino           |0          |0          |100        |0          |2176
-src/_P032_MS5611.ino          |0          |4          |88         |56         |2592
-src/_P033_Dummy.ino           |0          |4          |48         |0          |1168
-src/_P034_DHT12.ino           |0          |0          |16         |0          |656
-src/_P035_IRTX.ino            |0          |4          |64         |-8         |3840
-src/_P036_FrameOLED.ino       |0          |4          |96         |0          |33600
-src/_P037_MQTTImport.ino      |0          |0          |24         |40         |3536
-src/_P038_NeoPixel.ino        |128        |0          |56         |8          |1712
-src/_P039_Thermocouple.ino    |0          |0          |104        |8          |1536
-src/_P040_ID12.ino            |0          |4          |72         |8          |640
-src/_P041_NeoClock.ino        |128        |4          |128        |0          |3344
-src/_P042_Candle.ino          |128        |8          |160        |32         |8048
-src/_P043_ClkOutput.ino       |0          |0          |80         |0          |1456
-src/_P044_P1WifiGateway.ino   |0          |0          |80         |64         |4032
-src/_P045_MPU6050.ino         |0          |4          |216        |72         |4496
-src/_P046_VentusW266.ino      |325        |4          |184        |88         |3920
-src/_P047_i2c-soil-moisture-so|0          |4          |216        |8          |2144
-src/_P048_Motorshield_v2.ino  |0          |32         |208        |0          |5952
-src/_P049_MHZ19.ino           |380        |80         |184        |88         |3792
@@ -0,0 +1,105 @@
+  _____ ____  ____
+ | ____/ ___||  _ \ ___  __ _ ___ _   _
+ |  _| \___ \| |_) / _ \/ _` / __| | | |
+ | |___ ___) |  __/  __/ (_| \__ \ |_| |
+ |_____|____/|_|   \___|\__,_|___/\__, |
+                                  |___/
+
+
+This is the distribution folder for ESPeasy.
+In here you will find a flash tool to program the ESP module.
+
+Also a number of binary images is included.
+
+The filename is quite descriptive:
+  ESP_Easy_mega-<date>_<buildType>_<chip>_<memorySize>.bin
+
+Build type can be:  (differ in included plugins)
+- normal  => Only Stable plugins and controllers
+- test    => Stable + Testing
+- dev     => Stable + Testing + Development
+
+There is also a number of special builds:
+- normal_IR => "Normal" + IR receiver/transmitter plugins and library
+- hard_xxxxx => Special builds for some off-the-shelf hardware.
+- minimal_ESP82xx_1M_OTA => Minimum number of plugins and a limited set of controllers included to be able to perform a 2-step OTA on 1 MB flash nodes.
+- normal_core_xxx => "Normal" using core xxx (e.g. 2.4.1)
+- normal_beta => "Normal" using the staged (beta) branch of the esp8266/Arduino repository.
+
+Chip can be:
+- ESP8266      => Most likely option
+- ESP8285      => Used in some Sonoff modules
+- ESP32        => Experimental support at this moment
+
+MemorySize can be:
+- 1M  => 1 MB flash modules (e.g. almost all Sonoff modules)
+- 2M  => 2 MB flash modules (e.g. Shelly1/WROOM02)
+- 4M  => 4 MB flash modules (e.g. NodeMCU/ESP32)
+- 16M => 16 MB flash modules (e.g. Wemos D1 mini pro)
+
+Please note that the performance of 14MB SPIFFS (16M flash modules) is really slow.
+All file access takes a lot longer and since the settings are also read from flash, the entire node will perform slower.
+See [Arduino issue - SPIFFS file access slow on 16/14M flash config](https://github.com/esp8266/Arduino/issues/5932)
+
+If these speed issues will be fixed, it is very likely the SPIFFS must then be re-partitioned, thus loosing all data in the SPIFFS.
+
+Special memory partitioning:
+- 2M256  => 2 MB flash modules (e.g. Shelly1/WROOM02) with 256k SPIFFS (only core 2.5.0 or newer)
+- 4M316k => For ESP32 with 4MB flash, sketch size is set to 1.8 MByte (default: 1.4 MByte)
+- 4M1M   => 4MB flash, 1 MB SPIFFS. Default layout for 4MB flash.
+- 4M2M   => 4MB flash, 2 MB SPIFFS. Introduced in October 2019. Only possible with core 2.5.2 or newer.
+
+Difference between .bin and .bin.gz
+Starting on esp8266/Arduino core 2.7.0, it is possible to flash images that have been compressed using GZip.
+Please note that this only can be used on installs already running a very recent build.
+This also means we still need to update the 2-step updater to support .bin.gz files.
+
+
+ESP32 now has 3 builds:
+- custom_ESP32_4M316k  Build template using either the plugin set defined in ``Custom.h`` or ``tools/pio/pre_custom_esp32.py``
+- test_ESP32_4M316k  Build using the "testing" set of plugins for ESP32
+- test_ESP32-wrover-kit_4M316k  A build for ESP32 including build flags for the official WRover test kit.
+
+
+Since ESP32 does have its flash partitioned in several blocks, we have 2 bin files of each ESP32 build:
+- test_ESP32_4M316k.bin
+- test_ESP32_4M316k-factory.bin
+
+The binary with "-factory" in the name must be flashed on a new node, via the serial interface of the board.
+This flash must be started at address 0.
+
+The binary without "-factory" can be used for OTA updates. (OTA for ESP32 is added in May 2020)
+
+
+Please note that changing between those versions will destroy the settings!
+The SPIFFS partition will be lost and that contains all settings.
+
+
+To help recover from a bad flash, there are also blank images included.
+- blank_1MB.bin
+- blank_2MB.bin
+- blank_4MB.bin
+- blank_16MB.bin
+
+When the wrong image is flashed, or the module behaves unstable, or is in a reboot loop,
+flash these images first and then the right image for the module.
+
+ESP.Easy.Flasher.exe...
+... is the new flashing tool for ESP Easy. You need to run it in elevated mode (as admin)
+for it to fetch the COM ports correctly. If you want you may save YOUR settings using the
+"Save as default settings" button in the lower left corner. If the window is too big or
+too small you can experiment with the "Pixels Per Inch" variable in the
+..\Settings\Default.ini file. Setting it to =96 is working for most users but the
+application will try to find the most optimal value by default. Sometimes it fails to
+do that. More information about the tool is found here:
+https://github.com/Grovkillen/ESP_Easy_Flasher
+You can also have custom serial commands entered in a txt file. One command per line.
+
+
+For flashing ESP32 you need Espressif's own Flash Download Tools.
+The latest version can be downloaded from: https://www.espressif.com/en/support/download/other-tools
+
+
+Further reading:
+For more information, see: https://github.com/letscontrolit/ESPEasy
+Or our forum: https://www.letscontrolit.com/forum/
@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -0,0 +1,34 @@
+{"ESP_Easy_info":[
+ {
+   "MessageTitle":"Please support us",
+   "MessageBody":"We are in need for support. Currently we need to do a whole lot of consulting to keep us floating. If we could get funding for at least 50% of our time we could make a lot more than with our current 10-15%. Ideal would be 100% funding but we're realistic :) <br><br>We will add extra goodies for those who support us through monthly payments using Patreon.<br><br><br>Thanks for your support (from TD-er and Grovkillen)!",
+   "MessagePicture":"",
+   "MessageWriter":"Grovkillen",
+   "MessageColorBG":"",
+   "MessageColorFont":"",
+   "MessageDate":"2019-01-07",
+   "MessageType":"general",
+   "MessageLink1text":"Patreon",
+   "MessageLink1":"",
+   "MessageLink2text":"Ko-Fi",
+   "MessageLink2":"",
+   "MessageLink3text":"Paypal",
+   "MessageLink3":""
+ },{
+   "MessageTitle":"First announcement test",
+   "MessageBody":"We're planning on using the ESP Easy Flasher to push announcements to the users. Hopefully this will work out good and make more people aware of how things are evolving. This will be used as a channel for pretty much anything regarding the prject. Thanks for your support!",
+   "MessagePicture":"",
+   "MessageWriter":"Grovkillen",
+   "MessageColorBG":"",
+   "MessageColorFont":"",
+   "MessageDate":"2019-01-06",
+   "MessageType":"mega",
+   "MessageLink1text":"",
+   "MessageLink1":"",
+   "MessageLink2text":"",
+   "MessageLink2":"",
+   "MessageLink3text":"",
+   "MessageLink3":""
+ }
+]
+}
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd
@@ -0,0 +1,11 @@
+recommonmark==0.6.0
+Sphinx==3.1.2
+sphinx-autobuild==0.7.1
+sphinx-bootstrap-theme==0.7.1
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==1.0.3
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.4
+sphinxcontrib-websupport==1.2.3
@@ -0,0 +1,22 @@
+These scripts are used to render screenshots of the GUI.
+We use phantomJS (available on Win/Mac/Linux http://phantomjs.org/quick-start.html)
+and you control the script by passing arguments to the JavaScript files:
+
+########## rasterize.js ##########
+argument1: url (ampersand & need to be closed with "&")
+argument2: output file name (you can use .png or .pdf as output format)
+argument3: horisontalXvertical size (OPTIONAL)
+argument4: zoom ("entire page" or "window" or <value> OPTIONAL)
+....Example CLI....
+
+phantomjs rasterize.js http://95.143.204.227/devices?index=1"&"page=1 P001_Setup_Switch_1.png
+
+or
+
+phantomjs rasterize.js http://95.143.204.227/devices?index=1"&"page=1 P001_Setup_Switch_1.png 1200px 2
+
+WE USE THE SECOND EXAMPLE by default (you might need to change zoomFactor if the page is too big).
+
+If the rendering is not working you can use this CLI (arg --debug=true):
+
+phantomjs --debug=true rasterize.js http://95.143.204.227/devices?index=1"&"page=1 P001_Setup_Switch_1.png 1200px 2
@@ -0,0 +1,52 @@
+//removed use strict GROVKILLEN
+var page = require('webpage').create(),
+    system = require('system'),
+    address, output, size;
+
+if (system.args.length < 3 || system.args.length > 5) {
+    console.log('Usage: rasterize.js URL filename [paperwidth*paperheight|paperformat] [zoom]');
+    console.log('  image (png/jpg output) examples: "1920px" entire page, window width 1920px');
+    console.log('                                   "800px*600px" window, clipped to 800x600');
+    phantom.exit(1);
+} else {
+    address = system.args[1];
+    output = system.args[2];
+    page.viewportSize = { width: 600, height: 600 };
+    if (system.args.length > 3 && system.args[2].substr(-4) === ".pdf") {
+        size = system.args[3].split('*');
+        page.paperSize = size.length === 2 ? { width: size[0], height: size[1], margin: '0px' }
+                                           : { format: system.args[3], orientation: 'portrait', margin: '1cm' };
+    } else if (system.args.length > 3 && system.args[3].substr(-2) === "px") {
+        size = system.args[3].split('*');
+        if (size.length === 2) {
+            pageWidth = parseInt(size[0], 10);
+            pageHeight = parseInt(size[1], 10);
+            page.viewportSize = { width: pageWidth, height: pageHeight };
+            page.clipRect = { top: 0, left: 0, width: pageWidth, height: pageHeight };
+        } else {
+            console.log("size:", system.args[3]);
+            pageWidth = parseInt(system.args[3], 10);
+            pageHeight = parseInt(pageWidth * 3/4, 10); // it's as good an assumption as any
+            console.log ("pageHeight:",pageHeight);
+            page.viewportSize = { width: pageWidth, height: pageHeight };
+        }
+    }
+    if (system.args.length > 4) {
+        page.zoomFactor = system.args[4];
+    }
+    page.open(address, function (status) {
+        if (status !== 'success') {
+            console.log('Unable to load the address!');
+            phantom.exit(1);
+        } else {
+            window.setTimeout(function () {
+                //This is injected because of bug in phantomjs (rendering black background: http://phantomjs.org/tips-and-tricks.html) GROVKILLEN
+                page.evaluate(function() {
+                  document.body.bgColor = 'white';
+                });
+                page.render(output);
+                phantom.exit();
+            }, 200);
+        }
+    });
+}
@@ -0,0 +1,235 @@
+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.
+
+
+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``.
+
+
+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
+---------------------------
+
@@ -0,0 +1,39 @@
+.. include:: _controller_substitutions.repl
+
+.. _C001_page:
+
+|C001_typename|
+==================================================
+
+|C001_shortinfo|
+
+Controller details
+------------------
+
+Type: |C001_type|
+
+Name: |C001_name|
+
+Status: |C001_status|
+
+GitHub: |C001_github|_
+
+Maintainer: |C001_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,39 @@
+.. include:: _controller_substitutions.repl
+
+.. _C002_page:
+
+|C002_typename|
+==================================================
+
+|C002_shortinfo|
+
+Controller details
+------------------
+
+Type: |C002_type|
+
+Name: |C002_name|
+
+Status: |C002_status|
+
+GitHub: |C002_github|_
+
+Maintainer: |C002_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,39 @@
+.. include:: _controller_substitutions.repl
+
+.. _C003_page:
+
+|C003_typename|
+==================================================
+
+|C003_shortinfo|
+
+Controller details
+------------------
+
+Type: |C003_type|
+
+Name: |C003_name|
+
+Status: |C003_status|
+
+GitHub: |C003_github|_
+
+Maintainer: |C003_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,39 @@
+.. include:: _controller_substitutions.repl
+
+.. _C004_page:
+
+|C004_typename|
+==================================================
+
+|C004_shortinfo|
+
+Controller details
+------------------
+
+Type: |C004_type|
+
+Name: |C004_name|
+
+Status: |C004_status|
+
+GitHub: |C004_github|_
+
+Maintainer: |C004_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,39 @@
+.. include:: _controller_substitutions.repl
+
+.. _C005_page:
+
+|C005_typename|
+==================================================
+
+|C005_shortinfo|
+
+Controller details
+------------------
+
+Type: |C005_type|
+
+Name: |C005_name|
+
+Status: |C005_status|
+
+GitHub: |C005_github|_
+
+Maintainer: |C005_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,39 @@
+.. include:: _controller_substitutions.repl
+
+.. _C006_page:
+
+|C006_typename|
+==================================================
+
+|C006_shortinfo|
+
+Controller details
+------------------
+
+Type: |C006_type|
+
+Name: |C006_name|
+
+Status: |C006_status|
+
+GitHub: |C006_github|_
+
+Maintainer: |C006_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,39 @@
+.. include:: _controller_substitutions.repl
+
+.. _C007_page:
+
+|C007_typename|
+==================================================
+
+|C007_shortinfo|
+
+Controller details
+------------------
+
+Type: |C007_type|
+
+Name: |C007_name|
+
+Status: |C007_status|
+
+GitHub: |C007_github|_
+
+Maintainer: |C007_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,39 @@
+.. include:: _controller_substitutions.repl
+
+.. _C008_page:
+
+|C008_typename|
+==================================================
+
+|C008_shortinfo|
+
+Controller details
+------------------
+
+Type: |C008_type|
+
+Name: |C008_name|
+
+Status: |C008_status|
+
+GitHub: |C008_github|_
+
+Maintainer: |C008_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,39 @@
+.. include:: _controller_substitutions.repl
+
+.. _C009_page:
+
+|C009_typename|
+==================================================
+
+|C009_shortinfo|
+
+Controller details
+------------------
+
+Type: |C009_type|
+
+Name: |C009_name|
+
+Status: |C009_status|
+
+GitHub: |C009_github|_
+
+Maintainer: |C009_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,39 @@
+.. include:: _controller_substitutions.repl
+
+.. _C010_page:
+
+|C010_typename|
+==================================================
+
+|C010_shortinfo|
+
+Controller details
+------------------
+
+Type: |C010_type|
+
+Name: |C010_name|
+
+Status: |C010_status|
+
+GitHub: |C010_github|_
+
+Maintainer: |C010_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,97 @@
+.. include:: _controller_substitutions.repl
+
+.. _C011_page:
+
+|C011_typename|
+==================================================
+
+|C011_shortinfo|
+
+Controller details
+------------------
+
+Type: |C011_type|
+
+Name: |C011_name|
+
+Status: |C011_status|
+
+GitHub: |C011_github|_
+
+Maintainer: |C011_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
+
+Many systems provide a simple HTTP API where data can be changed using a HTTP request with a properly constructed querystring.
+
+This Controller allows you to send HTTP GET, POST and PUT Requests to the given webserver.
+
+For every device you have to choose to which Controllers it is sending its data. When configuring the Controller you can access this data and use them to generate your querystring.
+
+You can use this placeholders in http header and in the http body:
+
+* ``%systime%`` will be replaced with the local system time
+* ``%vcc%`` will be replaced with the power supply voltage (if enable in this build)
+* ``%ip%`` will be replaced with the local ip adress
+* ``%sysload%`` will be replaced with the system load
+* ``%uptime%`` will be replaced with the system uptime
+* ``%CR%`` will be replaced with "\r"
+* ``%LF%`` will be replaced with "\n" (newline)
+* ``%sysname%`` will be replaced with the system name
+* ``%tskname%`` will be replaced with the name of the device which is sending data to this controller
+* ``%id%`` will be replaced with IDX value.
+* ``%vname1%`` will be replaced with Valuename 1
+* ``%vname2%`` will be replaced with Valuename 2
+* ``%vname3%`` will be replaced with Valuename 3
+* ``%vname4%`` will be replaced with Valuename 4
+* ``%val1%`` will be replaced with the value 1 of the device which is sending data to this controller
+* ``%val2%`` will be replaced with the value 2 of the device which is sending data to this controller
+
+You can also write things like this:
+
+``%1%_some_text_and_placeholder_%/1%`` everything between ``%1%`` and ``%/1%`` will only print when there is a value ``1``
+
+
+Examples
+--------
+
+InfluxDB HTTP Api
+^^^^^^^^^^^^^^^^^
+
+* HTTP Method: ``POST``
+* HTTP URI: ``write?db=testdb``
+* HTTP Header: ``Content-Type: application/x-www-form-urlencoded``
+* HTTP Body: 
+
+.. code-block:: none
+
+  %1%%vname1%,Standort=%tskname%
+  Wert=%val1%%/1%%2%%LF%%vname2%,Standort=%taskname%
+  Wert=%val2%%/2%%3%%LF%%vname2%,Standort=%taskname%
+  Wert=%val3%%/3%%4%%LF%%vname2%,Standort=%taskname%
+  Wert=%val4%%/4%
+
+See also `InfluxDB API description <https://docs.influxdata.com/influxdb/v1.5/guides/writing_data/#writing-multiple-points>`_
+
+Nettemp HTTP Api
+^^^^^^^^^^^^^^^^
+
+untested but should work with something like this:
+
+``/receiver.php?device=ip&type=%1%%vname1%%/1%%2%;%vname2%%/2%%3%;%vname3%%/3%%4%;%vname4%%/4%&value=%1%%val1%%/1%%2%;%val2%%/2%%3%;%val3%%/3%%4%;%val4%%/4%``
@@ -0,0 +1,39 @@
+.. include:: _controller_substitutions.repl
+
+.. _C012_page:
+
+|C012_typename|
+==================================================
+
+|C012_shortinfo|
+
+Controller details
+------------------
+
+Type: |C012_type|
+
+Name: |C012_name|
+
+Status: |C012_status|
+
+GitHub: |C012_github|_
+
+Maintainer: |C012_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,309 @@
+.. include:: _controller_substitutions.repl
+
+.. _C013_page:
+
+|C013_typename|
+==================================================
+
+|C013_shortinfo|
+
+Controller details
+------------------
+
+Type: |C013_type|
+
+Name: |C013_name|
+
+Status: |C013_status|
+
+GitHub: |C013_github|_
+
+Maintainer: |C013_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0 
+  ...
+
+  |improved|
+  Implementation of secure communication and check for valid data.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
+
+ESPEasy is able to communicate between nodes itself.
+It is an IANA registered service: `espeasy-p2p <https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=8266#ESPeasy>`_
+
+* Service Name:  espeasy-p2p
+* Port Number: 8266
+* Transport Protocol:  UDP
+* Description: ESPeasy peer-2-peer communication
+* Registration date: 2018-11-28
+
+This protocol is targeted specific for use by ESPeasy to let ESPeasy nodes
+communicate with each other to create a big swarm of nodes working together
+without the need for a hosted service like MQTT, which needs a central broker.
+
+It is currently used for:
+
+* Discovery of nodes
+* Sharing sensor data among nodes
+
+Later updates may add:
+
+* Distribution of settings
+* Sending commands
+
+
+Sharing Plugins among Nodes
+---------------------------
+
+It is possible to share the data collected by a plugin on one node so it can be used on another node.
+This data can be used as if it is actually being run on the second node.
+
+For example, a Dallas DS18b20 sensor on Node-1 is shared using the ESPeasy p2p controller.
+This plugin can then automatically be setup on Node-2 and using the data collected by Node-1.
+
+This is a rather non-intuitive process to setup.
+
+Prerequisites
+^^^^^^^^^^^^^
+
+* Same UDP port must be setup on both nodes. (preferrably UDP port 8266) This can be done in Tools -> Advanced -> UDP port
+* Nodes must be rebooted after UDP port has changed. (Builds before 2020-07-19)
+* Each node must have an unique unit number. This must not be 0 and not 255, but anything inbetween is fine.
+
+
+How to share a plugin
+^^^^^^^^^^^^^^^^^^^^^
+
+* Check to see if all nodes can see eachother. This will be visible on the main page showing a list of all nodes.
+* Enable p2p networking controller on receiving node
+* Make sure the receiving node has the spot free which is being used on the 'sending' node (For example slot 12)
+* Enable p2p networking controller on sending node
+* Set the plugin you want to share to use the p2p controller
+
+Any node that is setup to receive data like this will see a plugin being added if the spot in the device list was still free.
+
+Builds made after 2019/08/08 will show in the device overview page from which unit the shared plugin does get its data.
+This also means the plugin must be removed and re-created if the sending node is changed. (e.g. another node or change of unit number)
+
+In later builds there will be added an option to update this node number.
+
+
+Some tips on trouble shooting
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Make sure to reboot the node after changing the UDP port.
+* Make sure all nodes have an unique unit number and share the same UDP port.
+* If you have ArduinoOTA enabled, use another port for ESPeasy p2p UDP (port suggested in most OTA examples use port 8266)
+* Ping the nodes from some other host to keep their WiFi awake.
+* Disable "Eco mode" in the advanced settings.
+* Sharing a plugin to be auto installed on another node is only sent right after the plugin is set to use the p2p controller. So if you don't see it appear on the other node, save it again on the source node.
+* Make sure the same plugin is available in the build on both nodes. (e.g. both supporting Dallas DS18b20, if that's the one you want to share)
+* When using the "Guest" feature of an access point, some will not allow direct communication between clients on the same AP. This will also prevent this p2p protocol to share data.
+* If updating from builds before 2019/08/08, you may need to remove and add again a plugin receiving data from a remote node.
+
+
+
+Sending & Known Nodes
+---------------------
+
+ESPEasy keeps track of all nodes advertising themselves via Sysinfo messages.
+
+This knowledge is kept in a ``NodeStruct`` for at least 10 minutes.
+If a node is not sending a Sysinfo message in this period, it will be removed from the list.
+
+Data Format Versions
+--------------------
+
+During the IANA port assignment assessment, a number of issues were pointed out by their experts.
+
+* Versioning
+* Security
+* Data validation
+* Traffic limiting and congestion handling
+
+There are now 2 versions available:
+
+* Version "0" - No security, no data validation.
+* Version "1" - Introduced in ESPeasy build <???>
+
+Data Format Version 0
+---------------------
+
+Sending and receiving is causing issues when the swarm of nodes increases.
+
+* All nodes with this service enabled will advertise their presence every 30 seconds via broadcast
+* Nodes can not subscribe to receiving sensor data updates
+* Non broadcast messages are sent to each individual known node, regardless if the receiving node will use the data
+* Sensor Data messages are sent to each individual known node
+* Sensor Info updates are sent to each individual known node when a plugin coupled to this plugin is saved.
+
+Of each known node the following data is kept:
+
+.. code-block:: C++
+
+  struct NodeStruct
+  {
+    String nodeName;
+    byte ip[4];
+    uint16_t build;
+    byte age;
+    byte nodeType;
+  };
+
+The key to index this ``NodeStruct`` is the nodes unit number.
+
+ASCII Data
+^^^^^^^^^^^^^^^^
+
+Command Message
+^^^^^^^^^^^^^^^^
+
+First byte is not 0xFF.
+
+The entire message processed as a command like this:
+
+.. code-block:: C++
+
+  packetBuffer[len] = 0;
+  ExecuteCommand_all(EventValueSource::Enum::VALUE_SOURCE_SYSTEM, &packetBuffer[0]);
+
+As can be seen, no checks for size, and it is just expected to be a valid ESPeasy command.
+Also no check to see if the command is supported by the receiving end and no feedback to the sender.
+
+Binary Data
+^^^^^^^^^^^^^^^^
+
+Binary data is marked with the first byte 0xFF.
+
+On the receiving end, it is packed in an event in the ``Data`` field and processed like this:
+
+.. code-block:: C++
+
+  struct EventStruct TempEvent;
+  TempEvent.Data = reinterpret_cast<byte*>(&packetBuffer[0]);
+  TempEvent.Par1 = remoteIP[3];
+  TempEvent.Par2 = len;
+  PluginCall(PLUGIN_UDP_IN, &TempEvent, dummyString);
+  CPluginCall(CPLUGIN_UDP_IN, &TempEvent);
+
+N.B. only the controller C013 implements code for handling UDP data.
+
+Message types supported, determined by the 2nd byte:
+
+* 1: Sysinfo message
+* 2: Sensor info pull request (not implemented)
+* 3: Sensor info
+* 4: Sensor data pull request (not implemented)
+* 5: Sensor data
+
+Sysinfo Message
+^^^^^^^^^^^^^^^^
+
+There are 2 types of Sysinfo messages, a standard and an extended message.
+The extended message starts with the same information as the standard one.
+
+Standard Sysinfo message (13 bytes):
+
+* 2 bytes marker (255 , 1)
+* 6 byte MAC address
+* 4 byte IP address
+* 1 byte unit number
+
+Extended Sysinfo message (13 + 28 = 41 bytes):
+
+* 2 bytes ESPeasy data version number (LSB, MSB)
+* 25 bytes node name
+* 1 byte node type
+
+The node type is defined as:
+
+*  1 = "ESP Easy"
+* 17 = "ESP Easy Mega"
+* 33 = "ESP Easy 32"
+* 65 = "Arduino Easy"
+* 81 = "Nano Easy"
+
+Sensor Info message
+^^^^^^^^^^^^^^^^^^^^
+
+Sensor Info messages are just a description of a shared sensor.
+It contains some information to setup a new sensor on the receiving end.
+
+These messages are just a serialized byte stream of ``struct C013_SensorInfoStruct`` .
+
+.. code-block:: C++
+
+  struct C013_SensorInfoStruct
+  {
+    byte header = 255;
+    byte ID = 3;
+    byte sourceUnit;
+    byte destUnit;
+    byte sourceTaskIndex;
+    byte destTaskIndex;
+    byte deviceNumber;
+    char taskName[26];
+    char ValueNames[VARS_PER_TASK][26];
+  };
+
+
+Sensor Data message
+^^^^^^^^^^^^^^^^^^^^
+
+
+These messages are just a serialized byte stream of ``struct C013_SensorDataStruct`` .
+
+.. code-block:: C++
+
+  struct C013_SensorDataStruct
+  {
+    byte header = 255;
+    byte ID = 5;
+    byte sourceUnit;
+    byte destUnit;
+    byte sourceTaskIndex;
+    byte destTaskIndex;
+    float Values[VARS_PER_TASK];
+  };
+
+
+Data Format Version 1
+---------------------
+
+This version remains compatible with version 0 for backwards compatibility.
+It is using the "next" unused marker.
+
+All messages will have a standard packet data format:
+
+* 2 bytes Marker (255 , 6)
+* 2 bytes Version   => also determines data offset (header length)
+* 2 bytes Message type
+* 2 bytes Size of data block in "N" blocks of 16 bytes
+* 2 bytes Key/group selector
+* 2 bytes Sequence number
+* (16 x N) bytes Data block AES encrypted data (including 2 bytes checksum)
+* 2 bytes Packet checksum
+
+This allows to:
+
+* Distinguish data format versions
+* Filter on message type before allocating large buffers
+* Use multiple (pre-shared) encryption keys to have several levels of security or just several groups.
+* Validate correct transmission of packet (last 2 checksum bytes) before decrypting data.
+* Allow for larger messages to be sent in sequences. (e.g. firmware upgrades?)
+* Validate sender and content of data block, since it contains a checksum too, which is part of the encrypted data block.
+
+Since AES has a block size of 16 bytes (128 bit), the size of the data block is defined as a block of 16 bytes.
+This allows up-to 1 MB of messages. (2^16 * 2^4 = 2^20)
+An UDP datagram sent over IPv4 cannot exceed 65,507 bytes (65,535 - 8 byte UDP header - 20 byte IP header).
+In IPv6 jumbograms it is possible to have UDP packets of size greater than 65,535 bytes.
@@ -0,0 +1,151 @@
+.. include:: _controller_substitutions.repl
+
+.. _C014_page:
+
+|C014_typename|
+==================================================
+
+|C014_shortinfo|
+
+Controller details
+------------------
+
+Type: |C014_type|
+
+Name: |C014_name|
+
+Status: |C014_status|
+
+GitHub: |C014_github|_
+
+Maintainer: |C014_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added| 2019/04/25
+  Initial alpha version of this plug-in.
+
+Description
+-----------
+
+This controller connects to a MQTT Server providing auto-discover information and a communication protocol according to the Homie convention 3.0.1 and the future development version 4.0.0.
+
+For more information head over to `Homie convention <https://homieiot.github.io/>`_
+
+Idea is to provide an easy way to include ESPEasy in modern home automation systems without any or with as less effort as possible. Imagine your device pops up in openHAB 2.4 or higher as a new device and you only have to pic the values you are interested in. You can immediately see measurements or switch GPIOs without a single line of code.
+
+When a MQTT connection is established after (re-)boot the controller sends auto-discovery information for system services like commands, basic GPIO functions and for all configured devices and there values. When all messages where sent successfully a homie compatible home automation server/hub or other compatible controllers should be able to detect the unit and establish two way communication.
+
+The :ref:`P086_page` plug-in can be used to set values and trigger actions / rules.
+
+MQTT topic scheme
+-----------------
+
+A homie topic scheme always starts with the root topic homie followed by the **unit name** (homie uses the term **device**), **device name** (**node** in homie) and a **value name**.
+
+``homie/%unitname%/%devicename%/%valname%``
+
+updates or commands can be sent by appending ``/set`` to the topics for values which can receive data.
+
+``homie/%unitname%/%devicename%/%valname%/set``
+
+Prequesites
+-----------
+
+A MQTT server capable of storing messages sent with ``retain=true`` when  ``QoS=0``. Due to limitation (intentional not implemented due to low memory footprint and performance considerations) of the MQTT library (pubsubclient) used in ESPEasy it is only possible to send messages with ``QoS=0`` which basically means `fire and forget`. The current MQTT specification says that the server SHOULD store these messages when they arrive via ``QoS=0``. Some servers like the MQTT server currently build into openHAB 2.4 (moquette) is configured to ignore the retain flag and drop the message after delivery to the currently subscribed clients when ``QoS=0``. Mosquito on the other hand store messages when retain flag is set even when they are sent with ``QOS=0``.
+Check with a MQTT client like MQTTspy or MQTTfx if the auto-discover messages are stored (retained).
+
+A home automation server/controller capable talking Homie like openHAB since 2.4. (Be aware there are issues in the Homie implementation 2.4 including 2.5M1 milestone release not working as expected after restart). Recent snapshot builds should work.
+
+Setup
+-------------
+
+- add the Homie **Homie MQTT (Version 4.0.0 dev)** or **Homie MQTT (Version 3.0.1 dev)** controller to your controller lists depending on your build.
+- insert your broker address
+- and user credentials if necessary
+- the publish scheme is fixed to meet the homie requirements to ``homie/%sysname%/%tskname%/%valname%``
+- the subscription scheme can be modified. Current defaults to ``homie/%sysname%/+/+/set`` to reduce incoming traffic to a minimum. Homie only expects messages via the ``homie/%sysname%/%tskname%/%valname%/set`` topic.
+- last will topic (LWT) should set to ``homie/%sysname%/$state``
+- LWT Connect Message to ``ready``
+- LWT Disconnect Message to ``lost``
+- save and reboot, best with connected serial monitor or syslog server with debug set to 4 (debug) or greater (alternatively use a MQTT client and subscribe to ``homie/%sysname%/#`` - replace %sysname% by the unit-name shown on the top of the webpage).
+
+.. image:: C0014_Setup_0.png
+
+- ``homie/%sysname%/$nodes`` enumerating all devices will be sent as final message of the auto-discover header.
+- The final event log should look like this:
+
+.. code-block:: none
+
+  5584 : EVENT: MQTT#Connected
+  5754 : C014 : autodiscover information of 4 Devices and 6 Nodes sent with no errors! (26 messages)
+
+Troubleshoot
+------------
+
+The auto-discover information is sent through a big number of messages (usual more than 20). If your controller software not recognize your device or shows errors during the auto-discover process try the following steps:
+
+- For testing purposes start with a basic setup with none or only one device configured and enabled.
+- More devices can be added or (re-)enabled later.
+- Disable already configured devices (devices without the enabled box ticked will be ignored)
+- Check with a MQTT client if all messages are sent. The last message sent is ``$nodes`` attribute listing minimum the ``SYSTEM`` node if no other devices are enabled.
+- check your WIFI connection. Perhaps bring your device nearer to your access point. (only necessary during the setup process because the messages should be stored by the broker)
+- check via syslog or serial console if the messages are sent successful (you normaly can't see the log output in the web log)
+- use the `mqqt-forget <https://www.npmjs.com/package/mqtt-forget>`_ tool to delete unused retained messages from your broker via wildcards
+
+Features
+--------
+
+The controller currently supports these features
+
+- send auto-discover nodes for all sending and enabled plug-ins to ``homie/%unitName%/%deviceName%/%valueName%``
+- receive commands through the ``homie/%unitName%/SYSTEM/cmd/set`` topic.
+- switch GPIOs through ``homie/%unitName%/SYSTEM/gpio#/set`` topic. The GPIO port must be set to **default low** or **default high** in the hardware tab to be included during auto-discover.
+- send updates of GPIO ports to ``homie/%unitName%/SYSTEM/gpio#`` regardless from where the change is triggered (to be fully tested).
+- in conjunction with :ref:`P086_page` actuators can be used according to the Homie convetion using rules.
+- receive values for dummy devices via ``homie/%unitName%/%dummyDeviceName%/%valueName%/set``. From there the values can be processed further by using rules.
+- handle ``$state`` attribute (for complete list see attribute table below)
+
+  - ``init`` during boot process
+  - ``ready`` during normal operation and as a heartbeat every 30sec (to be tested)
+  - ``alert`` currently only if auto-discover fails. But if sending the auto-discover messages fails it is more than likely that sending the alert message will fail to. (ToDo: inform about other error states like low ram or stack available, repeating reboots or failed sensors)
+  - ``sleeping`` sent before deep sleep
+  - ``lost`` configured as LWT
+  - ``disconnected`` sent to the old topic if the unit name changes to inform that the old topic is not valid any more. Auto-discover messages are sent automagically to the new topics afterwards.
+
+- acknowledge received message by the ``homie/%unitName%/%deviceName%/%valueName%/set`` topic to the corresponding value ``homie/%unitName%/%deviceName%/%valueName%`` even if the value was changed by a different source like HTTP or rule to keep the state in your home automation system allays up to date. (Needs further testing)
+
+Future / planned features
+-------------------------
+
+- a special Homie Plugin is in devolopment to pass ``\set`` messages to rules for further handling. Here ``$datatype`` and ``$format`` attributes for ``$setable`` values can be specified there. This will enable ESPEasy to handle direct inputs to plug-ins like dimmers (%,0:100), colors (RGB & HSV, 255,255,255), enum devices like remote controls (Play, Pause, Vol+, Vol-, ...). :yellow:`Testing` see :ref:`P086_page`
+- Further in field testing with different MQTT brokers and home automation systems.
+- Handling units via the ``$unit`` attribute. As ESPEasy is currenty "unitless" this needs a global concept within ESPEasy
+- Handling ``$datatype`` attribute. Currenly all values (except cmd and gpio) are defined as ``float``. :yellow:`Testing` see :ref:`P086_page` 
+- Prepare some "working examples".
+
+Under the hood
+--------------
+
+Auto-dicover information is sent by several $attributes
+
+currently the following attributes will be sent during boot
+
+Unit (Device) attributes
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. include:: C014_attributes.repl
+
+Device (Node) attributes
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. include:: C014_node_attributes.repl
+
+Value attributes
+^^^^^^^^^^^^^^^^
+
+.. include:: C014_property_attributes.repl
@@ -0,0 +1,16 @@
+.. csv-table::
+        :header: "Attribute", "Description", "Example", "3.0.1","Spec.","4.0.0","Spec."
+        :widths: 10, 35, 15, 10, 5, 10, 5
+
+        "``$name``", "Friendly name of the device", "EPSEasy#1", "YES", ":green:`required`", "YES", ":green:`required`"
+        "``$homie``", "The implemented Homie convention version", "4.0.0", "YES",":green:`required`", "YES", ":green:`required`"
+        "``$state``", "See chapter features", "ready", "YES",":green:`required`", "YES", ":green:`required`"
+        "``$localip``", "IP of the device on the local network", "192.168.2.10", "YES", ":green:`required`", "NO", ":red:`void`"
+        "``$mac``", "Mac address of the device network interface.", "A1:B2:C3:D4:E5:F6", "YES", ":green:`required`", "NO", ":red:`void`"
+        "``$fw/name``", "Name of the firmware running on the device.", "ESPEasy mega", "YES", ":green:`required`", "NO", ":red:`void`"
+        "``$fw/version``", "Version of the firmware running on the device.", "20103 - Mega", "YES", ":green:`required`", "NO", ":red:`void`"
+        "``$nodes``", "Nodes which the device exposes separated by commas. Sent at the end for performance reasons.", "SYSTEM,SysInfo", "YES",":green:`required`", "YES", ":green:`required`"
+        "``$implementation``", "An identifier for the Homie implementation.", "ESP8266", "YES", ":green:`required`", "NO", ":red:`void`"
+        "``$stats/interval``", "Interval in seconds at which the device refreshes.", "60", "YES", ":green:`required`", "NO", ":red:`void`"
+        "``$stats/uptime``", "Time elapsed in seconds since the boot of the device.", "12345", "YES", ":green:`required`", "NO", ":red:`void`"
+        "``$stats/signal``", "Signal strength in %.", "75", "YES", ":blue:`optional`", "NO", ":red:`void`"
@@ -0,0 +1,7 @@
+.. csv-table::
+        :header: "Attribute", "Description", "Example", "3.0.1","Spec.","4.0.0","Spec."
+        :widths: 10, 35, 15, 10, 5, 10, 5
+
+        "``$name``","Friendly name of the Node","SYSTEM", "YES",":green:`required`", "YES",":green:`required`"
+        "``$type``","Type of the node","System commands", "YES",":green:`required`", "YES",":green:`required`"
+        "``$properties``","Exposed properties. Separated by , for multiple ones.","value1,value2", "YES",":green:`required`", "YES",":green:`required`"
@@ -0,0 +1,10 @@
+.. csv-table::
+        :header: "Attribute", "Description", "Example", "3.0.1","Spec.","4.0.0","Spec."
+        :widths: 10, 40, 10, 5, 15, 5, 15
+
+        "``$name``","Friendly name of the property.","Command", "YES",":green:`required`", "YES",":green:`required`"
+        "``$datatype``","Describes the format of data.	integer/float/boolean/string/enum/color","float", "YES",":green:`required`", "YES",":green:`required`"
+        "``$settable``","Specifies whether the property is settable (true) or read-only (default false). True for cmd, GPIO and dummy device values.","true", "YES",":yellow:`required true` for settable values", "YES",":yellow:`required true` for settable values"
+        "``$retained``","Specifies whether the property is retained (true) or non-retained (false).","false", "NO",":green:`required`", "NO",":blue:`optional`"
+        "``$unit``","A string containing the unit of this property.","°C", "NO",":blue:`optional`", "NO",":blue:`optional`"
+        "``$format``","Describes what are valid values for this property.","-30:40", "NO",":blue:`optional`", "NO",":blue:`optional`"
@@ -0,0 +1,70 @@
+.. include:: _controller_substitutions.repl
+
+.. _C016_page:
+
+|C016_typename|
+==================================================
+
+|C016_shortinfo|
+
+Controller details
+------------------
+
+Type: |C016_type|
+
+Name: |C016_name|
+
+Status: |C016_status|
+
+GitHub: |C016_github|_
+
+Maintainer: |C016_maintainer|
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added| 2019/04/05
+  Initial pre-alpha version of this plugin.
+
+Description
+-----------
+
+This controller is a cache layer to collect data while not connected to a network.
+
+The data will first be stored in RTC memory, which will survive a crash/reboot and even an OTA update.
+
+If this RTC buffer is full, it will be flushed to whatever is set here as storage.
+
+Data Format
+-----------
+
+Each time a plugin sends data to this controller, a sample set is stored.
+
+A typical sample set contains:
+
+- UNIX timestamp
+- task index delivering the data
+- 4 float values
+
+Storage
+-------
+
+The controller can save the samples from RTC memory to several places on the flash:
+
+- Files on SPIFFS
+- Part reserved for OTA update (TODO)
+- Unused flash after the partitioned space (TODO)
+
+Data Delivery
+-------------
+
+The controller can deliver the data to:
+
+- Upload bin files to some server (HTTP post?) (TODO)
+- Provide a sample to any connected controller (TODO)
+- Do nothing and let some extern host pull the data from the node. (TODO)
+- JavaScript to process the data inside the browser. (TODO)
+- Feed it to some plugin (e.g. a display to show a chart) (TODO)
@@ -0,0 +1,33 @@
+.. include:: _controller_substitutions.repl
+
+.. _C017_page:
+
+|C017_typename|
+==================================================
+
+|C017_shortinfo|
+
+Controller details
+------------------
+
+Type: |C017_type|
+
+Name: |C017_name|
+
+Status: |C017_status|
+
+GitHub: |C017_github|_
+
+Maintainer: |C017_maintainer|
+
+Change log
+----------
+
+.. versionadded:: 2.0 
+  ...
+
+  |added|
+  Initial release version.
+
+Description
+-----------
@@ -0,0 +1,191 @@
+.. include:: _controller_substitutions.repl
+
+.. _C018_page:
+
+|C018_typename|
+==================================================
+
+|C018_shortinfo|
+
+Controller details
+------------------
+
+Type: |C018_type|
+
+Name: |C018_name|
+
+Status: |C018_status|
+
+GitHub: |C018_github|_
+
+Maintainer: |C018_maintainer|
+
+Change log
+----------
+
+.. versionadded:: 2.0 
+  ...
+
+  |added|
+  2019/08/13 First occurrence in the source.
+
+Description
+-----------
+
+`The Things Network (TTN) <https://www.thethingsnetwork.org/>`_ is a global open LoRaWAN network.
+LoRaWAN allows low power communication over distances of several km.
+
+A typical use case is a sensor "in the field" which only has to send a few sample values every few minutes.
+Such a sensor node does broadcast its message and hopefully one or more gateways may hear the message and route it over the connected network to a server.
+
+The data packets for this kind of cummunication have to be very short (max. 50 bytes) and a sender is only allowed to send for a limited amount of time.
+On most frequencies used for the LoRa networks there is a limit of 1% of the time allowed to send.
+
+Such a time limit does also apply for a gateway. This implies that most traffic will be "uplink" data from a node to a gateway.
+The analogy here is that the gateway is often mounted as high as possible while the node is at ground level ("in the field")
+
+There is "downlink" traffic possible, for example to notify some change of settings to a node, or simply to help the node to join the network.
+
+In order to communicate with the gateways in the TTN network, you need a LoRa/LoRaWAN radio module.
+
+The radio module does communicate via the LoRa protocol. On top of that you also need a layer for authentication, encryption and routing of data packets.
+This layer is called LoRaWAN.
+
+There are several modules available:
+
+- RFM95  & SX127x.  These are LoRa modules which needs to have the LoRaWAN stack implemented in software
+- Microchip RN2384/RN2903. These are the modules supported in this controller. They have the full LoRaWAN stack present in the module.
+
+
+Nodes, Gateways, Application
+----------------------------
+
+A typical flow of data on The Things Network (TTN) is to have multiple nodes collecting data for a specific use case.
+
+Such a use case is called an "Application" on The Things Network.
+For example, a farmer likes to keep track of the feeding machines for his cattle.
+
+So let us call this application "farmer-john-cattle".
+
+For this application, a number of nodes is needed to keep track of the feeding machines in the field.
+These nodes are called "Devices" in TTH terms.
+For example a device is needed to measure the amount of water in the water tank and one for the food supply.
+
+Such a device must be defined on the TTN console page.
+
+There are two means of authenticating a device to the network (this is called "Join" in TTN terms):
+- OTAA - Over-The-Air Authentication
+- ABP - activation by personalization
+
+With OTAA, a device broadcasts a join request and one of the gateways in the neighborhood that received this request, 
+will return a reply with the appropriate application- and network- session keys to handle further communication.
+
+This means the device can only continue if there is a gateway in range at the moment of joining.
+It may happen that a gateway does receive the join request, but the device is unable to receive the reply.
+When that's happening, the device will not be able to send data to the network since it cannot complete the join.
+Another disadvantage of OTAA authenticating is the extra time needed to wait for the reply.
+Especially on battery powered devices the extra energy needed may shorten the battery life significantly.
+
+With OTAA, the device is given 3 keys to perform the join:
+
+- Device EUI - An unique 64 bit key on the network.
+- Application EUI - An unique 64 bit key generated for the application.
+- App Key - A 128 bit key needed to exchange keys with the application.
+
+The result of such an OTAA join is again a set of 3 keys:
+
+- Device Address - An almost unique 32 bit address of your device.
+- Network Session Key - 128 bit key to access the network.
+- Application Session Key - 128 bit key to encrypt the data for your application.
+
+
+The other method of authenticating a device is via ABP.
+ABP is nothing other than storing the last 3 keys directly on the device itself and thus skipping the OTAA join request.
+This means you don't need to receive data on the device and can start sending immediately, and even more important, let your device sleep immediately after sending.
+
+A disadvantage is the deployment of the device. Every device does need to have an unique set of ABP keys generated and stored on the device.
+
+Updating session keys may also be a bit hard to do, since it does need to ask for an update and must also be able to receive that update.
+
+
+
+Hybrid OTAA/ABP
+---------------
+
+TODO TD-er.
+
+
+
+
+
+
+Configure LoRaWAN node for TTN
+------------------------------
+
+A LoRaWAN device must join the network in order to be able to route the packets to the right user account.
+
+Prerequisites:
+
+- An user account on the TTN network.
+- A TTN gateway in range to send data to (and receive data from)
+- Microchip RN2384 or RN2903 LoRaWAN module connected to a node running ESPeasy. (UART connection)
+
+On the TTN network:
+- Create an application
+- Add a device to the application, either using OTAA or ABP.
+
+In order to create a new device using OTAA, one must either copy the hardware Device EUI key from the device to the TTN console page, 
+or generate one and enter it into the controller setup page in ESPeasy.
+The Application EUI and App Key must be copied from the TTN console page to the ESPeasy controller configuration page.
+
+Using these steps, a device address is generated. 
+Such an address looks like this: "26 01 20 47"
+Also the Network Session Key and Application Session Key can be retrieved from this page and can even be used as if the device is using ABP to join the network.
+But keep in mind, these 3 keys will be changed as soon as an OTAA join is performed.
+
+Device configuration with solely an ABP setup are more persistent.
+
+
+Decoding Data
+-------------
+
+
+Controller Settings
+-------------------
+
+Since there are legal limitations on the amount of time you are allowed to send,
+it is even more important to understand what effect the Controller Queue parameters may have on the reliability of data transmission.
+
+You are allowed to send only 1% of the time.
+Meaning if your message takes 100 msec to send, you can only send a message every 10 seconds.
+
+As a rule of thumb, the time needed to send a message of N bytes doubles for every step up in the Spreading Factor.
+
+For example, a message sent at SF7 may take 100 msec to send.
+The same message sent at SF8, will take 200 msec.
+At SF9 takes 400 msec, etc. The slowest is SF12.
+
+The RN2483 module does keep track of the used air time, per channel.
+Meaning it is possible to send a burst of upto 8 messages (since we have 8 channels) after which we have to wait for a free channel to send out a new one.
+
+As with any other ESPEasy controller, there is a queue mechanism to manage the messages ready to be sent and also allow for a number of retries.
+
+This number of retries is even more important on this LoRaWAN TTN controller.
+If sending a message fails due to no free channels, the minimum send interval will be dynamically increased, based on the air time of the message to be sent.
+The dynamic adjustment is 10x the expected air time. So by setting the number of retries to 10, it is almost guaranteed the message will eventually be sent.
+10 retries with 10x the expected air time equals a maximum of 100x the expected air time, which eventually will be as low as 1% of the time sending.
+
+N.B. This expected air time is dependant on the set Spread Factor and the length of the message.
+
+In practice the messages will be sent in bursts, and thus the extra wait time is often 2 - 3x the expected air time of the message.
+So on setups with a large variation in message sizes, it makes sense to send the large ones at the start of a message burst.
+
+Setting the number of retries high (e.g. 10x), may be useful to make sure a sequence of messages in a burst will all get sent.
+But it may also lead to a large number of messages to be lost as the queue is full.
+So it depends on the use case what will be the best strategy here.
+
+At least the Minimum Send Interval can be kept low (e.g. the default 100 msec) to allow for quickly sending out a burst of upto 8 messages.
+
+
+
+
@@ -0,0 +1,106 @@
+.. include:: _controller_substitutions.repl
+
+Controller
+**********
+
+A controller is a component to enable a plugin to send data elsewhere.
+
+- Up-to 3 controllers can be active in ESPEasy.
+- Per plugin up-to 3 active controllers can be selected.
+- For some controllers an additional parameter can be given.
+
+For example, Domoticz needs an 'IDX' value to identify the configured entry in
+Domoticz for which new data is sent.
+
+Controller Plugins
+==================
+
+.. csv-table::
+   :header: "Plugin name", "Plugin status", "Plugin number"
+   :widths: 10, 8, 5
+
+   ":ref:`C001_page`","|C001_status|","C001"
+   ":ref:`C002_page`","|C002_status|","C002"
+   ":ref:`C003_page`","|C003_status|","C003"
+   ":ref:`C004_page`","|C004_status|","C004"
+   ":ref:`C005_page`","|C005_status|","C005"
+   ":ref:`C006_page`","|C006_status|","C006"
+   ":ref:`C007_page`","|C007_status|","C007"
+   ":ref:`C008_page`","|C008_status|","C008"
+   ":ref:`C009_page`","|C009_status|","C009"
+   ":ref:`C010_page`","|C010_status|","C010"
+   ":ref:`C011_page`","|C011_status|","C011"
+   ":ref:`C012_page`","|C012_status|","C012"
+   ":ref:`C013_page`","|C013_status|","C013"
+   ":ref:`C014_page`","|C014_status|","C014"
+   ":ref:`C016_page`","|C016_status|","C016"
+   ":ref:`C017_page`","|C017_status|","C017"
+   ":ref:`C018_page`","|C018_status|","C018"
+
+
+Controller Parameters
+=====================
+
+Generic fields
+--------------
+
+- **Protocol** - The type of controller (e.g. ThingSpeak/OpenHAB MQTT/etc.)
+- **Locate Controller** - Selection between hostname/IP
+- **Controller Hostname/IP**  - The address to reach the selected service
+- **Controller Port** - TCP/UDP Port number (0...65536)
+- **Enabled** - Whether or not the controller is active.
+
+Send queue parameters
+---------------------
+
+Controllers have a queue to keep unsent messages.
+This queue is used to handle message bursts and also store messages which are recorded
+before WiFi connection is made or during lost connection.
+
+- **Minimum Send Interval** - Minimum time between two messages in msec.
+- **Max Queue Depth** - Maximum length of the buffer queue to keep unsent messages.
+- **Max Retries** - Maximum number of retries to send a message.
+- **Full Queue Action** - How to handle when queue is full, ignore new or delete oldest message.
+- **Check Reply** - When set to false, a sent message is considered always successful.
+- **Client Timeout** - Timeout in msec for an network connection used by the controller.
+- **Sample Set Initiator** - Some controllers (e.g. C018 LoRa/TTN) can mark samples to belong to a set of samples. A new sample from set task index will increment this counter.
+  Especially useful for controllers which cannot send samples in a burst. This makes the receiving time stamp useless to detect what samples were taken around the same time.
+  The sample set counter value can help matching received samples to a single set.
+
+.. note::
+  Be careful when setting the timeout too high.
+  For almost all controllers, sending data is a blocking call, so it may halt execution of other code on the node.
+  With timouts longer than 2 seconds, the ESP may reboot as the software watchdog may step in.
+
+
+
+Sample ThingSpeak configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some controllers, like ThingSpeak, need a specific configuration.
+ThingSpeak only allows a message every 15 seconds for the free accounts.
+
+- **Minimum Send Interval** - 15000 msec
+- **Max Queue Depth** - 1 (only report the last value)
+- **Max Retries** - 2
+- **Full Queue Action** - Delete Oldest
+- **Check Reply** - Check Acknowledgment (VERY IMPORTANT)
+- **Client Timeout** - 500 msec (server is online, so timeout must be a bit longer)
+
+
+Controller user credentials
+---------------------------
+
+- **Controller User** - User name (optional)
+- **Controller Password** - Password (optional)
+
+MQTT related settings
+---------------------
+
+- **Controller Subscribe** - Subscribe to the given topic.
+- **Controller Publish** - Publish to the given topic.
+- **Controller lwl topic** - Topic to which LWT (Last Will Testament) messages should be sent.
+- **LWT Connect Message** - Connection established message.
+- **LWT Disconnect Message** - Connection lost message (sent to broker during connect and published by broker when connection is lost)
+
+
@@ -0,0 +1,189 @@
+
+
+
+.. |C001_name| replace:: :cyan:`Domoticz HTTP`
+.. |C001_type| replace:: :cyan:`Controller`
+.. |C001_typename| replace:: :cyan:`Controller - Domoticz HTTP`
+.. |C001_status| replace:: :green:`NORMAL`
+.. |C001_github| replace:: C001.ino
+.. _C001_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C001.ino
+.. |C001_usedby| replace:: `.`
+.. |C001_shortinfo| replace:: `.`
+.. |C001_maintainer| replace:: `.`
+.. |C001_compileinfo| replace:: `.`
+
+.. |C002_name| replace:: :cyan:`Domoticz MQTT`
+.. |C002_type| replace:: :cyan:`Controller`
+.. |C002_typename| replace:: :cyan:`Controller - Domoticz MQTT`
+.. |C002_status| replace:: :green:`NORMAL`
+.. |C002_github| replace:: C002.ino
+.. _C002_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C002.ino
+.. |C002_usedby| replace:: `.`
+.. |C002_shortinfo| replace:: `.`
+.. |C002_maintainer| replace:: `.`
+.. |C002_compileinfo| replace:: `.`
+
+.. |C003_name| replace:: :cyan:`Nodo Telnet`
+.. |C003_type| replace:: :cyan:`Controller`
+.. |C003_typename| replace:: :cyan:`Controller - Nodo Telnet`
+.. |C003_status| replace:: :green:`NORMAL`
+.. |C003_github| replace:: C003.ino
+.. _C003_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C003.ino
+.. |C003_usedby| replace:: `.`
+.. |C003_shortinfo| replace:: `.`
+.. |C003_maintainer| replace:: `.`
+.. |C003_compileinfo| replace:: `.`
+
+.. |C004_name| replace:: :cyan:`ThingSpeak`
+.. |C004_type| replace:: :cyan:`Controller`
+.. |C004_typename| replace:: :cyan:`Controller - ThingSpeak`
+.. |C004_status| replace:: :green:`NORMAL`
+.. |C004_github| replace:: C004.ino
+.. _C004_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C004.ino
+.. |C004_usedby| replace:: `.`
+.. |C004_shortinfo| replace:: `.`
+.. |C004_maintainer| replace:: `.`
+.. |C004_compileinfo| replace:: `.`
+
+.. |C005_name| replace:: :cyan:`Home Assistant (openHAB) MQTT`
+.. |C005_type| replace:: :cyan:`Controller`
+.. |C005_typename| replace:: :cyan:`Controller - Home Assistant (openHAB) MQTT`
+.. |C005_status| replace:: :green:`NORMAL`
+.. |C005_github| replace:: C005.ino
+.. _C005_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C005.ino
+.. |C005_usedby| replace:: `.`
+.. |C005_shortinfo| replace:: `.`
+.. |C005_maintainer| replace:: `.`
+.. |C005_compileinfo| replace:: `.`
+
+.. |C006_name| replace:: :cyan:`PiDome MQTT`
+.. |C006_type| replace:: :cyan:`Controller`
+.. |C006_typename| replace:: :cyan:`Controller - PiDome MQTT`
+.. |C006_status| replace:: :green:`NORMAL`
+.. |C006_github| replace:: C006.ino
+.. _C006_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C006.ino
+.. |C006_usedby| replace:: `.`
+.. |C006_shortinfo| replace:: `.`
+.. |C006_maintainer| replace:: `.`
+.. |C006_compileinfo| replace:: `.`
+
+.. |C007_name| replace:: :cyan:`Emoncms`
+.. |C007_type| replace:: :cyan:`Controller`
+.. |C007_typename| replace:: :cyan:`Controller - Emoncms`
+.. |C007_status| replace:: :green:`NORMAL`
+.. |C007_github| replace:: C007.ino
+.. _C007_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C007.ino
+.. |C007_usedby| replace:: `.`
+.. |C007_shortinfo| replace:: `.`
+.. |C007_maintainer| replace:: `.`
+.. |C007_compileinfo| replace:: `.`
+
+.. |C008_name| replace:: :cyan:`Generic HTTP`
+.. |C008_type| replace:: :cyan:`Controller`
+.. |C008_typename| replace:: :cyan:`Controller - Generic HTTP`
+.. |C008_status| replace:: :green:`NORMAL`
+.. |C008_github| replace:: C008.ino
+.. _C008_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C008.ino
+.. |C008_usedby| replace:: `.`
+.. |C008_shortinfo| replace:: `.`
+.. |C008_maintainer| replace:: `.`
+.. |C008_compileinfo| replace:: `.`
+
+.. |C009_name| replace:: :cyan:`FHEM HTTP`
+.. |C009_type| replace:: :cyan:`Controller`
+.. |C009_typename| replace:: :cyan:`Controller - FHEM HTTP`
+.. |C009_status| replace:: :green:`NORMAL`
+.. |C009_github| replace:: C009.ino
+.. _C009_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C009.ino
+.. |C009_usedby| replace:: `.`
+.. |C009_shortinfo| replace:: `.`
+.. |C009_maintainer| replace:: `.`
+.. |C009_compileinfo| replace:: `.`
+
+.. |C010_name| replace:: :cyan:`Generic UDP`
+.. |C010_type| replace:: :cyan:`Controller`
+.. |C010_typename| replace:: :cyan:`Controller - Generic UDP`
+.. |C010_status| replace:: :green:`NORMAL`
+.. |C010_github| replace:: C010.ino
+.. _C010_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C010.ino
+.. |C010_usedby| replace:: `.`
+.. |C010_shortinfo| replace:: `.`
+.. |C010_maintainer| replace:: `.`
+.. |C010_compileinfo| replace:: `.`
+
+.. |C011_name| replace:: :cyan:`Generic HTTP Advanced`
+.. |C011_type| replace:: :cyan:`Controller`
+.. |C011_typename| replace:: :cyan:`Controller - Generic HTTP Advanced`
+.. |C011_status| replace:: :yellow:`TESTING`
+.. |C011_github| replace:: C011.ino
+.. _C011_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C011.ino
+.. |C011_usedby| replace:: `.`
+.. |C011_shortinfo| replace:: `.`
+.. |C011_maintainer| replace:: `.`
+.. |C011_compileinfo| replace:: `.`
+
+.. |C012_name| replace:: :cyan:`Blynk`
+.. |C012_type| replace:: :cyan:`Controller`
+.. |C012_typename| replace:: :cyan:`Controller - Blynk`
+.. |C012_status| replace:: :yellow:`TESTING`
+.. |C012_github| replace:: C012.ino
+.. _C012_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C012.ino
+.. |C012_usedby| replace:: `.`
+.. |C012_shortinfo| replace:: `.`
+.. |C012_maintainer| replace:: `.`
+.. |C012_compileinfo| replace:: `.`
+
+.. |C013_name| replace:: :cyan:`ESPEasy P2P Networking`
+.. |C013_type| replace:: :cyan:`Controller`
+.. |C013_typename| replace:: :cyan:`Controller - ESPEasy P2P Networking`
+.. |C013_status| replace:: :green:`NORMAL`
+.. |C013_github| replace:: C013.ino
+.. _C013_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C013.ino
+.. |C013_usedby| replace:: `.`
+.. |C013_shortinfo| replace:: `.`
+.. |C013_maintainer| replace:: `TD-er`
+.. |C013_compileinfo| replace:: `.`
+
+.. |C014_name| replace:: :cyan:`Homie MQTT (Version 3.0.1 & 4.0.0dev)`
+.. |C014_type| replace:: :cyan:`Controller`
+.. |C014_typename| replace:: :cyan:`Controller - Homie MQTT convention`
+.. |C014_status| replace:: :yellow:`TESTING`
+.. |C014_github| replace:: C014.ino
+.. _C014_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C014.ino
+.. |C014_usedby| replace:: `.`
+.. |C014_shortinfo| replace:: `Controller for communication following the Homie convention`
+.. |C014_maintainer| replace:: `.`
+.. |C014_compileinfo| replace:: `Can be compiled for Homie 3.0.1 or 4.0.0dev`
+
+.. |C016_name| replace:: :cyan:`Cache`
+.. |C016_type| replace:: :cyan:`Controller`
+.. |C016_typename| replace:: :cyan:`Controller - Cache`
+.. |C016_status| replace:: :red:`DEVELOPMENT`
+.. |C016_github| replace:: C016.ino
+.. _C016_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C016.ino
+.. |C016_usedby| replace:: `.`
+.. |C016_shortinfo| replace:: `Cache layer to collect data while offline`
+.. |C016_maintainer| replace:: `TD-er`
+.. |C016_compileinfo| replace:: `Not in nightly builds. Only pre-built for special builds.`
+
+.. |C017_name| replace:: :cyan:`Zabbix`
+.. |C017_type| replace:: :cyan:`Controller`
+.. |C017_typename| replace:: :cyan:`Controller - Zabbix`
+.. |C017_status| replace:: :yellow:`TESTING`
+.. |C017_github| replace:: C017.ino
+.. _C017_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C017.ino
+.. |C017_usedby| replace:: `.`
+.. |C017_shortinfo| replace:: `.`
+.. |C017_maintainer| replace:: `.`
+.. |C017_compileinfo| replace:: `.`
+
+.. |C018_name| replace:: :cyan:`LoRa TTN - RN2483/RN2903`
+.. |C018_type| replace:: :cyan:`Controller`
+.. |C018_typename| replace:: :cyan:`Controller - LoRa TTN - RN2483/RN2903`
+.. |C018_status| replace:: :yellow:`TESTING`
+.. |C018_github| replace:: C018.ino
+.. _C018_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C018.ino
+.. |C018_usedby| replace:: `.`
+.. |C018_shortinfo| replace:: `Controller for the LoRaWAN/TTN network supporting RN2384 (434/868 MHz) and RN2903 (915 MHz)`
+.. |C018_maintainer| replace:: `TD-er`
+.. |C018_compileinfo| replace:: `.`
@@ -0,0 +1,138 @@
+About Us
+********
+The ESP Easy project is being handled by the core team of TD-er and Grovkillen.
+TD-er being the head of backend and Grovkillen being head of the frontend.
+We both dig down into each others areas of responsible on a daily basis though.
+
+Other than us we have around 100 volunteers that helping us maintain
+and improve the source code.
+
+History
+=======
+ESP Easy has gone through a lot of changes over the last years and here's some
+of the major milestones.
+
+Early days (Nodo Uno)
+---------------------
+It's somewhat unknown how it all started but Paul Tonkes (part of the Nodo team)
+built a IR (infrared) to Kaku controller because he was not happy with the
+commercial version. That unit came to the world named as Nodo (Uno).
+
+04/2010 (Nodo Due)
+------------------
+Taken from the old Nodo website at the time that the Nodo update was introduced
+(named Nodo Due). During this time, a nice production class Arduino Shield was
+also built.
+
+10/2011 (Joining the Nodo community)
+------------------------------------
+The founder of the ESP Easy project, Mvb, read about the Nodo project and
+ordered his first Nodo Arduino board from the Nodo shop. He was using it to
+control Kaku lights around his house.
+
+03/2012 (Nodo Mega)
+--------------------
+Beta Nodo Mega was released, based on Arduino Mega 2560 board with Ethernet
+Shield. Using a hosted web application.
+
+05/2013 (Nodo NES Shield)
+-------------------------
+The hardware guys from the Nodo team released a shield for Arduino Mega 2560
+that contains everything needed to run Nodo Mega with the web application.
+
+01/2014 (Exploring new wireless capabilities)
+---------------------------------------------
+Nodo got its first 2.4GHz communication plugin, using the well known NRF24L01.
+This had solved limitations of the 433MHz OOK modules and at the same time it
+reduced the load on that frequency so Kaku became more reliable.
+
+Mvb decided to run a setup with two Nodo Mega units in the house. First unit
+runs the NES board for 433MHz communication, second board was dedicated for
+NRF24L01 communications. Both Mega's could communicate through I2C or Ethernet.
+
+02/2015 (Entering the Wi-Fi solution)
+-------------------------------------
+Nodo got its first ESP Wi-Fi plugin, using it as a serial to Wi-Fi bridge.
+At that time we were using the stock firmware that came with the module.
+
+04/2015 (ESP Connexio)
+----------------------
+The ESP Connexio project was initiated as the first effort to port the original
+Nodo code to the ESP platform using early version of the ESP8266 Arduino Core.
+The team had to workaround a lot of issues but got it working reasonably.
+
+05/2015 (ESP Easy initiative)
+-----------------------------
+ESP Easy was initiated, mainly because the Nodo Connexio concept was a bit
+over complicated. It had the same event list as the original Nodo project.
+Quite powerful but also complicated to end users. So the idea was to have
+something plug and play to hook up sensors to Domoticz. That decision of
+targeting Domoticz is still present in current source code since many plugins
+from the early days have the values setup in such a way that Domoticz can
+import them with little effort.
+
+09/2015 (ESP Easy R020)
+-----------------------
+As of R017 the Nodo Plugin mechanism was also implemented within ESP Easy.
+Some other inconvenient bugs were fixed, help buttons added and it was decided
+that R020 could be the first production edition.
+
+ESP Easy was launched on Sourceforge as the very first production edition.
+No programming required.
+
+02/2016 (ESP Easy R078)
+-----------------------
+To make things even more easy, edition R078 was provided as binary images
+with a simple installer. No need for a complicated Arduino IDE setup.
+And it also introduced OTA, so subsequent updates could be done without
+connecting the module to a serial port.
+
+08/2016 (ESP Easy R120)
+-----------------------
+Lots of fixes and additional features:
+
+* Rules engine
+* Custom dummy device
+* GlobalSync
+* More commands
+* More controllers
+* More devices
+
+Estimated user count was at this time around 7 000.
+
+11/2016 (ESP Easy Mega)
+-----------------------
+ESP Easy Mega was initiated (only for ESP Modules with at least 1MB flash
+memory). We had to many limitations in ESP Easy, due to the code size that
+exceeded the 512kB modules flash size. Decided to drop support for these
+classic modules and went forward with this version.
+
+02/2017 (Change of roles)
+-------------------------
+Psy0rz took over lead development of ESP Easy Mega (2.0.0), he moved the
+source code onto the GitHub page and started to modularize the code. He also
+made ESP Easy support multiple controllers and fallback Wi-Fi. During this time
+nightly releases was introduced and user counts had grown to around 20 000.
+
+08/2018 (New core team)
+-----------------------
+With both Mvb and Psy0rz having little time to spend on the project two of the
+most eager contributors Grovkillen (mainly wiki documentation and help tools
+at that time) and TD-er (had already implemented the event based Wi-Fi and
+scheduler for better timing) stepped in. The aim for the core team is to
+make the ESP Easy OS as great as can be by dedicating full time commitment to
+the project.
+
+User count was at this point approximately around 32 000 and 24 hour download
+count around 280.
+
+.. 11/2018 (First stable 2+ version)
+   ----------------------------------
+   The first stable release of the new 2.0.0 version was finally released. Much
+   of the features added had been in the nightly releases for more than a year
+   but in the process of modularizing the source code a lot of bugs were fixed,
+   much better timing added, but also some new bugs came into the light. The
+   team wanted to have the official stable release to be just that, stable.
+
+   Estimated user count was at this point around 40 000 and 24 hour download count
+   around 540.
@@ -0,0 +1,2 @@
+ESP Easy Function Blocks
+************************
@@ -0,0 +1,260 @@
+Hardware page
+*************
+
+Overview
+========
+
+ESPEasy has some centralized hardware configuration settings, shown in this page, and divided in sections.
+
+
+---------------
+Wifi Status LED
+---------------
+
+To display the Wifi acitivity, a pin can be configured to light up a LED when data is transfered via Wifi. Optionally, the LED signal can be 'inverted'.
+
+As many ESP boards have an onboard LED connected to GPIO-2 and inverted, it is shown as a note how to configure that.
+
+.. image:: Hardware_Wifistatusled.png
+
+
+---------
+Reset pin
+---------
+
+To provide a possible escape from a malfunctioning ESP module, a factory-reset button/feature can be configured by setting up a GPIO-pin for this.
+
+.. warning::
+    **When connecting this pin to ground for ca. 10 seconds the unit will be completely reset, and all settings/configuration irretrievably deleted!**
+
+This feature can be useful in a development/laboratory environment, for when the configuration gets corrupted in some way.
+
+
+.. image:: Hardware_Resetpin.png
+
+
+-------------
+I2C Interface
+-------------
+
+When using devices that use the I2C bus (Inter-integrated circuit, also known as IIC, and mostly compatible with SM Bus) (`Wikipedia: I2C <https://en.wikipedia.org/wiki/I%C2%B2C>`_) some pins have to be configured, and initialized during boot, for the SDA and SCL connections. This can be any unused pair of pins on the ESP board.
+
+The pins can be configured here, and will have default values initially (ESP8266: SDA: GPIO-4 (D2), SCL: GPIO-5 (D3), ESP32: SDA: GPIO-22, SCL: GPIO-23). When I2C is not used, these can be set to `- None -`, so the pins are available for other purposes.
+
+The default bus clock speed can also be set here. If only devices supporting 100 kHz are connected (Old/Slow devices), then the value can be set to 100 kHz, by default 400 kHz is configured, that is supported by newer devices, though there are many devices supporting higher frequencies. ESP8266 is able to achieve ca. 400 kHz, while ESP32 allows much higher speeds.
+
+Since build 20110, ESPEasy has a separate setting for Slow I2C devices, and per I2C device this slow clock speed can be selected in the Device edit page. This value is by default set to 100 kHz, but can be set lower or higher if desired.
+
+.. image:: Hardware_I2CInterface.png
+
+*Device specific Force Slow I2C speed selection:*
+
+.. image:: Device_I2COptionsShort.png
+
+
+---------------
+I2C Multiplexer
+---------------
+
+Since build 20110, there is the option of using an I2C multiplexer. This option is not available in all builds, because of the size of the code. It is usually available in the normal, testing and custom builds, but ommitted from minimal, IR and hardware-specific builds.
+
+Possible use-cases for an I2C multiplexer are:
+
+* Connect multiple devices that have fixed or limited I2C addresses (For example, some OLED devices have a single fixed address but you need to connect 2 or more, or connect more than 3 TLS2561 devices, that support only 3 different addresses).
+* Connect different devices that have the same I2C address (For example connecting a TSL2561 light/lux sensor and an APDS9960 proximity sensor).
+* Connect slow and fast devices, where the speed of the fast device prohibits proper working of the slow device.
+
+.. |br| raw:: html
+
+    <br>
+
+.. note::
+    If devices with conflicting I2C addresses are to be used, then *none* of them can be connected to the ESP main I2C bus, but they should each be connected to a separate channel of the multiplexer. |br|
+    Devices that do not conflict with other devices *can* be connected to the ESP main I2C bus, this might improve the performance/responsiveness of these devices.
+
+.. note::
+    When using an I2C Multiplexer, make sure there is no address conflict with any of the devices you intend to connect, f.e. when connecting BME280 sensors, don't set the address of the multiplexer to 0x76 or 0x77.
+
+There are a couple of I2C multiplexer chips available, currently there is support for:
+
+* TCA9548a (8 channels, multiple channel-connections, 8 I2C addresses, with reset)
+* TCA9546a (4 channels, multiple channel-connections, 8 I2C addresses, with reset, also TCA9545a can be used, but no support for the Interrupt function though)
+* TCA9543a (2 channels, multiple channel-connections, 4 I2C addresses, with reset)
+* PCA9540 (2 channels, fixed I2C address, no reset, experimental support)
+
+The TCA9548a, TCA9546a and TCA9543a support connecting multiple channels to the main I2C channel. This can be configured on the Device edit page for I2C devices, once the I2C Multiplexer configuration is enabled by selecting a multiplexer type and an I2C address for the multiplexer.
+
+Also, the TCA9548a, TCA9546a and TCA9543a chips have a connection for a reset signal available. This allows the chip to be reset if it gets stuck by some 'less compatible' or 'badly behaving' devices. Once connected and configured, the multiplexer can be reset from the software, if desired or required. This feature is not yet used in any I2C device plugin.
+
+A TCA9543a board has the advantage of being quite a bit smaller than either TCA9546a or TCA9548a, while being digitally compatible. (But with less channels and only 4 I2C addresses).
+
+All these chips/boards can be found at Adafruit, Aliexpress, Banggood, EBay, etc.
+
+.. image:: Hardware_I2CMultiplexerNone.png
+
+*Available multiplexer types:*
+
+.. image:: Hardware_I2CMultiplexer_Type.png
+
+*Select the I2C Address for the multiplexer:*
+
+.. image:: Hardware_I2CMultiplexer_Address.png
+
+
+Device configuration
+^^^^^^^^^^^^^^^^^^^^
+
+If an I2C multiplexer is configured, every Device edit page for I2C devices will show extra options to select the channel the device is connected on.
+
+There is the default option of Single channel, or, when a TCA9548a, TCA9546a or TCA9543a is configured, Multiple channels.
+
+*Example: A multiplexer is configured, but the device is connected directly on the ESP board I2C channel:*
+
+.. image:: Device_I2COptionsMultiplexerNone.png
+
+*Configure a (single) multiplexer channel the device is connected on:*
+
+.. image:: Device_I2COptionsMultiplexerSelectSingleChannel.png
+
+NB: Only acceptable channels (0-7/0-3/0-1) will be available in the dropdown list, depending on the Multiplexer type configured.
+
+*Select Single channel or Multiple channels:*
+
+.. image:: Device_I2COptionsMultiplexerSelect.png
+
+*Configure multiple channels for a device, 8 channel multiplexer configured*
+
+.. image:: Device_I2COptionsMultiplexerMultipleSelect.png
+
+Above configuration results in channels 0, 4, 5, 6 and 7 being connected to the ESP board I2C bus when this sensor is active via I2C.
+
+NB: Only acceptable channel checkboxes (0-7/0-3/0-1) will be shown, depending on the Multiplexer type configured.
+
+
+-------------
+SPI Interface
+-------------
+
+When using devices that are connected via the SPI interface (`Wikipedia: SPI <https://en.wikipedia.org/wiki/Serial_Peripheral_Interface>`_), the interface must be initialized during boot. This can be enabled here. For ESP32 there is the option to select either the Hardware SPI (HSPI) interface or the Virtual SPI (VSPI) interface (software controlled).
+
+The common SPI pins are shown here.
+
+Other SPI pins to be used are device specific, and need to be configured from the corresponding Device edit page.
+
+*For ESP8266:*
+
+.. image:: Hardware_SPIInterfaceESP8266.png
+
+*For ESP32, disabled:*
+
+.. image:: Hardware_SPIInterfaceESP32.png
+
+*For ESP32, select the desired interface:*
+
+.. image:: Hardware_SPIInterfaceESP32_Select.png
+
+NB: When using the VSPI interface and also the I2C interface is used, another pin has to be selected for I2C GPIO -> SCL, as its configuration is fixed for the VSPI setting.
+
+--------
+Ethernet
+--------
+
+On builds including ``_eth`` in their build name, it is also possible to use ethernet instead of WiFi.
+Currently this is only present for ESP32 builds and no plans currently exist to support it for ESP82xx.
+
+N.B. This is still in testing phase, so not all kinds of network communications work right now.
+
+Preferred network medium
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Allows to switch between:
+
+* WiFi (default)
+* Ethernet
+
+To activate a new configuration, a reboot is needed.
+
+Ethernet PHY type
+^^^^^^^^^^^^^^^^^
+
+Select the used PHY controller type:
+
+* LAN8710  (LAN8720 is also supported, but none of the newer features are supported)
+* TLK110  
+
+Ethernet PHY Address
+^^^^^^^^^^^^^^^^^^^^
+
+The PHY address depends on the hardware and the PHY configuration. 
+
+* Espressif's Ethernet board with TLK110 PHY use PHY address 31.
+* Common Waveshare LAN8720 PHY breakout use PHY address 1.
+* Olimex ESP32 EVB REV B IoT LAN8710 PHY Board with CAN use PHY address 0.
+* Other LAN8720 breakouts often use PHY address 0.
+
+If the PHY address is incorrect then the EMAC will initialise but all attempts to read/write configuration registers on the PHY will fail.
+
+GPIO pins
+^^^^^^^^^
+
+RMII PHY SMI Wiring
+"""""""""""""""""""
+
+Most PHY boards have documented their *RMII PHY SMI Wiring* pins:
+
+* **MDC**  Output to PHY, usually pin 23
+* **MDIO** Bidirectional, usually pin 18
+
+Clock sync
+""""""""""
+
+The PHY and the ESP need to keep a clock in sync.
+This can either be done via an external crystal, which is connected to a GPIO pin.
+Another option is to let the ESP provide the clock to the PHY.
+
+* External crystal oscillator
+* 50MHz APLL Output on GPIO0
+* 50MHz APLL Output on GPIO16
+* 50MHz APLL Inverted Output on GPIO17
+
+Power pin
+"""""""""
+
+On almost all PHY boards, or ESP boards equiped with an ethernet PHY, it is possible to turn the PHY on or off.
+Either to save energy, or to make sure the external clock is not affecting the ESP boot mode when it restarts.
+
+For example the Olimex ESP32-EVB does have the *external crystal oscillator* connected to GPIO-0, which could boot the ESP32 randomly into UART flash mode.
+Most boards use a specific GPIO pin to control the power to the PHY.
+The Olimex ESP32-EVB does have a specific delay circuit to only allow power to the PHY after boot and therefore does not need to control the PHY power.
+
+For other boards, the default is often GPIO-17, but this may change per board.
+
+RMII PHY Wiring
+"""""""""""""""
+
+Apart from these GPIO pins, there is a number of other pins reserved on the ESP32 for RMII PHY Wiring.
+
+Since these GPIO pin assignments cannot be changed, it is also not needed to configure them.
+However, they also cannot be used when *RMII PHY* is used.
+
+.. include:: ../Reference/Ethernet_PHY_ESP32.rst
+
+
+-------------------
+GPIO boot states
+-------------------
+
+For some GPIO pins, the boot state (initial configuration after startup) can be configured.
+
+Some differences exist between ESP8266 and ESP32:
+
+* ESP8266 can't initialize GPIO's 6, 7 and 8 (technical limitation of ESP8266 chip) and 16 (always has pull-down setting)
+* ESP32 can't initialize GPIO's from 16 and up (settings storage limitation, could be initialized from Rules in `System#Boot` event)
+
+*ESP8266 GPIO boot states:*
+
+.. image:: Hardware_GPIObootstatesESP8266.png
+
+*ESP32 GPIO boot states:*
+
+.. image:: Hardware_GPIObootstatesESP32.png
@@ -0,0 +1,117 @@
+Arduino IDE
+***********
+
+The preferred way to build ESPEasy is using PlatformIO.
+However, there are still lots of people happily using Arduino IDE.
+Therefore we try to keep the project source compatible with Arduino IDE.
+
+Since development is not done in Arduino IDE, it may happen that some commit breaks Arduino IDE compatibility.
+Usually it is something as simple as an include not being relative compared to the file which is being compiled.
+This is a bug, which PlatformIO does not complain about and thus can be missed easily during development.
+
+If something like this happens, please open an issue (or pull request) for it on GitHub.
+Also, if someone knows a build flag for PlatformIO to signal those errors, please let us know.
+
+
+Prepare Arduino IDE
+===================
+
+When installing Arduino IDE, its default installation folder structure is to share libraries and sketches among all installations of Arduino IDE.
+If you only build one project, this is just fine. 
+However, if you try to build several projects or versions of projects, then you will run into library dependency issues.
+
+See: `how to create portable version of Arduino IDE <https://www.arduino.cc/en/Guide/PortableIDE>`_
+
+For building ESPEasy it is adviced to use a "portable installation" of Arduino IDE.
+
+
+Arduino IDE Prerequisites
+=========================
+
+For building ESPEasy in Arduino IDE, you need to install the board manager and ESP8266/ESP32 library.
+
+See these excellent tutorials:
+
+* `How to install ESP8266 board for Arduino IDE <https://randomnerdtutorials.com/how-to-install-esp8266-board-arduino-ide/>`_
+* `How to install ESP32 board for Arduino IDE <https://randomnerdtutorials.com/installing-the-esp32-board-in-arduino-ide-windows-instructions/>`_
+
+
+Download ESPEasy Sources
+========================
+
+The sources can be downloaded from `GitHub <https://github.com/letscontrolit/ESPEasy>`_ as ZIP file.
+
+In this document, the given file system paths refer to a portable installation of Arduino IDE in ``D:\temp\Arduino-EspEasy\``
+
+The structure in the ZIP file are made for use in PlatformIO.
+To use the source in Arduino IDE, you have to split the sources into 2 parts:
+
+* The used libraries: ``D:\temp\Arduino-EspEasy\portable\sketchbook\libraries``
+* The source code: ``D:\temp\Arduino-EspEasy\portable\sketchbook\ESPEasy``
+
+Some used libraries differ from the original ones to make them work with ESPEasy.
+So make sure to use the ones supplied in the ZIP file in the ``lib`` folder.
+If some libraries are missing from the ``lib`` folder, you can install them via the Arduino IDE library manager.
+
+The source code files to be placed in the ``ESPEasy`` directory must be taken from the (first) ``src`` directory in the ZIP file.
+Meaning the file ``ESPEasy.ino`` must be in the ``ESPEasy`` folder. (including all files in sub folders)
+
+
+Building using Custom.h
+=======================
+
+There is a ``Custom-sample.h`` file supplied, which has lots of defines that can be set or uncommented to make a specific build 
+including just the plugins and controllers needed and maybe even some proper default settings.
+
+To use this file, it must be renamed to ``Custom.h``.
+
+There are two options to define ``USE_CUSTOM_H`` for an Arduino IDE build:
+
+* In ``ESPEasy_common.h``: uncomment ``//#define USE_CUSTOM_H``
+* Create a personal ``platform.local.txt`` file
+
+Define USE_CUSTOM_H in ESPEasy_common.h
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+PlatformIO does recognize the presence of this file when building a ``Custom`` build environment.
+But for Arduino IDE, a single line must be uncommented in ``ESPEasy_common.h``
+
+Make sure to uncomment this line at the start of ``ESPEasy_common.h``: ``//#define USE_CUSTOM_H``
+This define makes sure the ``Custom.h`` file is actually included during build.
+
+
+Build definition via platform.local.txt
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Locate the file ``platform.txt`` in the esp8266 platform directory of ArduinoIDE.
+
+The exact location depends on the installation, usually in a directory below the main application called ``hardware/esp8266.com/``.
+
+In the same directory add an (untraced) file called ``platform.local.txt`` with the following lines:
+
+.. code-block:: none
+
+   compiler.minsize=
+   compiler.c.extra_flags=-DUSE_CUSTOM_H -DPUYA_SUPPORT=0 -DCONFIG_FREERTOS_ASSERT_DISABLE -DCONFIG_LWIP_ESP_GRATUITOUS_ARP -DCONFIG_LWIP_GARP_TMR_INTERVAL=30 -DCORE_POST_2_5_0 -DCORE_POST_2_6_0 -DNDEBUG -DICACHE_FLASH -DWEBSERVER_RULES_DEBUG=0 -DVTABLES_IN_FLASH -mtarget-align -Werror=unused-variable {compiler.minsize}
+   compiler.c.elf.extra_flags=-DUSE_CUSTOM_H -DPUYA_SUPPORT=0 -DCONFIG_FREERTOS_ASSERT_DISABLE -DCONFIG_LWIP_ESP_GRATUITOUS_ARP -DCONFIG_LWIP_GARP_TMR_INTERVAL=30 -DCORE_POST_2_5_0 -DCORE_POST_2_6_0 -DNDEBUG -DICACHE_FLASH -DWEBSERVER_RULES_DEBUG=0 -DVTABLES_IN_FLASH -mtarget-align -Werror=unused-variable {compiler.minsize}
+   compiler.S.extra_flags=-DUSE_CUSTOM_H -DPUYA_SUPPORT=0 -DCONFIG_FREERTOS_ASSERT_DISABLE -DCONFIG_LWIP_ESP_GRATUITOUS_ARP -DCONFIG_LWIP_GARP_TMR_INTERVAL=30 -DCORE_POST_2_5_0 -DCORE_POST_2_6_0 -DNDEBUG -DICACHE_FLASH -DWEBSERVER_RULES_DEBUG=0 -DVTABLES_IN_FLASH -mtarget-align -Werror=unused-variable {compiler.minsize}
+   compiler.cpp.extra_flags=-DUSE_CUSTOM_H -DPUYA_SUPPORT=0 -DCONFIG_FREERTOS_ASSERT_DISABLE -DCONFIG_LWIP_ESP_GRATUITOUS_ARP -DCONFIG_LWIP_GARP_TMR_INTERVAL=30 -DCORE_POST_2_5_0 -DCORE_POST_2_6_0 -DNDEBUG -DICACHE_FLASH -DWEBSERVER_RULES_DEBUG=0 -DVTABLES_IN_FLASH -mtarget-align -Werror=unused-variable {compiler.minsize}
+   compiler.ar.extra_flags=
+   compiler.objcopy.eep.extra_flags=
+   compiler.elf2hex.extra_flags=
+
+
+Board definitions
+=================
+
+In Arduino IDE you must prepare the environment variables yourself.
+
+.. image:: ArduinoIDEBoardConfig.png
+
+* Board: "Generic ESP8266 Module"
+* Flash Size: Pick the one reflecting your board (4M flash 1M FS is the most used)
+* Flash Mode: "DOUT"
+
+The other settings are likely to be correct when using the defaults.
+See the screenshot to be sure.
+
@@ -0,0 +1,45 @@
+Documentation
+*************
+
+For documentation we use Sphinx and this will be read by ReadTheDocs.
+We use the `Sphinx Bootstrap Theme <https://github.com/ryan-roemer/sphinx-bootstrap-theme>`_
+
+This documentation is included in the GitHub repository.
+It allows us to create documentation per version of ESPEasy.
+
+See also the `ESPEasy wiki <https://www.letscontrolit.com/wiki/index.php/ESPEasy>`_
+for more documentation which has not been moved here.
+
+Needed Python packages::
+
+   pip install sphinx recommonmark sphinx_bootstrap_theme
+
+PlatformIO with Atom
+====================
+
+With the ESPEasy project open in Atom, open the PIO terminal in Atom.
+
+Install dependencies::
+
+   cd docs
+   pip install ... (see needed Python packages above)
+
+Build on Windows::
+
+   cd docs
+   .\make.bat html
+
+Build on Linux/Mac::
+
+   cd docs
+   ./make html
+
+
+LaTeX (PDF) build on Linux
+==========================
+
+To build a PDF document of this documentation, you need to have LaTeX installed and some texlive packages.
+
+Via apt-get installed packages::
+
+  sudo apt-get install xzdec texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra
@@ -0,0 +1,155 @@
+PlatformIO
+**********
+
+ESP easy can be built using the Arduino IDE or PlatformIO (PIO).
+Arduino IDE is not being used during development, so it may take some more effort to get it setup for building ESPeasy.
+
+We advice to use PlatformIO as build environment.
+
+PlatformIO is just the build, test and upload environment for many micro controllers like the ESP8266 and ESP32 we use.
+
+On top of that you need to use an editor, or so called IDE in which PlatformIO will be used.
+
+The two main choices are:
+
+* Atom
+* Microsoft Visual Studio Code. (MS VS-Code)
+
+Both are free to use and are available for Windows, MacOS and Linux.
+
+Apart from these two, there are more available, like Eclipse and probably more.
+
+
+PlatformIO Prerequisites
+========================
+
+PlatformIO does need at least the following:
+
+* Python
+* Git command line tools (`download <https://git-scm.com/downloads>`_)
+
+For most operating systems, Python is already present, but for Windows you may need to install it.
+Starting October 2019, Python 3.x is supported in all build tools we use for ESPEasy.
+
+Please follow `these steps <https://docs.platformio.org/en/latest/faq.html#faq-install-python>`_ to 
+install Pyton in Windows for PlatformIO.
+
+**Do not forget to check "Add Python xxx to PATH".**
+
+Windows ExecutionPolicy
+-----------------------
+
+For PlatformIO 4.1.x and newer in Windows, you may need to change the Windows ExecutionPolicy 
+to be able to start a powershell script.
+PlatformIO does use a PowerShell script to activate the Python virtual environment.
+
+Default Windows security settings prevent execution of a PowerShell script.
+
+Enter in the PowerShell terminal window in VScode::
+
+    Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser
+
+Please note this does lower your security, so make sure you know its implications.
+See `Microsoft - About Execution Policies <https:/go.microsoft.com/fwlink/?LinkID=135170>`_ for more details.
+
+
+PlatformIO with Atom
+====================
+
+
+
+PlatformIO with VS-Code
+=======================
+
+install
+-------
+
+For development of ESPeasy, a number of extensions has to be installed in VS-Code:
+
+* PlatformIO IDE (by PlatformIO)
+* C/C++ IntelliSense (by Microsoft)
+* Arduino for Visual Studio Code (by Microsoft)
+* Uncrustify (by Laurent Tréguier)
+
+Optional:
+* Bookmarks (by Alessandro Fragnani)
+* Bracket Pair Colorizer 2 (by CoenraadS)
+* GitLens - Git supercharged (by Eric Amodio)
+* Todo Tree (by Gruntfuggly)
+* All Autocomplete (by Atishay Jain)
+* Excel Viewer (by GrapeCity)
+
+
+Uncrustify
+----------
+
+The extension Uncrustify is mainly to format the code using a standard code format definition.
+This code format standard is defined in the file uncrustify.cfg in the main directory of this repository.
+For new code contributions, it is highly appreciated if the code is formatted using this tool.
+
+To do so:
+
+* Right click mouse in editor
+* "Format Document"
+
+The first time (after installing uncrustify) it must be confirmed to use Uncrustify as formatter and using the default suggested config file.
+
+
+Load a project using PlatformIO
+-------------------------------
+
+If you have PIO installed and the source tree cloned to your hard drive, then you can open the main dir of the repository.
+The main directory of the repository is the level with platformio.ini in it.
+
+Then in a few moments after opening the directory, on the left there will appear an alien logo, the logo of PlatformIO.
+If you click that one, you will get a tree with lots and lots of project tasks and environments.
+
+It is important  to note that PlatformIO does everything based on environments, which are defined in the platformio.ini file.
+In the PlatformIO menu (on the left) everything is grouped per environment.
+
+An environment entry has several tasks, like:
+
+* Build
+* Upload
+* Monitor
+* Upload and Monitor
+* ... many more.
+
+Some of these options only are available when you have registered with PlatformIO and some are only for paid subscriptions.
+At least the basic ones used for almost any user are available with the free account.
+
+The environment definitions all have at least the used micro controller in the name and the amount of flash memory used.
+
+For example:
+
+* ..._ESP8266_4M -> ESP8266 has external flash, which can vary in size from 512 kB to 16 MB.
+* ..._ESP8285_1M -> ESP8285 has the flash internal, so is always 1 MB.
+* ..._ESP32_4M316k -> ESP32 with 4 MB flash and a 1.8 MB partition for the sketch. (316k SPIFFS)
+
+Make a custom build using PlatformIO
+------------------------------------
+
+The easiest is to go for the environment "env:custom_ESP8266_4M" and unfold that one.
+Then select "Build" to see if it will start building.
+
+If that's working, you can open the file "pre_extra_script.py" and add or remove the plugins and controllers you need.
+That Python file is used in the "env:custom_ESP8266_4M" to define what should be embedded and what not.
+
+For example to have only the controller "C014", you can remove "CONTROLLER_SET_ALL", and just add "USES_C014", 
+The same for the plugins you need.
+
+The file is built in the ".pio/build/...." directory right under the main repository directory (the one with the platformio.ini in it)
+
+All builds will be made in a directory with the same name as the environment used.
+
+
+
+Upload to ESP
+=============
+
+
+
+Linux
+-----
+
+For Linux, you may need to install 99-platformio-udev.rules to make PlatformIO upload tools work in vscode.
@@ -0,0 +1,181 @@
+Project Structure
+*****************
+
+The files and directories in the ESPEasy file repository are organized in folders.
+Some of the choices for folder structure may not look very logical at first sight and may need some explanation to understand.
+
+
+ESPEasy Project Directories
+===========================
+
+Below a list of the most important directories and files used in this project.
+
+* ``.pio/`` Working dir for PlatformIO (Ignored by Git)
+* ``build_output/`` The output directory where all built files are collected.
+* ``dist/`` Files also includd in the nightly builds (e.g. blank flash files and ESPEasy flasher)
+* ``docs/`` Documentation tree using Sphinx to build the documents.
+* ``hooks/`` Used for the continous integration process, used by Travis CI.
+* ``include/`` PlatformIO's suggested folder for .h files (not yet used)
+* ``lib/`` Libraries used in this project. Some have patches which make them different from the maintainers version.
+* ``misc/`` Additional files needed for some use cases, like specialized a firmware for some boards or decoder files for the TTN project.
+* ``patches/`` Patches we apply during build for core libraries.
+* ``src/`` The source code of ESPeasy
+* ``static/`` Static files we use in ESPEasy, like CSS/JS/ICO files.
+* ``test/`` Test scripts to be used in the continous integration process.
+* ``tools/`` Tools to help build ESPeasy.
+* ``tools/pio/pre_custom_esp32.py`` Python helper script for building custom ESP32 binary
+* ``tools/pio/pre_extra_script.py`` Python helper script for building custom ESP8266 binary
+* ``venv/`` Directory to store the used Python Virtual Environment. (Ignored by Git)
+* ``platformio.ini``  Configuration file for PlatformIO to define various build setups.
+* ``uncrustify.cfg``  Configuration file for Uncrustify, to format source code using some uniform formatting rules.
+* ``requirements.txt``  List of used Python libraries and their version (result of ``pip freeze`` with Virtual env active)
+* ``esp32_partition_app1810k_spiffs316k.csv`` Used partition layout in ESP32 builds.
+
+
+ESPEasy src dir
+===============
+
+In order to compile the project using PlatformIO, you need to make sure the ``platformio.ini`` file is in the 
+root of the project dir opened in the editor.
+
+The ``src/`` directory has the source files of the project.
+
+In this directory, there is another ``src/`` dir, which is needed by ArduinoIDE in order to find files in sub-directories.
+Arduino IDE also demands include directives to be relative compared to the file they are used in. 
+For example: ``#include "../DataStructs/Settings.h"``
+
+We are currently working on converting the core ESPeasy code from .ino files into .h/.cpp files. (see PR #2617 and issue #2621)
+
+The header and source files are organized in a few directories in ``src/src/``.
+
+* ``Commands`` Functions to process commands.
+* ``ControllerQueue`` Mainly macro definitions for the queue system used by controllers.
+* ``DataStructs`` Data structures used in ESPEasy. Note that some of them are stored in settings files, so take care when changing them.
+* ``Globals`` Declaration of global variables. Declare them using ``extern`` in .h files and construct them in .cpp files or else you may end up with several instances of the same object with the same name.
+* ``Static`` C++ encoded version of objects which have to be included in the binary. N.B. JS and CSS files are minified.
+
+The Arduino based .ino files are still in the ``src/`` directory. (and some .h files, which are not yet moved)
+
+In the end, there should be only .ino files left for the plugins and controllers and ``ESPEasy.ino`` 
+All other .ino files used in the ESPEasy core should be converted to .h/.cpp.
+
+This conversion is needed to have full control over ``#define`` statements used to determine what is included in a binary and what not.
+This also allows for more flexible control over user defined builds.
+
+
+ESPEasy 'nightly builds'
+========================
+
+On a regular basis we make so called "nightly builds".
+These can be found here: `ESPEasy releases download <https://github.com/letscontrolit/ESPEasy/releases>`_ .
+
+See the included ``README.txt`` in the downloaded ZIP file for more detailed information of the content of that build.
+
+We have 2 main build platforms:
+
+* ESP8266/ESP8285
+* ESP32
+
+For these platforms we also have a lot of different build setups.
+
+The filename is quite descriptive:
+  ESP_Easy_mega-<date>_<buildType>_<chip>_<memorySize>.bin
+
+Build Type
+----------
+
+Build type can be:  (differ in included plugins)
+
+* normal  => Only Stable plugins and controllers
+* test    => Stable + Testing
+* dev     => Stable + Testing + Development
+
+There is also a number of special builds:
+
+* normal_IR => "Normal" + IR receiver/transmitter plugins and library
+* hard_xxxxx => Special builds for some off-the-shelf hardware.
+* minimal_ESP82xx_1M_OTA => Minimum number of plugins and a limited set of controllers included to be able to perform a 2-step OTA on 1 MB flash nodes.
+* normal_core_xxx => "Normal" using core xxx (e.g. 2.6.3)
+* normal_beta => "Normal" using the staged (beta) branch of the esp8266/Arduino repository.
+
+ESP Chip Type
+-------------
+
+* ``ESP8266`` Most likely option.
+* ``ESP8285`` Used in some Sonoff modules. This chip has embedded flash, so no extra flash chip.
+* ``ESP32``   Experimental support at this moment.
+
+Memory Size and Partitioning
+----------------------------
+
+* ``1M`` 1 MB flash modules (e.g. almost all Sonoff modules)
+* ``2M`` 2 MB flash modules (e.g. Shelly1/WROOM02)
+* ``4M`` 4 MB flash modules (e.g. NodeMCU/ESP32)
+* ``16M`` 16 MB flash modules (e.g. Wemos D1 mini pro)
+
+Please note that the performance of 14MB SPIFFS (16M flash modules) is really slow.
+All file access takes a lot longer and since the settings are also read from flash, the entire node will perform slower.
+See `Arduino issue - SPIFFS file access slow on 16/14M flash config <https://github.com/esp8266/Arduino/issues/5932>`_
+
+If these speed issues will be fixed, it is very likely the SPIFFS must then be re-partitioned, thus loosing all data in the SPIFFS.
+
+Special memory partitioning:
+
+* ``2M256``  2 MB flash modules (e.g. Shelly1/WROOM02) with 256k SPIFFS (only core 2.5.0 or newer)
+* ``4M316k`` For ESP32 with 4MB flash, sketch size is set to 1.8 MByte (default: 1.4 MByte)
+* ``4M1M``   4MB flash, 1 MB SPIFFS. Default layout for 4MB flash.
+* ``4M2M``   4MB flash, 2 MB SPIFFS. Introduced in October 2019. Only possible with core 2.5.2 or newer.
+
+.. warning::
+    Changing between builds with different flash layout will destroy the settings!
+
+    The SPIFFS partition will be lost, which contains all settings.
+
+
+
+Difference between .bin and .bin.gz
+-----------------------------------
+
+Starting on esp8266/Arduino core 2.7.0, it is possible to flash images that have been compressed using GZip.
+
+Please note that this only can be used on installs already running a very recent build.
+
+This also means we still need to update the 2-step updater to support .bin.gz files.
+
+
+.. warning::
+    Currently there is NO 2-step OTA image available supporting ``.bin.gz`` images.
+
+
+ESP32 builds
+------------
+
+There are 3 builds for ESP32:
+
+* ``custom_ESP32_4M316k``  Build template using either the plugin set defined in ``Custom.h`` or ``tools/pio/pre_custom_esp32.py``
+* ``test_ESP32_4M316k``  Build using the "testing" set of plugins for ESP32
+* ``test_ESP32-wrover-kit_4M316k``  A build for ESP32 including build flags for the official WRover test kit.
+
+Since ESP32 does have its flash partitioned in several blocks, we have 2 bin files of each ESP32 build:
+
+* ``test_ESP32_4M316k.bin`` Use for OTA upgrades.
+* ``test_ESP32_4M316k-factory.bin`` Use on clean nodes as initial inistall.
+
+The binary with ``-factory`` in the name must be flashed on a new node, via the serial interface of the board.
+This flash must be started at address 0.
+
+The binary without ``-factory`` can be used for OTA updates. (OTA for ESP32 is added in May 2020)
+
+
+Blank Images
+------------
+
+To help recover from a bad flash, there are also blank images included.
+
+* ``blank_1MB.bin``
+* ``blank_2MB.bin``
+* ``blank_4MB.bin``
+* ``blank_16MB.bin``
+
+When the wrong image is flashed, or the module behaves unstable, or is in a reboot loop,
+flash these images first and then the right image for the module.
@@ -0,0 +1,54 @@
+.. include:: ../Plugin/_plugin_substitutions_p00x.repl
+.. _P000_page:
+
+|P000_typename|
+==================================================
+
+|P000_shortinfo|
+
+Plugin details
+--------------
+
+Type: |P000_type|
+
+Name: |P000_name|
+
+Status: |P000_status|
+
+GitHub: |P000_github|_
+
+Maintainer: |P000_maintainer|
+
+Used libraries: |P000_usedlibraries|
+
+
+Supported hardware
+------------------
+
+|P000_usedby_GPIO|, |P000_usedby_RTTTL|
+
+Commands available
+------------------
+
+.. include:: P001_commands_GPIO.repl
+.. include:: P001_commands_RTTTL.repl
+
+.. Events
+.. ~~~~~~
+
+.. .. include:: P000_events.repl
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
@@ -0,0 +1,106 @@
+.. include:: ../Plugin/_plugin_substitutions_p00x.repl
+.. _P000_Buzzer_page:
+
+Buzzer (RTTTL)
+==============
+
+|P000_typename|
+|P000_status|
+
+.. image:: P000_Buzzer_RTTTL_1.jpg
+
+Introduction
+------------
+
+RTTTL (Ring Tone [Text] Transfer Language) was developed by Nokia to play more "easy on the ear" melodies as ringtones for mobile phones. The tunes over all characteristics are created by using three different commands:
+
+**d** - duration
+
+**o** - octave
+
+**b** - tempo (beat)
+
+After that the actual tune is then created using standard notes (a, b, c, d, e, f, and g), before the note the duration is set, after the note the octave is set:
+
+.. code-block:: none
+
+   <duration><note><octave>
+
+To compose a jingle you separate the notes with a comma.
+
+Specifications:
+ * Output sound
+
+
+Wiring
+------
+
+.. code-block:: none
+
+  ESP               Buzzer
+  GPIO       <-->   I/O
+
+  Power
+  3.3V       <-->   VCC
+  GND        <-->   GND
+
+
+Setup
+-----
+
+No device is needed, generally you use rules to activate different notifications, or you send commands to activate them. Below you find more information on how to do this.
+
+Rules examples
+--------------
+
+From ESP Easy v2.0.0 its possible to play melodies via `RTTTL <https://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language#Technical_specification>`_ (don't forget to remove the spaces and replace # with -, this might be fixed in future releases):
+
+.. code-block:: none
+
+   http://<ESP IP address>/control?cmd=rtttl,14:d=4,o=5,b=112:8a,8a,a,8a,8a,a,8a,8c6,8f.,16g,2a,8a-,8a-,8a-.,16a-,8a-,8a,8a.,16a,8a,8g,8g,8a,g,c6
+
+This plays a melody on pin 14.
+
+You can also use these from rules. We use it to let our alarm system give feedback to the user via a piezo speaker.
+
+To make a boot-sound on startup, create a rule like this:
+
+.. code-block:: none
+
+   On System#Boot do
+     rtttl,14:d=10,o=6,b=180,c,e,g
+   endon
+
+`A place to find more tunes <http://www.picaxe.com/RTTTL-Ringtones-for-Tune-Command/>`_, all saved as txt files.
+
+Besides RTTTL it's also possible to play a single tone on a pin, via a buzzer, speaker or piezo element:
+
+.. code-block:: none
+
+   http://<ESP IP address>/control?cmd=tone,14,1300,200
+
+Plays a 1300 Hz tone for 200 ms on GPIO-14.
+
+Indicators (recommended settings)
+---------------------------------
+
+No device is needed.
+
+Commands
+--------
+
+.. include:: P001_commands_RTTTL.repl
+
+Where to buy
+------------
+
+.. csv-table::
+  :header: "Store", "Link"
+  :widths: 5, 40
+
+  "AliExpress","`Link 1 ($) <http://s.click.aliexpress.com/e/cMvVWYS4>`_"
+
+|affiliate|
+
+.. More pictures
+.. -------------
@@ -0,0 +1,125 @@
+.. include:: ../Plugin/_plugin_substitutions_p00x.repl
+.. _P000_Level_converter_page:
+
+Level converter
+===============
+
+.. image:: P000_Level_converter_1.jpg
+
+Introduction
+------------
+
+Level-converters, aka level-shifters, aka voltage dividers, are used to adapt between a 3.3V device like the ESP8266 and devices using 5V or more internally.
+The ESP8266 runs with 3.3V - many devices need 5V or more, for example a LCD display or a Wiegand card reader. It is said that the ESP8266 can
+take 5V at its inputs. Basically this is correct and confirmand by Espressif, the manufacturer. Anyways this as always has some limitations.
+
+**First**, overcurrent. If you use a GPIO as input and the output of the connected device has 5V it should work. But if the internal resistance
+of the device is low the current might exceed the limits of the ESP8266. With some specific settings of the ESP8266 the GPIO can not take 5V,
+who checks every plugin or never made a setting mistake? So for making sure no GPIO is blown accidentally or by a bug some measurements should be taken.
+
+**Second**, some devices need higher voltage if GPIO used as output. For example the PCF8574 or the MCP23017, port multiplexer. This chips use
+3.3V or 5V as you choose. For some purpose higher voltage is useful. If using 5V there is a point you have to take care for:
+
+The High and Low levels depend on the voltage!
+
+With the PCF8574 the minimum "High" level Vih = 0.7 × Vdd, with 5V as Vdd it is 3.5V. With the MCP23017 the Vih = 0.8 × Vdd, with 5V as Vdd it is 4V.
+(Vdd is the supplied voltage) So with 3.3V max from the ESP we are too low. It might work, it might fail. Worse, it might work with one chip
+and fail with another one due to tolerances. In this case a level-converter is needed.
+
+Specifications:
+ * Level shifter, aka logic converter. Used to turn logics of higher voltage (5V) down to ESP friendly voltage (3.3V).
+
+.. note::
+   **Troubleshooting**:
+   If your level converter does not work, please check cabling first. As said cabling mistakes and slack joints with the usual cheap breadboard cables are the most likely reason.
+   If you use breakout board type level converters have a second one at hand. We've seen some "dead on arrival", other died by electrostatic discharge.
+   And again, breadboards are somewhat unreliable. Use a digital multi-meter to check contacts and wires.
+
+Wiring
+------
+
+.. warning::
+   Be careful with wiring. A wrong connection from 5V to the 3.3V rail can cause damages of the ESP and/or the power supply.
+   A direct connection by mistake from 5V to a GPIO may fry your ESP! Handle level-shifters with some care.
+   The used FET transistors are somewhat sensible against electrostatic discharge. Use a anti-static mat.
+
+.. code-block:: none
+
+  ESP                 Level converter             Connected hardware
+  GPIO (X)     <-->   3A, LV1, A1 etc.     <-->   5A, HV1, B2 etc.
+  GPIO (Y)     <-->   3B, LV2, A2 etc.     <-->   5B, HV2, B2 etc.
+
+  Power
+  3.3V         <-->   3V3, LV, VA, 3V etc.
+  5.0V         <-->   VIN, HV, VB, +5V etc.
+  GND          <-->   GND
+
+Different ways of level converting
+----------------------------------
+
+Other than using a level converter it is possible to do it "manually" through resistors.
+
+Just Input - simple unidirectional
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As an example we will use a HC-SR04 ultrasonic distance metering module. The HC-SR04 needs 5V, it will not work with 3.3V.
+It works like bat ears, sending ultrasonic pulses and waiting for the echo. It has an input "Trigger" for sending ultrasonic pulses and an output "Echo" for the received signals.
+The "trigger" input is no problem as it can take 3.3V for "High". Just connect it to the desired GPIO. But the "Echo" pin sends back 5V signals!
+As this signaling is working just in one direction ("unidirectional") from the HC-SR04 to the ESP8266, a simple voltage divider does the job. Look at the schematic:
+
+.. image:: P000_Level_converter_2.jpg
+
+Note the two resistors R1 and R2, configured as a voltage divider. The divider gives 2.2/(1.2+2.2) = 0.65 so with 5V you get 5V × 0.65 = 3.25V at the GPIO pin.
+
+Just Input - precise unidirectional
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The simple circuit with two resistors has one disadvantage. It is calculated for 5V. For other voltages you have to calculate another pair of resistor values. And worse,
+spikes, short spikes of high voltage from unstable power supply or other reasons) pass through the divider. A better and more precise way is using a Zener diode.
+A Zener diode simplified is a semiconductor that gets conductive at a specific voltage.
+
+.. image:: P000_Level_converter_3.jpg
+
+Here a Zener diode is used as voltage limiter. The resistor must not be omitted, it is necessary to limit the current. If a 5V signal comes the diode gets conductive - it would
+short circuit the device output without the resistor. This circuit is dimensioned for input voltages from 5V to 9V (resistor should have 0.25W!). It can be used nicely for Wiegand
+card readers for example. You may use even higher voltages, for example if you want to check a 24V pump. You need an adapted resistor value for that.
+
+Input and Output - Bidirectional Level Converter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For devices that use one wire for input and output ("bidirectional") or devices that need higher voltage on an input an active level converter is necessary.
+This applies mainly to I²C devices as SCL (the clock signal) comes with 3.3V from the ESP and the SDA (data signal) goes in both directions. There are
+specialized chips for this purpose. Most of them have 8 channels - bit of an overkill for an ESP. There is a much simpler way you can buy as a cheap
+breakout board or solder together yourself.
+
+.. image:: P000_Level_converter_4.jpg
+
+A little FET and two resistors do the job. This is the circuit most level shifters you can buy at the market use.
+
+How does it work? Lets have a simplified look in a nutshell. A FET gets conductive if the voltage at the gate (pin 1) is higher then the voltage at
+the source (pin 2). So if the ESP gives 3.3V (High), gate and source have same voltage - the FET isolates both sides (pin 2 & 3) from each other.
+If the ESP goes to 0.3V (Low), the gate still has 3.3V - now the FET gets conductive pulling the 5V-side down. If the 5V-side goes to zero (low)
+because your device sends data, the diode inside the FET gets conductive and pulls the 3.3V side down to nearly zero (Low).
+
+Use of a dedicated level converter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Quite an easy job. The pins on a level shifter are usually divided in a LV (Low Voltage) and a HV (High Voltage) side. Sometimes it is just called 3V and 5V.
+Connect the 3V pin to 3.3V from ESP and the 5V pin to 5V from your device, for example a LCD display. Don't forget ground, some breakouts have some additional
+capacitors which need it. Then connect the GPIOs from the ESP to the LV side, the equivalent pins from your 5V device to the HV side. That's all.
+
+.. image:: P000_Level_converter_5.jpg
+
+Where to buy
+------------
+
+.. csv-table::
+  :header: "Store", "Link"
+  :widths: 5, 40
+
+  "AliExpress","`Link 1 ($) <http://s.click.aliexpress.com/e/c5dMH05S>`_"
+
+|affiliate|
+
+.. More pictures
+.. -------------
@@ -0,0 +1,104 @@
+.. include:: ../Plugin/_plugin_substitutions_p00x.repl
+.. _P000_Piezo_element_page:
+
+Piezo element
+=============
+
+|P000_typename|
+|P000_status|
+
+.. image:: P000_Piezo_element_RTTTL_1.jpg
+
+Introduction
+------------
+
+RTTTL (Ring Tone [Text] Transfer Language) was developed by Nokia to play more "easy on the ear" melodies as ringtones for mobile phones. The tunes over all characteristics are created by using three different commands:
+
+**d** - duration
+
+**o** - octave
+
+**b** - tempo (beat)
+
+After that the actual tune is then created using standard notes (a, b, c, d, e, f, and g), before the note the duration is set, after the note the octave is set:
+
+.. code-block:: none
+
+   <duration><note><octave>
+
+To compose a jingle you separate the notes with a comma.
+
+Specifications:
+ * Output sound
+
+
+Wiring
+------
+
+.. code-block:: none
+
+  ESP              Piezo
+  GPIO     <-->    Positive (red)
+  GND      <-->    Negative (black)
+
+
+Setup
+-----
+
+No device is needed, generally you use rules to activate different notifications, or you send commands to activate them. Below you find more information on how to do this.
+
+Rules examples
+--------------
+
+From ESP Easy v2.0.0 its possible to play melodies via `RTTTL <https://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language#Technical_specification>`_ (don't forget to remove the spaces and replace # with -, this might be fixed in future releases):
+
+.. code-block:: none
+
+   http://<ESP IP address>/control?cmd=rtttl,14:d=4,o=5,b=112:8a,8a,a,8a,8a,a,8a,8c6,8f.,16g,2a,8a-,8a-,8a-.,16a-,8a-,8a,8a.,16a,8a,8g,8g,8a,g,c6
+
+This plays a melody on pin 14.
+
+You can also use these from rules. We use it to let our alarm system give feedback to the user via a piezo speaker.
+
+To make a boot-sound on startup, create a rule like this:
+
+.. code-block:: none
+
+   On System#Boot do
+     rtttl,14:d=10,o=6,b=180,c,e,g
+   endon
+
+`A place to find more tunes <http://www.picaxe.com/RTTTL-Ringtones-for-Tune-Command/>`_, all saved as txt files.
+
+Besides RTTTL it's also possible to play a single tone on a pin, via a buzzer, speaker or piezo element:
+
+.. code-block:: none
+
+   http://<ESP IP address>/control?cmd=tone,14,1300,200
+
+Plays a 1300 Hz tone for 200 ms on GPIO-14.
+
+Indicators (recommended settings)
+---------------------------------
+
+No device is needed.
+
+Commands
+--------
+
+.. include:: P001_commands_RTTTL.repl
+
+Where to buy
+------------
+
+.. csv-table::
+  :header: "Store", "Link"
+  :widths: 5, 40
+
+  "AliExpress","`Link 1 ($) <http://s.click.aliexpress.com/e/CG00mPI>`_"
+
+|affiliate|
+
+
+.. More pictures
+.. -------------
@@ -0,0 +1,340 @@
+.. include:: ../Plugin/_plugin_substitutions_p00x.repl
+.. _P000_Relay_page:
+
+Relay
+=====
+
+|P000_typename|
+|P000_status|
+
+.. image:: P000_Relay_1.jpg
+
+Introduction
+------------
+
+The ESP8266 can't switch high currents or voltages and no AC at all. But it can switch a relay that can switch high load, isolating high
+voltage from the ESP circuit. There are several relay types in the wild.
+
+The ESP can control a relay using one of it's GPIO pins. All relay boards that work with Arduino should also work with the ESP module.
+Note this is only a possible application of the ESPs ability to send a logic 1/0 (TTL at 3.3V) on a GPIO. These relay are usually available
+as 1,2,4,8,16 Relay modules and work electromagnetically. They can switch both AC/DC(or imitate a button press of a remote for example)
+as they are "power operated mechanical switches". Each relay has the screw terminal. The middle one is usually "always connected" terminal.
+The NC contact will be connected to the middle terminal when the relay is not powered. The NO is connected when the relay is powered
+and activated. Note that there are "active high" and "active low" versions of these relays.
+
+There are mainly two relay types in the wild: The good old mechanical relay with the nice "click-clack" sound and the electronic relays, so called
+"Solid State Relays" (SSR) which are completely silent.
+
+Specifications:
+ * Opto coupler (mechanical)
+ * Solid state (SSR)
+
+Relays are the most used actuators in home automation. Most people use breakout boards with a relay on it. Sadly there is no "standard" relay board.
+It seems every small manufacturing garage in china has it's own layout and schematic. Some use 5V, some use 12V, some do with opto couplers, some without...
+the perfect chaos. Several problems result from this chaos. Relays keeping switched on no mater what your ESP says. Relays not switching at all.
+And last but not least - sometimes they work. Let's get some order into that chaos.
+
+.. note::
+   You have just got your brand new relay board and it does not work. What to do?
+   At first you should check the switching level. Is it switching on with "high" or with "low"?
+
+   * Connect the board to power only (5V or 12V usually).
+   * Plug a jumper cable to one of the inputs.
+   * With the other end of the cable touch GND and +Vcc (5V or 12V).
+
+   On one of these touches the relay should switch. If it switches when connecting to GND the board uses "low" as active (relay on) signal.
+   In this case diodes or a transistor / FET as described above might help.
+
+   Connect the board to the ESP carefully. Check voltages, the power supply should be able to deliver enough current for the relays!
+   Check the connection cables. Jumper cables are well known for slack joints.
+
+Mechanical relay
+----------------
+
+The mechanical relay is a simple construction.
+It consist of a coil, one or more contacts and a spring. The spring keeps the contact in the "open" position. If the coil gets current, the magnetic
+field pulls the contact into the second position, the contact closes. As soon as the current is switched off the spring pulls the contact back.
+Mechanical relays may just have one contact switching to closed if the coil works (Normally open or NO). The contact might be a changeover contact which
+has a "common" connector and a NO (open without coil current, "normally open") and a NC (closed without coil current, "normally closed") connection.
+There might even be several contacts in one relay.
+
+There are several special types of mechanical relay
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Latching relay:
+
+.. image:: P000_Relay_2.jpg
+
+One current pulse switches on and keeps on when current goes off, a second pulse switches off.
+
+
+Polarized relay:
+
+.. image:: P000_Relay_3.jpg
+
+These relays have a defined + and - pin for the coil that must be followed.
+
+.. warning:: These micro relays can not switch mains voltage! Use them for low voltage door openers or similar.
+
+Pros and cons of mechanical relays
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:green:`+` Several contacts in one relay available.
+
+:green:`+` NO/NC available.
+
+:green:`+` Limited resistance to overload and overvoltage.
+
+:red:`-` Noisy, might disturb in a living room or bedroom.
+
+:red:`-` Mechanical, moving parts that might wear out over time.
+
+:red:`-` Contact bumping when switching.
+
+:red:`-` High current for the coil, needs a transistor or FET for driving and generates peaks on power supply.
+
+:red:`-` The coil induces high voltage when switching off.
+
+Solid state relay
+-----------------
+
+The solid state relay, SSR for short, is a complex electronic circuit. It uses an opto coupler for input, this isolating the driving circuit from the load voltage.
+Isolation voltage is usually 2000V, 4000V or more. The switching element usually is a triac for AC switching types. For DC there are types with a MOSFET as switching element.
+
+There are several special types of SSR relay
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: P000_Relay_4.jpg
+
+As with the mechanical relays there are specialized types of SSR's.
+
+**AC Type** : Can only (!!) switch AC. AC with zero crossing circuit. This type switches on and off if the AC voltage is at the zero point. **Expensive** and necessary only for special applications.
+
+**DC Type** : Can only (!!) switch DC! And a lot more that are reserved for special cases.
+
+Pros and cons of SSR relays
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:green:`+` Completely noiseless
+
+:green:`+` Low driving current and voltage available. Some types can be driven directly from the ESP.
+
+:green:`+` No mechanical parts, no wearing out.
+
+:green:`+` No contact bumping.
+
+:green:`+` No voltage peaks on the low voltage side.
+
+:green:`+` Available for very high current for an affordable price.
+
+:red:`-` Very sensitive to overvoltage and overcurrent.
+
+:red:`-` No NC available usually.
+
+:red:`-` Usually with only one or sometimes three "normally open" circuits.
+
+:red:`-` Needs cooling! Smaller relays up to 5A must be mounted with at least 1cm distance to other parts.
+
+:red:`-` Bigger relays usually need a heat sink. Watch out: Heat sink may carry mains voltage with some types!
+
+:red:`-` Leak current! These relays leak some current even if switched off.
+
+Leak currents
+~~~~~~~~~~~~~
+
+Leak Current from SSR's might lead into problems under certain circumstances.
+The both types shown above ("Hoymk D3805KH" and "Mager GJ-6-L", 5A AC) were tested here.
+The Mager GJ-5-L showed a low leaking current and is useable for most purposes.
+The D3805HK showed a really high leaking current, enough for a 10W LED to glow and a small solenoid valve to keep open!
+This is not recommended for normal use.
+
+Meanwhile a third sample arrived: The SSR-D32A380/5 sold by Pollin.
+Similar to the D3805HK it shows a leaking current, as the test LED is slightly glowing in the dark when off.
+It seems to be a lower leaking then with the D3805HK, this is subject to some further investigation.
+The advantage of the Pollin SSR: It contains a small LED on the top indicating if the relay is on.
+This SSR is a bit bigger then the other two types tested, it just fits the case. So holes for the LEDs
+can be drilled on the top side of the case.
+
+.. danger::
+   Always remember that a switched-off SSR is not completely switched off!
+   Even a small leaking current is enough to give a shock. Nice surprise if you're on the ladder changing bulbs....
+
+Choosing your relay
+~~~~~~~~~~~~~~~~~~~
+
+Which relay should be used?
+
+Well, this depends on what you want to switch. If you control a heavy motor or pump, I'd always prefer a mechanical relay.
+The resistance against short overcurrent is a good point here.
+For experimenting we prefer mechanical relays too - we just love the "click" sound, i.e. we don't have to connect a load to see if it works.
+If noise counts or if you place the relay in a dusty or humid environment a SSR is the better choice. It's completely encapsulated so dust
+and humidity can't damage it. As it has no mechanical parts it is completely noise-free. So it's the perfect choice to switch lighting in a living room or sleeping room.
+Of course you have to chose a relay that fits your parameters.
+
+Which voltage you want to switch? AC or DC? Which current?
+
+If you want to use a SSR for high current you have to calculate the space for a heat sink and you have to use a vented case. All these parameters
+have to be figured into your project. It is also possible to use a small SSR to drive a really heavy external relay for a heavy machine for example.
+
+Wiring
+------
+
+.. code-block:: none
+
+  ESP               Relay (board)
+  GPIO (X)   <-->   IN1
+  GPIO (Y)   <-->   IN2
+
+  Power
+  5.0V       <-->   VCC
+  GND        <-->   GND
+
+
+Setup
+-----
+
+No device is needed, generally you use rules to activate relays, or you send commands to activate them. Below you
+find more information on how to do this.
+
+.. note::
+  If you want to monitor and have the GPIO state published you do this by adding as a |P001_typename| ,
+  it will not be a switch per say but you will get the state published automatically.
+
+
+Rules examples
+--------------
+
+.. code-block:: none
+
+    On Switch#State Do
+     if [Switch#State]=1
+      GPIO,12,1
+     else
+      GPIO,12,0
+     endif
+    EndOn
+
+This rule will turn the relay ON when the button is pressed, and OFF when released.
+
+Indicators (recommended settings)
+---------------------------------
+
+No device is needed.
+
+Commands
+--------
+
+.. include:: P001_commands_GPIO.repl
+
+How to connect your relay
+-------------------------
+
+You can connect the relay in multiple ways, we explain them all below.
+
+Basic ESP circuit: mechanical relays
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The basic circuit is simple.
+As the relay usually consumes more current as the ESP can handle it needs a transistor or FET to drive the relay.
+To suppress the voltage peak when switching off the coil a free-wheeling diode is needed. This can be a standard silicium diode, a 1N4148 for example.
+
+.. image:: P000_Relay_5.jpg
+
+Well, there is another way to switch the relay. In the above example we used a NPN transistor or a N-channel FET. A PNP transistor or P-Channel FET can be used too.
+Some board manufacturers do this and now we run into problems promptly. The relays usually need some higher voltage then the ESP, 5V or 12 V in most cases.
+The PNP transistor in the example is connected to +5V. It will switch the relay to "on" if the voltage at the input is at least 0.7V below the Vcc of 5V.
+The ESP delivers a maximum of 3.3V if the GPIO is "high", around 0.5V if it is "low". Both voltages are far below the 5V-0.7V = 4.3V threshhold of the relay board.
+The relay is permanently on, no matter what your ESP says. We can get this to work in a simple way with a 5V relay board. A standard diode has a loss of around 0.7V.
+We can use this to get a higher output level from the ESP. We simply use two diodes in the connection between relay board and ESP. This raises the voltage from the
+ESP up to 3.3v + 1.4V = 4.7V. This is above the threshhold of 4.3V. If the board uses a FET it might be necessary to use three diodes. That usually will work.
+On top: This circuit switches the relay off if the GPIO is "high", this leading to irritations sometimes.
+The picture shows the basic circuit with a PNP transistor, and the " 2 Diodes " solution:
+
+.. image:: P000_Relay_6.jpg
+
+More complex: using an opto coupler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many widespread relay boards use opto couplers. Honestly we don't know the reason besides it looks good in advertising.
+In theory the opto coupler isolates the relay coil from the ESP circuit. Well, that's nice theory. In real world we use the same power supply for relays and ESP.
+This bridges the opto coupler as the circuits are connected via power supply making the opto coupler completely useless. Anyways the relay isolates the load from
+the ESP anyways. It might be useful only if relay switching interferes with the ESP. In this case you might try a separate power supply for relay coils.
+This isolates the ESP completely from the coil circuits. Note that a jumper has to be set for that on some boards.
+Again there are two possible ways to use this circuit. The opto coupler input has one pin to the ESP and one to ground - this works without any problem but it is not widespread.
+
+.. image:: P000_Relay_7.jpg
+
+Most boards we've seen connect the opto coupler to 5V or 12V and the other input pin to the ESP.
+
+.. image:: P000_Relay_8.jpg
+
+This runs into same issues as with the PNP transistor above. The high voltage of 3.3V from ESP is far below 5V, this keeping the relay permanently active.
+The solution is same as with the transistor board above. Use some diodes between ESP and relay board usually does the job with relay boards using 5V.
+Depending on the circuit you will have to experiment how many diodes are necessary.
+
+Boards with 12V
+~~~~~~~~~~~~~~~
+
+If your relay board uses 12V and needs "Low" to switch the relay on it gets somewhat more complex. Basically it is possible to use a lot of diodes but
+it's not very handy. You may try a Zener diode of around 8.5.. 8.7 V. Honestly we don't recommend it. In this case it is better to use an additional
+transistor or FET to get it to work. This has one advantage: It inverts the switching signal so a "low" output says the relay is off.
+
+.. image:: P000_Relay_9.jpg
+
+Special designed boards
+~~~~~~~~~~~~~~~~~~~~~~~
+
+There are some boards in the wild which can be configured if "low" or "high" should switch the relay on.
+With this boards you will have to experiment a bit with your ESP and the board, there should be a combination that works.
+
+.. image:: P000_Relay_10.jpg
+
+Note the jumpers down left - that's the configuration for switching on high or low level.
+
+Basic ESP circuit: SSR
+~~~~~~~~~~~~~~~~~~~~~~
+
+This is more simple. If you got a SSR that has an input of "3...12V" or "3...30V" it usually can be driven directly from the ESP.
+The only thing you should keep in mind: Do not omit the varistor (RVx in the schematics). It protects the SSR from voltage peaks that
+may kill it within some milliseconds. Instead of the varistor a TVS diode can be used, for example a P6K400CA.
+Be careful, you have to use a bidirectional type!
+
+.. image:: P000_Relay_11.jpg
+
+It is possible to direct drive a SSR from the ESP but we won't recommend this. We prefer the same circuit as with the mechanical relay.
+It makes the relay circuit more universal and reduces load on the ESP.
+
+.. image:: P000_Relay_12.jpg
+
+Instead of the 2N2222/BC547 you may use a small FET, a BSS138 or 2N7000 / 7002. Omit the 22K resistor if useing a FET.
+R2 is needed if your relay can't take the Vcc directly. If you use a "3...30V" input SSR it's not necessary.
+
+Any opto coupler is completely needless if you use a SSR. The SSR has an opto coupler built in to isolate the load from the ESP.
+At this time there are not that much relay boards with SSR in the market, this will change over time as they get more popular.
+From what is on the market be careful what you buy. Most boards we've seen nowadays on AliExpress and Ebay have a DC relay installed - they can switch DC only! They can't switch mains voltage.
+
+Some words about DIY relay boards
+---------------------------------
+All in all it's no problem to build your own relay board fitting your needs exactly. But watch out if you want to switch
+mains voltage. There is a reason why in some countries the policies specify a minimum distance between the parts with high
+voltage and the low voltage circuits. Do not use experimental PCB's with copper pads or stripes!
+Good breakout boards are milled out, there is a gap in the PCB for isolating mains from low voltage.
+Prefer these boards over others without milling.
+
+.. danger::
+   Be very careful - mains voltage can burn your home or kill you. In case of doubt ask an expert!
+
+Where to buy
+------------
+
+.. csv-table::
+  :header: "Store", "Link"
+  :widths: 5, 40
+
+  "AliExpress","`Link 1 ($) <http://s.click.aliexpress.com/e/cM59HXVq>`_ `Link 2 ($) <http://s.click.aliexpress.com/e/cerop6s0>`_"
+
+|affiliate|
+
+
+.. More pictures
+.. -------------
--- a/Show More
+++ b/Show More