From b7dcac1ba50a2b622fec79cda7e69267a909c3ef Mon Sep 17 00:00:00 2001
From: Otto Winter <otto@otto-winter.com>
Date: Fri, 18 Jan 2019 14:50:50 +0100
Subject: [PATCH] Add ESP8266 advanced info (#128)

* Add ESP8266 advanced info

* Improve
---
 esphomeyaml/components/switch/index.rst |  4 +-
 esphomeyaml/devices/esp8266.rst         | 94 +++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 2 deletions(-)

diff --git a/esphomeyaml/components/switch/index.rst b/esphomeyaml/components/switch/index.rst
index 1a11f20ab..04b92170f 100644
--- a/esphomeyaml/components/switch/index.rst
+++ b/esphomeyaml/components/switch/index.rst
@@ -125,8 +125,8 @@ advanced stuff (see the full :doc:`API Reference </api/cover/index>` for more in
 
 .. _switch-is_on_off_condition:
 
-``switch.is_on`` / ``switch.is_off Condition
-********************************************
+``switch.is_on`` / ``switch.is_off`` Condition
+**********************************************
 
 This :ref:`condition <config-condition>` passes if the given switch is on/off.
 
diff --git a/esphomeyaml/devices/esp8266.rst b/esphomeyaml/devices/esp8266.rst
index 933cfca4d..c4207b5c2 100644
--- a/esphomeyaml/devices/esp8266.rst
+++ b/esphomeyaml/devices/esp8266.rst
@@ -47,6 +47,100 @@ Some notes on the pins:
         name: "Pin GPIO17"
         pin: GPIO17
 
+
+Special Pins
+------------
+
+.. table::
+    :class: no-center
+
+    =================== =============================================
+    ``GPIO0``           Controls Boot Mode
+    ------------------- ---------------------------------------------
+    ``GPIO1``           UART TX pin
+    ------------------- ---------------------------------------------
+    ``GPIO2``           Controls Boot Mode
+    ------------------- ---------------------------------------------
+    ``GPIO3``           UART RX pin
+    ------------------- ---------------------------------------------
+    ``GPIO6``           SDIO/Flash CLK pin
+    ------------------- ---------------------------------------------
+    ``GPIO7``           SDIO/Flash Data 0 pin
+    ------------------- ---------------------------------------------
+    ``GPIO8``           SDIO/Flash Data 1 pin
+    ------------------- ---------------------------------------------
+    ``GPIO9``           SDIO/Flash Data 2 pin (qio/qout only)
+    ------------------- ---------------------------------------------
+    ``GPIO10``          SDIO/Flash Data 3 pin (qio/qout only)
+    ------------------- ---------------------------------------------
+    ``GPIO11``          SDIO/Flash CMD pin
+    ------------------- ---------------------------------------------
+    ``GPIO12``          Attached to Hardware SPI controller MISO
+    ------------------- ---------------------------------------------
+    ``GPIO13``          Attached to Hardware SPI controller MOSI
+    ------------------- ---------------------------------------------
+    ``GPIO14``          Attached to Hardware SPI controller CLK
+    ------------------- ---------------------------------------------
+    ``GPIO15``          Controls Boot Mode; Attached to Hardware SPI
+                        controller CS
+    ------------------- ---------------------------------------------
+    ``GPIO16``          Special pin that can be accessed from RTC,
+                        and is Deep-Sleep wakeup pin
+    ------------------- ---------------------------------------------
+    TOUT aka ``GPIO17`` ADC pin for measuring voltages, can only be
+                        used as analog input pin
+    =================== =============================================
+
+Boot Modes
+----------
+
+On each boot, the ESP8266 will check three pins to determine in which boot mode to enter.
+There are three boot modes:
+
+.. table::
+    :class: no-center
+
+    ========================= ========= ========= ========== ==============
+    **Mode**                  ``GPIO0`` ``GPIO2`` ``GPIO15`` ``boot mode:``
+    ------------------------- --------- --------- ---------- --------------
+    Boot from Flash (normal)  HIGH      HIGH      LOW        3
+    ------------------------- --------- --------- ---------- --------------
+    Download Code from UART   LOW       HIGH      LOW        1
+    ------------------------- --------- --------- ---------- --------------
+    Boot from SD-Card         ANY       ANY       HIGH       4-7
+    ========================= ========= ========= ========== ==============
+
+You can identify these on boot-up by looking at the UART output, the first number
+in the ``boot mode:`` line tells you what mode was selected
+
+.. code-block:: text
+
+    ets Jan  8 2013,rst cause:4, boot mode:(3,6)
+
+The first lines when viewing the UART logs might have unrecognized characters. This is
+because the ESP8266 bootloader uses a baudrate of 76800, whereas the use program uses 115200.
+
+Reset Causes
+------------
+
+Additionally, the first line also contains the **reset cause**.
+These reset causes `are documented <https://www.espressif.com/sites/default/files/documentation/esp8266_reset_causes_and_common_fatal_exception_causes_en.pdf>`__:
+
+.. table::
+    :class: no-center
+
+    == ===================================
+    0  Undefined
+    -- -----------------------------------
+    1  Power On Reboot
+    -- -----------------------------------
+    2  External reset or deep-sleep wakeup
+    -- -----------------------------------
+    4  Hardware WDT reset
+    == ===================================
+
+After a software reset, the reset cause will not change.
+
 See Also
 --------